Treatment decodeMono

audio/decode::decodeMono

Parameters

↳ var hint: Option<string>

Inputs

⇥ data: Stream<byte>

Outputs

↦ errors: Stream<string>
↦ failed: Block<void>
↦ info: Block<AudioInfo> (audio/audio_info::AudioInfo)
↦ signal: Stream<f32>

Decode an audio stream of any supported format into a normalised mono f32 signal.

Audio bytes arrive through data and are decoded on-the-fly as they stream in, without buffering the entire input first. The decoded samples are emitted through signal as a continuous stream of f32 values in the range [-1.0, 1.0], regardless of the bit depth or sample format of the source.

If the source audio has more than one channel, all channels are mixed down to mono by averaging each frame across channels before emission.

The format is detected automatically from the content of the stream. The optional hint parameter can be set to a file extension (e.g. "mp3", "flac", "ogg", "wav") to help the detection when the content alone is ambiguous. When none, detection relies entirely on the byte content.

Supported formats and codecs:

  • WAVE (.wav): PCM (all standard bit depths: 8, 16, 24, 32-bit integer and 32/64-bit float), ADPCM (Microsoft and IMA/DVI variants), A-law, μ-law.
  • AIFF (.aiff, .aif): PCM.
  • FLAC (.flac): Free Lossless Audio Codec, all standard bit depths.
  • Ogg (.ogg, .oga): Vorbis audio inside an Ogg container.
  • MP3 (.mp3): MPEG-1 Audio Layer I, II, and III.
  • Matroska / WebM (.mkv, .mka, .webm): any audio track whose codec is otherwise supported (e.g. PCM, FLAC, Vorbis, MP3).
  • ISO Base Media / MP4 / M4A (.mp4, .m4a, .aac): AAC, ALAC, and other codecs carried in an ISOBMFF container.
  • Core Audio Format (.caf): PCM and other codecs in Apple's CAF container.

errors emits a message for every problem encountered during decoding:

  • recoverable problems (a single corrupt packet that is skipped) produce one message and decoding continues;
  • fatal problems (unrecognised format, missing audio track, unsupported codec, unrecoverable I/O error) produce one message, trigger failed, and close all outputs immediately.

failed triggers if and only if decoding cannot continue at all, regardless of whether any samples were already emitted on signal before the failure occurred.

⚠️ data must carry a single, complete audio stream from start to finish. Mixing bytes from different files or restarting mid-stream will cause detection or decoding to fail.

graph LR
     T("decodeMono()")
     D["🟦 … 🟥"] -->|data| T
     T -->|signal| S["−0.3 … 0.7"]
     T -->|info| I["AudioInfo"]
     T -->|errors| E["…"]
     T -->|failed| F["⬛"]

     style D fill:#ffff,stroke:#ffff
     style S fill:#ffff,stroke:#ffff
     style I fill:#ffff,stroke:#ffff
     style E fill:#ffff,stroke:#ffff
     style F fill:#ffff,stroke:#ffff

use audio/decode::decodeMono
use fs/local::readLocal
use std/engine/util::startup

treatment playFlacFile()
  output signal: Stream<f32>
{
    startup()
    readLocal(path="track.flac")
    decodeMono(hint="flac")

    startup.trigger -> readLocal.trigger,data -> decodeMono.data,signal -> Self.signal
}