feat(audio): add channel-aware streaming output

[ruiling-smartbear]

Background

Refs #1254. The existing streaming callback carries samples and sample rate but cannot describe stereo. This adds the streaming counterpart to the complete-result/WAV proposal in #1256, as an independent PR based on main.

Exit Criteria

• Carry channel metadata with ordered interleaved PCM chunks.
• Keep existing mono family implementations working unchanged.
• Validate chunk shape, format stability, and completion counts before reporting success.

Implementation

Add AudioChunkView and the optional IMultichannelStreamingAudioGeneration capability. The CLI prefers that capability when available, otherwise uses the existing mono capability. Raw float32 output JSON now includes num_channels.

Document synchronous borrowed-buffer lifetime, completion by return, and exception propagation. Existing interfaces/vtables and AudioResult are unchanged. No model-family, bundle-format, or dependency changes.

Change categories

• Model or runtime behavior
• Public API
• ABI
• Bundle or artifact format
• Dependencies
• Documentation only
• CI or developer tooling

Validation

Commands and Results

On Linux, compiled and ran the actual CLI test with ASan/UBSan, using real loader/bundle sources and synthetic task fixtures:

g++ -std=c++17 -DTRTMC_VERSION_STRING='"0.1.0"' \
  -fsanitize=address,undefined -fno-omit-frame-pointer -g \
  -Wall -Wextra -Wpedantic -Wno-missing-field-initializers \
  -Icore/runtime/include -Icore -Iapps -Ithird_party/stb \
  -I/usr/local/lib/python3.11/site-packages/nlohmann_json/include \
  -I/usr/local/lib/python3.11/site-packages/nvidia/cuda_runtime/include \
  -I/usr/local/lib/python3.11/site-packages/nvidia/cuda_nvcc/include \
  apps/cli/tests/test_cli.cpp apps/cli/cli.cpp apps/cli/io.cpp \
  core/runtime/loader/family_loader.cpp core/runtime/bundle/bundle_format.cpp \
  -ldl -o /tmp/test_cli
/tmp/test_cli

Passed (ALL PASSED). Covers legacy mono, multichannel capability precedence, exact stereo chunk concatenation, metadata, and 12 failure modes: empty stream, null data, partial frame, empty/negative chunk count, invalid rate/channels, non-finite data, producer failure, rate/channel changes, and wrong final total.

Also passed locally:

c++ -std=c++17 -Icore/runtime/include core/runtime/tests/test_task_api.cpp \
  -o /tmp/trtmc-stream-task-api
/tmp/trtmc-stream-task-api
clang-format --dry-run --Werror apps/cli/cli.cpp apps/cli/tests/test_cli.cpp \
  core/runtime/include/trtmc/task.h core/runtime/tests/test_task_api.cpp
git diff --check

Hardware, Environment, and Revisions

Tested head 7fb82240, base a50cf5dc. Linux x86_64 Debian 12 CPU container, GCC 12, CUDA header packages nvidia-cuda-runtime-cu12==12.4.127 and nvidia-cuda-nvcc-cu12==12.4.131, nlohmann_json==3.12.0. Local API/format checks used Apple Silicon macOS and clang-format 22.1.8. No GPU or TensorRT inference; synthetic float32 audio only.

Not Run / Remaining Gaps

No real model has been migrated to the new capability in this PR, so model streaming quality/latency is not qualified. Full repository CMake/CI was not run locally. HTTP, WAV streaming, and other encoded formats remain outside scope.

Contributor Self-Review

• I have completed a self-review of this change.

Notes For Future Readers

The new interface is opt-in and does not require #1256's AudioResult change. num_samples means scalar samples, with whole frames in every chunk. A failed stream can leave a partial raw file, but must not emit success JSON. This is not a cancellation/preemption API; callback exceptions must propagate and the implementation must clean up its own generation state.

Risk level

• Low
• Medium
• High

Existing ABI types are unchanged, but this is a new public capability and CLI validation now rejects malformed legacy chunks and inconsistent totals. Model-specific adoption needs its own validation.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: b2e6ba52-4cb6-45ff-8963-219363435194

📥 Commits

Reviewing files that changed from the base of the PR and between a50cf5d and 7fb8224.

📒 Files selected for processing (5)

• apps/cli/cli.cpp
• apps/cli/tests/test_cli.cpp
• core/runtime/include/trtmc/task.h
• core/runtime/tests/test_task_api.cpp
• website/docs/architecture/runtime-lifecycle.md

Included review availability: Your plan provides up to 12 included reviews per hour; 10 remain after this review.

---

📝 Summary

Summary

Adds channel-aware audio streaming through AudioChunkView and the optional IMultichannelStreamingAudioGeneration capability.

