feat(video,audio,publish)!: matching capture Control handles, with a keyframe request

doc/lib/js/publish.md

@@ -54,6 +54,10 @@ framerate, and bitrate are tunable through `el.video.config`; the audio
 encoder exposes its codec and volume. For simulcast or several renditions,
 drop the element and register your own encoders on a `Publish.Broadcast`.
 
+`el.video.cut()` asks for a keyframe on top of the `keyframeInterval` cadence,
+for a resume, a recording cut, or a known tune-in moment. Requests coalesce into
+the next keyframe, and forced keyframes land at least 500ms apart.
+
 The video and audio encoders measure how far their output falls behind the media
 clock when they flush frames. Catalog jitter is the spread above each
 rendition's own recent minimum lateness, so a constant encoder delay is not jitter.

doc/lib/rs/moq-audio.md

@@ -37,7 +37,7 @@ than falling back to the catalog's fields.
 
 Highlights:
 
-- **`encode::Publication`** advertises the track and opens the microphone only while someone listens. Stop, swap devices, and restart without changing the track subscribers know; read a level meter for the UI.
+- **`encode::Control`** advertises the track and opens the microphone only while someone listens. Stop, swap devices, and restart without changing the track subscribers know; read a level meter for the UI.
 - **A/V sync signal.** `Sink::buffered()` reports how far ahead the speaker is, which is what a video clock steers by.
 - **Activity per packet**, read off the Opus stream, so a call UI shows who is talking without a second voice detector.
 - **One Linux build dependency**: ALSA headers, and only when `capture` or `playback` is enabled.

doc/lib/rs/moq-video.md

@@ -21,7 +21,7 @@ ffmpeg, no GStreamer, no system codec to install.
 Highlights:
 
 - **Automatic backend selection**, hardware first. Linux GPU libraries are `dlopen`ed at runtime, so one binary starts anywhere and warns when it falls back to software. openh264 (the default-on `openh264` feature) is statically linked as the H.264 fallback; H.265 is hardware-only; AV1 decodes via NVDEC. The VAAPI encoder, decoder, and GPU resize share one render node: the first whose driver does all three, or the one the `MOQ_VAAPI_DEVICE` environment variable names (for example `/dev/dri/renderD129`).
-- **Publish on demand.** `encode::publish_capture` advertises the track up front and opens the camera only while someone subscribes.
+- **Publish on demand.** `encode::publish_capture` advertises the track up front and opens the camera only while someone subscribes. `encode::Control::new` is the same with a handle kept, the mirror of `moq-audio`'s: `Control::cut()` asks for a keyframe, requests coalesce, and forced keyframes land at least 500ms apart.
 - **GPU ownership where the platform allows.** Matching codec backends consume their native GPU surfaces directly. The renderer imports `CVPixelBuffer` and supported DMA-BUF formats. Linux/NVIDIA producers can import dedicated Vulkan RGBA8 slots into CUDA with timeline-semaphore ordering and completion-driven slot return. Vulkan/CUDA surfaces deliberately have no CPU pixel fallback; other surfaces use the typed `Surface::into_i420()` and configured `Surface::to_rgba(config)` when needed.
 - **Live bitrate control** where the selected backend supports it, without forcing a keyframe. An unsupported backend keeps its opening rate.
 - **Typed group structure.** `encode::Config::gop` is a `Gop` enum (`Keyframe { interval }` today), so a later mode adds a variant instead of replacing the field. `cut()` opens a group at the next frame on both `Encoder` and `Sink`, and refuses with `Error::CutUnsupported` on a backend that cannot force one rather than letting the boundary silently slip to the interval.

js/publish/src/video/encoder.test.ts

@@ -537,3 +537,104 @@ test.each(["encoder lag", "quiet startup"])("marks a rendition stalled for %s",
 		else Reflect.deleteProperty(globalThis, "VideoEncoder");
 	}
 });
