feat(presenter): subtitle/audio delay, mute, and volume query across the full stack

[Shinokawa]

Summary

Adds four playback-control APIs that the engine previously lacked, wired end to end: Rust presenter → C ABI → platform plugins (macOS/iOS/Windows/Android) → Dart.

C ABI	Semantics	Range
erika_presenter_set_subtitle_delay(handle, double seconds)	mpv sub-delay: positive delays subtitle display	clamped to ±60 s
erika_presenter_set_audio_delay(handle, double seconds)	mpv audio-delay: positive delays audio relative to video	clamped to ±10 s
erika_presenter_set_muted(handle, bool) / erika_presenter_muted(handle, bool*)	independent mute flag; does not clobber the stored volume	—
erika_presenter_get_volume(handle, double*)	reads the user volume; reports the stored level while muted	—

Without these, hosts could not correct A/V or subtitle sync (external audio tracks, Bluetooth latency, badly muxed sources) and had to emulate mute with set_volume(0), losing the user's level and the muted/zero-volume distinction that OS media controls expect.

Implementation

Subtitle delay. The pts handed to subtitle overlay composition is shifted at all four append_to_overlay call sites (render tick, clock update, overlay refresh, frame capture), via a pure helper shifted_subtitle_pts. The danmaku timeline is deliberately not shifted — it has its own per-track and global offset mechanism. Changing the delay refreshes the current overlay immediately, following the set_subtitle_scale pattern. Negative delay is bounded by decode lookahead; documented on the setter.

Audio delay. Frame pts is shifted in push_audio before the ring-buffer hand-off. Because the audio-master clock disciplines itself to these pts values, video scheduling, subtitles, and danmaku follow automatically; no backend changes are required. A delay change takes effect from the next pushed frame and does not reset the output device.

Mute. muted and saved_volume are independent presenter state: muting drives the backend volume to zero without touching saved_volume; set_volume while muted updates the stored level without unmuting; volume() always reports the stored level. This contract is fixed in C ABI tests.

Platform wiring follows the existing set_volume / setSubtitleScale template at every layer: header declarations with cfg-gated stubs for unsupported targets, JNI dispatch entries, macOS and iOS Swift bindings (function additions only — no mirrored C struct is modified), the Windows C++ plugin, the Kotlin method registry (setSubtitleDelay also added to RENDER_REQUEST_METHODS since it must trigger a re-render), and Dart methods taking Duration/bool.

Testing

• Rust: pts-shift helper and mute state-machine unit tests — cargo test -p erika --lib, 317 passed
• C ABI: volume/mute round-trip, delay setter null-handle and clamp behavior; new exported functions carry # Safety docs — cargo test -p erika_capi --lib, 24 passed
• Dart: four method-channel forwarding tests — flutter test, 37 passed
• Both Swift files pass swiftc -parse; cargo clippy reports no new warnings

Notes for reviewers

The Android JNI dispatch entries mirror the existing setVolume / getUpscalerStatus patterns but were not compiled locally (macOS host without the Android toolchain); the android.yml workflow covers that target.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a1727254be

ℹ️ 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".

[chatgpt-codex-connector]

Delay audio samples instead of retagging their clock

For any nonzero audio delay, changing only frame.pts does not delay or advance the samples: AudioRingBuffer queues and reads sample data immediately in FIFO order and uses PTS only to produce clock_snapshot(). That shifted snapshot is then sent to Player::update_audio_clock, so a positive delay drives the video/master clock forward rather than holding audio back, while a negative shift may be rejected as a stale clock. The implementation needs to schedule/insert/drop audio relative to an unshifted playback clock rather than altering the clock reported for the samples.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Apply subtitle delay before subtitle delivery and retention

Shifting only the overlay lookup time cannot implement the documented delay semantics. PlaybackEngine::tick_subtitle does not deliver a cue until its unshifted start time, so negative delays can never display it early; for positive delays, SubtitleFrameState::push prunes preceding finite cues using the next cue's original start, meaning adjacent text/bitmap cues are commonly discarded before their delayed display window. Subtitle delivery and retention must account for the configured delay, not just the final lookup.

Useful? React with 👍 / 👎.

[Shinokawa]

This PR has been split into three focused drafts:

• feat(presenter): add mute and volume query #60 — mute and saved-volume query
• feat(presenter): add subtitle delay controls #61 — subtitle delay controls (draft: negative-delay delivery/retention semantics remain)
• feat(presenter): isolate audio delay controls for redesign #62 — audio delay controls (draft: output/source clock redesign required)

Each replacement branch is based on the latest main, contains one feature area, and has passed Rust/C ABI and Flutter tests. Closing #53 to avoid duplicate review and merge paths.