Difference between revisions of "TEsound"

m (Improved some phrasing)
m
 
(16 intermediate revisions by 7 users not shown)
Line 2: Line 2:
 
TEsound is a sound manager for the Love2D framework. TEsound is intended to make it easier to use sounds and music in your games.
 
TEsound is a sound manager for the Love2D framework. TEsound is intended to make it easier to use sounds and music in your games.
  
It's under the [http://www.opensource.org/licenses/zlib-license.php zlib license]. If you use the library and your game ends up making a lot of money, its creators politely request that you consider sending a little bit of it their way.
+
It's under the [http://www.opensource.org/licenses/zlib-license.php ZLIB license]. If you use the library and your game ends up making a lot of money, its creators politely request that you consider sending a little bit of it their way.
  
 
=== Download ===
 
=== Download ===
[http://dl.dropbox.com/u/3713769/web/Love/TEsound/TEsound.lua Direct from Dropbox]
+
The original Dropbox link is dead; leaving for posterity and in case it comes back. Until it does, [https://github.com/drhayes/TESound here's the GitHub link].
 +
 
 +
[http://dl.dropbox.com/u/3713769/web/Love/TLTools/TEsound.lua Direct from Dropbox]
  
 
=== Contact ===
 
=== Contact ===
Line 16: Line 18:
  
 
# Put TEsound.lua in your game's folder
 
# Put TEsound.lua in your game's folder
# At the top of main.lua, add the line: require"TEsound"
+
# At the top of main.lua, add the line <code>require"TEsound"</code>
# In love.update(), add the line: TEsound.cleanup()
+
# In love.update(), add the line <code>TEsound.cleanup()</code>
 +
 
 +
== FAQ ==
 +
;Q) How do I just play a sound?
 +
:A) All you need to do is <code>TEsound.play(sound)</code>, where <code>sound</code> is either a [[SoundData]] or a string filepath to a sound file (like <code>"sounds/boom.ogg"</code>).
 +
 
 +
;Q) I have three different jump sounds, how can I play one at random?
 +
:A) <code>TEsound.play(list)</code>, where <code>list</code> is a table like <code>{"jump1.ogg", "jump2.ogg", "jump3.ogg"}</code>.
 +
 
 +
;Q) Can I make it constantly play randomized music?
 +
:A) Sure! <code>TEsound.playLooping(list)</code>. When one song ends, a new one from the list will automatically start playing.
 +
 
 +
;Q) Now how do I stop the music? / What are sound tags?
 +
:A) The best way is to use TEsound's "tagging" feature. Simply put, TEsound lets you add one or more tags to each sound that's playing, and you can call various functions on all sounds with a given tag. So you could do this:
 +
:<code>TEsound.playLooping("song1.ogg", "music")</code>
 +
:<code>TEsound.stop("music")</code>
 +
:Sounds can have multiple tags if you desire (use a list: <code>TEsound.play(sound, {"something", "whatever", "lol"})</code>, and multiple sounds can share tags (if you call something like <code>TEsound.pitch("sfx", .5)</code>, all sounds with the "sfx" tag will immediately be low-pitched). Tags can also be unique, in case you want to work with a specific sound.
 +
 
 +
;Q) What if I want to change the volume/pitch of all sounds?
 +
:A) That's what the special "all" tag is for. You don't need to give the tag to sounds, it's automatically applied to them. So if you wanted to cut the volume of everything in half, you just need to <code>TEsound.volume("all",.5)</code>.
 +
 
 +
;Q) I want to let the player choose different volume levels for sound effects, music, and voice-acting. Can TEsound handle it?
 +
:A) Yep! You can set a volume multiplier for any tag with <code>TEsound.volume(tag, volume)</code>. Tag-volume changes take immediate effect (even on sounds that are already playing!). So you could use <code>TEsound.volume("voice", .75)</code>, and any sound with the "voice" tag would play at .75 volume. This is multiplied by the sound's own volume and what the "all" tag is set to - if you <code>TEsound.play("splat.ogg", "sfx", .5)</code>, and you've set the "sfx" and "all" tags to .6 and 1 volume, then the sound would play at .3 volume.
 +
 
 +
