Module sfxr
A port of the sfxr sound effect synthesizer to Lua
Functions
| newSound (...) | The constructor for the Sound class. |
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 (...)
-
The constructor for the Sound class.
Parameters:
- ...
Returns:
-
Sound
a Sound instance
Tables
- WAVEFORM
-
Waveform constants
Fields:
- SQUARE
square wave (
= 0) - SAW
saw wave (
= 1) - SINE
sine wave (
= 2) - NOISE
white noise (
= 3)
- SQUARE
square wave (
- 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)
- 22050
22.05 kHz (
- 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)
- 0
floating point bit depth, -1 to 1 (
- ENDIANNESS
-
Endianness constants
Fields:
- LITTLE
little endian (
= 0) - BIG
big endian (
= 1)
- LITTLE
little endian (
Fields
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:
- {number,...} the table filled with sample data
- 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:
- string a binary string of sample data
- 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:
- love.sound.SoundData a SoundData instance
- 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" - f
string, file or love.filesystem.File
a path or file in
- 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)
- f
string, file or love.filesystem.File
a path or file in
- 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" - f
string, file or love.filesystem.File
a path or file in
- 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)
- f
string, file or love.filesystem.File
a path or file in
- 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" - f
string, file or love.filesystem.File
a path or file in