Module `aukit`

AUKit: Audio decoding and processing framework for ComputerCraft

AUKit is a framework designed to simplify the process of loading, modifying, and playing audio files in various formats.

It includes support for loading audio from many sources, including PCM, DFPWM, G.711, and ADPCM codecs, as well as WAV, AIFF, AU, and FLAC files. It can also generate audio on-the-fly as tones, noise, or silence.

AUKit uses a structure called Audio to store information about each audio chunk. An audio object holds the sample rate of the audio, as well as the data for each channel stored as floating-point numbers. Audio objects can hold any number of channels at any sample rate with any duration.

To obtain an audio object, you can use any of the main functions in the aukit module. These allow loading from various raw codecs or file formats, with data sources as strings, or tables if using a raw codec loader.

Once the audio is loaded, various basic operations are available. A subset of the string library is available to simplify operations on the audio, and a number of operators (+, *, .., #) are overridden as well. There's also built- in functions for resampling the audio, with nearest-neighbor, linear, cubic, and sinc interpolation available; as well as mixing channels (including down to mono) and combining/splitting channels. Finally, audio objects can be exported back to PCM, DFPWM, or WAV data, allowing changes to be easily stored on disk. The stream function also automatically chunks data for use with a speaker. All of these functions return a new audio object, leaving the original intact.

There are also a number of effects available for audio. These are contained in the aukit.effects table, and modify the audio passed to them (as well as returning the audio for streamlining). The effects are intended to speed up common operations on audio. More effects may be added in future versions.

For simple audio playback tasks, the aukit.stream table provides a number of functions that can quickly decode audio for real-time playback. Each function returns an iterator function that can be called multiple times to obtain fully decoded chunks of audio in 8-bit PCM, ready for playback to one or more speakers. The functions decode the data, resample it to 48 kHz (using the default resampling method), apply a low-pass filter to decrease interpolation error, mix to mono if desired, and then return a list of tables with samples in the range [-128, 127], plus the current position of the audio. The iterators can be passed directly to the aukit.play function, which complements the aukit.stream suite by playing the decoded audio on speakers while decoding it in real-time, handling synchronization of speakers as best as possible.

If you're really lazy, you can also call `aukit` as a function, which takes the path to a file, and plays this on all available speakers.

Be aware that processing large amounts of audio (especially loading FLAC or resampling with higher quality) is *very* slow. It's recommended to use audio files with lower data size (8-bit mono PCM/WAV/AIFF is ideal), and potentially a lower sample rate, to reduce the load on the system - especially as all data gets converted to 8-bit DFPWM data on playback anyway. The code yields internally when things take a long time to avoid abort timeouts.

For an example of how to use AUKit, see the accompanying auplay.lua file.

Info:

License: MIT
Author: JackMacWindows

Fields

_VERSION
defaultInterpolation

Audio

Audio.sampleRate
Audio.metadata
Audio.info
Audio:len ()	Returns the length of the audio object in seconds.
Audio:channels ()	Returns the number of channels in the audio object.
Audio:resample (sampleRate, interpolation)	Creates a new audio object with the data resampled to a different sample rate.
Audio:mono ()	Mixes down all channels to a new mono-channel audio object.
Audio:concat (...)	Concatenates this audio object with another, adding the contents of each new channel to the end of each old channel, resampling the new channels to match this one (if necessary), and inserting silence in any missing channels.
Audio:sub (start, last)	Takes a subregion of the audio and returns a new audio object with its contents.
Audio:combine (...)	Combines the channels of this audio object with another, adding the new channels on the end of the new object, resampling the new channels to match this one (if necessary), and extending any channels that are shorter than the longest channel with zeroes.
Audio:split (...)	Splits this audio object into one or more objects with the specified channels.
Audio:mix (amplifier, ...)	Mixes two or more audio objects into a single object, amplifying each sample with a multiplier (before clipping) if desired, and clipping any values outside the audio range ([-1, 1]).
Audio:rep (count)	Returns a new audio object that repeats this audio a number of times.
Audio:reverse ()	Returns a reversed version of this audio.
Audio:pcm (bitDepth, dataType, interleaved)	Converts the audio data to raw PCM samples.
Audio:stream (chunkSize, bitDepth, dataType)	Returns a function that can be called to encode PCM samples in chunks.
Audio:wav (bitDepth)	Coverts the audio data to a WAV file.
Audio:dfpwm (interleaved)	Converts the audio data to DFPWM.

aukit

pcm (data, bitDepth, dataType, channels, sampleRate, interleaved, bigEndian)	Creates a new audio object from the specified raw PCM data.
adpcm (data, channels, sampleRate, topFirst, interleaved, predictor, step_index)	Creates a new audio object from IMA ADPCM data.
msadpcm (data, blockAlign, channels, sampleRate, coefficients)	Creates a new audio object from Microsoft ADPCM data.
g711 (data, ulaw, channels, sampleRate)	Creates a new audio object from G.711 u-law/A-law data.
dfpwm (data, channels, sampleRate)	Creates a new audio object from DFPWM1a data.
mdfpwm (data, head)	Creates a new audio object from MDFPWMv3 data.
wav (data, head)	Creates a new audio object from a WAV file.
aiff (data, head)	Creates a new audio object from an AIFF or AIFC file.
au (data)	Creates a new audio object from an AU file.
flac (data, head)	Creates a new audio object from a FLAC file.
new (duration, channels, sampleRate)	Creates a new empty audio object with the specified duration.
tone (frequency, duration, amplitude, waveType, duty, channels, sampleRate)	Creates a new audio object with a tone of the specified frequency and duration.
noise (duration, amplitude, channels, sampleRate)	Creates a new audio object with white noise for the specified duration.
pack (data, bitDepth, dataType, bigEndian)	Packs a table with PCM data into a string using the specified data type.
play (callback, progress, volume, ...)	Plays back stream functions created by one of the aukit.stream functions or Audio:stream.
detect (data)	Detect the type of audio file from the specified data.

aukit.stream

aukit.stream.pcm (data, bitDepth, dataType, channels, sampleRate, bigEndian, mono)	Returns an iterator to stream raw PCM audio in CC format.
aukit.stream.dfpwm (data, sampleRate, channels, mono)	Returns an iterator to stream audio from DFPWM data.
aukit.stream.mdfpwm (data, mono)	Returns an iterator to stream audio from MDFPWMv3 data.
aukit.stream.msadpcm (input, blockAlign, channels, sampleRate, mono, coefficients)	Returns an iterator to stream audio from Microsoft ADPCM data.
aukit.stream.adpcm (input, blockAlign, channels, sampleRate, mono)	Returns an iterator to stream data from IMA ADPCM data.
aukit.stream.g711 (input, ulaw, channels, sampleRate, mono)	Returns an iterator to stream data from u-law/A-law G.711 data.
aukit.stream.wav (data, mono, ignoreHeader)	Returns an iterator to stream audio from a WAV file.
aukit.stream.aiff (data, mono, ignoreHeader)	Returns an iterator to stream audio from an AIFF or AIFC file.
aukit.stream.au (data, mono, ignoreHeader)	Returns an iterator to stream data from an AU file.
aukit.stream.flac (data, mono)	Returns an iterator to stream data from a FLAC file.

aukit.effects

aukit.effects.amplify (audio, multiplier)	Amplifies the audio by the multiplier specified.
aukit.effects.speed (audio, multiplier)	Changes the speed and pitch of audio by a multiplier, resampling to keep the same sample rate.
aukit.effects.fade (audio, startTime, startAmplitude, endTime, endAmplitude)	Fades a period of music from one amplitude to another.
aukit.effects.invert (audio)	Inverts all channels in the specified audio.
aukit.effects.normalize (audio, peakAmplitude, independent)	Normalizes audio to the specified peak amplitude.
aukit.effects.center (audio)	Centers the DC offset of each channel.
aukit.effects.trim (audio, threshold)	Trims any extra silence on either end of the specified audio.
aukit.effects.delay (audio, delay, multiplier)	Adds a delay to the specified audio.
aukit.effects.echo (audio, delay, multiplier)	Adds an echo to the specified audio.
aukit.effects.reverb (audio, delay, decay, wetMultiplier, dryMultiplier)	Adds reverb to the specified audio.
aukit.effects.lowpass (audio, frequency)	Applies a low-pass filter to the specified audio.
aukit.effects.highpass (audio, frequency)	Applies a high-pass filter to the specified audio.

Fields

_VERSION

_VERSION string The version of AUKit that is loaded. This follows [SemVer](https://semver.org) format.

defaultInterpolation

defaultInterpolation "none", "linear", "cubic" or "sinc" Default interpolation mode for Audio:resample and other functions that need to resample.

Audio

Audio.sampleRate

sampleRate number The sample rate of the audio.

Audio.metadata

metadata table Stores any metadata read from the file if present.

Audio.info

info table Stores any decoder-specific information, including `bitDepth` and `dataType`.

Audio:len ()

Returns the length of the audio object in seconds.

Returns:

number _ The audio length

Audio:channels ()

Returns the number of channels in the audio object.

Returns:

number _ The number of channels

Audio:resample (sampleRate, interpolation)

Creates a new audio object with the data resampled to a different sample rate. If the target rate is the same, the object is copied without modification.

Parameters:

sampleRate number The new sample rate in Hertz
interpolation ? "none"|"linear"|"cubic" The interpolation mode to use

Returns:

Audio _ A new audio object with the resampled data

Audio:mono ()

Mixes down all channels to a new mono-channel audio object.

Returns:

Audio _ A new audio object with the audio mixed to mono

Audio:concat (...)

Concatenates this audio object with another, adding the contents of each new channel to the end of each old channel, resampling the new channels to match this one (if necessary), and inserting silence in any missing channels.

Parameters:

... Audio The audio objects to concatenate

Returns:

Audio _ The new concatenated audio object

Audio:sub (start, last)

Takes a subregion of the audio and returns a new audio object with its contents. This takes the same arguments as string.sub, but positions start at 0.

Parameters:

start ? number The start position of the audio in seconds
last ? number The end position of the audio in seconds (0 means end of file)

Returns:

Audio _ The new split audio object

Audio:combine (...)

Combines the channels of this audio object with another, adding the new channels on the end of the new object, resampling the new channels to match this one (if necessary), and extending any channels that are shorter than the longest channel with zeroes.

Parameters:

... Audio The audio objects to combine with

Returns:

Audio _ The new combined audio object

Audio:split (...)

Splits this audio object into one or more objects with the specified channels. Passing a channel that doesn't exist will throw an error.

Parameters:

... number[] The lists of channels in each new object

Returns:

Audio ... The new audio objects created from the channels in each list

Usage:

Split a stereo track into independent mono objects

     local left, right = stereo:split({1}, {2})

Audio:mix (amplifier, ...)

Mixes two or more audio objects into a single object, amplifying each sample with a multiplier (before clipping) if desired, and clipping any values outside the audio range ([-1, 1]). Channels that are shorter are padded with zeroes at the end, and non-existent channels are replaced with all zeroes. Any audio objects with a different sample rate are resampled to match this one.

Parameters:

amplifier number|Audio The multiplier to apply, or the first audio object
... Audio The objects to mix with this one

Returns:

Audio _ The new mixed audio object

Audio:rep (count)

Returns a new audio object that repeats this audio a number of times.

Parameters:

count number The number of times to play the audio

Returns:

Audio _ The repeated audio

Audio:reverse ()

Returns a reversed version of this audio.

Returns:

Audio _ The reversed audio

Audio:pcm (bitDepth, dataType, interleaved)

Converts the audio data to raw PCM samples.

Parameters:

bitDepth ? number The bit depth of the audio (8, 16, 24, 32)
dataType ? "signed"|"unsigned"|"float" The type of each sample
interleaved ? boolean Whether to interleave each channel

Returns:

number[]|nil ... The resulting audio data

Audio:stream (chunkSize, bitDepth, dataType)

Returns a function that can be called to encode PCM samples in chunks. This is useful as a for iterator, and can be used with aukit.play.

Parameters:

chunkSize ? number The size of each chunk
bitDepth ? number The bit depth of the audio (8, 16, 24, 32)
dataType ? "signed"|"unsigned"|"float" The type of each sample

Returns:

fun():number[][]|nil,number|nil _ An iterator function that returns chunks of each channel's data as arrays of signed 8-bit 48kHz PCM, as well as the current position of the audio in seconds
number _ The total length of the audio in seconds

Audio:wav (bitDepth)

Coverts the audio data to a WAV file.

Parameters:

bitDepth ? number The bit depth of the audio (1 = DFPWM, 8, 16, 24, 32)

Returns:

string _ The resulting WAV file data

Audio:dfpwm (interleaved)

Converts the audio data to DFPWM. All channels share the same encoder, and channels are stored sequentially uninterleaved if `interleaved` is false, or in one interleaved string if `interleaved` is true.

Parameters:

interleaved ? boolean Whether to interleave the channels

Returns:

string ... The resulting DFPWM data for each channel (only one string if `interleaved` is true)

aukit

pcm (data, bitDepth, dataType, channels, sampleRate, interleaved, bigEndian)

Creates a new audio object from the specified raw PCM data.

Parameters:

data string|table The audio data, either as a raw string, or a table of values (in the format specified by `bitDepth` and `dataType`)
bitDepth ? number The bit depth of the audio (8, 16, 24, 32); if `dataType` is "float" then this must be 32
dataType ? "signed"|"unsigned"|"float" The type of each sample
channels ? number The number of channels present in the audio
sampleRate ? number The sample rate of the audio in Hertz
interleaved ? boolean Whether each channel is interleaved or separate
bigEndian ? boolean Whether the audio is big-endian or little-endian; ignored if data is a table

Returns:

Audio _ A new audio object containing the specified data

adpcm (data, channels, sampleRate, topFirst, interleaved, predictor, step_index)

Creates a new audio object from IMA ADPCM data.