;Q) How do I pronounce the name of your module? "Tee ee sound"?
 +
:A) That works, but I, personally, say "teh sound" ;)
  
 
== Functions ==
 
== Functions ==
Line 26: Line 53:
 
Plays a sound. Returns either the number of the channel the sound is playing in, or nil and an error message.
 
Plays a sound. Returns either the number of the channel the sound is playing in, or nil and an error message.
  
{{param|string or table|sound|A filepath to the sound file (example: "sounds/jump.ogg"), or a list of filepaths. If a list is used, a random sound from that list will be played.}}
+
{{param|table|sound|Either a [[SoundData]] or a string filepath to a sound file (example: "sounds/jump.ogg"), or a list of these. If a list is used, a random sound from that list will be played.}}
{{param|string or table|tags (optional)|One or more tags that can be used to identify a sound (Example, single: "music". Example, multiple: {"sfx", "gun", "player"}). Multiple sounds may share tags, or tags may be unique. If omitted, no tags are assigned.}}
+
{{param|table|tags ({})|One or more tags that can be used to identify a sound (Example, single: "music". Example, multiple: {"sfx", "gun", "player"}). Multiple sounds may share tags, or tags may be unique. If omitted, no tags are assigned. Passing a string is shorthand for passing a table with only one item.}}
{{param|number|volume (optional)| A number between 0 and 1 which specifies how loud a sound is. If the sound has a tag which a volume has been specified for, it will multiply this number (ie., if you use the tag "sfx" and volume 0.5, and "sfx" has been tagVolume-ed to 0.6, then the sound will be played at 0.3 volume). If omitted, the number 1 will be used.}}
+
{{param|number|volume (1)| A number between 0 and 1 which specifies how loud a sound is. If the sound has a tag which a volume has been specified for, it will multiply this number (ie., if you use the tag "sfx" and volume 0.5, and "sfx" has been volume-ed to 0.6, then the sound will be played at 0.3 volume).}}
{{param|number|pitch (optional)|A number which specifies the speed/pitch the sound will be played it. If the sound has a tag which a pitch has been specified for, it will multiply this number. If omitted, the number 1 will be used.}}
+
{{param|number|pitch (1)|A number which specifies the speed/pitch the sound will be played it. If the sound has a tag which a pitch has been specified for, it will multiply this number.}}
{{param|number|func (optional)| A function which will be called when the sound is finished playing (it's passed one parameter - a list with the sound's volume and pitch). If omitted, no function will be used.}}
+
{{param|function|func (no callback)| A function which will be called when the sound is finished playing (it's passed one parameter - a list with the sound's volume and pitch). If omitted, no function will be used.}}
  
 
==== TEsound.playLooping ====
 
==== TEsound.playLooping ====
 
<source lang="lua">TEsound.playLooping(sound, tags, n, volume, pitch)</source>
 
<source lang="lua">TEsound.playLooping(sound, tags, n, volume, pitch)</source>
 
Plays a sound which will repeat be repeated n times. If n isn't given, it will loop until stopped manually with TEsound.stop. Returns either the number of the channel the sound is playing in, or nil and an error message.
 
Plays a sound which will repeat be repeated n times. If n isn't given, it will loop until stopped manually with TEsound.stop. Returns either the number of the channel the sound is playing in, or nil and an error message.
{{param|string or table|sound|See TEsound.play}}
+
{{param|table|sound|See TEsound.play. If a list is used, each loop will randomly choose from the list. Good for randomized background music.}}
{{param|string or table|tags|See TEsound.play}}
+
{{param|table|tags|See TEsound.play}}
 
{{param|number|n|The number of times the sound will be looped. If omitted, the sound will loop forever.}}
 
{{param|number|n|The number of times the sound will be looped. If omitted, the sound will loop forever.}}
 
{{param|number|volume|See TEsound.play}}
 
{{param|number|volume|See TEsound.play}}
 
{{param|number|pitch|See TEsound.play}}
 
{{param|number|pitch|See TEsound.play}}
 +
  
 
=== Sound Modification Functions ===
 
=== Sound Modification Functions ===
Line 45: Line 73:
 
