TEsound - simple, easy sound/music manager
Posted: Sun Jan 09, 2011 2:44 am
Tired of not being able to overlap sounds in Love? Or maybe you just can't figure out the love.audio module? Ensayia and I wrote this module to make sound and music easy.
Mini-tutorial!
Q) What do I have to do to use it?
1) Put TEsound.lua in your game's folder.
2) At the top of main.lua, add require"TEsound".
3) In love.update(), add TEsound.cleanup(). That's it! TEsound will automatically manage sound channels (sounds can overlap) and memory.
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:
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.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"
Q) Anything else I should know?
A) Each function has several more optional parameters - I've just covered the basics here. Check out the documentation for a full list of functions and their parameters.
Ready for sound and music to finally be easy to use? Download the module, and check out the wiki page for more documentation.
EDIT) Updated it slightly - I streamlined it by merging playRandom into play, and playRandomLooping into playLooping (just pass them a list instead of a single filepath). Updated documentation accordingly.
EDIT2) Updated it slightly again - make pitch work identically to volume, and added special "all" tag functionality. Updated documentation accordingly.
Mini-tutorial!
Q) What do I have to do to use it?
1) Put TEsound.lua in your game's folder.
2) At the top of main.lua, add require"TEsound".
3) In love.update(), add TEsound.cleanup(). That's it! TEsound will automatically manage sound channels (sounds can overlap) and memory.
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:
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.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"
Q) Anything else I should know?
A) Each function has several more optional parameters - I've just covered the basics here. Check out the documentation for a full list of functions and their parameters.
Ready for sound and music to finally be easy to use? Download the module, and check out the wiki page for more documentation.
EDIT) Updated it slightly - I streamlined it by merging playRandom into play, and playRandomLooping into playLooping (just pass them a list instead of a single filepath). Updated documentation accordingly.
EDIT2) Updated it slightly again - make pitch work identically to volume, and added special "all" tag functionality. Updated documentation accordingly.
