Module audio 

Audio loading and conversion.

Strategy for v0.0.0:

• Prefer system ffmpeg for decoding any common format to 16 kHz mono f32 PCM
• Fail fast with install instructions if ffmpeg is missing
• WAV files that are already 16 kHz mono PCM can be read directly via hound
• Enforce duration / decoded-size bounds during decode so we fail before OOM

Remote TTS wire formats use [remote_normalize] (JOE-1937): bounded PCM/WAV in-process, supervised FFmpeg for MP3 only.

Structs

AudioInput

In-memory audio ready for a transcription provider.

BoundedAudioBody

Encoded provider body already under a hard byte cap.

NormalizedAudio

Validated mono PCM result of remote-audio normalization.

RemoteAudioLimits

Resource bounds for remote audio normalization.

Enums

ChannelPolicy

How multi-channel PCM is handled.

EncodedAudioFormat

Wire format declared by the provider/capability path (not raw MIME guessing).

FfmpegTermination

Structured FFmpeg termination reason (JOE-1585).

Constants

ALLOWED_SAMPLE_RATES_HZ

Discrete sample rates accepted for remote TTS wire formats.

DEFAULT_FFMPEG_TIMEOUT

Default wall-clock deadline for a single FFmpeg decode (JOE-1585).

DEFAULT_MAX_DECODED_BYTES

Approximate decoded PCM budget (f32 mono 16 kHz) — ~500 MB ≈ 2.25 h.

DEFAULT_MAX_DURATION

Default maximum duration of normalized audio.

DEFAULT_MAX_DURATION_SECS

Default maximum audio duration accepted for transcription (~2.25 h matches PCM budget).

DEFAULT_MAX_ENCODED_BYTES

Default hard cap on encoded provider response bodies (16 MiB).

DEFAULT_MAX_PCM_SAMPLES

Default hard cap on decoded mono PCM sample count (~10 min @ 48 kHz).

DEFAULT_MAX_UPLOAD_BYTES

Max compressed upload size for remote providers (~24 MB keeps base64 JSON manageable).

SUPPORTED_EXTENSIONS

Supported input extensions (informational; ffmpeg is the real gate).

WHISPER_SAMPLE_RATE

Sample rate required by the local whisper.cpp path (Hz).

Functions

encode_for_upload

Encode samples to a compressed temp file for remote upload (JOE-1648).

encode_for_upload_with_timeout

Supervised upload encode with explicit deadline and optional cancel flag.

ffmpeg_available

Check whether ffmpeg is available (non-fatal).

format_from_path

Infer a reasonable audio format label from a path extension.

load_audio

Load an audio file, converting to 16 kHz mono f32 PCM as needed.

load_audio_with_limits

Load audio with explicit safety limits (used by tests and future flags).

load_via_ffmpeg_with_timeout

Supervised FFmpeg decode with explicit deadline and optional cancel flag.

normalize_remote_audio

Normalize provider audio bytes into mono i16 PCM under shared limits.

require_ffmpeg

Ensure ffmpeg is available on PATH.

try_load_wav_file

Attempt to read a 16 kHz mono PCM WAV directly, rejecting oversized files first.

write_temp_wav

Write samples out as a 16 kHz mono WAV using an exclusive create (O_EXCL).