readme.md

Ripple

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
• Usage
  • Creating a sound
  • Playing sounds
  • Pausing, resuming, and stopping sounds
  • Tags
  • Effects
• API
  • ripple
    • Functions
      • local sound = ripple.newSound(source, options)
      • local tag = ripple.newTag(options)
  • Taggable
    • Properties
      • volume (number)
    • Functions
      • Taggable:tag(...)
      • Taggable:untag(...)
      • Taggable:setEffect(name, effectSettings)
      • Taggable:removeEffect(name)
      • local effect = Taggable:getEffect(name)
  • Sound
    • Properties
      • loop (boolean)
    • Functions
      • local instance = Sound:play(options)
      • Sound:pause(fadeDuration)
      • Sound:resume(fadeDuration)
      • Sound:stop(fadeDuration)
  • Instance
    • Properties
      • loop (boolean)
      • pitch (number)
    • Functions
      • local stopped = Instance:isStopped()
      • Instance:pause(fadeDuration)
      • Instance:resume(fadeDuration)
      • Instance:stop(fadeDuration)
  • Tag
    • Functions
      • Tag:pause(fadeDuration)
      • Tag:resume(fadeDuration)
      • Tag:stop(fadeDuration)
  • EffectSettings
• Contributing

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 filter
• table - uses an effect with the specified filter settings
• false - 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 sound
• options (table) (optional) - options to apply to the sound. The options table can have the following values:
  • volume (number) (optional, defaults to 1) - the volume of the sound, from 0 to 1
  • tags (table) (optional) - a list of tags to apply to the sound
  • effects (table) (optional) - the effects to apply to the instance. Each key should be the name of the effect, and each value should be an EffectSettings value
  • loop (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 to 1) - the volume of the tag, from 0 to 1
  • tags (table) (optional) - a list of tags to apply to the tag
  • effects (table) (optional) - the effects to apply to the instance. Each key should be the name of the effect, and each value should be an EffectSettings 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 disable
• effectSettings (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 to 1) - the volume of the instance, from 0 to 1
  • tags (table) (optional) - a list of tags to apply to the instance
  • effects (table) (optional) - the effects to apply to the instance. Each key should be the name of the effect, and each value should be an EffectSettings value
  • loop (boolean) (optional) - whether the instance of the sound should be repeated until stopped
  • pitch (number) (optional, defaults to 1) - 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 down
  • seek (number) (optional) - the position to start the sound at in seconds
  • fadeDuration (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 filter
• false - explicitly disables an effect, even if normally an object would inherit an effect from a parent, like a tag or a sound
• table - 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.