Skip to content

feat(ffi): share container source timebases - #5559

Merged
kixelated merged 5 commits into
mainfrom
quest/m1/ffi-timebase
Oct 15, 2026
Merged

kixelated merged 5 commits into
mainfrom
quest/m1/ffi-timebase

Conversation

@kixelated

@kixelated kixelated commented Oct 15, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

Separate container importers for one source currently choose independent arrival-based offsets. A two-second video/audio source gap becomes five seconds when the first frames arrive five seconds apart.

Approach

Expose a broadcast-owned media Timebase and let chunk and byte-stream container init records select it. Binding handles hold only a weak broadcast reference; the broadcast owns the core timebases. Reject foreign and closed owners, preserve independent offsets when omitted, and release unused handles without withholding the catalog or publication shutdown. Mirror the surface and examples in every active binding, regenerate Dart, and retire the quest.

Both container constructors share one private reserve_container helper that takes the catalog reservation (from the timebase, or independent) and clones the broadcast under the owner lock, then builds the importer after the lock is released.

Impact

  • Add MoqMediaTimebase and the ergonomic media Timebase handles, including moq::MediaTimebase in C++ and explicit Go handle release.
  • Add optional timebase to ContainerInit and introduce ContainerStreamInit. The byte-stream constructor now takes that record instead of a bare format, a breaking API change across bindings, noted in doc/setup/upgrade.md. Python, Swift and Go init types are ergonomic wrapper records rather than raw FFI aliases. The context-free Rust From<MoqContainerInit> conversion is removed because ownership validation needs the broadcast.
  • Generated UniFFI ABI changes require matching libraries and regenerated bindings. The retired handwritten C API is unaffected.
  • No network wire or catalog schema change. Codec frame timestamp semantics are unchanged; Timebase::place remains Rust-only.

Validation

  • Reproduced the original mismatch: 16,000,000 us instead of 13,000,000 us. Six deterministic native regressions cover shared video90k/audio48k offsets, omission, foreign/closed refusal, temporary and moved handles, unused catalog gating, and owner-drop/close teardown.
  • Rebased onto main after Preserve caller-supplied producer timestamps #5560; full just check modules pass locally (Rust workspace, Python, Kotlin, Go, Dart, C++, OBS, docs, flake, workflow checks). Dart bindings regenerate with no diff. moq-uring is excluded locally only because this host's shared memlock limit is exhausted; CI covers it.
  • just test interop --all passes on the rebased head.
  • The two-axis benchmark (1/32/1024 timebases by 1/16/256 importer batches) now runs in the Rust workload of the split Nightly in sh/gh/nightly.sh, without codec features, with no acceptance threshold.

Alternatives

A strong core timebase in each binding handle would keep catalog outputs alive after its broadcast disappears. Per-importer offsets cannot preserve the source's cross-container timing.

