feat(runtime-v2): add optional native WebM output

[jmccaffrey-nv]

Summary

• add an optional Linux flashdreams-webm companion wheel whose single native extension statically links checksum-pinned libvpx 1.17.0, libopus 1.6.1, and libwebm 1.0.0.32
• expose --mode webm without changing the V2 model or AudioOutput APIs; preserve external-FFmpeg H.264/AAC --mode mp4 as the default legacy/native-viewer fallback
• prefer VP9+Opus, benchmarking VP9 at 768×768/24 fps on first use and caching a CPU/native-version-specific VP8 fallback when p90 encode latency exceeds one 41.667 ms frame interval
• retain the MP4 transaction contract: native video packets and normalized PCM stay in private sibling staging, successful close publishes with one atomic replace, and failed cleanup retains ownership for an explicit abort retry
• ship exact upstream license/patent grants, REUSE metadata, third-party checksums, runtime docs, policy tests, native container tests, and transactional sink tests

This is stacked on #526 because it consumes that PR's synchronized audio
staging and abort contracts. Retarget it to main after #526 merges.

Validation

• compact wheel build: 1.32 MB, 15 files; one native extension plus Python policy/metadata/licenses, with no dynamic libvpx/libopus/libwebm dependencies
• companion CPU tests: 10 passed (real VP8, VP9, and VP9+Opus containers checked with ffprobe)
• V2 CPU suite: 323 passed
• targeted Ruff format/lint and ty: passed
• reuse lint: REUSE 3.3 compliant, 1291/1291 files classified
• uv lock --check, version sync, and git diff --check: passed
• required local benchmark: VP9 p90 3.601 ms versus 41.667 ms budget, so this machine selected VP9

The whole-repository ty command still reports existing diagnostics in unrelated docs, WebRTC, Wan, LingBot, and OmniDreams files; no WebM-touched file reports a diagnostic.

Merge prerequisite

Because this adds a new optional direct package and statically redistributed third-party libraries, reopen OSRB Bug 6107043 under CONTRIBUTING/OSS policy §14 before merge.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[greptile-apps]

Greptile Summary

The PR adds an optional Linux WebM companion package and integrates native VP8/VP9 video plus Opus audio output into runtime-v2 while retaining MP4 as the default.

• Adds the checksum-pinned native companion build, packaging metadata, licenses, codec benchmark, and cache-backed VP8/VP9 selection.
• Adds transactional WebM staging, muxing, cleanup, runtime mode selection, and associated tests.
• Extracts the existing FFmpeg MP4 implementation behind legacy backend modules while preserving its public runtime behavior.

Confidence Score: 5/5

The PR appears safe to merge from the reviewed code perspective, subject to the stated external OSRB prerequisite.

No blocking failure remains.

Important Files Changed

Filename	Overview
extensions/flashdreams-webm/src/native/webm_writer.cpp	Implements native RGB-to-VPx encoding, Opus packetization, timestamp-ordered WebM muxing, and staging cleanup.
extensions/flashdreams-webm/src/flashdreams_webm/policy.py	Implements machine-specific VP9 benchmarking, VP8 fallback selection, environment overrides, and atomic cache persistence.
flashdreams/flashdreams/runtime_v2/webm_output_sink.py	Connects runtime-v2 video and synchronized audio staging to the optional native WebM writer under a transactional publication contract.
flashdreams/flashdreams/runtime_v2/client_window_factory.py	Adds WebM mode routing and mode-specific argument validation while preserving MP4 as the default.
flashdreams/flashdreams/runtime_v2/audio_stager.py	Extracts reusable PCM normalization and timeline staging used by the file-output backends.
flashdreams/pyproject.toml	Exposes the optional WebM companion dependency without adding it to the default installation.
uv.lock	Registers the new workspace companion package while retaining the existing resolved dependency versions relevant to the investigated advisories.

Sequence Diagram

sequenceDiagram
    participant CLI
    participant Factory as Client Window Factory
    participant Sink as WebM Output Sink
    participant Policy as Codec Policy
    participant Native as Native WebM Writer
    participant FS as Filesystem
    CLI->>Factory: Select --mode webm
    Factory->>Sink: Open with SessionDesc
    Sink->>Policy: Select VP9 or cached VP8 fallback
    Policy-->>Sink: Codec decision
    Sink->>Native: Create private staged writer
    loop Generated results
        Sink->>Native: Encode RGB frames
        Sink->>FS: Stage normalized PCM
    end
    Sink->>Native: Finalize VPx + Opus WebM
    Native-->>Sink: Completed staged container
    Sink->>FS: Atomically replace destination

