Quikcast Help

Ogg FLAC continuous streaming completion review

Date: 2026-10-08. Ogg FLAC implementation and FFmpeg external validation are complete. Direct BUTT 1.46 interoperability remains awaiting manual validation. No further codec, relay, optimization or platform milestone is started.

  1. Mapping architecture. FLAC is another codec state inside src/media/ogg.rs, using the existing page scanner, CRC, sequence and continuation handling, BOS/EOS/chains, initialization cache and generation ring. No second Ogg parser/fanout, remuxer or native-frame successor scanner is introduced. Mapping rules are based on the Xiph Ogg FLAC specification. Encoded page bytes remain unchanged.

  2. Codec detection. The identification packet must have the standardized 0x7fFLAC signature, supported version 1.0, bounded following-header count, embedded fLaC marker and exact STREAMINFO envelope/payload. It is exactly 51 bytes and occupies the sole packet of a 79-byte BOS page. Unknown Ogg payloads and incidental fLaC occurrences do not select FLAC. New mixed transitions involving FLAC are rejected. Detection happens after page CRC validation; unresolved sources are not made listener-ready prematurely.

  3. Initialization/header model. The mapping count excludes identification; nonzero counts must agree exactly with the last-metadata-block flag. Zero means unknown, still bounded and terminated by that flag. At least one following metadata packet is required, with VORBIS_COMMENT first. Each following packet contains one complete native metadata envelope, with bounded size and exact declared packet length. Duplicate singleton blocks, forbidden types, short APPLICATION IDs and malformed SEEKTABLE entry lengths reject. Unknown legal types remain opaque and preserved. Header packets may span pages; the last header finishes its page. Header-only granules are zero and audio starts on a fresh page. Cached initialization contains original complete Ogg pages, never bare native bytes. Header-tag payloads are not fully decoded.

  4. STREAMINFO reuse. media::flac::streaminfo is shared with native FLAC, with an explicit 34-byte input guard. The existing validation of block/frame sizes, audio sample rate, channels and bit depth is retained. Ogg stores only the resulting small property value; it does not allocate a native FLAC cache or construct/run the native frame parser. Native framing tests still pass.

  5. Late joins. Existing Ring::ogg_page, cached initialization and page boundary markers are reused unchanged. A listener receives the source's required header pages, then a retained/new non-continued audio page. A page beginning inside an unfinished packet is not a join point. Ongoing listeners receive continued pages normally. Original page headers, laces, CRC bytes, sequence numbers, granules and payloads are neither reconstructed nor rewritten. Responses preserve admitted audio/ogg or application/ogg, close-delimited delivery and existing no-cache/no-store semantics. ICY requests never produce interleaving or icy-metaint; external track updates remain visible separately.

  6. Chains. FLAC-to-FLAC chains are supported after EOS followed by valid BOS. Reset mapping count, readiness, metadata singleton tracking, packet prefix, packet lengths, codec identification and FLAC properties. Parse the next STREAMINFO independently, allowing changed rate, channels and depth. The original next-chain BOS/header/audio pages reach ongoing listeners; new listeners receive the next initialization. Existing waiting-boundary cursors with old initialization close on chain change. Sequence counters restart at zero and then retain the existing modulo-2^32 tracking; granules remain exactly those supplied by the encoder, including header zero and per-chain reset. Reconnect creates an entirely new generation with no inherited Ogg state. Malformed input clears parsed FLAC properties before failure propagates.

  7. Mixed-codec policy. Reject Vorbis/Opus-to-FLAC and FLAC-to-Vorbis/Opus deterministically with an unsupported-media error. Preserve the pre-existing Vorbis/Opus chain behavior, including its already tested codec transitions. This milestone makes no new player compatibility claim for those old mixed chains. FLAC property changes are valid server transport, but client ability to consume such chains varies; see the explicit decoder limits below.

  8. Resource bounds. Existing page ceiling 65,307 bytes and aggregate initialization ceiling 65,536 bytes remain unchanged. The initialization byte budget also bounds retained page count (at least 27 bytes per page). At most 128 following FLAC metadata packets are accepted, even for count zero; packet/header counters use checked arithmetic. Header payloads stay under the same Ogg initialization budget. An Ogg FLAC audio packet is limited to 1 MiB, tracked by a counter across continued pages; it is never assembled in an independent large buffer. Audio packets require mapping's FLAC packet type and minimum framing size, but subframes are not decoded. A 51-byte prefix replaces the previous 30-byte identification prefix. No new configuration knobs or large reservations are needed; existing bounded page/header/ring and generation admission reservations apply. Input failures close only their source generation. Source inactivity, ring eviction and SlowConsumer policies are inherited unchanged.

  9. Management. Keep the existing Ogg format identity ogg-audio, add resolved codec: "flac", and retain audio/ogg/application/ogg as appropriate. Shared flat sample_rate_hz, channels, bits_per_sample fields expose accepted STREAMINFO properties and update across chains. No FLAC API subtree is added. Capabilities add ogg-flac; existing flac continues to identify native support. Metrics continue using existing fixed counters and labels. /admin/metadata changes external track state without rewriting Ogg comments, pictures, STREAMINFO or seek tables.

  10. BUTT evidence and remaining gap. The installed application plist reports BUTT 1.46.0. /Applications/butt.app/Contents/MacOS/butt --help terminated with exit 134 in the sandbox without output. An additional unsandboxed probe, butt -c /private/tmp/quikcast-ogg-flac-butt-test.cfg -L, used an isolated configuration path but produced no audio-device output or test configuration; it was terminated after waiting. Native GUI controls are unavailable in this session, so no usable audio/GUI source session could be established. No BUTT admission, source-method/MIME/header capture, playback, metadata or reconnect success is claimed from its manual. The required manual pass is: connect BUTT 1.46 with FLAC/Ogg selected to an isolated authenticated Quikcast mount; record actual method/MIME/headers, management detection, early/late decode, external title updates, stop/reconnect and source bytes. This is the concrete remaining interoperability gate, not a production-code feature follow-up.

  11. FFmpeg and external decoder evidence. tools/proof/ogg_flac.py starts localhost Quikcast and generates genuine Ogg FLAC with FFmpeg 8.1.2:

    ffmpeg -hide_banner -loglevel error -f lavfi \ -i 'sine=frequency=997:sample_rate=48000:duration=8' \ -ac 2 -sample_fmt s16 -c:a flac -f ogg pipe:1 ffmpeg -hide_banner -loglevel error -f lavfi \ -i 'sine=frequency=503:sample_rate=44100:duration=4' \ -ac 1 -sample_fmt s16 -c:a flac -f ogg pipe:1 ffmpeg -hide_banner -loglevel error -f lavfi \ -i 'anoisesrc=sample_rate=48000:duration=120:seed=42' \ -ac 2 -sample_fmt s16 -c:a flac -f ogg pipe:1

    A test-only adapter writes original pages via authenticated raw PUT, HTTP/1.1, localhost Host and Content-Type: audio/ogg; there is no Content-Length or chunked transfer header. The actual configured request and response headers, producer commands, hashes and parsed management fields are saved in ignored evidence/ogg-flac/report.json. Two generations received 11,711,956 bytes. Seven listener captures match exact source pages (full streams or cached initialization plus complete page suffixes), and all decode with FFmpeg -hide_banner -loglevel error -xerror -i CAPTURE -f s16le pipe:1, exit 0 and nonempty PCM. First-generation early/concurrent captures contain 161,507 bytes and 16 pages; late contains 131,793 bytes and 14 pages; a listener joining the new chain contains 48,791 bytes and 6 pages. Reconnected healthy captures contain 11,550,449 bytes and 195 pages; its late join contains 11,430,386 bytes and 193 pages. The deliberately stopped reader is evicted as SlowConsumer, while healthy captures remain complete, byte-exact and decodable. The long noise input exists solely to force functional stopped-socket eviction, not profiling or capacity qualification. Sources/captures and server logs are retained beside the JSON; FFmpeg remains test tooling, not a runtime dependency.

  12. Tests and fuzz coverage. Nine new Rust tests bring cargo test --all-targets to 109 passing tests: 73 library, 11 relay, 25 streaming. Mapping signature, versions, truncated identification, STREAMINFO, known/unknown/excessive counts, required-comment ordering, split metadata, initialization readiness and cache, byte/packet ceilings, header granules, reserved packet type, last-header page separation, continuation, CRC, sequence, chain resets, changed properties and mixed-codec rejection have unit coverage. Property tests mutate real Ogg FLAC pages with recomputed CRCs, test pending and chained states, assert memory/count bounds and compare results across input chunking. Socket tests exercise both MIME types, concurrent and late delivery, exact whole pages, track updates, changed 48 kHz/stereo/16-bit to 44.1 kHz/mono/24-bit properties, reconnect, capabilities and malformed-FLAC isolation while both Vorbis and Opus remain exact. Existing Ogg/native-FLAC/MP3/AAC/ICY/HLS/relay/drain/lifecycle tests pass. fuzz/fuzz_targets/ogg_flac.rs uses production modules in unresolved, identification-only, initialized-audio and finished-chain states. A 10,000-run smoke and a further 2,000 seeded runs completed without failure; checked-in FLAC seeds support future runs. Stable-toolchain libFuzzer emits missing sanitizer/coverage warnings, so this is not a claim of instrumented fuzz coverage. Strict Clippy, formatting and diff checks pass; there is no runtime encoder dependency.

  13. Known limitations. Only mapping version 1.0 is admitted; older informal mappings and future versions are not claimed. Oversized headers/artwork or audio packets reject locally. Opaque metadata and audio packet contents are transported, not semantically decoded; Ogg CRC is error detection, not proof of valid PCM or protection against deliberate forged input. The server is a live non-seekable distributor, not a file/tag editor. Existing immediate generation closure does not promise flushing a downloadable file on arbitrary source failure. FFmpeg 8.1.2 successfully decodes rate/channel-changing chains at constant bit depth but emits a one-sample output DTS rounding diagnostic; that output-muxer diagnostic is recorded separately from decoder success. It fails continuous 16-to-24-bit chain decoding with “switching bps mid-stream is not supported”; evidence/ogg-flac/bit-depth-chain.json records that failed decoder command/diagnostic. Each logical stream is valid and the server preserves the changed-depth chain; clients may need to reopen/reset their decoder. BUTT interoperability remains untested as described above.

  14. Native FLAC remains separate. audio/flac still uses its native marker, metadata cache and bounded successor-frame scanner. Ogg FLAC still uses Ogg MIME, pages/packets and the original Ogg cache. Only STREAMINFO parsing and the existing management property fields are shared. Native framing, ICY exclusion and exact-byte tests continue passing. No native bytes are emitted outside Ogg framing, and Ogg FLAC is not implemented as a MIME alias.

  15. Updated roadmap and stopping point. feature-roadmap.md now places manual BUTT validation first, followed by broader named-client/operator validation and the freeze review. Client chain limitations must be part of that review. New codecs, FLAC HLS, remuxing/transcoding, relays, fallback, takeover, reload, TLS/PROXY and RadioPlatform remain deferred; no compatibility milestone for relays was executed here. Profiling/optimization remains gated on accepted scope and satisfactory manual validation. This implementation stops here.

08 October 2026
Native FLAC continuous streaming completion reviewStandalone feature-completeness audit