jbs
jbs is an audio library for LÖVE that simplifies various aspects of audio handling, including tagging and playing multiple instances of a sound.
It is based on the ripple
library by tesselode. As of this writing (2019-08-22 Thursday), the code is almost entirely theirs. I'm renaming to differentiate it as I add additional functionality; in case it ends up being useful to someone else in the future, I want to avoid confusion. Still, all credit should go to tesselode for the initial creation of the library.
Installation
To use jbs, place jbs.lua in your project, and then add this code to your main.lua:
jbs = require 'jbs' -- if your jbs.lua is in the root directory
jbs = require 'path.to.jbs' -- if it's in subfolders
Usage
Loading sounds
local sound = jbs.newSound(source, options)
Use jbs.newSound
to load a sound.
source
- the Source or SoundData to use for the sound. Sources can be created usinglove.audio.newSource
, and SoundData can be created usinglove.sound.newSoundData
.options
(optional) - a table of additional options to apply to the sound. The table can have the following keys:volume
(optional) - the volume of the sound, from 0 to 1. Defaults to 1.tags
(optional) - a list of tags to apply to the sound (see below for more information on tags).
Playing sounds
sound:play(options)
Plays a sound. options
is a table with the following keys, all of which are optional:
volume
- sets the volume of this particular occurrence of the sound relative to the sound's main volume, from 0 to 1. Defaults to 1.pitch
- the pitch of this particular occurrence of the sound, in terms of a multiple of the default playback speed. Defaults to 1.
Tagging sounds
To create a tag, use jbs.newTag
:
local tag = jbs.newTag()
You can then add tags to sounds or remove them from sounds using sound.tag
and sound.untag
:
sound:tag(tag1)
sound:untag(tag2)
If you don't want to add or remove tags individually, you can also specify an entire list of tags using sound.setTags
:
sound:setTags {tag1, tag2, ...}
You can get a list of the tags a sound is currently tagged with using sound.getTags
:
local tags = sound:getTags()
You can pause, resume, or stop all of the currently playing sounds with a tag using tag:pause()
, tag:resume()
, and tag:stop()
.
Adjusting volume levels
You can adjust the volume of individual sounds by setting the volume
property of a sound. You can also adjust the volume of a tag by setting its volume
property. The overall volume level of a sound is its own volume multiplied by the volume of each of its tags. This allows you to easily set the volume of categories of sounds. For example, you could have separate "music" and "sfx" tags, and you can adjust the volume of all music tracks and sound effects at once by setting the volume of their respective tags.
Looping sounds
You can set whether a sound should loop or not using sound.setLooping
:
sound:setLooping(true) -- enables looping
sound:setLooping(false) -- disables looping
Using audio effects
You can set a sound to use an effect defined by love.audio.setEffect
using sound.setEffect
:
sound:setEffect(name, filtersettings)
name
- the name of the effect to use.filtersettings
(optional) - filter settings to apply to the sound (seeSource:setEffect
).
You can disable an effect by passing false
as the second argument.
You can also set effects on tags using tag.setEffect
:
tag:setEffect(name, filtersettings)
Tag effects will be applied to every sound with that tag.
Contributing
This library is still in early development, so feel free to report bugs, make pull requests, or just make suggestions about the code or design of the library. To run the test project, run lovec .
in the jbs base directory.