Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion doc/lib/js/publish.md
Original file line number Diff line number Diff line change
Expand Up @@ -173,7 +173,9 @@ running. It does not retry on demand or bandwidth changes, and enable cycles
that keep the same capture do not retry. A new capture source (such as the
track a camera or microphone reopens after a device swap), changed encoder settings, or
a replacement encoder recovers it. Recovery keeps the catalog ID and uses a
fresh `track` name.
fresh `track` name. A new network broadcast (a rename or a `maxAge` change)
also starts the encoder over, under the catalog ID, with its advertised
maxima reset.

## Strict CSP

Expand Down
1 change: 1 addition & 0 deletions js/publish/src/audio/capture.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -559,6 +559,7 @@ test("a failed encoder stays failed until the capture source changes", async ()
const capture = new Capture({ enabled, source: source as never });
const track = new Moq.Track.Producer("audio").accept({ timescale: Moq.Time.Timescale.MILLI });
const rendition = {
slot: new Signal(undefined),
config: new Signal(undefined),
track: new Signal<Moq.Track.Producer | undefined>(track),
close: () => {},
Expand Down
1 change: 1 addition & 0 deletions js/publish/src/audio/encoder.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -291,6 +291,7 @@ async function setup(order = new Order(), codec?: Codec, groupDuration?: Milli)
};

const rendition = {
slot: new Signal(undefined),
config: new Signal(undefined),
track: new Signal<Moq.Track.Producer | undefined>(track),
close: () => {
Expand Down
68 changes: 36 additions & 32 deletions js/publish/src/audio/encoder.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,14 @@ import {
type Getter,
getter,
type Inputs,
Once,
type Readonlys,
readonlys,
Signal,
} from "@moq/signals";
import type { Broadcast } from "../broadcast";
import { errors, watched } from "../internal";
import { watched } from "../internal";
import { Estimator, type Order } from "../order";
import { Slot } from "../publication";
import type { AudioFrame, Capture, Format } from "./capture";
import { Gain } from "./gain";
import { Resampler } from "./resampler";
Expand Down Expand Up @@ -233,18 +233,18 @@ export class Encoder {
*/
readonly settled: Computed<boolean>;

// Each registration keeps its terminal failure even after the public error clears.
#failure = new Signal(new Once<Error>());
// The capture inputs #runCaptureRecovery last saw, carried across a gap in the source or format.
#seen?: { capture?: Capture; source?: unknown; format?: Format };
#signals = new Effect();
#estimator = new Estimator();
// The estimator's delay, republished whenever it rises.
#estimate = new Signal<Estimator["estimate"]>({});
// What this rendition advertised on each broadcast, keyed by the broadcast or, with none, the
// encoder. A broadcast keeps a rendition's track when it re-registers, so returning to one
// continues its bitrate maximum and last config, while another broadcast starts its own.
#advertised = new WeakMap<object, { bitrate: number; last?: Catalog.AudioConfig }>();
// What this rendition keeps for the current network broadcast's track: its bitrate maximum, last
// config, and failure. A network broadcast keeps a rendition's track when it re-registers, so
// returning to one continues them, while a new one starts its own.
#slot = new Signal<Slot<Catalog.AudioConfig> | undefined>(undefined);
// The slot while no network broadcast is serving the rendition.
#local = new Slot<Catalog.AudioConfig>();
// Whether the rendition was disabled since a config last resolved, so it keeps advertising its last
// config as disabled until the re-enabled capture resolves a new one. A capture that never reopens
// leaves it disabled, which is accurate: no frames are coming.
Expand Down Expand Up @@ -298,6 +298,7 @@ export class Encoder {
}
});
}
this.#signals.run(this.#runError.bind(this));
this.#signals.run(this.#runSettingsRecovery.bind(this));
this.#signals.run(this.#runCaptureRecovery.bind(this));
this.#signals.run(this.#runRegister.bind(this));
Expand Down Expand Up @@ -376,24 +377,34 @@ export class Encoder {
this.#rearm();
}

// Clear a latched failure so a fresh registration retries.
// The current slot, read through `effect`.
#current(effect: Effect): Slot<Catalog.AudioConfig> {
return effect.get(this.#slot) ?? this.#local;
}

// The public error is the current slot's, so a new network broadcast starts without one.
#runError(effect: Effect): void {
effect.set(this.#out.error, effect.get(this.#current(effect).error));
}

// Clear a latched failure, so the broadcast serves the rendition again under a fresh track name.
#rearm(): void {
if (!this.#out.error.peek()) return;
this.#out.error.set(undefined);
const failure = (this.#slot.peek() ?? this.#local).error;
if (!failure.peek()) return;
failure.set(undefined);
this.#floor = undefined;
this.#failure.set(new Once<Error>());
}

// Register the rendition on the broadcast, publish its config, and encode while it hands over a
// track. Re-registers cleanly when the broadcast swaps.
#runRegister(effect: Effect): void {
const failure = effect.get(this.#failure);
const broadcast = effect.get(this.in.broadcast);
if (!broadcast) return;

const rendition = broadcast.audio(this.name);
errors.set(rendition, failure);
effect.cleanup(() => rendition.close());
effect.proxy(this.#slot, rendition.slot);
effect.cleanup(() => this.#slot.set(undefined));

// Publish the resolved config; undefined (no capture) drops it from the catalog.
effect.proxy(rendition.config, this.out.catalog);
Expand Down Expand Up @@ -436,12 +447,10 @@ export class Encoder {
const capture = effect.get(this.in.capture);
const format = capture ? effect.get(capture.out.format) : undefined;
const track = effect.get(rendition.track);
// A dead encoder can't serve anyone: the broadcast aborts its track with the real error, so
// the current subscriber and every later one get it rather than a track that stays silent.
const fatal = effect.get(this.#out.error);

// A dead encoder can't serve anyone, so the current subscriber and every later one get
// the real error rather than a track that stays silent.
if (fatal) track?.abort(fatal);

const onDemand = effect.get(broadcast.in.onDemand) ?? true;
const demanded = track && effect.get(track.demand().wanted) !== undefined;
this.#encoding = enabled && !!format && !!track && !fatal && (!onDemand || !!demanded);
Expand Down Expand Up @@ -581,27 +590,22 @@ export class Encoder {
#runCatalog(effect: Effect): void {
const estimate = effect.get(this.#estimate);
const enabled = effect.get(this.in.enabled) && !effect.get(this.#out.error);
const key = effect.get(this.in.broadcast) ?? this;
let track = this.#advertised.get(key);
if (!track) {
track = { bitrate: 0 };
this.#advertised.set(key, track);
}
const slot = this.#current(effect);
if (!enabled) this.#paused = true;
const config = enabled ? effect.get(this.#config)?.catalog : undefined;
if (!config) {
const last = this.#paused ? track.last : undefined;
const last = this.#paused ? slot.last : undefined;
effect.set(this.#out.catalog, last && { ...last, ...estimate, enabled: false });
return;
}
this.#paused = false;

// The catalog bitrate is the most this track has been configured for, so lowering the knob
// retunes the encoder without lowering what the catalog advertises.
track.bitrate = Math.max(track.bitrate, config.bitrate ?? 0);
const bitrate = track.bitrate > 0 ? Catalog.u53(track.bitrate) : undefined;
track.last = { ...config, bitrate, ...estimate };
effect.set(this.#out.catalog, track.last);
slot.bitrate = Math.max(slot.bitrate, config.bitrate ?? 0);
const bitrate = slot.bitrate > 0 ? Catalog.u53(slot.bitrate) : undefined;
slot.last = { ...config, bitrate, ...estimate };
effect.set(this.#out.catalog, slot.last);
}

// Collect the encode-only Opus knobs that are set, reading the codec through the effect so the
Expand Down Expand Up @@ -810,10 +814,10 @@ export class Encoder {
}

#abort(error: unknown): void {
if (this.#out.error.peek()) return;
const failure = (this.#slot.peek() ?? this.#local).error;
if (failure.peek()) return;
const cause = error instanceof Error ? error : new Error(String(error));
this.#failure.peek().set(cause);
this.#out.error.set(cause);
failure.set(cause);
this.#live?.track.abort(cause);
}

Expand Down
130 changes: 130 additions & 0 deletions js/publish/src/broadcast.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -761,3 +761,133 @@ test("identity changes before the first announce take a fresh track name", async

broadcast.close();
});

// Identity follows hang's `same_identity`: interlacing reinitializes a video decoder.
test("an interlacing change takes a fresh track name", async () => {
const broadcast = new Broadcast({ origin: new Origin.Producer(), name: Path.from("interlaced.hang") });
const video = broadcast.video("video");
video.config.set(videoConfig);
await settle();
video.config.set({ ...videoConfig, interlaced: true });
await settle();
expect((await readCatalog(broadcast))?.video?.renditions.video?.track).toBe("video/1");
expect(video.track.peek()?.name).toBe("video/1");

broadcast.close();
});

// Names belong to one network broadcast, so a new one serves each rendition under its ID again.
test("a new network broadcast starts every track name over", async () => {
const name = new Signal(Path.from("one.hang"));
const broadcast = new Broadcast({ origin: new Origin.Producer(), name });
const video = broadcast.video("video");
video.config.set(videoConfig);
await settle();
video.config.set({ ...videoConfig, codec: "vp8" });
await settle();
expect((await readCatalog(broadcast))?.video?.renditions.video?.track).toBe("video/1");
expect(() => broadcast.video("video/1")).toThrow("replacement track");

name.set(Path.from("two.hang"));
await settle();
expect((await readCatalog(broadcast))?.video?.renditions.video?.track).toBeUndefined();
expect(video.track.peek()?.name).toBe("video");
expect(video.track.peek()?.appendGroup().sequence).toBe(0);
expect(() => broadcast.video("video/1").close()).not.toThrow();

broadcast.close();
});

// A fold that throws publishes nothing, so it must not move a track the catalog still lists.
test("a refused catalog fold renames no track", async () => {
const broadcast = new Broadcast({ origin: new Origin.Producer(), name: Path.from("refused.hang") });
const video = broadcast.video("video");
const audio = broadcast.audio("audio");
video.config.set(videoConfig);
await settle();
const track = video.track.peek();

video.config.set({ ...videoConfig, codec: "vp8" });
audio.config.set({ ...audioConfig, track: "elsewhere" });
await settle();
expect(video.track.peek()).toBe(track);
expect(track?.closed.peek()).toBeUndefined();
expect((await readCatalog(broadcast))?.video?.renditions.video?.codec).toBe(videoConfig.codec);

// Once the fold succeeds, the new identity moves to a fresh name.
audio.config.set(audioConfig);
await settle();
expect((await readCatalog(broadcast))?.video?.renditions.video?.track).toBe("video/1");
expect(video.track.peek()?.name).toBe("video/1");

broadcast.close();
});

// A failure keeps the rendition down, even across a sibling's registration, until it clears. The
// rendition then recovers under a fresh track name, so its group sequence can start over.
test("a failed rendition stays down until its failure clears", async () => {
const broadcast = new Broadcast({ origin: new Origin.Producer(), name: Path.from("failed.hang") });
const video = broadcast.video("video");
video.config.set(videoConfig);
await settle();
const track = video.track.peek();
const slot = video.slot.peek();
if (!track || !slot) throw new Error("expected a served rendition");

const failure = new Error("encoder failed");
slot.error.set(failure);
await settle();
expect(track.closed.peek()).toBe(failure);
expect(video.track.peek()).toBeUndefined();
broadcast.audio("audio").config.set(audioConfig);
await settle();
expect(video.track.peek()).toBeUndefined();

slot.error.set(undefined);
await settle();
expect(video.track.peek()?.name).toBe("video/1");
expect((await readCatalog(broadcast))?.video?.renditions.video?.track).toBe("video/1");

broadcast.close();
});

// A producer may abort its track itself, which fails the rendition's slot the same way.
test("aborting a rendition's track fails its slot", async () => {
const broadcast = new Broadcast({ origin: new Origin.Producer(), name: Path.from("aborted.hang") });
const video = broadcast.video("video");
video.config.set(videoConfig);
await settle();
const failure = new Error("encoder failed");
video.track.peek()?.abort(failure);
await settle();
expect(video.slot.peek()?.error.peek()).toBe(failure);

broadcast.close();
});

// What a producer keeps for a rendition belongs to one network broadcast, so a new one starts it over.
test("a new network broadcast starts each rendition's slot over", async () => {
const name = new Signal(Path.from("one.hang"));
const broadcast = new Broadcast({ origin: new Origin.Producer(), name });
const video = broadcast.video("video");
video.config.set(videoConfig);
await settle();
const first = video.slot.peek();
if (!first) throw new Error("expected a slot");
first.bitrate = 1_000_000;
first.error.set(new Error("encoder failed"));
await settle();
expect(video.track.peek()).toBeUndefined();

name.set(Path.from("two.hang"));
await settle();
const second = video.slot.peek();
expect(second).toBeDefined();
expect(second).not.toBe(first);
expect(second?.bitrate).toBe(0);
expect(second?.error.peek()).toBeUndefined();
expect(video.track.peek()?.name).toBe("video");
expect(video.track.peek()?.closed.peek()).toBeUndefined();

broadcast.close();
});
Loading