<source lang="lua">TEsound.volume(channel, volume)</source>
 
<source lang="lua">TEsound.volume(channel, volume)</source>
 
Sets the volume of channel or tag and its loops (if any).
 
Sets the volume of channel or tag and its loops (if any).
{{param|number or string|channel|Determines which channel will be affected. If a number, a channel will be set directly; if a string, all channels playing a sound with that tag will be affected. Since sound channels aren't static, it's generally advisible to use the tag method.}}
+
{{param|number|channel|Determines which channel will be affected. Since sound channels aren't static, it's generally advisable to use the tag method (see below).}}
{{param|number|volume (optional)|See TEsound.play. If omitted, the sound's volume won't be changed (pointless in most cases).}}
+
{{param|number|volume (no change)|See TEsound.play. If omitted, the sound's volume won't be changed (pointless in most cases).}}
 +
 
 +
====TEsound.volume====
 +
<source lang="lua">TEsound.volume(tag, volume)</source>
 +
Sets the volume of channel or tag and its loops (if any).
 +
{{param|string|tag|Determines which channel will be affected. All channels playing a sound with that tag will be affected. Since sound channels aren't static, it's generally advisable to use the tag method.}}
 +
{{param|number|volume (no change)|See TEsound.play. If omitted, the sound's volume won't be changed (pointless in most cases).}}
  
 
====TEsound.pitch====
 
====TEsound.pitch====
 
<source lang="lua">TEsound.pitch(channel, pitch)</source>
 
<source lang="lua">TEsound.pitch(channel, pitch)</source>
 
Sets the pitch of channel or tag and its loops (if any).
 
Sets the pitch of channel or tag and its loops (if any).
{{param|number or string|channel|See TEsound.volume}}
+
{{param|number|channel|See TEsound.volume}}
{{param|number|pitch (optional)|See TEsound.play. If omitted, the sound's pitch won't be changed.}}
+
{{param|number|pitch (no change)|See TEsound.play. If omitted, the sound's pitch won't be changed.}}
 +
 
 +
====TEsound.pitch====
 +
<source lang="lua">TEsound.pitch(tag, pitch)</source>
 +
Sets the pitch of channel or tag and its loops (if any).
 +
{{param|string|tag|See TEsound.volume}}
 +
{{param|number|pitch (no change)|See TEsound.play. If omitted, the sound's pitch won't be changed.}}
  
 
====TEsound.pause====
 
====TEsound.pause====
 
<source lang="lua">TEsound.pause(channel)</source>
 
<source lang="lua">TEsound.pause(channel)</source>
 
Pauses a channel or tag. Use TEsound.resume to unpause.
 
Pauses a channel or tag. Use TEsound.resume to unpause.
{{param|number or string|channel|See TEsound.volume}}
+
{{param|number|channel|See TEsound.volume}}
 +
 
 +
====TEsound.pause====
 +
<source lang="lua">TEsound.pause(tag)</source>
 +
Pauses a channel or tag. Use TEsound.resume to unpause.
 +
{{param|string|tag|See TEsound.volume}}
  
 
====TEsound.resume====
 
====TEsound.resume====
 
<source lang="lua">TEsound.resume(channel)</source>
 
<source lang="lua">TEsound.resume(channel)</source>
 
Resumes a channel or tag from a pause.
 
Resumes a channel or tag from a pause.
{{param|number or string|channel|See TEsound.volume}}
+
{{param|number|channel|See TEsound.volume}}
 +
 
 +
====TEsound.resume====
 +
<source lang="lua">TEsound.resume(tag)</source>
 +
Resumes a channel or tag from a pause.
 +
{{param|string|tag|See TEsound.volume}}
  
 
====TEsound.stop====
 
====TEsound.stop====
 
<source lang="lua">TEsound.stop(channel, finish)</source>
 
<source lang="lua">TEsound.stop(channel, finish)</source>
 
Stops a sound channel or tag either immediately or when finished, and prevents it from looping.
 
