View source for minetest.sound play

{{DISPLAYTITLE:minetest.sound_play}}
== Syntax ==
<source>minetest.sound_play(SimpleSoundSpec, SoundParameters)</source>

== Description ==
Plays a sound.

Only OGG files are supported. For positional playing of sounds, only single-channel (mono) files are supported. Otherwise OpenAL will play them non-positionally.

<code>[[SimpleSoundSpec]]</code> can be a string with the filename (without the file extention) or a table with the fields <code>name="name"</code> and <code>gain=float</code>.

<code>SoundParameters</code> is a table with the following fields:
* <code>gain = float</code>: the gain. default = 1.0
* <code>max_hear_distance = int</code>: the maximum hear distance. default = 32
* <code>loop = bool</code>: Sound is looped. Only sounds connected to objects can be looped. default = false

The location can be specified with one of the following fields in the SoundParameters (if none is used, its played locationless to all players):
* <code>to_player = "playername"</code>: Sound is played locationless to the player
* <code>pos = [[position]]</code>: Sound is played at this position
* <code>object = [[ObjectRef]]</code>: Sound is played connected to the object

The function returns a sound handle that can be passed to <source enclose=none>minetest.sound_stop(handle)</source> to stop the sound.

== Features ==
You can play random sound using sound filenames convention: modname_soundname.N.ogg (see examples)

== Examples ==
<source>
minetest.sound_play("testmod_testsound", {
	pos = {x=0, y=0, z=0},
	max_hear_distance = 100,
	gain = 10.0,
})
</source>
Plays the sound <code>testmod_testsound.ogg</code> at the [[position]] 0,0,0.
<source>
minetest.sound_play("testmod_foobar", {
	to_player = "foo",
	gain = 2.0,
})
</source>
Plays the sound <code>testmod_foobar.ogg</code> to player "foo".
<source>
-- mod/sounds listing:
--     /testmod_foobar.1.ogg
--     /testmod_foobar.2.ogg
--     /testmod_foobar.3.ogg
minetest.sound_play("testmod_foobar")
</source>
Plays a random <code>testmod_foobar</code> sound to player.
[[Category:Methods]]