lovr.data.newSound
EditCreates a new Sound. A sound can be loaded from an audio file, or it can be created empty with capacity for a certain number of audio frames.
When loading audio from a file, use the decode option to control whether compressed audio should remain compressed or immediately get decoded to raw samples.
When creating an empty sound, the contents parameter can be set to 'stream' to create an audio stream. On streams, Sound:setFrames will always write to the end of the stream, and Sound:getFrames will always read the oldest samples from the beginning. The number of frames in the sound is the total capacity of the stream's buffer.
Create a raw or stream Sound from a frame count and format info:
Arguments
| Name | Type | Default | Description |
| frames | number | The number of frames the Sound can hold. | |
| format | SampleFormat | 'f32' | The sample data type. |
| channels | ChannelLayout | 'stereo' | The channel layout. |
| sampleRate | number | 48000 | The sample rate, in Hz. |
| contents | * | nil |
A Blob containing raw audio samples to use as the initial contents, 'stream' to create an audio stream, or nil to leave the data initialized to zero.
|
Returns
| Name | Type | Description |
| sound | Sound | Sounds good. |
Load a sound from a file. Compressed audio formats (OGG, MP3) can optionally be decoded into raw sounds.
Arguments
| Name | Type | Description |
| filename | string | The filename of a sound to load. |
| decode | boolean | Whether compressed audio files should be immediately decoded. |
Returns
| Name | Type | Description |
| sound | Sound | Sounds good. |
Load a sound from a Blob containing the data of an audio file. Compressed audio formats (OGG, MP3) can optionally be decoded into raw sounds.
If the Blob contains raw audio samples, use the first variant instead of this one.
Arguments
| Name | Type | Description |
| blob | Blob | The Blob containing audio file data to load. |
| decode | boolean | Whether compressed audio files should be immediately decoded. |
Returns
| Name | Type | Description |
| sound | Sound | Sounds good. |
Notes
It is highly recommended to use an audio format that matches the format of the audio module: f32 sample formats at a sample rate of 48000, with 1 channel for spatialized sources or 2 channels for unspatialized sources. This will avoid the need to convert audio during playback, which boosts performance of the audio thread.
The WAV importer supports 16, 24, and 32 bit integer data and 32 bit floating point data. The data must be mono, stereo, or 4-channel full-sphere ambisonic. The WAVE_FORMAT_EXTENSIBLE extension is supported.
Ambisonic channel layouts are supported for import (but not yet for playback). Ambisonic data can be loaded from WAV files. It must be first-order full-sphere ambisonic data with 4 channels. If the WAV has a WAVE_FORMAT_EXTENSIBLE chunk with an AMBISONIC_B_FORMAT format GUID, then the data is understood as using the AMB format with Furse-Malham channel ordering and normalization. All other 4-channel files are assumed to be using the AmbiX format with ACN channel ordering and SN3D normalization. AMB files will get automatically converted to AmbiX on import, so ambisonic Sounds will always be in a consistent format.
OGG and MP3 files will always have the f32 format when loaded.