diff --git a/doc/lib/js/publish.md b/doc/lib/js/publish.md index 36d1c08c0e0..88f65829f1b 100644 --- a/doc/lib/js/publish.md +++ b/doc/lib/js/publish.md @@ -31,7 +31,8 @@ WebCodecs, writes the catalog, and publishes a hang broadcast. | `url`, `name` | Relay URL (with `?jwt=` if needed) and broadcast name. | | `versions` | Protocol versions to offer, most preferred first, comma-separated like `moq-transport-18,moq-lite-06`. Every stable version by default. | | `source` | `camera`, `screen`, or `file`. | -| `muted`, `invisible` | Stop publishing audio or video. The microphone and camera stay open, so unmuting or unhiding is instant and the browser's capture indicators stay lit; clear `source` or remove the element to release them. `source` covers both devices, so releasing one while keeping the other takes the library: toggle `Source.Microphone` or `Source.Camera` `enabled`. | +| `muted`, `invisible` | Stop publishing audio or video. By default the microphone and camera stay open, so unmuting or unhiding is instant and the browser's capture indicators stay lit. | +| `capture` | What a muted or invisible track does with its device: `hold` (default) keeps it open, `release` closes it so its capture indicator goes dark, and resuming reopens it. A screen share or file stops once both tracks are off. Clearing `source` or removing the element releases everything either way. | | `preview` | What the nested element shows: the raw `source` (default), a decoded copy of the `encoded` stream to see what viewers get, or `none`. | | `backend` | How a `` preview is drawn; see [@moq/video](/lib/js/video). `auto` (default), `webgpu`, or `2d`. | | `announce` | When to advertise: once the `source` is live (default), or `always`. Nobody can see or subscribe to the broadcast until it is announced. To keep it out of discovery, use a hidden name with a `.`-prefixed segment; it is still subscribable by name. | diff --git a/js/publish/MIGRATE.md b/js/publish/MIGRATE.md index d3adb3619a4..318f8276ac6 100644 --- a/js/publish/MIGRATE.md +++ b/js/publish/MIGRATE.md @@ -9,7 +9,7 @@ How to update your code for each breaking change, newest first. `` and `invisible` now stop only the encoder, so the microphone and camera stay open and the browser's capture indicators stay lit. Unmuting no longer waits on getUserMedia, a new AudioContext, or a camera reopen. A camera source opens both devices even when it starts muted or hidden. -To release the devices, clear `source` or remove the element; to release one and keep the other, build the pipeline with the library and toggle `Source.Microphone` or `Source.Camera` `enabled`. +To release each device while it is muted or hidden, as before, set `capture="release"`. ### Element reflection and invalid configuration diff --git a/js/publish/README.md b/js/publish/README.md index 963b89647d2..a41af07982d 100644 --- a/js/publish/README.md +++ b/js/publish/README.md @@ -67,8 +67,9 @@ The simplest way to publish a stream: | `name` | string | required | Broadcast name | | `versions` | string | stable versions | Comma-separated protocol versions to offer, most preferred first, like `moq-transport-18,moq-lite-06` | | `source` | string | - | `"camera"`, `"screen"`, `"file"` | -| `muted` | boolean | false | Stop publishing audio; the microphone stays open | -| `invisible` | boolean | false | Stop publishing video; the camera stays open | +| `muted` | boolean | false | Stop publishing audio | +| `invisible` | boolean | false | Stop publishing video | +| `capture` | string | `"hold"` | What a muted or invisible track does with its device: `"hold"` keeps it open so resuming is instant, `"release"` closes it so the browser's capture indicator goes dark. A screen share or file stops once both are off. | | `preview` | string | `"source"` | What the preview renders: `"source"`, `"encoded"`, `"none"` | | `backend` | string | `"auto"` | Graphics API for a `` preview: `"auto"`, `"webgpu"`, `"2d"` | | `announce` | string | `"source"` | When to advertise: `"always"` or `"source"` (once media is captured). A camera source waits for every enabled track, and `"source"` waits until each captured track's config resolves or fails, so the first catalog lists every rendition. After its first announcement, a camera stays announced until deselected or disconnected, including mute, hide, device swaps, and capture retries. The broadcast is created while connected either way. To keep it out of discovery, use a hidden name with a `.`-prefixed segment; it is still subscribable by name. | diff --git a/js/publish/api/element.api.md b/js/publish/api/element.api.md index 8470d0b8f2b..8096ec435e0 100644 --- a/js/publish/api/element.api.md +++ b/js/publish/api/element.api.md @@ -11,22 +11,27 @@ import { Video } from "@moq/publish"; export type AnnounceMode = "always" | "source"; +export type CaptureMode = "hold" | "release"; + export type SourceType = "camera" | "screen" | "file"; export default class extends HTMLElement { constructor(); get announce(): AnnounceMode | undefined; set announce(value: AnnounceMode); - attributeChangedCallback(name: "source" | "url" | "stats" | "announce" | "name" | "backend" | "versions" | "muted" | "invisible" | "preview" | "echo-path", oldValue: string | null, newValue: string | null): void; + attributeChangedCallback(name: "source" | "url" | "stats" | "announce" | "name" | "capture" | "backend" | "versions" | "muted" | "invisible" | "preview" | "echo-path", oldValue: string | null, newValue: string | null): void; audio: Audio.Encoder; get backend(): Preview.Backend; set backend(value: Preview.Backend); broadcast: Broadcast; + get capture(): CaptureMode; + set capture(value: CaptureMode); connectedCallback(): void; connection: Net.Connection; readonly controls: { announce: Signals.Signal; backend: Signals.Signal; + capture: Signals.Signal; echoPath: Signals.Signal; invisible: Signals.Signal; muted: Signals.Signal; @@ -43,7 +48,7 @@ export default class extends HTMLElement { set muted(value: boolean); get name(): Net.Path.Valid; set name(value: string | Net.Path.Valid); - static observedAttributes: readonly ["url", "versions", "name", "muted", "invisible", "source", "preview", "backend", "announce", "stats", "echo-path"]; + static observedAttributes: readonly ["url", "versions", "name", "muted", "invisible", "source", "preview", "backend", "announce", "stats", "echo-path", "capture"]; get preview(): Preview.Mode; set preview(value: Preview.Mode); readonly signals: Signals.Effect; diff --git a/js/publish/src/element.ts b/js/publish/src/element.ts index 68bc497ef3b..90b4e73d6c7 100644 --- a/js/publish/src/element.ts +++ b/js/publish/src/element.ts @@ -51,6 +51,7 @@ const OBSERVED = [ "announce", "stats", "echo-path", + "capture", ] as const; /** The built-in capture sources selectable via the `source` attribute. */ @@ -67,6 +68,15 @@ export type SourceType = "camera" | "screen" | "file"; */ export type AnnounceMode = "always" | "source"; +/** + * What a muted or invisible track does with its capture. + * + * `hold` keeps the device open, so resuming is instant but the browser's capture indicator stays lit. + * `release` closes it, so the indicator goes dark and resuming reopens it. A screen share or file + * stops only once both tracks are off. Defaults to `hold`. + */ +export type CaptureMode = "hold" | "release"; + /** * Parse a boolean attribute: absent uses `defaultValue`, bare presence is true, and an explicit * `"false"`/`"0"` is false. Matches ``. @@ -89,6 +99,12 @@ function parseAnnounce(value: string | null): AnnounceMode { throw invalidAttribute("announce", value, '"source" or "always"'); } +function parseCapture(value: string | null): CaptureMode { + if (value === null) return "hold"; + if (value === "hold" || value === "release") return value; + throw invalidAttribute("capture", value, '"hold" or "release"'); +} + function parsePreview(value: string | null): Preview.Mode { if (value === null) return "source"; if (value === "encoded" || value === "source" || value === "none") return value; @@ -132,6 +148,8 @@ export default class MoqPublish extends HTMLElement { stats: new Signal(false), // Where viewers may publish feedback, relative to the broadcast, or undefined to solicit none. echoPath: new Signal(undefined), + // Whether a muted or invisible track keeps its capture open. + capture: new Signal("hold"), }; /** @@ -178,13 +196,17 @@ export default class MoqPublish extends HTMLElement { // The preview element, either a