The CLI uses the multichannel capability when available. It falls back to existing mono generation when it is not available. Raw float32 JSON output now includes num_channels.

The CLI validates chunk shape, PCM format, channel count, sample rate, finite samples, sample-count overflow, producer errors, callback failures, and final sample counts. Tests cover stereo ordering, metadata, capability precedence, legacy mono behavior, and malformed streams.

Architecture impact

• Family-owned files: apps/cli/cli.cpp and apps/cli/tests/test_cli.cpp own CLI selection, validation, output, and coverage.
• Changed shared surfaces: core/runtime/include/trtmc/task.h adds the public AudioChunkView, callback type, and optional capability interface. core/runtime/tests/test_task_api.cpp verifies the interface contract.
• Dependency direction: The CLI consumes the runtime capability. The runtime API does not depend on CLI code, model families, bundle formats, or new dependencies.
• Affected consumers: CLI audio generation and consumers that implement or detect runtime audio-generation capabilities. Existing mono implementations remain supported.
• Unresolved blast-radius questions: Model-family implementations are not migrated in this change. Full CMake/CI coverage, GPU inference, HTTP output, WAV output, and encoded formats remain outside the change scope.

PASS — The change preserves existing interfaces and vtables while adding an optional runtime capability.
HUMAN REVIEW REQUIRED — Confirm implementation coverage for model families and integration coverage in full build and deployment environments.

Walkthrough

The runtime adds a multichannel streaming capability with interleaved PCM chunks. The CLI selects this capability, validates streamed data, writes raw samples, reports channel metadata, and preserves mono fallback behavior. Tests and lifecycle documentation cover the new contract.

Changes

Multichannel audio streaming

Layer / File(s)	Summary
Multichannel streaming contract core/runtime/include/trtmc/task.h, core/runtime/tests/test_task_api.cpp	Adds AudioChunkView, MultichannelAudioChunkCallback, and IMultichannelStreamingAudioGeneration with synchronous ordered callbacks and scalar-sample totals.
CLI dispatch and validation apps/cli/cli.cpp, apps/cli/tests/test_cli.cpp	Adds multichannel dispatch, chunk and total validation, stereo output metadata, interleaved sample checks, fault coverage, and mono fallback tests.
Lifecycle documentation website/docs/architecture/runtime-lifecycle.md	Documents multichannel chunk semantics, validation, error handling, output metadata, and unchanged mono behavior.

Priority: ➖ Normal

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant Generator as IMultichannelStreamingAudioGeneration
  participant Output as RawAudioFile
  CLI->>Generator: Request streaming audio
  Generator->>CLI: Deliver interleaved PCM chunks
  CLI->>Output: Validate and write samples
  Generator-->>CLI: Return total scalar sample count
  CLI-->>Output: Close output and report num_channels

Loading

Merge Risk: ⚪ Minimal · up to 7fb82

The multichannel streaming path validates audio chunks and metadata while preserving mono fallback behavior. No merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 8 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 23.08% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 13 functions across 4 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (8 passed)

Check name	Status	Explanation
Description check	✅ Passed	The description covers the required background, exit criteria, implementation, change categories, validation evidence, environment, remaining gaps, self-review, notes, and risk level. It does not prov…
Title check	✅ Passed	The title clearly and concisely describes the main change: adding channel-aware streaming audio output.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Family Ownership Boundary	✅ Passed	No family-ownership violation is introduced. The authoritative diff contains no path under families/ and no family build or registry file. The changed CLI lines apps/cli/cli.cpp:991-1031 use the s…
Shared Semantic Neutrality	✅ Passed	PASS. The only changed shared implementation file is apps/cli/cli.cpp. Its change is model-agnostic: it selects the optional audio streaming capabilities, validates generic PCM chunk properties, wri…
Benchmark Validation Integrity	✅ Passed	PASS. The pull request changes CLI streaming validation, not benchmark timing, metrics, workload units, or report aggregation. Both compared CLI paths—the direct `IMultichannelStreamingAudioGeneration…
Shared Change Blast Radius	✅ Passed	The shared-surface rationale is identified. The description states the model-agnostic need: the existing streaming callback cannot describe stereo. It identifies the CLI as the consumer, preserves the…

Full details: Docstring Coverage

Explanation

Docstring coverage is 23.08% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 13 functions across 4 files. (1 skipped: 1 unsupported.)

---

_{Comment @coderabbitai help to get the list of available commands.}

[yifeif-nv]

Triggered the internal CI for you. But please work with @jkzhang7 on the minimax music PR to see what's the best way to get the stereo audio merge in

[ruiling-smartbear]

Hi @yifeif-nv, the latest Community CPU checks have now passed. Could you please retrigger internal CI for #1259 when convenient? The previous attempt stopped at the CPU prerequisite gate. Thanks!