+
+test("cut forces a keyframe, coalescing requests and spacing them at least 500ms apart", async () => {
+	const keys: number[] = [];
+	class RecordingVideoEncoder {
+		state: CodecState = "unconfigured";
+
+		static async isConfigSupported(config: VideoEncoderConfig): Promise<{ supported: boolean }> {
+			return { supported: config.codec.startsWith("avc1") };
+		}
+
+		configure(): void {
+			this.state = "configured";
+		}
+
+		encode(frame: VideoFrame, options?: VideoEncoderEncodeOptions): void {
+			if (options?.keyFrame) keys.push(frame.timestamp / 1000);
+		}
+
+		close(): void {
+			this.state = "closed";
+		}
+	}
+
+	const original = Object.getOwnPropertyDescriptor(globalThis, "VideoEncoder");
+	Object.defineProperty(globalThis, "VideoEncoder", {
+		configurable: true,
+		value: RecordingVideoEncoder,
+		writable: true,
+	});
+
+	class Frame {
+		readonly timestamp: number;
+		constructor(timestamp: number) {
+			this.timestamp = timestamp;
+		}
+		clone(): Frame {
+			return new Frame(this.timestamp);
+		}
+		close(): void {}
+	}
+
+	const { Fanout } = await import("../fanout");
+	let controller!: ReadableStreamDefaultController<VideoFrame>;
+	const fanout = new Fanout(
+		new ReadableStream<VideoFrame>({
+			start: (c) => {
+				controller = c;
+			},
+		}),
+		{ clone: (frame) => frame.clone(), release: (frame) => frame.close() },
+	);
+
+	const track = new Moq.Track.Producer("video").accept();
+	const rendition = {
+		config: new Signal(undefined),
+		track: new Signal<Moq.Track.Producer | undefined>(track),
+		close: () => track.close(),
+	};
+	const capture = {
+		in: { source: new Signal({ getSettings: () => ({ frameRate: 30 }), getConstraints: () => ({}) } as never) },
+		out: { display: new Signal({ width: 640, height: 480 }), frames: new Signal(fanout) },
+	};
+	const encoder = new Encoder("video", {
+		enabled: true,
+		broadcast: { video: () => rendition } as never,
+		capture: capture as never,
+	});
+
+	// One frame per 100ms of media time, after calling cut() when `cut` says so.
+	const send = async (millis: number, cut = false) => {
+		if (cut) encoder.cut();
+		controller.enqueue(new Frame(millis * 1000) as unknown as VideoFrame);
+		await new Promise((resolve) => setTimeout(resolve, 5));
+	};
+
+	try {
+		await settle();
+
+		// The opening keyframe serves a request made before it.
+		await send(0, true);
+		await send(100);
+		// Several requests before one frame produce one keyframe.
+		encoder.cut();
+		encoder.cut();
+		await send(600, true);
+		await send(700);
+		// Too soon after the last: deferred until 500ms have passed, not dropped.
+		await send(800, true);
+		await send(1000);
+		await send(1100);
+		await send(1200);
+
+		expect(keys).toEqual([0, 600, 1100]);
+	} finally {
+		encoder.close();
+		fanout.close();
+		track.close();
+		if (original) Object.defineProperty(globalThis, "VideoEncoder", original);
+		else Reflect.deleteProperty(globalThis, "VideoEncoder");
+	}
+});

js/publish/src/video/encoder.ts