Follow-ups

  • The panic supervision PR (fix(ffi)!: supervise binding-owned background task panics #5562) extends reserve_container to return the driver as well, keeping construction outside the owner lock. Its with_state driver refusal also protects new Timebase handles.
  • Kotlin's generated converter can clone an already-destroyed argument without checking its guard. An invalid test reuse after close() exposed a native abort; the valid closed-publication regression uses the existing end() contract. Investigating generated invalid-handle safety is separate follow-up scope.

(Written by GPT-6, rebased and updated by Claude Opus 5.5)

🤖 Generated with Claude Code

kixelated and others added 5 commits October 15, 2026 15:08
Co-Authored-By: GPT-6 <noreply@openai.com>
Co-Authored-By: GPT-6 <noreply@openai.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated force-pushed the quest/m1/ffi-timebase branch from 4366a21 to 1154941 Compare October 15, 2026 22:29
@kixelated
kixelated marked this pull request as ready for review October 15, 2026 22:29
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 15, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-15T22:32:50.288415Z 1154941 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 11549419f5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread rs/moq-ffi/src/media.rs
Comment on lines +370 to +372
/// A shared source timebase, or absent for an independent offset.
#[uniffi(default = None)]
pub timebase: Option<Arc<MoqMediaTimebase>>,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Expose the shared timebase through the C binding

When a C publisher splits one source across multiple container imports, rs/moq-c/src/publish.rs:228-234 still creates every importer with catalog.reserve(), so delayed arrival between those imports is still converted into timestamp drift even though the other bindings can now share an offset. Mirror this timebase option into moq-c and document it under doc/lib/c so the active C API receives the same correctness fix.

AGENTS.md reference: rs/moq-ffi/AGENTS.md:L9-L14

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Leaving rs/moq-c as is. The hand-written C ABI is frozen for feature work and slated for retirement (quest/m2/release/c-retire.md, and the "no new libmoq API" decision in quest/m1/auth/bindings.md). C and C++ users get new features through the generated moq-ffi bindings, and the C++ package already exposes this as moq::MediaTimebase. A C import that needs a shared offset should move to those.

(Written by Claude Opus 5.5)

@coderabbitai

coderabbitai Bot commented Oct 15, 2026

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: e387923f-4293-43f2-8b97-3f8dc7717d17
📥 Commits

Reviewing files that changed from the base of the PR and between 196cf7e and 1154941.

📒 Files selected for processing: 29
  • cpp/moq/include/moq/moq.hpp
  • cpp/moq/test/probe.cpp
  • dart/moq/lib/media.dart
  • dart/moq/test/moq_test.dart
  • dart/moq_ffi/lib/src/moq.dart
  • doc/lib/cpp/index.md
  • doc/lib/dart/index.md
  • doc/lib/go/index.md
  • doc/lib/kt/index.md
  • doc/lib/py/index.md
  • doc/lib/swift/index.md
  • doc/setup/upgrade.md
  • go/wrapper/README.md
  • go/wrapper/media/media.go
  • go/wrapper/media/media_test.go
  • kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/media/Media.kt
  • kt/moq/src/jvmAndAndroidTest/kotlin/dev/moq/SmokeTest.kt
  • py/moq-rs/README.md
  • py/moq-rs/docs/index.md
  • py/moq-rs/moq/media.py
  • py/moq-rs/tests/test_local.py
  • quest/m1/README.md
  • quest/m1/ffi-timebase.md
  • quest/m2/sibling-broadcasts.md
  • rs/moq-ffi/src/media.rs
  • rs/moq-ffi/src/producer.rs
  • sh/gh/nightly.sh
  • swift/Sources/Moq/Media.swift
  • swift/Tests/MoqTests/SmokeTests.swift
💤 Files with no reviewable changes: 2
  • quest/m1/ffi-timebase.md
  • quest/m1/README.md

Included review availability: This review used your included allowance. Your plan provides up to 4 included reviews per hour; 0 remain after this review.

Walkthrough

Container initialization now accepts an optional shared timebase. Container producers use a shared catalog offset when a timebase is supplied and an independent offset otherwise. Timebases are scoped to their broadcast, and the binding APIs expose the new initialization types and timebase handles. The stream producer API now takes a container stream init record. Tests cover shared timing, foreign-broadcast rejection, and closed broadcasts.

Priority: ➖ Normal

Merge Risk: ⚪ Minimal · up to 11549

The shared-timebase behavior and importer lifetime are supported by the implementation. No issue requiring a change before merge was identified.

Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 40 functions across 13 files. (14 skipped… Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Title check Passed The title clearly and concisely identifies the main change: sharing container source timebases through FFI.
Description check Passed The description directly explains the problem, implementation, API changes, validation, compatibility impact, and follow-up scope.
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.
Full details: Docstring Coverage

Explanation

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

  • Fix all pre-merge checks with AI
✨ Finishing Touches
✨ Simplify code
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Some tools did not complete. Review the errors below.

🔧 Clippy (1.98.1)

Clippy execution timed out

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

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

@kixelated

Copy link
Copy Markdown
Collaborator Author

Merging 1154941:

  • Rebased onto main after Preserve caller-supplied producer timestamps #5560. Both container constructors now share a private reserve_container helper: it takes the catalog reservation (shared timebase or independent) and clones the broadcast under the owner lock, and the importer is built after the lock is released.
  • The timebase benchmark moved into the Rust workload of the split Nightly (sh/gh/nightly.sh); the byte-stream init record is noted in doc/setup/upgrade.md.
  • Validation: full local just check modules and just test interop --all pass, Dart regenerates with no diff, and CI is green. Codex reviewed this head; its one finding (mirror the timebase into the hand-written moq-c) is answered in-thread: that ABI is frozen for feature work and slated for retirement.

(Written by Claude Opus 5.5)

@kixelated
kixelated added this pull request to the merge queue Oct 15, 2026
Merged via the queue into main with commit 5c20060 Oct 15, 2026
31 checks passed
@kixelated
kixelated deleted the quest/m1/ffi-timebase branch October 15, 2026 23:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant