Skip to content
Closed
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
11 changes: 11 additions & 0 deletions bun.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

24 changes: 24 additions & 0 deletions js/media-sync/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# @moq/media-sync

Transport-neutral media clock, pacing, and generation-safe per-track delivery queues.
No dependencies: no transport, container, decoder, or renderer.

```ts
import { MediaSync } from "@moq/media-sync";

const sync = new MediaSync({ buffer: { video: 50, audio: 100 }, timestampScale: 1_000 }); // µs timestamps
sync.enqueue(frame.timestamp, "video", async (signal) => {
const decoded = await decode(frame, signal); // stage the effect
return () => render(decoded); // commit only if the generation is still current
});
sync.cancel("video"); // retire the video generation: staged commits are discarded
```

- `received(timestamp)` seeds the clock. It must run before `wait()`, which throws on an unseeded clock.
- `timestampScale` is the number of media timestamp units per clock unit, so callers keep their own units.
- `cancel(kind)` and `reset()` retire a generation: nothing staged before the retirement commits after it,
including stages that are mid-`await`, and timestamps may be reused afterwards.
- `reset()` also clears the clock and wakes every waiter, so parked waits release.

`@moq/media-sync/vectors` exports the clock, pacing, and retirement vectors, so a wrapper that adapts units
or callbacks can be tested against the same cases as the core.
28 changes: 28 additions & 0 deletions js/media-sync/package.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
{
"name": "@moq/media-sync",
"type": "module",
"version": "0.1.0",
"description": "Transport-neutral media clock, pacing, and generation-safe delivery queues.",
"license": "(MIT OR Apache-2.0)",
"repository": {
"type": "git",
"url": "git+https://github.com/moq-dev/moq.git",
"directory": "js/media-sync"
},
"sideEffects": false,
"exports": {
".": "./src/index.ts",
"./vectors": "./src/vectors.ts"
},
"scripts": {
"build": "rimraf dist && tsc -b tsconfig.build.json && bun ../common/package.ts",
"check": "tsc --noEmit",
"test": "bun test --only-failures",
"release": "bun ../common/release.ts"
},
"devDependencies": {
"@types/bun": "^1.4.2",
"rimraf": "^6.1.3",
"typescript": "7.0.2"
}
}
147 changes: 147 additions & 0 deletions js/media-sync/src/index.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,147 @@
import { describe, expect, it } from "bun:test";
import { MediaSync } from "./index.ts";
import { MEDIA_SYNC_CLOCK_VECTORS, MEDIA_SYNC_DELIVERY_VECTORS, MEDIA_SYNC_PACING_VECTORS } from "./vectors.ts";

describe("MediaSync", () => {
for (const vector of MEDIA_SYNC_CLOCK_VECTORS) {
it(`runs the shared clock vector: ${vector.name}`, () => {
let now: number = vector.anchorClock;
const sync = new MediaSync({
now: () => now,
buffer: vector.buffer,
timestampScale: vector.timestampScale,
});
sync.received(vector.anchorTimestamp);
now = vector.readClock;

expect(sync.reference).toBe(vector.expected.reference);
expect(sync.timestamp).toBe(vector.expected.timestamp);
expect(sync.now("video")).toBe(vector.expected.videoNow);
expect(sync.now("audio")).toBe(vector.expected.audioNow);
});
}

for (const vector of MEDIA_SYNC_PACING_VECTORS) {
it(`runs the shared pacing vector: ${vector.name}`, async () => {
let now: number = vector.anchorClockMs;
const sync = new MediaSync({ now: () => now, buffer: vector.bufferMs });
sync.received(vector.anchorTimestampMs);
now = vector.earlyClockMs;
sync.received(vector.deliveryTimestampMs);
let delivered = false;
sync.enqueue(vector.deliveryTimestampMs, vector.kind, () => () => (delivered = true));
await Promise.resolve();
await Promise.resolve();
expect(delivered).toBe(false);

now = vector.dueClockMs;
sync.received(vector.anchorTimestampMs);
await sync.drain(vector.kind);
expect(delivered).toBe(true);
});
}

it("clears clock state on reset", () => {
const sync = new MediaSync({ now: () => 1_000 });
sync.received(900);
sync.reset();
expect(sync.reference).toBeUndefined();
expect(sync.timestamp).toBeUndefined();
});

for (const vector of MEDIA_SYNC_DELIVERY_VECTORS) {
it(`prevents post-await and queued commits after ${vector.name}`, async () => {
const sync = new MediaSync({ now: () => 0 });
const started = Promise.withResolvers<void>();
const release = Promise.withResolvers<void>();
const delivered: number[] = [];
const signal = sync.captureSignal(vector.kind);
const retire = () => {
if (vector.retire === "cancel") sync.cancel(vector.kind);
else sync.reset();
};

sync.enqueue(
vector.firstTimestampMs,
vector.kind,
async () => {
started.resolve();
await release.promise;
return () => delivered.push(1);
},
undefined,
signal,
false,
);
sync.enqueue(
vector.queuedTimestampMs,
vector.kind,
() => () => delivered.push(2),
undefined,
signal,
false,
);

await started.promise;
retire();
release.resolve();
await Promise.resolve();
await Promise.resolve();

expect(signal.aborted).toBe(true);
expect(delivered).toEqual([]);
});

it(`accepts timestamp reuse after ${vector.name}`, async () => {
const sync = new MediaSync({ now: () => 0 });
let delivered = 0;
const retire = () => {
if (vector.retire === "cancel") sync.cancel(vector.kind);
else sync.reset();
};
const enqueue = () =>
sync.enqueue(
vector.reusedTimestampMs,
vector.kind,
() => () => delivered++,
undefined,
undefined,
false,
);
enqueue();
await sync.drain(vector.kind);
retire();
enqueue();
await sync.drain(vector.kind);
expect(delivered).toBe(2);
});
}

it("does not advance clock state for a canceled speculative delivery", () => {
let now = 1_000;
const sync = new MediaSync({ now: () => now });
sync.received(900);

now = 1_010;
sync.enqueue(950, "video", () => () => undefined, undefined, undefined, false);
sync.cancel("video");

expect(sync.reference).toBe(100);
expect(sync.timestamp).toBe(900);
});

it("reports a synchronous immediate-stage failure", () => {
const sync = new MediaSync();
let failure: unknown;
sync.deliver(
"video",
() => {
throw new Error("stage failed");
},
(error) => {
failure = error;
},
);
expect(failure).toBeInstanceOf(Error);
});
});
Loading
Loading