Stops a sound channel or tag either immediately or when finished, and prevents it from looping.
{{param|number or string|channel|See TEsound.volume}}
+
{{param|number|channel|See TEsound.volume}}
{{param|boolean|finish (optional)|If true, the sound will be allowed to finish playing instead of stopping immediately. This is mainly used to end a sound loop.}}
+
{{param|boolean|finish (false)|If true, the sound will be allowed to finish playing instead of stopping immediately. This is mainly used to end a sound loop.}}
 +
 
 +
====TEsound.stop====
 +
<source lang="lua">TEsound.stop(tag, finish)</source>
 +
Stops a sound channel or tag either immediately or when finished, and prevents it from looping.
 +
{{param|string|tag|See TEsound.volume}}
 +
{{param|boolean|finish (false)|If true, the sound will be allowed to finish playing instead of stopping immediately. This is mainly used to end a sound loop.}}
 +
 
  
 
=== Utility Functions ===
 
=== Utility Functions ===
Line 75: Line 132:
 
Cleans up finished sounds, freeing memory. It's highly recommended you call this in love.update(). If not called, memory and channels won't be freed, and sounds won't loop.
 
Cleans up finished sounds, freeing memory. It's highly recommended you call this in love.update(). If not called, memory and channels won't be freed, and sounds won't loop.
  
====TEsound.tagVolume====
+
====TEsound.volume====
<source lang="lua">TEsound.tagVolume(tag, volume)</source>
+
<source lang="lua">TEsound.volume(tag, volume)</source>
 
Change the volume level for a specified tag. Volume changes take effect immediately and last until changed again. This is recommended for changing entire categories of sounds, so you can independently adjust the volume of all sound effects, music, etc. (but don't forget to tag your sounds appropriately). If a sound has multiple tags with set volumes, the first one (in the order of its tag list) will be used.
 
Change the volume level for a specified tag. Volume changes take effect immediately and last until changed again. This is recommended for changing entire categories of sounds, so you can independently adjust the volume of all sound effects, music, etc. (but don't forget to tag your sounds appropriately). If a sound has multiple tags with set volumes, the first one (in the order of its tag list) will be used.
 
{{param|string|tag|The tag to set the volume of. There is a special tag called "all" which will multiply ALL sounds (in addition to a regular tag, if present) - use it as a master volume control. Sounds do not need to be assigned the "all" tag for this to happen.}}
 
{{param|string|tag|The tag to set the volume of. There is a special tag called "all" which will multiply ALL sounds (in addition to a regular tag, if present) - use it as a master volume control. Sounds do not need to be assigned the "all" tag for this to happen.}}
Line 84: Line 141:
 
<source lang="lua">TEsound.tagPitch(tag, volume)</source>
 
<source lang="lua">TEsound.tagPitch(tag, volume)</source>
 
Change the pitch for a specified tag. Changes take effect immediately and last until changed again. This is recommended for changing entire categories of sounds. If a sound has multiple tags with set pitches, the first one (in the order of its tag list) will be used.
 
Change the pitch for a specified tag. Changes take effect immediately and last until changed again. This is recommended for changing entire categories of sounds. If a sound has multiple tags with set pitches, the first one (in the order of its tag list) will be used.
{{param|string|tag|See TEsound.tagVolume}}
+
{{param|string|tag|See TEsound.volume}}
 
{{param|number|pitch (optional)|See TEsound.play. If omitted, the tag will no longer affect the pitch of matching sounds.}}
 
{{param|number|pitch (optional)|See TEsound.play. If omitted, the tag will no longer affect the pitch of matching sounds.}}
 +
  
 
=== Internal Functions ===
 
=== Internal Functions ===
Line 96: Line 154:
 
<source lang="lua">TEsound.findVolume(tag)</source>
 
<source lang="lua">TEsound.findVolume(tag)</source>
 
Returns a volume level for a given tag or tags, or 1 if the tag(s)'s volume hasn't been set. If a list of tags is given, it will return the level of the first tag with a setting.
 
Returns a volume level for a given tag or tags, or 1 if the tag(s)'s volume hasn't been set. If a list of tags is given, it will return the level of the first tag with a setting.
{{param|string or table|tag|Chooses the tag to check the volume of.}}
+
{{param|string|tag|Chooses the tag to check the volume of. Passing a table will check only the first item.}}
  
 
====TEsound.findPitch====
 
====TEsound.findPitch====
 
<source lang="lua">TEsound.findPitch(tag)</source>
 
<source lang="lua">TEsound.findPitch(tag)</source>
 
Returns a pitch level for a given tag or tags, or 1 if the tag(s)'s pitch hasn't been set.
 
Returns a pitch level for a given tag or tags, or 1 if the tag(s)'s pitch hasn't been set.
{{param|string or table|tag|See TEsound.findVolume}}
+
{{param|string|tag|See TEsound.findVolume}}
  
== FAQ ==
 
;Q) How do I just play a sound?
 
:A) All you need to do is TEsound.play(filepath), where filepath is a string like "sounds/boom.ogg".
 
 
;Q) I have three different jump sounds, how can I play one at random?
 
