Awesome
Ripple <!-- omit in toc -->
Ripple is an audio library for LÖVE that simplifies various aspects of audio handling, including tagging and playing multiple instances of a sound.
Installation
To use Ripple, place ripple.lua in your project, and then add this code to your main.lua:
ripple = require 'ripple' -- if your ripple.lua is in the root directory
ripple = require 'path.to.ripple' -- if it's in subfolders
Usage
Creating a sound
local source = love.audio.newSource('sound.wav', 'static')
local sound = ripple.newSound(source)
This creates a new sound with the default settings. You can also pass an options table as the second argument:
local sound = ripple.newSound(source, {
volume = .5,
loop = true,
})
You can also change a sound's options after the fact by modifying the properties directly:
sound.volume = .75
sound.loop = false
See the API for the full list of options.
Playing sounds
local instance = sound:play()
Playing a sound returns an instance, which represents an occurrence of a sound. For example, if you play a bird sound 4 times in quick succession, you will hear 4 birds simultaneously, and each one would be represented by a separate instance.
Like with ripple.newSound
, you can pass an options table to sound.play
:
local instance = sound:play {
volume = .5,
pitch = 2,
}
Unlike ripple.newSound
, this options table will only affect this specific instance of the sound.
Pausing, resuming, and stopping sounds
-- controls all of the currently playing instances of a sound
sound:pause()
sound:resume()
sound:stop()
-- controls a specific instance
instance:pause()
instance:resume()
instance:stop()
You can pause, resume, and stop sounds and instances using the corresponding functions. All of these functions can optionally take a fadeDuration
parameter, which will cause the sound or instance to fade in or out over the specified duration of time (in seconds).
sound:pause(.3)
sound:resume(.5)
Note that for these functions to work correctly, you have to call sound.update
somewhere in your love.update
callback:
sound:update(dt)
Tags
Tags act as categories for sounds and instances. You can create them using ripple.newTag
:
local music = ripple.newTag()
local sfx = ripple.newTag()
And you can apply them to sounds and instances by using tag
and untag
:
backgroundMusic1:tag(music)
birdCall:tag(sfx)
Tags themselves can be tagged, leading to nested tags:
local ambience = ripple.newTag()
ambience:tag(sfx)
As a shortcut, you can set these tags in the options table when you create a sound or instance:
local birdCall = ripple.newSound(love.audio.newSource 'bird.wav', 'static', {
tags = {sfx},
})
local farAwayBirdCall = birdCall:play {tags = {ambience}}
The most common use for tags is to set the relative volume of a large group of sounds. For example, we could immediately make every sound or instance tagged with "ambience" quieter:
ambience.volume = .25
You can also pause, resume, or stop all sounds tagged with a certain tag:
ambience:pause(1)
ambience:resume(2)
ambience:stop()
Effects
You can apply LÖVE effects to a sound, instance, or tag.
love.audio.setEffect('ambient', {type = 'reverb'})
tag.ambience:setEffect('ambient', true)
An effect can be set to:
true
- uses an effect without any filtertable
- uses an effect with the specified filter settingsfalse
- explicitly disables the filter, even if it would normally be inherited from a parent sound or tag
In this example, most bird calls would have reverb from the "ambient" effect, but this specific one would not:
birdCall:play {
effects = {
ambient = false,
}
}
See here for information on how to define audio effects.
API
ripple
This is the main module that lets you create sounds and tags.
Functions
local sound = ripple.newSound(source, options)
Creates a new sound.
Parameters:
source
(Source
) - the source to use for the soundoptions
(table
) (optional) - options to apply to the sound. The options table can have the following values:volume
(number
) (optional, defaults to1
) - the volume of the sound, from 0 to 1tags
(table
) (optional) - a list of tags to apply to the soundeffects
(table
) (optional) - the effects to apply to the instance. Each key should be the name of the effect, and each value should be anEffectSettings
valueloop
(boolean
) (optional) - whether the sound should be repeated until stopped
Returns:
sound
(Sound
) - the newly created sound
local tag = ripple.newTag(options)
Creates a new tag.
Parameters:
options
(table
) (optional) - options to apply to the tag. The options table can have the following values:volume
(number
) (optional, defaults to1
) - the volume of the tag, from 0 to 1tags
(table
) (optional) - a list of tags to apply to the tageffects
(table
) (optional) - the effects to apply to the instance. Each key should be the name of the effect, and each value should be anEffectSettings
value
Returns:
tag
(Tag
) - the newly created tag
Taggable
This class is not something you create directly, but it does contain functions you can use on any taggable object: sounds, instances, and tags.
Properties
volume (number)
The volume of the taggable object from 0 to 1.
Functions
Taggable:tag(...)
Applies one or more tags to a taggable object.
Parameters:
...
(Tag
) - the tags to apply
Taggable:untag(...)
Removes one or more tags from a taggable object.
Parameters:
...
(Tag
) - the tags to remove
Taggable:setEffect(name, effectSettings)
Enables or disables an effect on a taggable object.
Parameters:
name
(string
) - the effect to enable or disableeffectSettings
(EffectSettings
) - the settings to use for the effect
Taggable:removeEffect(name)
Unsets an effect on a taggable object.
Parameters:
name
(string
) - the name of the effect to remove
local effect = Taggable:getEffect(name)
Returns the EffectSettings for an effect on a taggable object.
Sound
Sounds represent a piece of audio that you can play back multiple times simultaneously with different pitches and volumes. Inherits from Taggable.
Properties
loop (boolean)
Whether the sound should be repeated until stopped.
Functions
local instance = Sound:play(options)
Plays a sound.
Parameters:
options
(table
) (optional) - options to apply to this instance of the sound. The options table can have the following values:volume
(number
) (optional, defaults to1
) - the volume of the instance, from 0 to 1tags
(table
) (optional) - a list of tags to apply to the instanceeffects
(table
) (optional) - the effects to apply to the instance. Each key should be the name of the effect, and each value should be anEffectSettings
valueloop
(boolean
) (optional) - whether the instance of the sound should be repeated until stoppedpitch
(number
) (optional, defaults to1
) - the pitch to play the sound at - 2 would be twice as fast and one octave up, .5 would be half speed and one octave downseek
(number
) (optional) - the position to start the sound at in secondsfadeDuration
(number
) (optional) - the length of time to use to fade in the sound from silence
Returns:
instance
(Instance
) - the new instance of the sound
Sound:pause(fadeDuration)
Pauses all instances of this sound.
Parameters:
fadeDuration
(number
) (optional) - the length of time to use to fade the sound to silence before pausing it
Sound:resume(fadeDuration)
Resumes all of the paused instances of this sound.
Parameters:
fadeDuration
(number
) (optional) - the length of time to use to fade the sound from silence
Sound:stop(fadeDuration)
Stops all instances of this sound.
Parameters:
fadeDuration
(number
) (optional) - the length of time to use to fade the sound to silence before stopping it
Instance
An instance is a single occurrence of a sound. Inherits from Taggable.
Properties
loop (boolean)
Whether this instance of a sound should be repeated until stopped.
pitch (number)
The pitch of the instance.
Functions
local stopped = Instance:isStopped()
Returns if the instance is stopped, either because it reached the end of the sound or it was manually stopped. Note that stopped instances may be reused later.
Instance:pause(fadeDuration)
Pauses the instance.
Parameters:
fadeDuration
(number
) (optional) - the length of time to use to fade the sound to silence before pausing it
Instance:resume(fadeDuration)
Resumes a paused instance.
Parameters:
fadeDuration
(number
) (optional) - the length of time to use to fade the sound from silence
Instance:stop(fadeDuration)
Stops the instance.
Parameters:
fadeDuration
(number
) (optional) - the length of time to use to fade the sound to silence before stopping it
Tag
A tag represents a category of sounds. You can apply it to sounds to control the volume and effect settings of multiple sounds at once. Inherits from Taggable.
Functions
Tag:pause(fadeDuration)
Pauses all of the sounds tagged with this tag.
Parameters:
fadeDuration
(number
) (optional) - the length of time to use to fade the sound to silence before pausing it
Tag:resume(fadeDuration)
Resumes all of the paused sounds tagged with this tag.
Parameters:
fadeDuration
(number
) (optional) - the length of time to use to fade the sound from silence
Tag:stop(fadeDuration)
Stops all of the sounds tagged with this tag.
Parameters:
fadeDuration
(number
) (optional) - the length of time to use to fade the sound to silence before stopping it
EffectSettings
Effect settings can either be:
true
- enables an effect with no filterfalse
- explicitly disables an effect, even if normally an object would inherit an effect from a parent, like a tag or a soundtable
- enables an effect with a filter with the specified settings
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 ripple base directory.