|
AUKit
|
Classes | |
| class | aukit |
| The main AUKit module. More... | |
| class | aukit::Audio |
| The aukit.Audio class represents a chunk of audio with variable channels and sample rate. More... | |
| class | aukit::Player |
An asynchronous player created by aukit.player. More... | |
| class | aukit::effects |
| Effects that can modify audio chunks. More... | |
| class | aukit::stream |
Loader functions for streaming audio from a remote resource. These are usually used with aukit.play. More... | |
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 aukit.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. aukit.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.
MIT License
Copyright (c) 2021-2024 JackMacWindows
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
1.10.0