:A) TEsound.play(list), where list is a table like {"jump1.ogg", "jump2.ogg", "jump3.ogg"}
 
 
;Q) Can I make it constantly play randomized music?
 
:A) Sure! TEsound.playLooping(list). When one song ends, a new one from the list will automatically start playing.
 
 
;Q) Now how do I stop the music? / What are sound tags?
 
:A) The best way is to use TEsound's "tagging" feature. Simply put, TEsound lets you add one or more tags to each sound that's playing, and you can call various functions on all sounds with a given tag. So you could do this:
 
<source lang="lua">TEsound.playLooping("song1.ogg", "music")
 
TEsound.stop("music")</source>
 
:Sounds can have multiple tags if you desire (use a list: TEsound.play(sound, {"something", "whatever", "lol"}), and multiple sounds can share tags (if you call something like TEsound.pitch("sfx", .5), all sounds with the "sfx" tag will immediately be low-pitched). Tags can also be unique, in case you want to work with a specific sound.
 
 
;Q) What if I want to change the volume/pitch of all sounds?
 
:A) That's what the special "all" tag is for. You don't need to give the tag to sounds, it's automatically applied to them. So if you wanted to cut the volume of everything in half, you just need to TEsound.tagVolume("all",.5).
 
 
;Q) I want to let the player choose different volume levels for sound effects, music, and voice-acting. Can TEsound handle it?
 
:A) Yep! You can set a volume multiplier for any tag with TEsound.tagVolume(tag, volume). Tag-volume changes take immediate effect (even on sounds that are already playing!). So you could use TEsound.tagVolume("voice", .75), and any sound with the "voice" tag would play at .75 volume. This is multiplied by the sound's own volume and what the "all" tag is set to - if you TEsound.play("splat.ogg", "sfx", .5), and you've set the "sfx" and "all" tags to .6 and 1 volume, then the sound would play at .3 volume.
 
 
;Q) How do I pronounce the name of your module? "Tee ee sound"?
 
