Module sfxr

A port of the sfxr sound effect synthesizer to Lua

Functions

newSound (...) Construct and return a new Sound instance.

Tables

WAVEFORM Waveform constants
SAMPLERATE Sampling rate constants (use the number values directly, these are just for lookup)
BITDEPTH Bit depth constants (use the number values directly, these are just for lookup)
ENDIANNESS Endianness constants

Fields

VERSION The module version (SemVer)

Class Sound

sfxr.Sound:__init () Initialize the Sound instance.
self.volume The sound volume and gain all samples are multiplied with
self.envelope The ASD envelope that controls the sound amplitude (volume) over time
self.frequency The base and minimum frequencies of the tone generator and their slides
self.vibrato A vibrato-like amplitude modulation effect.
self.change Changes the frequency mid-sound to create the characteristic "coin"-effect
self.duty The duty of the square waveform
self.phaser A simple phaser effect
self.lowpass A lowpass filter effect
self.highpass A highpass filter effect
self.volume.master Master volume (default 0.5)
self.volume.sound Additional gain (default 0.5)
sfxr.Sound:resetParameters () Set all parameters to their default values.
self.repeatspeed Repeat speed: Times to repeat the frequency slide over the course of the envelope (default 0.0, min 0.0, max 1.0)
self.waveform The base waveform (default SQUARE)
self.envelope.attack Attack time: Time the sound takes to reach its peak amplitude (default 0.0, min 0.0, max 1.0)
self.envelope.sustain Sustain time: Time the sound stays on its peak amplitude (default 0.0, min 0.0, max 1.0)
self.envelope.punch Sustain punch: Amount by which the sound peak amplitude is increased at the start of the sustain time (default 0.0, min 0.0, max 1.0)
self.envelope.decay Decay time: Time the sound takes to decay after its sustain time (default 0.0, min 0.0, max 1.0)
self.frequency.start Start frequency: Base tone of the sound, before sliding (default 0.0, min 0.0, max 1.0)
self.frequency.min Min frequency: Tone below which the sound will get cut off (default 0.0, min 0.0, max 1.0)
self.frequency.slide Slide: Amount by which the frequency is increased or decreased over time (default 0.0, min -1.0, max 1.0)
self.frequency.dslide Delta slide: Amount by which the slide is increased or decreased over time (default 0.0, min -1.0, max 1.0)
self.vibrato.depth Vibrato depth: Amount of amplitude modulation (default 0.0, min 0.0, max 1.0)
self.vibrato.speed Vibrato speed: Oscillation speed of the vibrato (default 0.0, min 0.0, max 1.0)
self.vibrato.delay Vibrato delay: Unused and unimplemented (default 0.0, min 0.0, max 1.0)
self.change.amount Change amount: Amount by which the frequency is changed mid-sound (default 0.0, min -1.0, max 1.0)
self.change.speed Change speed: Time before the frequency change happens (default 0.0, min 0.0, max 1.0)
self.duty.ratio Square duty: Width of the square wave pulse cycle (doesn't affect other wave forms) (default 0.0, min 0.0, max 1.0)
self.duty.sweep Duty sweep: Amount by which the square duty is increased or decreased over time (default 0.0, min -1.0, max 1.0)
self.phaser.offset Phaser offset: Amount by which the phaser signal is offset from the sound (default 0.0, min -1.0, max 1.0)
self.phaser.sweep Phaser sweep: Amount by which the phaser offset is increased or decreased over time (default 0.0, min -1.0, max 1.0)
self.lowpass.cutoff Lowpass filter cutoff: Lower bound for frequencies allowed to pass through this filter (default 0.0, min 0.0, max 1.0)
self.lowpass.sweep Lowpass filter cutoff sweep: Amount by which the LP filter cutoff is increased or decreased over time (default 0.0, min -1.0, max 1.0)
self.lowpass.resonance Lowpass filter resonance: Amount by which certain resonant frequencies near the cutoff are increased (default 0.0, min 0.0, max 1.0)
self.highpass.cutoff Highpass filter cutoff: Upper bound for frequencies allowed to pass through this filter (default 0.0, min 0.0, max 1.0)
self.highpass.sweep Highpass filter cutoff sweep: Amount by which the HP filter cutoff is increased or decreased over time (default 0.0, min -1.0, max 1.0)
sfxr.Sound:sanitizeParameters () Clamp all parameters within their sane ranges.
sfxr.Sound:generate ([rate=44100[, depth=0]]) Generate the sound and yield the sample data.
sfxr.Sound:getEnvelopeLimit ([rate=44100]) Get the maximum sample limit allowed by the current envelope.
sfxr.Sound:generateTable ([rate=44100[, depth=0[, tab]]]) Generate the sound into a table.
sfxr.Sound:generateString ([rate=44100[, depth=16[, endianness=0]]]) Generate the sound to a binary string.
sfxr.Sound:generateSoundData ([rate=44100[, depth=0[, sounddata]]]) Synthesize the sound to a LÖVE SoundData instance.
sfxr.Sound:randomize ([seed]) Randomize all sound parameters
sfxr.Sound:mutate ([by=1][, seed], whether) Mutate all sound parameters
sfxr.Sound:randomPickup ([seed]) Randomize all sound parameters to generate an item pick up sound
sfxr.Sound:randomLaser ([seed]) Randomize all sound parameters to generate a laser sound
sfxr.Sound:randomExplosion ([seed]) Randomize all sound parameters to generate an explosion sound
sfxr.Sound:randomPowerup ([seed]) Randomize all sound parameters to generate a power up sound
sfxr.Sound:randomHit ([seed]) Randomize all sound parameters to generate a hit sound
sfxr.Sound:randomJump ([seed]) Randomize all sound parameters to generate a jump sound
sfxr.Sound:randomBlip ([seed]) Randomize all sound parameters to generate a blip sound
sfxr.Sound:exportWAV (f[, rate=44100[, depth=0]]) Generate and export the audio data to a PCM WAVE file.
sfxr.Sound:save (f[, minify=true]) Save the sound parameters to a file as a Lua table
sfxr.Sound:load (f) Load the sound parameters from a file containing a Lua table
sfxr.Sound:saveBinary (f) Save the sound parameters to a file in the sfxr binary format (version 102)
sfxr.Sound:loadBinary (f) Load the sound parameters from a file in the sfxr binary format (version 100-102)


Functions

newSound (...)
Construct and return a new Sound instance.

Parameters:

  • ...

Returns:

    Sound a Sound instance

Tables

WAVEFORM
Waveform constants

Fields:

SAMPLERATE
Sampling rate constants (use the number values directly, these are just for lookup)

Fields:

  • 22050 22.05 kHz (= 22050)
  • 44100 44.1 kHz (= 44100)
BITDEPTH
Bit depth constants (use the number values directly, these are just for lookup)

Fields:

  • 0 floating point bit depth, -1 to 1 (= 0)
  • 8 unsigned 8 bit, 0x00 to 0xFF (= 8)
  • 16 unsigned 16 bit, 0x0000 to 0xFFFF (= 16)
ENDIANNESS
Endianness constants

Fields:

  • LITTLE little endian (= 0)
  • BIG big endian (= 1)

Fields

VERSION
The module version (SemVer)

Class Sound

The main Sound class.
sfxr.Sound:__init ()
Initialize the Sound instance. Called by the constructor.
self.volume
The sound volume and gain all samples are multiplied with
self.envelope
The ASD envelope that controls the sound amplitude (volume) over time
self.frequency
The base and minimum frequencies of the tone generator and their slides
self.vibrato
A vibrato-like amplitude modulation effect.
self.change
Changes the frequency mid-sound to create the characteristic "coin"-effect
self.duty
The duty of the square waveform
self.phaser
A simple phaser effect
self.lowpass
A lowpass filter effect
self.highpass
A highpass filter effect
self.volume.master
Master volume (default 0.5)
self.volume.sound
Additional gain (default 0.5)
sfxr.Sound:resetParameters ()
Set all parameters to their default values. Called by the initializer.
self.repeatspeed
Repeat speed: Times to repeat the frequency slide over the course of the envelope (default 0.0, min 0.0, max 1.0)
self.waveform
The base waveform (default SQUARE)
self.envelope.attack
Attack time: Time the sound takes to reach its peak amplitude (default 0.0, min 0.0, max 1.0)
self.envelope.sustain
Sustain time: Time the sound stays on its peak amplitude (default 0.0, min 0.0, max 1.0)
self.envelope.punch
Sustain punch: Amount by which the sound peak amplitude is increased at the start of the sustain time (default 0.0, min 0.0, max 1.0)
self.envelope.decay
Decay time: Time the sound takes to decay after its sustain time (default 0.0, min 0.0, max 1.0)
self.frequency.start
Start frequency: Base tone of the sound, before sliding (default 0.0, min 0.0, max 1.0)
self.frequency.min
Min frequency: Tone below which the sound will get cut off (default 0.0, min 0.0, max 1.0)
self.frequency.slide
Slide: Amount by which the frequency is increased or decreased over time (default 0.0, min -1.0, max 1.0)
self.frequency.dslide
Delta slide: Amount by which the slide is increased or decreased over time (default 0.0, min -1.0, max 1.0)
self.vibrato.depth
Vibrato depth: Amount of amplitude modulation (default 0.0, min 0.0, max 1.0)
self.vibrato.speed
Vibrato speed: Oscillation speed of the vibrato (default 0.0, min 0.0, max 1.0)
self.vibrato.delay
Vibrato delay: Unused and unimplemented (default 0.0, min 0.0, max 1.0)
self.change.amount
Change amount: Amount by which the frequency is changed mid-sound (default 0.0, min -1.0, max 1.0)
self.change.speed
Change speed: Time before the frequency change happens (default 0.0, min 0.0, max 1.0)
self.duty.ratio
Square duty: Width of the square wave pulse cycle (doesn't affect other wave forms) (default 0.0, min 0.0, max 1.0)
self.duty.sweep
Duty sweep: Amount by which the square duty is increased or decreased over time (default 0.0, min -1.0, max 1.0)
self.phaser.offset
Phaser offset: Amount by which the phaser signal is offset from the sound (default 0.0, min -1.0, max 1.0)
self.phaser.sweep
Phaser sweep: Amount by which the phaser offset is increased or decreased over time (default 0.0, min -1.0, max 1.0)
self.lowpass.cutoff
Lowpass filter cutoff: Lower bound for frequencies allowed to pass through this filter (default 0.0, min 0.0, max 1.0)
self.lowpass.sweep
Lowpass filter cutoff sweep: Amount by which the LP filter cutoff is increased or decreased over time (default 0.0, min -1.0, max 1.0)
self.lowpass.resonance
Lowpass filter resonance: Amount by which certain resonant frequencies near the cutoff are increased (default 0.0, min 0.0, max 1.0)
self.highpass.cutoff
Highpass filter cutoff: Upper bound for frequencies allowed to pass through this filter (default 0.0, min 0.0, max 1.0)
self.highpass.sweep
Highpass filter cutoff sweep: Amount by which the HP filter cutoff is increased or decreased over time (default 0.0, min -1.0, max 1.0)
sfxr.Sound:sanitizeParameters ()
Clamp all parameters within their sane ranges.
sfxr.Sound:generate ([rate=44100[, depth=0]])
Generate the sound and yield the sample data.

Parameters:

  • rate SAMPLERATE the sampling rate (default 44100)
  • depth BITDEPTH the bit depth (default 0)

Returns:

    function() a generator that yields the next sample when called

Raises:

"invalid sampling rate: x", "invalid bit depth: x"

Usage:

     for s in sound:generate(44100, 0) do
   -- do something with s
 end
sfxr.Sound:getEnvelopeLimit ([rate=44100])
Get the maximum sample limit allowed by the current envelope. Does not take any other limits into account, so the returned count might be higher than samples actually generated. Still useful though.

Parameters:

  • rate SAMPLERATE the sampling rate (default 44100)

Raises:

"invalid sampling rate: x", "invalid bit depth: x"
sfxr.Sound:generateTable ([rate=44100[, depth=0[, tab]]])
Generate the sound into a table.

Parameters:

  • rate SAMPLERATE the sampling rate (default 44100)
  • depth BITDEPTH the bit depth (default 0)
  • tab {} the table to synthesize into (optional)

Returns:

  1. {number,...} the table filled with sample data
  2. int the number of written samples (== #tab)

Raises:

"invalid sampling rate: x", "invalid bit depth: x"
sfxr.Sound:generateString ([rate=44100[, depth=16[, endianness=0]]])
Generate the sound to a binary string.

Parameters:

  • rate SAMPLERATE the sampling rate (default 44100)
  • depth BITDEPTH the bit depth (may not be 0) (default 16)
  • endianness ENDIANNESS the endianness (ignored when depth == 8) (default 0)

Returns:

  1. string a binary string of sample data
  2. int the number of written samples

Raises:

"invalid sampling rate: x", "invalid bit depth: x", "invalid endianness: x"
sfxr.Sound:generateSoundData ([rate=44100[, depth=0[, sounddata]]])
Synthesize the sound to a LÖVE SoundData instance.

Parameters:

  • rate SAMPLERATE the sampling rate (default 44100)
  • depth BITDEPTH the bit depth (default 0)
  • sounddata love.sound.SoundData a SoundData instance (will be created if not passed) (optional)

Returns:

  1. love.sound.SoundData a SoundData instance
  2. int the number of written samples

Raises:

"invalid sampling rate: x", "invalid bit depth: x"
sfxr.Sound:randomize ([seed])
Randomize all sound parameters

Parameters:

  • seed number a random seed (optional)
sfxr.Sound:mutate ([by=1][, seed], whether)
Mutate all sound parameters

Parameters:

  • by amount how much to mutate the parameters (default 1)
  • seed number a random seed (optional)
  • whether bool to change the frequency parameters
sfxr.Sound:randomPickup ([seed])
Randomize all sound parameters to generate an item pick up sound

Parameters:

  • seed number a random seed (optional)
sfxr.Sound:randomLaser ([seed])
Randomize all sound parameters to generate a laser sound

Parameters:

  • seed number a random seed (optional)
sfxr.Sound:randomExplosion ([seed])
Randomize all sound parameters to generate an explosion sound

Parameters:

  • seed number a random seed (optional)
sfxr.Sound:randomPowerup ([seed])
Randomize all sound parameters to generate a power up sound

Parameters:

  • seed number a random seed (optional)
sfxr.Sound:randomHit ([seed])
Randomize all sound parameters to generate a hit sound

Parameters:

  • seed number a random seed (optional)
sfxr.Sound:randomJump ([seed])
Randomize all sound parameters to generate a jump sound

Parameters:

  • seed number a random seed (optional)
sfxr.Sound:randomBlip ([seed])
Randomize all sound parameters to generate a blip sound

Parameters:

  • seed number a random seed (optional)
sfxr.Sound:exportWAV (f[, rate=44100[, depth=0]])
Generate and export the audio data to a PCM WAVE file.

Parameters:

  • f string, file or love.filesystem.File a path or file in wb-mode (passed files will not be closed)
  • rate SAMPLERATE the sampling rate (default 44100)
  • depth BITDEPTH the bit depth (default 0)

Raises:

"invalid sampling rate: x", "invalid bit depth: x"
sfxr.Sound:save (f[, minify=true])
Save the sound parameters to a file as a Lua table

Parameters:

  • f string, file or love.filesystem.File a path or file in w-mode (passed files will not be closed)
  • minify bool whether to minify the output or not (default true)
sfxr.Sound:load (f)
Load the sound parameters from a file containing a Lua table

Parameters:

  • f string, file or love.filesystem.File a path or file in r-mode (passed files will not be closed)

Raises:

"incompatible version: x.x.x"
sfxr.Sound:saveBinary (f)
Save the sound parameters to a file in the sfxr binary format (version 102)

Parameters:

  • f string, file or love.filesystem.File a path or file in wb-mode (passed files will not be closed)
sfxr.Sound:loadBinary (f)
Load the sound parameters from a file in the sfxr binary format (version 100-102)

Parameters:

  • f string, file or love.filesystem.File a path or file in rb-mode (passed files will not be closed)

Raises:

"incompatible version: x", "unexpected file length"
generated by LDoc 1.4.3 Last updated 2016-03-05 20:26:21