feat(spf): allow microphone-only capture and audio-only publish sessions

Merged
MM
3mo ago
+509-59

Fixes #26

Summary

acquireMicrophone was gated on cameraActive || screenShareActive, so there was no audio-only publish session: a voice-only page had to put a camera or screen share in the browser's permission prompt, light the hardware indicator, and advertise a video track it never wanted. This adds a first-class microphone intent so a publish session can start with the mic as the sole capture source — no video source in the getUserMedia constraints, no video track in the catalog.

Changes

  • acquireMicrophone gains a micActive intent slot, OR'd into its gate beside the video intents and consumed on the pipeline's own termination (denied / ended / acquisition failure) under the module's existing multi-writer contract. The mic consumes only its own slot — a dead mic still never ends a video capture. Video intent still implies the mic (v1 UX), so micActive: false under an active camera neither releases nor re-acquires; it is acquisition intent, not a mute. The missing-device quiet idle deliberately does not consume the intent, so a mic-only session waits for a plug-in and recovers on devicechange.
  • openPublishSession counts the mic toward its session gate (open on active, ride out acquiring) — but only under explicit micActive. An implied mic's status is a side effect of video capture; it must not open or hold a session the video pipelines no longer justify (e.g. a mic that outlives a dismissed screen picker by a beat).
  • Engine: micActive is a seeded, shared intent slot on MoqPublishEngineState.
  • Adapter: micActive property, included in capturesourcechange, and publish() accepts an active explicit mic as its capture precondition.
  • HTML element: mic-active attribute beside camera-active/screen-share-active, with the same intent-consumption reflection that keeps property retry live. React picks the prop up automatically through Partial<MoqPublishMediaProps>.
  • Downstream needed no changes: the probes, track publishers, and catalog derivation were already kind-agnostic — an audio-only session publishes exactly catalog + audio.

Not included (possible follow-ups): a micActive addition to @videojs/media's MediaCaptureSourceCapability contract and the core store/UI surfaces (mic-enable button), and a mic-stream accessor on the adapter for level meters (available today via media.engine.context.micStream).

Testing

  • acquireMicrophone: mic-only acquisition uses audio-only constraints; release on intent drop; denial and out-of-band end consume micActive (video intents untouched); camera-held gate ignores a micActive drop; missing-device idle holds the intent and recovers on devicechange.
  • openPublishSession: opens on an active mic alone; ignores an implied mic without micActive; rides out a mic device switch in a mic-only session.
  • Engine end-to-end (real WebCodecs in headless Chromium): micActive alone captures and encodes Opus with one audio-only getUserMedia call and no video pipeline touched.
  • Adapter: audio-only surface + publish() precondition; HTML: mic-active attribute mapping and consumption reflection.
  • Full @videojs/spf (2237), @videojs/html (403), and @videojs/react (463) suites, workspace pnpm typecheck, and biome all clean.

🤖 Generated with Claude Code


Summary by cubic

Enables microphone-only capture and audio-only publish. Previously the mic only acquired under camera/screen intent; now micActive is a first‑class intent so voice‑only pages can capture and open a session without requesting video. An implied mic still does not gate a session; micActive is required to count the mic.

  • @videojs/spf:
    • acquireMicrophone: gates on micActive OR video intent; consumes only micActive on denied/ended/failure; holds intent on missing‑device idle for devicechange recovery; re‑fires acquisition on a micActive rising edge over a parked mic even while video holds the gate.
    • openPublishSession: counts the mic toward the session gate only under explicit micActive; rides out mic acquiring like other sources.
    • Engine seeds and shares micActive. Adapter adds a micActive prop, includes it in capturesourcechange, and publish() accepts an active explicit mic as the capture precondition.
  • @videojs/html: MoqPublishVideo maps a mic-active attribute beside camera-active/screen-share-active, reflects intent consumption to keep property retry live, and tests the retry write after consumption.
  • @videojs/react: Prop docs mention micActive; the prop forwards automatically.

No migration required. Video flows are unchanged and still imply the mic. To publish audio‑only, set micActive and call publish().