Files and editing
Create, load, save and edit audio buffers.
On this page
Create, load, save and edit audio buffers.
audioSilence
Creates an audio buffer filled with silence. Useful as a blank canvas to mix sounds into.
audioSilence( seconds, channels=2, sampleRate=44100 )
| Argument | Type | Default | |
|---|---|---|---|
seconds | double | required | The length in seconds, rounded to the nearest frame. |
channels | integer | 2 | The number of channels, 1 for mono, 2 for stereo. Defaults to 2. |
sampleRate | integer | 44100 | The sample rate in Hz. Defaults to 44100. |
Returns The new audio buffer.
audioLoad
Reads an audio file fully into memory. WAV (PCM at 8, 16, 24 and 32 bits, and IEEE float) and MP3 are supported, and the format is found from the content of the file, not its name. MP3 needs the optional codec jars that ship with the module.
audioLoad( path )
| Argument | Type | Default | |
|---|---|---|---|
path | string | required | The path of the audio file. Relative paths and mappings are resolved like other file functions. |
Returns The audio buffer.
audioSave
Writes an audio buffer to a file, replacing any existing file. Missing parent folders are created. The format follows the file extension: .wav (or none) writes WAV and .mp3 writes a constant bitrate MP3, which needs the optional codec jars that ship with the module. Any other extension is an error.
audioSave( audio, path, bitDepth=16, bitrate=0 )
| Argument | Type | Default | |
|---|---|---|---|
audio | any | required | The audio buffer to save. |
path | string | required | The destination path. Relative paths and mappings are resolved like other file functions. |
bitDepth | integer | 16 | For WAV: 16 or 24 for integer PCM, or 32 for 32 bit float. Defaults to 16. Samples beyond -1 to 1 are clipped for 16 and 24. Ignored for MP3. |
bitrate | integer | 0 | For MP3: the constant bitrate in kbps. At 32, 44.1 and 48 kHz use 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256 or 320. At lower sample rates use 8 to 160 (8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160). Defaults to 0, which means 192, or 128 below 32 kHz where 192 does not exist. Ignored for WAV. |
Returns The absolute path of the file that was written.
audioInfo
Describes some audio. A file is read fully into memory to measure its levels.
audioInfo( source )
| Argument | Type | Default | |
|---|---|---|---|
source | any | required | An audio buffer, or the path of an audio file. |
Returns A struct with channels, sampleRate, frames, seconds, peak (0 to 1 for undistorted audio) and rms.
audioWaveform
Summarize audio as a list of peak levels for drawing a waveform. The audio is split into equal slices and each value is the loudest absolute sample in its slice across all channels.
audioWaveform( audio, points=800 )
| Argument | Type | Default | |
|---|---|---|---|
audio | any | required | The audio buffer. |
points | integer | 800 | How many values to return, from 1 to 100000. Defaults to 800. |
Returns An array of numbers from 0 (silence) upwards, 1 is full scale.
audioGain
Change the volume of an audio buffer. The input buffer is left untouched.
audioGain( audio, db )
| Argument | Type | Default | |
|---|---|---|---|
audio | any | required | The audio buffer. |
db | double | required | The gain in decibels. Negative values make it quieter, 6 roughly doubles the amplitude. |
Returns A new audio buffer.
audioPan
Position an audio buffer in the stereo field. The input buffer is left untouched.
audioPan( audio, pan )
| Argument | Type | Default | |
|---|---|---|---|
audio | any | required | A mono or stereo audio buffer. Mono becomes stereo, stereo is treated as a balance control. |
pan | double | required | From -1 for hard left through 0 for center to 1 for hard right, using a constant power law. |
Returns A new audio buffer.
audioFade
Fade an audio buffer in and out. The input buffer is left untouched.
audioFade( audio, fadeIn=0, fadeOut=0, curve="linear" )
| Argument | Type | Default | |
|---|---|---|---|
audio | any | required | The audio buffer. |
fadeIn | double | 0 | Length of the fade in, in seconds. Defaults to 0. |
fadeOut | double | 0 | Length of the fade out, in seconds. Defaults to 0. |
curve | string | "linear" | The fade shape: linear (default) or smooth, a raised cosine. |
Returns A new audio buffer.
audioNormalize
Scale an audio buffer so its peak hits a target level. The input buffer is left untouched.
audioNormalize( audio, targetDb=-1 )
| Argument | Type | Default | |
|---|---|---|---|
audio | any | required | The audio buffer. Silence is returned unchanged. |
targetDb | double | -1 | The target peak in decibels relative to full scale. Defaults to -1. |
Returns A new audio buffer.
audioTrim
Cut a section out of an audio buffer. The input buffer is left untouched.
audioTrim( audio, start=0, end )
| Argument | Type | Default | |
|---|---|---|---|
audio | any | required | The audio buffer. |
start | double | 0 | Where the section starts, in seconds. Defaults to 0. |
end | double | optional | Where the section ends, in seconds. Defaults to the end of the audio. Values past the end are clamped. |
Returns A new audio buffer.
audioConcat
Join audio buffers end to end. The input buffer is left untouched.
audioConcat( audios )
| Argument | Type | Default | |
|---|---|---|---|
audios | array | required | An array of audio buffers. They must share channel count and sample rate. |
Returns A new audio buffer.
audioReverse
Reverse an audio buffer. The input buffer is left untouched.
audioReverse( audio )
| Argument | Type | Default | |
|---|---|---|---|
audio | any | required | The audio buffer. |
Returns A new audio buffer.
audioMix
Add audio buffers together so they play at the same time
audioMix( audios )
| Argument | Type | Default | |
|---|---|---|---|
audios | array | required | An array of audio buffers. They must share channel count and sample rate. All start at time 0, the result is as long as the longest. |
Returns A new audio buffer. Scale it with audioGain() or audioNormalize() if the sum is too loud.
audioChannels
Convert an audio buffer between mono and stereo. The input buffer is left untouched.
audioChannels( audio, channels )
| Argument | Type | Default | |
|---|---|---|---|
audio | any | required | The audio buffer. |
channels | integer | required | The target channel count. Mono to any count copies the signal, any count to mono averages the channels. |
Returns A new audio buffer.
audioResample
Change the sample rate of an audio buffer. The input buffer is left untouched.
audioResample( audio, sampleRate )
| Argument | Type | Default | |
|---|---|---|---|
audio | any | required | The audio buffer. |
sampleRate | integer | required | The new sample rate in Hz, using a windowed sinc filter. |
Returns A new audio buffer.