feat(packages): surface explicit mic intent so built-in controls can publish audio-only

Merged
MM
3mo ago
+675-69

Closes #32

Summary

The engine and adapter learned audio-only capture in #31, but the stock publish UI couldn't drive it: the media contract had no mic intent slot, the capture-source store slice didn't expose one, and the capture aggregation only counted the video pipelines — so a voice-only page's publish button never enabled. This surfaces micActive end to end, with the mic counting toward capture aggregation only under explicit intent.

Changes

  • MediaCaptureSourceCapability declares micActive with the same intent-consumption semantics as the video intents; the "mic has no intent slot" contract prose is updated to match.
  • The captureSource store feature exposes the mic intent (micActive state + toggleMic() action). Older media generations without the property stay coherent: the slice defaults the intent to false, and toggleMic() refuses to write an inert expando that the next sync would read back as real intent.
  • aggregateCaptureState now takes the capture slice and counts the mic only when micActive is set — the load-bearing rule lives in one place. An implied mic (video-driven, e.g. one that outlives a dismissed screen picker by a beat) never enables capture-gated controls on its own.
  • With the mic as the sole capture source, PublishButton enables and starts/stops the session; EnableDevicesButton and CapturePlaceholder report the mic-only capture state coherently. HTML and React behave identically (parity tests).

Testing

  • pnpm -F @videojs/media test (613), pnpm -F @videojs/core test (1602), pnpm -F @videojs/html test (406), pnpm -F @videojs/react test (467), pnpm -F @videojs/spf test (all files) — green
  • pnpm typecheck clean after a full declarations rebuild
  • New coverage: mic gating in the aggregation precedence tests, mic intent slice + older-generation tolerance in the feature tests, mic-only enable/publish and implied-mic-stays-disabled cases across the core, HTML, and React publish button and capture placeholder tests

🤖 Generated with Claude Code


Summary by cubic

Enables audio-only publishing by adding an explicit mic intent and provenance. Previously publish required an active camera or screen; now an explicitly requested mic can start a session, while a video‑implied mic never enables controls or shows permission errors.

  • Adds optional micActive to MediaCaptureSourceCapability. The sandbox FakePublishMedia implements a real audio‑only pipeline (token‑canceled acquisition, consume intent on denied/ended, device re‑keying, mute wiring), accepts an explicit active mic as a publish() precondition, reports source‑aware stats (NaN for absent metrics), and only dispatches mic capture state events on real changes.

  • The captureSource store exposes toggleMic() and latches micExplicit across intent consumption on terminal outcomes; it resets when a new implied lifecycle starts. Legacy hosts without micActive remain compatible; the intent defaults to false and toggleMic() no‑ops.

  • aggregateCaptureState(media) replaces the two‑arg form and counts the mic only when micExplicit is true; terminal mic states keep counting after intent consumption. An implied mic never surfaces active or denied on its own.

  • PublishButton, EnableDevicesButton, and capture placeholders handle mic‑only across @videojs/core, @videojs/html, and @videojs/react. Elements pass micState and micExplicit into the core; explicit mic enables Publish, implied mic does not.

  • Migration

    • Media hosts should add a writable optional micActive and emit capturesourcechange when it changes.
    • Update calls to aggregateCaptureState to pass the capture source object. If gating publish outside the built‑ins, enable on mic only when micExplicit is true and micState is active; surface blocks with micExplicit && (micState === 'denied' || micState === 'ended').