contrib/avcodec: whole-track audio decode to PCM — load_pcm's producer

[paul-hammant]

The producer half of asks/pcm-please.md, completing the loop with the audio.load_pcm consumer that landed in 0.512.0 (#1481). Together they mean an MP4's audio reaches the speakers with no hand-extracted sidecar WAV — the last hand-cranked step in an otherwise in-process pipeline.

Three commits: the ask itself, the implementation (Paul's), and a CHANGELOG entry.

What it adds

pcm, n, rate, ch, err = avcodec.audio_pcm(path)
src, e = audio.load_pcm(pcm, n, rate, ch, audio.FORMAT_S16)

avc_audio_decode_raw demuxes and decodes a file's audio stream to interleaved s16 stereo at the source rate in one shot. libswresample does the conversion in the same pass, so a 5.1 float-planar AAC track comes back as plain stereo s16 without the caller arranging anything. The whole-buffer shape deliberately mirrors load_pcm's, so the two compose directly.

Verified end to end, not just asserted

I rebuilt the pipeline here before writing the CHANGELOG rather than transcribing the commit's numbers — a 2s AAC clip, all the way to a playable source:

decoded n=356352 rate=44100 ch=2
load_pcm ok: duration_ms=2020    (expect ~2000)

FFmpeg demux → s16 stereo → std.audio → playable. The ~1% over 352800 is AAC encoder padding, not a defect. (The original commit's own evidence is a 117.3s clip → 22,523,904 bytes at 48 kHz stereo = 117.3s exactly, with position_ms advancing in real time.)

make contrib-check passes all seven contrib tests including the extended avcodec one.

Dependency change

contrib/avcodec now requires libswresample alongside the other four FFmpeg libraries. Both the contrib-check table and the build probe were updated together; all five are required as a set, and a partial install stays a clean SKIP rather than a build failure.

Shaping up

Three things the commits needed before this could go out:

• They were local-only on main, which had diverged from origin/main. Moved to a branch and rebased.
• Both carried a Claude-Session: trailer; stripped, so each ends at Co-Authored-By.
• No CHANGELOG entry and no [current] section — the exact gap that let 0.506.0–0.509.0 ship empty (backfilled in docs(CHANGELOG): backfill 0.506.0-0.509.0, which shipped unrecorded #1474, root cause in Release pipeline silently ships releases with no CHANGELOG section (4 so far), and races the merge window #1477). Added one, pairing audio_pcm with load_pcm since producer and consumer only make sense together.

Verification

• make ci — C suite 230/230; .ae 978/979. The one failure is integration_http_server_h2, pre-existing and diagnosed in pesky_bug.md.
• gcc -Werror -Wall -Wextra on the new C with the FFmpeg cflags, checked locally before pushing.
• End-to-end run above.

One ergonomic note

Building this by hand hit the ae build --extra shim.c link-flag limitation — it compiles a C shim but cannot pass -l flags, so an aether.toml workspace is required. That is the same gap the avcodec contrib-check fix worked around, and it is what the TODO.md "contrib runtime coverage is split across two mechanisms" entry is about. Not addressed here.

🤖 Generated with Claude Code