Audio import: WAV, Vorbis and MP3
WAV options, loop units, music metadata, and imported versus direct loading.
Import audio from WAV, Ogg Vorbis or MP3, then load the original resource path. The editor stores import settings beside the source and creates a playback resource in its cache. Changing import options does not rewrite the source recording.
Import and play one sound
- Put a valid PCM WAV at Audio/pcm.wav inside the project.
- Select it in Content Browser. In Import, set compress/mode to PCM (Uncompressed) for this first test, then apply Reimport.
- Create an AudioStreamPlayer, leave Autoplay disabled and attach this complete ImportedSound.cs:
using Reckfell;
public partial class ImportedSound : AudioStreamPlayer
{
public override void _Ready()
{
Stream = ResourceLoader.Load<AudioStream>("asset://Audio/pcm.wav");
if (Stream == null)
{
ReckfellApi.PushError("Cannot load asset://Audio/pcm.wav");
return;
}
Play();
}
}Start the level. A non-looping sound plays once; Finished is emitted at natural completion. If no sound is heard, check the player's bus, mute/volume settings and output device before changing the codec. The audio streams guide covers playback, pause, stop and spatial players.
Format and size
| Source | Imported C# resource | Practical starting point |
|---|---|---|
| WAV | AudioStreamWav | Effects needing exact PCM control or WAV import processing |
| Ogg Vorbis | AudioStreamOggVorbis | Encoded music, ambience or speech |
| MP3 | AudioStreamMP3 | Existing MP3 assets or a measured target-platform choice |
WAV import defaults to Quite OK Audio compression, not uncompressed PCM. PCM, IMA ADPCM and QOA are distinct output choices. An .ogg extension alone does not identify Vorbis: verify the codec. Renaming a file does not convert it.
For uncompressed PCM, bytes = duration × sample rate × channels × bytes per sample. One second of 48,000 Hz stereo 16-bit PCM has 192,000 audio-data bytes, excluding the container header. This is not a prediction for compressed files. Compare your actual assets and target-device measurements; no format guarantees a fixed voice count, CPU ranking or equal perceived quality at a particular size.
WAV options
The paths below identify Import parameters; apply Reimport after changing them.
| Parameter | Effect and constraint |
|---|---|
| compress/mode | 0: PCM; 1: IMA ADPCM; 2: Quite OK Audio, the importer default |
| force/8_bit | Select 8-bit output for PCM. The compression choice still determines a compressed output format |
| force/mono | Average stereo channels. Can reduce PCM data size; opposite-phase channels can cancel |
| force/max_rate | Enable the sample-rate cap |
| force/max_rate_hz | Cap used only when force/max_rate is enabled; a higher cap does not upsample a lower-rate source |
| edit/normalize | Scale by the peak amplitude before later processing; not a loudness-matching or bus-limiting system |
| edit/trim | Remove low-level material at the ends using the current −50 dB threshold; may remove intentional quiet tails |
| edit/loop_mode | 0: detect from WAV; 1: disabled; 2: forward; 3: ping-pong; 4: backward |
| edit/loop_begin / edit/loop_end | Explicit WAV loop points in sample frames, not seconds or interleaved channel values |
For a cap of 24,000 Hz, enable force/max_rate and set force/max_rate_hz to 24000. Changing only the numeric value leaves the cap disabled. Rate reduction changes data size while retaining approximately the same duration; assess the audible result rather than assuming it is transparent.
Normalization precedes trim. The trim implementation fades the end over up to 500 frames; it does not promise a matching fade-in. At 48,000 Hz, 500 frames are about 10.4 ms, not 500 ms. Trim is skipped for a detected WAV loop. Explicit loop overrides are applied later, so do not assume that choosing Forward protects an unmarked source from trimming. Verify loop points after any trim or resampling change.
Do not assume a high-bit-depth source remains a same-bit-depth playback resource. Inspect Format, MixRate, Stereo and GetLength on the imported AudioStreamWav. Data contains the selected output encoding; it is not always a raw PCM byte array.
WAV loop units
At 48,000 Hz, a point 0.25 seconds from the start is frame 12000, including for stereo. Do not multiply by two channels. Explicit points refer to the processed sample. In the current importer, end −1 resolves to frame count − 1: for the tested 48,000-frame sample, LoopEnd is 47999.
Detect From WAV reads supported smpl loop metadata. Disabled ignores that loop. The import loop-mode numbers include the extra Detect entry; do not pass them directly as AudioStreamWav.LoopModeEnum values.
Check loop boundaries by listening. Correct stored points and a supported mode do not establish a seamless loop. A looping player does not naturally finish at each repeat; use Stop when you intend to end it.
Ogg Vorbis and MP3 options
| Parameter | Meaning |
|---|---|
| loop | Enable repetition |
| loop_offset | Restart position in seconds after reaching the loop boundary; relevant when looping |
| bpm | Authored beats per minute for music timing |
| beat_count | Number of beats describing the music segment |
| bar_beats | Beats per bar; for example, 4 for a four-beat bar |
These formats do not expose WAV's independent loop-end, backward and ping-pong import controls. Their music metadata is not automatic tempo detection and does not by itself time-stretch a recording. Configure it from the actual composition; mismatched timing can move an interactive music boundary.
The importer provides an Advanced dialog for loop and music metadata. Reimport remains the step that applies stored import settings. This guide's automated run changes the same parameters through import metadata; it does not verify mouse interaction or audible preview in that dialog.
Diagnose an imported sound
For project assets, ResourceLoader.Load uses the imported resource and its settings. The static AudioStreamWav.LoadFromFile, AudioStreamOggVorbis.LoadFromFile and AudioStreamMP3.LoadFromFile read raw files directly and do not apply the editor's .import settings. For WAV, supply conversion options explicitly when needed; an empty options dictionary defaults to PCM rather than the editor's QOA choice. For Ogg/MP3, set loop and music properties on the loaded resource yourself. Ensure the raw file is actually available in an exported build before choosing this workflow.
| Symptom | Check |
|---|---|
| No resource or decoder error | Actual file format/codec, import messages and enabled runtime format support |
| WAV size hardly changed after an option edit | Reimport, compression mode, channels and whether the rate cap was enabled |
| Sound nearly disappears in mono | Stereo phase relationship and channel averaging |
| Quiet tail or intended pause vanished | Trim; compare with an untrimmed import |
| Loop starts at the wrong time | WAV frames versus Ogg/MP3 seconds; processed sample rate and trim |
| Imported sound is louder but clips when combined | Peak normalization and summed bus levels; normalization is not a mix limiter |
| Finished never arrives | Loop setting, explicit Stop or other playback lifecycle; see the streams guide |
Native tests cover real imports, untouched source bytes, WAV conversion and loop metadata, Ogg/MP3 music parameters, the exact C# example and decoded PCM captured from the engine mixer for PCM/QOA/ADPCM/Vorbis/MP3. The mixer uses the Dummy driver: this proves decoded audio data, not speaker output, listening quality or performance. Loop seam/direction waveforms, every WAV variant, editor interaction and browser/mobile/exported builds remain unverified here.