> For the complete documentation index, see [llms.txt](https://frinn.gitbook.io/custom-machinery-1.21/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://frinn.gitbook.io/custom-machinery-1.21/creating-custom-machines/machine-appearance/sound-ambient.md).

# Sound (Ambient)

Customize the sound the machine makes when running/idling/erroring.

You can define a sound that will play when the machine is in a specific status (corresponding of where you put the property in the appearance json).

The sound must be a OGG file and must be loaded in-game. Sounds are different than models and textures and must be registered to be usable so for using custom sounds you will have either to use a mod that let you add sounds to the game or replace an existing sound with a resource pack and use it's name in the property.

{% hint style="info" %}
If no sound property is set the machine will just make no sound.
{% endhint %}

Ambient sound has 1 mandatory property and can be configured with 7 optional properties : 

#### Mandatory property : 

<details>

<summary>Sound</summary>

#### Name : `sound`

#### Description :&#x20;

The id of the sound to play while the machine is in the specified status.

#### Example :&#x20;

Use the vanilla furnace sound :&#x20;

```json
"ambient_sound" : {
    "sound": "minecraft:block.furnace.fire_crackle"
}
```

</details>

#### Optional properties :&#x20;

<details>

<summary>Volume</summary>

#### Name : `volume`

#### Description :&#x20;

A positive float value used to calculate the volume of the played sound.

Values higher than 1.0 will increase the volume and values between 0.0 and 1.0 will lower it.

#### Default : `1.0`

#### Example :&#x20;

The sound's volume will be doubled :&#x20;

```json
"ambient_sound": {
    "volume": 2.0
}
```

</details>

<details>

<summary>Pitch</summary>

#### Name : `pitch`

#### Description :&#x20;

A positive float value used to calculate the pitch of the played sound.

Values higher than 1.0 will increase the pitch and values between 0.0 and 1.0 will lower it.

#### Default : `1.0`

#### Example :&#x20;

The sound's pitch will be doubled :&#x20;

```json
"ambient_sound": {
    "pitch": 2.0
}
```

</details>

<details>

<summary>Source</summary>

#### Name : source

#### Description :&#x20;

One of Minecraft sound sources :&#x20;

* master
* music
* record
* weather
* block
* hostile
* neutral
* player
* ambient
* voice

The player can adjust any of these sound sources in sound options.

#### Default : `block`

#### Example :&#x20;

The machine's ambient sound will be played as "music" source :&#x20;

```json
"ambient_sound": {
    "source": "music"
}
```

</details>

<details>

<summary>Loop</summary>

#### Name : `loop`

#### Description :&#x20;

A boolean value which set if the sound should be looped or not.

If set to false the machine will still play the sound continuously but there will be a short blank between each loop.

#### Default : `true`

#### Example :&#x20;

Set the loop to false :&#x20;

```json
"ambient_sound": {
    "loop": false
}
```

</details>

<details>

<summary>Attenuation</summary>

#### Name : `attenuation`

#### Description :&#x20;

A boolean value which set if the sound should be attenuated or not.

If set to true, the sound's volume will decrease as the player moves away the machine.

#### Default : `true`

#### Example :&#x20;

Set the attenuation to false :&#x20;

```json
"ambient_sound": {
    "attenuation": false
}
```

</details>

<details>

<summary>Delay</summary>

#### Name : `delay`

#### Description :&#x20;

A positive integer value that sets the amount (in game ticks) that will be waited before playing the sound.

#### Default : `0`

#### Example :&#x20;

Set the delay to 20 ticks (1 second) :&#x20;

```json
"ambient_sound": {
    "delay": 20
}
```

</details>

<details>

<summary>Relative</summary>

#### Name : `relative`

#### Description :&#x20;

Not sure of what this property does.

#### Default : `false`

#### Example :&#x20;

Set the relative to true :&#x20;

```json
"ambient_sound": {
    "relative": true
}
```

</details>

#### Example :&#x20;

Simply add an ambient sound to the machine :&#x20;

```json5
{
    "ambient_sound": "namespace:sound_location"
}
```

Add a configured ambient sound :&#x20;

```json
{
    "ambient_sound": {
        "sound": "namespace:sound_location",
        "volume": 2.0,
        "pitch": 2.0,
        "source": "music"
    }
}
```