**Title:** Sounds

**Description:** 

**Details:**
### Description

A mod that provides a set of free sounds & methods.

*(For a headache, listen to [these sounds](https://antummt.github.io/mod-sounds/reference/latest/topics/groups.html#sounds.chalk_screech))*

What is the purpose of this mod? There are four ideas behind `sounds`:

1. It is intended as a more universal method for adding sounds to games rather than depending on [MTG & default](https://github.com/minetest/minetest_game/tree/master/mods/default) for sounds only. It is completely compatible with default sounds. The same methods called in `default` to set node sounds, like `default.node_sound_stone_defaults`, are implemented & it can be installed in parallel. *Section: [Replacement for default](#replacement-for-default)*
2. It is simply a well of sounds. Many sound files are provided & can be used with [minetest.sound_play](https://minetest.gitlab.io/minetest/minetest-namespace-reference/#sounds) just as normal. There is also a wrapper function, `sounds.play`, that does its best to verify that a sound played successfully. If so, it will return a sound handle ID. Otherwise it will return `nil`. It also caches all loaded mod sounds after server startup in `sounds.cache` table. So sound files can easily be checked for existence. *Section: [Checking for Existing Sounds](#checking-for-existing-sounds)*
3. It adds callable sound groups that can be used to play specified individual sounds, or a random sound in the group. The benefit to this is that the file naming convention is irrelivent. The only thing that matters is that the sound file is registered with the group. *Section: [Playing Sounds Manually](#playing-sounds-manually)*
4. Adds an API for setting biome ambiance sounds.

Note that most included sounds have been set with a peak amplitude of -6.0db.

### Licensing

- Code: [MIT](https://github.com/AntumMT/mod-sounds/blob/master/LICENSE.txt)
- Icon/Screenshot: [CC0](https://openclipart.org/detail/260975)
- Media: multiple (see [sources.md](https://github.com/AntumMT/mod-sounds/blob/master/sources.md))

### Usage

<a name="replacement-for-default"></a>
##### Replacement for default

If your mod depends on *default* for node sounds only, then you can easily switch to *sounds*. Simply add *default* & *sounds* as optional dependencies in your *mod.conf*. *sounds* overrides methods used by *default* to its own. For example *default.node_sound_dirt_defaults*.

Example of overidden method:
```lua
function sounds.node_dirt(tbl)
	tbl = tbl or {}

	tbl.footstep = tbl.footstep or {name="sounds_dirt_step", gain=0.4}
	tbl.dug = tbl.dug or {name="sounds_dirt_step", gain=1.0}
	tbl.place = tbl.place or {name="sounds_node_place_soft", gain=1.0}

	sounds.node(tbl)
	return tbl
end

default.node_sound_dirt_defaults = sounds.node_dirt
```

Example of setting node sounds:
```lua
minetest.register_node("foo:bar", {
	description = "Foo Node",
	-- this is the same as calling `sounds.node_stone()`
	sounds = default.node_sound_stone_defaults()
	...
})
```

##### <a name="playing-sounds-manually">Playing Sounds Manually</a>

`SoundGroup` instances are objects for storing & playing sounds. These objects can be called to play a sound from their group. An index can be specified when called to determine which sound to play. If the index parameter is omitted, a random sound will be picked. A table of arguments can also be passed. This is compatible with [SimpleSoundSpec](https://minetest.gitlab.io/minetest/sounds/#simplesoundspec).

Creating `SoundGroup` objects:
```lua
local s_group1 = SoundGroup({"sound1", "sound2"})
local s_group2 = SoundGroup({"sound3", "sound4", "sound5"})

-- SoundGroup objects can be concatenated with the arithmetic operator
local s_group3 = s_group1 + s_group2

-- strings can also be concatenated to group with arithmetic operator
s_group3 = s_group3 + "sound6"

-- to prevent sound file names from being prefixed with "sounds_" when played,
-- the `no_prepend` field must be set to `true`
s_group1(2) -- plays "sounds_sound2"

s_group1.no_prepend = true
s_group1(2) -- plays "sound2"
```

There are many [pre-defined sound groups](https://antummt.github.io/mod-sounds/reference/latest/topics/groups.html).

Calling a `SoundGroup` object:
```lua
-- play random sound from group
sounds.horse_neigh()

-- play specific sound from group
sounds.horse_neigh(2)

-- play random sound from group with parameters
sounds.horse_neigh({gain=1.0})

-- play specific sound from group with parameters
sounds.horse_neigh(2, {gain=1.0})

-- the `play` method is the same as calling the object directly
sounds.horse_neigh:play(2, {gain=1.0})
```

See [sources.md](https://github.com/AntumMT/mod-sounds/blob/master/sources.md) for list of included sounds. And [preview sounds here](https://antummt.github.io/mod-sounds/reference/latest/topics/groups.html).

##### Node Sounds

`SoundGroup` objects can also be used in node registration:
```lua
minetest.register_node("foo:bar", {
	description = "Foo Node",
	sounds = {
		-- a random sound from the `sounds.cow_moo` group will be played when digging this node
		dig = sounds.cow_moo,
	},
	...
```

Currently using `SoundGroup` for node sounds only works for "dig", "dug", & "place".

`SoundGroup` objects are tables & are indexed by integer. But using the `get` method is more reliable as it will return the string name with "sounds_" prefix if `no_prepend` isn't set:
```lua
local s_group1 = SoundGroup({"sound1", "sound2"})
local s1 = s_group1:get(1) -- returns "sounds_sound1"
local s2 = s_group1[2] -- returns "sound2"

local s_group2 = SoundGroup({"sound3", "sound4", no_prepend=true})
local s3 = s_group2:get(1) -- returns "sound3"
local s4 = s_group2[2] -- returns "sound4"
```

The built-in `type` function can be used to check for a `SoundGroup` instance:
```lua
if type(s_group1) == "SoundGroup" then
	s_group1()
end
```

##### <a name="checking-for-existing-sounds">Checking for Existing Sounds</a>

All mod sound files are stored in the global table `sounds.cache` after server startup. Checking if a file exists for playing is simple:

```lua
if sounds.cache["default_dig_crumbly"] then
	core.sound_play("default_dig_crumbly")
end
```

##### Testing Sounds

If setting `sounds.enable_tests` is enabled, the chat command `/sounds_tests` can be used to show a formspec for playing & testing sounds.

To test *any* sound, input the sound name in the "Manual play" field & press the corresponding "Play" button. If the sound file exists, it will play & some info will be filled in the "Last played" field.

To test sounds cached in sound groups, select a group in the left column of the "Group play" field. Then select a sound in the right column & press the corresponding "Play" button.

Sounds can be looped by checking the "Loop" box.

##### Biome Ambiance

A sound group can be registered for playing sounds randomly in a biome with the `sounds:register_biome_sounds` method (`sounds.enable_biome_sounds` must be enabled):

```
sounds:register_biome_sounds(biome, snds, params)
- Registers a sound group to be played in a biome.
- parameters:
  - biome:  Biome name.
  - snds:   string, table, or SoundGroup of sounds registered with biome.
  - params: SimpleSoundSpec parameters (optional).
```

Example usage:
```lua
sounds:register_biome_sounds("grassland", sounds.bird, {gain=0.25})
```

##### Settings

```
sounds.disabled_groups
- Disables individual built-in sound groups categories. "all" disables all categories.
- type:    string (comma-separated list)
- default: empty

sounds.enable_tests
- Enables sounds testing with sounds_tests chat command.
- type:    bool
- default: false

sounds.enable_biome_sounds
- Enables/Disables ambiance sounds for biomes.
- type:    bool
- default: false

sounds.biome_interval
- Interval between playing biome sounds.
- type:    int
- min:     5
- default: 30

sounds.biome_chance
- Chance that sound will be played at interval.
- type:    int
- min:     0
- max:     100
- default: 20
```

### Links

- [Reference](https://antummt.github.io/mod-sounds/reference/latest/)
- [Changelog](https://github.com/AntumMT/mod-sounds/blob/master/changelog.txt)
- [TODO](https://github.com/AntumMT/mod-sounds/blob/master/TODO.txt)

**Tags:** environment, library
**Repository:** https://github.com/AntumMT/mod-sounds
**License:** MIT