@@ -147,6 +147,9 @@ export class Encoder {
 	// doesn't re-probe the hardware.
 	#codecFilter: Computed<string>;
 
+	// A keyframe asked for by {@link cut} and not yet encoded.
+	#cut = false;
+
 	#signals = new Effect();
 	#stalled = new Catalog.Stalled.Detector();
 	#firstCaptured?: Time.Micro;
@@ -326,11 +329,17 @@ export class Encoder {
 
 							const interval = config?.keyframeInterval ?? Time.Milli.fromSecond(2 as Time.Second);
 
-							// Force a keyframe if this is the first frame (no group yet), or GOP elapsed.
+							// Force a keyframe if this is the first frame (no group yet), the GOP elapsed, or
+							// the caller asked for one and the last is old enough.
+							const since = lastKeyframe === undefined ? undefined : frame.timestamp - lastKeyframe;
 							const keyFrame =
-								!lastKeyframe || lastKeyframe + Time.Micro.fromMilli(interval) <= frame.timestamp;
+								since === undefined ||
+								since >= Time.Micro.fromMilli(interval) ||
+								(this.#cut && since >= Time.Micro.fromMilli(MIN_CUT_INTERVAL));
 							if (keyFrame) {
 								lastKeyframe = frame.timestamp as Time.Micro;
+								// Any keyframe serves an outstanding request.
+								this.#cut = false;
 							}
 
 							encoder.encode(frame, { keyFrame });
@@ -664,11 +673,27 @@ export class Encoder {
 		throw new Error("no supported codec");
 	}
 
+	/**
+	 * Request a keyframe, opening a new group at a frame no earlier than this call.
+	 *
+	 * For a resume, a recording cut, or a known tune-in moment; {@link Config.keyframeInterval} is the
+	 * cadence. Requests coalesce into the next keyframe, and forced keyframes land at least 500ms
+	 * apart so a caller in a loop cannot pin the encoder at all-keyframe. A request while not encoding
+	 * is served by the keyframe every encode starts with.
+	 */
+	cut(): void {
+		this.#cut = true;
+	}
+
 	close() {
 		this.#signals.close();
 	}
 }
 
+// The closest two requested keyframes may land. A keyframe costs several times a predicted frame,
+// and this stays well under the default two-second GOP so a request still beats the cadence.
+const MIN_CUT_INTERVAL = 500 as Time.Milli;
+
 // The source's nominal frame rate: what the capture device settled on, or what a frame stream
 // declared. Undefined when nothing reports one.
 function sourceFrameRate(source: Source): number | undefined {

quest/m1/README.md

@@ -59,7 +59,6 @@ transport, benchmark tooling); worktrees isolate commits, not semantics.
 - [NVENC recovery](/quest/m1/nvenc-recovery.md) - partial initialization and rejected rate changes preserve valid state
 - [Transcode source](/quest/m1/transcode-source.md) - select a rendition the chosen backend can actually decode
 - [Egress rendition pick](/quest/m1/egress-rendition-pick.md) - WHEP and single-track RTMP/FLV serve the best rendition, not the first by name
-- [Keyframe trigger](/quest/m1/keyframe-trigger.md) - an application can ask the built-in capture encoder for a keyframe
 - [QoS](/quest/m1/qos/README.md) - broadcast health: relay starvation and timeliness histograms, and client stats broadcasts from publishers and viewers
 - [Drain](/quest/m1/drain/README.md) - relay restarts drain sessions over GOAWAY instead of hard-dropping them
 - [Transport upgrade](/quest/m1/transport-upgrade/README.md) - a session that came up over WebSocket moves to QUIC once the QUIC dial lands, handing over at a group boundary

quest/m1/qos/stats/encoder-feedback.md

@@ -46,5 +46,3 @@ prefix. Keyframe requests stay out.
 
 - [Ladder](/quest/m1/ladder/README.md) - the transcode ladder that adapts to
   its uplink today
-- [Keyframe trigger](/quest/m1/keyframe-trigger.md) - the keyframe request
-  this loop does not send

quest/m2/capture-clock-source.md

@@ -2,17 +2,17 @@
 
 ## Goal
 
-`moq_video::encode::publish_capture` and `moq_audio::encode::Publication` stamp
+`moq_video::encode::publish_capture` and `moq_audio::encode::Control` stamp
 on the clock their catalog advertises, with no separate clock to pass. Today
-each takes its own `moq_mux::Clock`, and `PublicationOptions::default()` builds
+each takes its own `moq_mux::Clock`, and `CaptureOptions::default()` builds
 a fresh one, so a caller relying on the default publishes audio against a
 mapping the catalog never advertised. `moq import capture` passes
 `catalog.clock()` to both, which is the only correct value.
 
 ## Plan
 
 Drop the `clock` parameter from video `publish_capture` and the `clock` field
-from `PublicationOptions`, reading `catalog.clock()` instead. Update moq-cli and
+from `CaptureOptions`, reading `catalog.clock()` instead. Update moq-cli and
 any binding that forwards a clock. The clock fixtures in both crates already
 pass the catalog's clock, so they keep grading the same path.
 

quest/m2/gop-overhead.md

@@ -33,11 +33,6 @@ a verdict on whether a long GOP plus a keyframe request is worth designing.
 A verdict of "2 seconds is fine" is a valid, expected outcome and completes
 this quest.
 
-## Related
-
-- [Keyframe trigger](/quest/m1/keyframe-trigger.md) - the publisher-side half a
-  keyframe request would drive, useful on its own
-
 ## Closes
 
 - [#2284](https://github.com/moq-dev/moq/issues/2284) - close this issue when the quest finishes