TEsound

About

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

It's under the zlib license, but if your game ends up making a lot of money, maybe you could please consider sending a little bit of it my way? ;)

Download

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()

Functions

Sound Functions

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. sound (string or table) - 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. tags (optional string or table) - 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. volume (optional number) - 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. pitch (optional number) - 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. func (optional function) - 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(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. sound (string) - See TEsound.play tags (optional string or table) - See TEsound.play n (optional number) - The number of times the sound will be looped. If omitted, the sound will loop forever. volume (optional number) - See TEsound.play pitch (optional number) - See TEsound.play

Sound Modification Functions

TEsound.volume(channel, volume) Sets the volume of channel/tag and its loops (if any). channel (number or string) - 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. volume (optional number) - See TEsound.play. If omitted, the sound's volume won't be changed (pointless in most cases).

TEsound.pitch(channel, pitch) Sets the pitch of channel/tag and its loops (if any). channel (number or string) - See TEsound.volume pitch - See TEsound.play. If omitted, the sound's pitch won't be changed.

TEsound.pause(channel) Pauses a channel/tag. Use TEsound.resume to unpause. channel (number or string) - See TEsound.volume

TEsound.resume(channel) Resumes a channel/tag from a pause. channel (number or string) - See TEsound.volume

TEsound.stop(channel, finish) Stops a sound channel/tag either immediately or when finished, and prevents it from looping. channel (number or string) - See TEsound.volume finish (optional boolean) - if true, the sound will be allowed to finish playing instead of stopping immediately. This is mainly used to end a looping sound.

Utility Functions

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.tagVolume(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. tag (string) - 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. volume (optional number) - See TEsound.play. If omitted, the tag will no longer affect the volume of matching sounds.

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. tag (string) - See TEsound.tagVolume pitch (optional number) - See TEsound.play. If omitted, the tag will no longer affect the pitch of matching sounds.

Internal Functions

TEsound.findTag(tag) Returns a list of all sound channels with a given tag. tag (string) - The channels of all sounds with this tag will be returned.

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. tag (string or table) - Chooses the tag to check the volume of.

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. tag (string or table) - See TEsound.findVolume

Contact: Ensayia - Ensayia@gmail.com Taehl - SelfMadeSpirit@gmail.com Also feel free to post in this module's forum thread: http://love2d.org/forums/viewtopic.php?f=5&t=2334