Loading

_{Reviews (3): Last reviewed commit: "refactor(runtime-v2): isolate legacy FFm..." | Re-trigger Greptile}

[jmccaffrey-nv]

/ok to test e6c8a74

[jmccaffrey-nv]

Paralegal OSS-license and codec-patent review (head e6c8a74)

Disposition: OSS copyright/notice review passes; patent/OSRB review remains a merge and publication hold. This is issue-spotting for counsel, not a freedom-to-operate opinion.

What I verified

• I independently downloaded the exact three build archives. Their SHA-256 values match CMakeLists.txt and THIRD-PARTY-NOTICES: libvpx 1.17.0 1020f...c0a, libopus 1.6.1 6ffcb...1a1, and libwebm 1.0.0.32 7fd5e...9eb8.
• The wheel-carried libvpx LICENSE/PATENTS, libopus COPYING, and libwebm LICENSE.TXT/PATENTS.TXT are byte-for-byte identical to those pinned archives. The companion Apache-2.0 text also matches the repository copy.
• libvpx, libopus, and libwebm use permissive BSD-3-Clause terms compatible with Apache-2.0. Their binary-redistribution condition is to reproduce the copyright notice, conditions, and disclaimer; license-files = ["licenses/*"] is set to carry the exact notices in the wheel, and THIRD-PARTY-NOTICES accurately records the static linkage. I found no copyleft component and no FFmpeg library redistribution in this companion.
• REUSE.toml, the custom LicenseRef-WebM-Additional-IP-Rights-Grant, the optional-component notice block, pyproject.toml, and uv.lock are internally coherent. Because upstream sources are fetched during the build rather than committed as a repository subtree, leaving the minimal top-level NOTICE unchanged follows the repository's current collateral policy.

Patent issues requiring written disposition

1. VP9 is not cleared by the bundled Google grant alone. The exact WebM Additional IP Rights Grant covers only claims owned/acquired and licensable by Google that are necessarily infringed by Google's implementations; it excludes claims arising only from further modification and contains defensive termination. Google also expressly acknowledges that third parties can demand fees. Sisvel currently lists a multi-owner VP9 patent programme with asserted VP9-specification patents and royalty-bearing consumer-product terms (while excluding components/subassemblies from its offered licence). That does not establish infringement or that a royalty is owed here, but it prevents treating the Google file as complete VP9 patent clearance. Patent Legal must document NVIDIA's licence/non-infringement/other disposition for this encoder and its expected distribution/use.

2. VP8 has a separate cross-licence. Google's broader VP8 Patent Cross-License is independent of the bundled WebM grant, covers claims from additional primary licensors, and requires affirmative execution plus a reciprocal necessary-claims grant and defensive-termination obligations. Confirm whether NVIDIA already participates or whether counsel concludes the separate agreement is unnecessary; do not infer that status from shipping libvpx-PATENTS.txt.

3. Opus patent terms are real and conditional even though royalty-free grants exist. The exact upstream COPYING correctly points to the Xiph, Microsoft, and Broadcom IETF disclosures. The official Opus licence page says those grants are automatic/royalty-free, but the Xiph/Broadcom terms include patent-litigation termination, and Microsoft's terms include reciprocity/availability conditions for a recipient that owns or controls Necessary Claims. The same page identifies additional potentially royalty-bearing IETF disclosures from Qualcomm, Huawei, France Telecom, and Ericsson and reports outside counsel's view that Opus can be implemented without licensing those patents. OSRB/Patent Legal—not this PR—must adopt that conclusion for NVIDIA's use.

4. Defensive-termination review is corporate, not merely technical. The WebM grant terminates on specified patent-enforcement activity by the user, its agent, or exclusive licensee; the Opus grants have their own termination/reciprocity language. Those obligations need Patent Legal review for a patent-holding corporate distributor.

Merge gate

• Reopen OSRB Bug 6107043, amend §14 for flashdreams-webm plus the statically linked libvpx/libopus/libwebm versions and use, and re-confirm the codec/patent answers (Q11/Q12) as the PR body already anticipates.
• Obtain a written OSRB/Patent Legal disposition covering VP9/Sisvel, the separate VP8 cross-licence, and the Opus reciprocity/third-party disclosures; link or record the approval on this PR before merge/publish.
• In the approval or THIRD-PARTY-NOTICES, preserve the narrow wording: the PR carries exact upstream grants, but makes no blanket representation that VP8, VP9, or Opus is patent-free or fully cleared worldwide.

With those approvals recorded, I see no remaining OSS copyright/licence blocker in the PR's current packaging.