:A) That works, but I, personally, say "teh sound" ;)
 
 
{{#set:LOVE Version=0.7.0}}
 
{{#set:LOVE Version=0.7.0}}
{{#set:Description=An easy sound manager for the Love2D framework}}
+
{{#set:Description=A sound manager that makes it easy to use sound and music}}
 +
{{#set:Keyword=Sound}}
 +
{{#set:License=ZLIB license}}
 +
{{#set:Author=User:Taehl}}
 +
{{#set:Author=User:Ensayia}}
 
[[Category:Libraries]]
 
[[Category:Libraries]]
 +
 +
== Other Languages ==
 +
{{i18n|TEsound}}

Latest revision as of 06:14, 15 December 2019

About

TEsound is a sound manager for the Love2D framework. TEsound is intended to make it easier to use sounds and music in your games.

It's under the ZLIB license. If you use the library and your game ends up making a lot of money, its creators politely request that you consider sending a little bit of it their way.

Download

The original Dropbox link is dead; leaving for posterity and in case it comes back. Until it does, here's the GitHub link.

Direct from Dropbox

Contact

  • Forum Thread
  • Ensayia - Ensayia@gmail.com
  • Taehl - SelfMadeSpirit@gmail.com

Setup

Everything in the module is contained in the TEsound namespace, so don't worry about it messing with your global variables. Memory and channel management is automatic.

  1. Put TEsound.lua in your game's folder
  2. At the top of main.lua, add the line require"TEsound"
  3. In love.update(), add the line TEsound.cleanup()

FAQ

Q) How do I just play a sound?
A) All you need to do is TEsound.play(sound), where sound is either a SoundData or a string filepath to a sound file (like "sounds/boom.ogg").
Q) I have three different jump sounds, how can I play one at random?
A) TEsound.play(list), where list is a table like {"jump1.ogg", "jump2.ogg", "jump3.ogg"}.
Q) Can I make it constantly play randomized music?
A) Sure! TEsound.playLooping(list). When one song ends, a new one from the list will automatically start playing.
Q) Now how do I stop the music? / What are sound tags?
A) The best way is to use TEsound's "tagging" feature. Simply put, TEsound lets you add one or more tags to each sound that's playing, and you can call various functions on all sounds with a given tag. So you could do this:
TEsound.playLooping("song1.ogg", "music")
TEsound.stop("music")
Sounds can have multiple tags if you desire (use a list: TEsound.play(sound, {"something", "whatever", "lol"}), and multiple sounds can share tags (if you call something like TEsound.pitch("sfx", .5), all sounds with the "sfx" tag will immediately be low-pitched). Tags can also be unique, in case you want to work with a specific sound.
Q) What if I want to change the volume/pitch of all sounds?
A) That's what the special "all" tag is for. You don't need to give the tag to sounds, it's automatically applied to them. So if you wanted to cut the volume of everything in half, you just need to TEsound.volume("all",.5).
Q) I want to let the player choose different volume levels for sound effects, music, and voice-acting. Can TEsound handle it?
A) Yep! You can set a volume multiplier for any tag with TEsound.volume(tag, volume). Tag-volume changes take immediate effect (even on sounds that are already playing!). So you could use TEsound.volume("voice", .75), and any sound with the "voice" tag would play at .75 volume. This is multiplied by the sound's own volume and what the "all" tag is set to - if you TEsound.play("splat.ogg", "sfx", .5), and you've set the "sfx" and "all" tags to .6 and 1 volume, then the sound would play at .3 volume.
Q) How do I pronounce the name of your module? "Tee ee sound"?
A) That works, but I, personally, say "teh sound" ;)

Functions

Playback Functions

TEsound.play

TEsound.play(sound, tags, volume, pitch, func)

Plays a sound. Returns either the number of the channel the sound is playing in, or nil and an error message.

table sound
Either a SoundData or a string filepath to a sound file (example: "sounds/jump.ogg"), or a list of these. If a list is used, a random sound from that list will be played.
table tags ({})
One or more tags that can be used to identify a sound (Example, single: "music". Example, multiple: {"sfx", "gun", "player"}). Multiple sounds may share tags, or tags may be unique. If omitted, no tags are assigned. Passing a string is shorthand for passing a table with only one item.
number volume (1)
A number between 0 and 1 which specifies how loud a sound is. If the sound has a tag which a volume has been specified for, it will multiply this number (ie., if you use the tag "sfx" and volume 0.5, and "sfx" has been volume-ed to 0.6, then the sound will be played at 0.3 volume).
number pitch (1)
A number which specifies the speed/pitch the sound will be played it. If the sound has a tag which a pitch has been specified for, it will multiply this number.
function func (no callback)
A function which will be called when the sound is finished playing (it's passed one parameter - a list with the sound's volume and pitch). If omitted, no function will be used.

TEsound.playLooping

TEsound.playLooping(sound, tags, n, volume, pitch)

Plays a sound which will repeat be repeated n times. If n isn't given, it will loop until stopped manually with TEsound.stop. Returns either the number of the channel the sound is playing in, or nil and an error message.

table sound
See TEsound.play. If a list is used, each loop will randomly choose from the list. Good for randomized background music.
table tags
See TEsound.play
number n
The number of times the sound will be looped. If omitted, the sound will loop forever.
number volume
See TEsound.play
number pitch
See TEsound.play


Sound Modification Functions

TEsound.volume

TEsound.volume(channel, volume)

Sets the volume of channel or tag and its loops (if any).

number channel
Determines which channel will be affected. Since sound channels aren't static, it's generally advisable to use the tag method (see below).
number volume (no change)
See TEsound.play. If omitted, the sound's volume won't be changed (pointless in most cases).

TEsound.volume

TEsound.volume(tag, volume)

Sets the volume of channel or tag and its loops (if any).

string tag
Determines which channel will be affected. All channels playing a sound with that tag will be affected. Since sound channels aren't static, it's generally advisable to use the tag method.
number volume (no change)
See TEsound.play. If omitted, the sound's volume won't be changed (pointless in most cases).

TEsound.pitch

TEsound.pitch(channel, pitch)

Sets the pitch of channel or tag and its loops (if any).

number channel
See TEsound.volume
number pitch (no change)
See TEsound.play. If omitted, the sound's pitch won't be changed.

TEsound.pitch

TEsound.pitch(tag, pitch)

Sets the pitch of channel or tag and its loops (if any).

string tag
See TEsound.volume
number pitch (no change)
See TEsound.play. If omitted, the sound's pitch won't be changed.

TEsound.pause

TEsound.pause(channel)

Pauses a channel or tag. Use TEsound.resume to unpause.

number channel
See TEsound.volume

TEsound.pause

TEsound.pause(tag)

Pauses a channel or tag. Use TEsound.resume to unpause.

string tag
See TEsound.volume

TEsound.resume

TEsound.resume(channel)

Resumes a channel or tag from a pause.

number channel
See TEsound.volume

TEsound.resume

TEsound.resume(tag)

Resumes a channel or tag from a pause.

string tag
See TEsound.volume

TEsound.stop

TEsound.stop(channel, finish)

Stops a sound channel or tag either immediately or when finished, and prevents it from looping.

number channel
See TEsound.volume
boolean finish (false)
If true, the sound will be allowed to finish playing instead of stopping immediately. This is mainly used to end a sound loop.

TEsound.stop

TEsound.stop(tag, finish)

Stops a sound channel or tag either immediately or when finished, and prevents it from looping.

string tag
See TEsound.volume
boolean finish (false)
If true, the sound will be allowed to finish playing instead of stopping immediately. This is mainly used to end a sound loop.


Utility Functions

TEsound.cleanup

TEsound.cleanup()

Cleans up finished sounds, freeing memory. It's highly recommended you call this in love.update(). If not called, memory and channels won't be freed, and sounds won't loop.

TEsound.volume

TEsound.volume(tag, volume)

Change the volume level for a specified tag. Volume changes take effect immediately and last until changed again. This is recommended for changing entire categories of sounds, so you can independently adjust the volume of all sound effects, music, etc. (but don't forget to tag your sounds appropriately). If a sound has multiple tags with set volumes, the first one (in the order of its tag list) will be used.

string tag
The tag to set the volume of. There is a special tag called "all" which will multiply ALL sounds (in addition to a regular tag, if present) - use it as a master volume control. Sounds do not need to be assigned the "all" tag for this to happen.
number volume (optional)
See TEsound.play. If omitted, the tag will no longer affect the volume of matching sounds.

TEsound.tagPitch

TEsound.tagPitch(tag, volume)

Change the pitch for a specified tag. Changes take effect immediately and last until changed again. This is recommended for changing entire categories of sounds. If a sound has multiple tags with set pitches, the first one (in the order of its tag list) will be used.

string tag
See TEsound.volume
number pitch (optional)
See TEsound.play. If omitted, the tag will no longer affect the pitch of matching sounds.


Internal Functions

TEsound.findTag

TEsound.findTag(tag)

Returns a list of all sound channels with a given tag.

string tag
The channels of all sounds with this tag will be returned.

TEsound.findVolume

TEsound.findVolume(tag)

Returns a volume level for a given tag or tags, or 1 if the tag(s)'s volume hasn't been set. If a list of tags is given, it will return the level of the first tag with a setting.

string tag
Chooses the tag to check the volume of. Passing a table will check only the first item.

TEsound.findPitch

TEsound.findPitch(tag)

Returns a pitch level for a given tag or tags, or 1 if the tag(s)'s pitch hasn't been set.

string tag
See TEsound.findVolume

Other Languages