@eventual-ai/mcap-viewer 0.1.0-alpha.0 → 0.1.0-alpha.2

package/README.md

@@ -1,8 +1,8 @@
 # @eventual-ai/mcap-viewer
 
 A TypeScript browser SDK for playing native H.264/H.265 video from streamed MCAP
-recordings. `/core` plays MCAP video topics; `/data-loader` handles the replay
-service. The package root exports both.
+recordings. `/core` plays MCAP video topics; `/data-loader` handles the MCAP
+Delivery API (MDA). The package root exports both.
 
 ```sh
 npm install @eventual-ai/mcap-viewer@alpha
@@ -11,12 +11,12 @@ npm install @eventual-ai/mcap-viewer@alpha
 ```ts
 import {
   McapRecording,
-  ReplayPlayer,
+  Player,
   ImageRenderer,
 } from "@eventual-ai/mcap-viewer/core";
 
 const recording = await McapRecording.open(url, { signal });
-const player = new ReplayPlayer(recording);
+const player = new Player(recording);
 const renderer = new ImageRenderer(canvas, { imageTopic: "head_left" });
 player.subscribe(renderer);
 await player.seek(recording.start);
@@ -28,34 +28,36 @@ by `logTime`; unordered input fails. Do not await `recording.loaded` before play
 Observe loading and late errors with `recording.subscribe`; call `player.close()`,
 `recording.close()` and `renderer.destroy()` when unmounting.
 
-The core plays `eventual.replay.v1.CompressedVideo`, the only schema the service
+The core plays `eventual.mda.v1.CompressedVideo`, the only schema the service
 serves: native H.264/HEVC packets with their decode order, in ZSTD-compressed MCAP
 with embedded Protobuf schemas. Times remain `bigint` nanoseconds.
 
 ```ts
-import { ReplayDataLoader } from "@eventual-ai/mcap-viewer/data-loader";
+import { DataLoader } from "@eventual-ai/mcap-viewer/data-loader";
 
-const loader = new ReplayDataLoader({
-  baseUrl: REPLAY_URL,
+const loader = new DataLoader({
+  baseUrl: MDA_URL,
   headers: { Authorization: `Bearer ${token}` },
 });
 const topics = await loader.discover(datasource);
-const [span] = await loader.manifest({
+const [result] = await loader.manifest({
   datasource,
   topics: ["head_left"],
   spans: [{ id: episodeId, start: 10, end: 20 }],
 });
-const recording = await loader.openSpan(span, { signal });
+const recording = await loader.openSpan(result, { signal });
 ```
 
 Each manifest supplies one streamed MCAP URL. Payload requests omit control
-credentials. The loader applies the requested span bounds. `discover` maps topic
+credentials. Playback covers the requested span, which the MCAP records in its
+`mda` metadata, so `McapRecording.open` on a saved file starts at the same time
+(`bounds: null` keeps the keyframe preroll). `discover` maps topic
 names to canonical schemas and actual wire encodings:
 
 ```json
 {
   "head_left": {
-    "schema": "eventual.replay.v1.CompressedVideo",
+    "schema": "eventual.mda.v1.CompressedVideo",
     "schema_encoding": "protobuf",
     "message_encoding": "protobuf"
   }
@@ -67,5 +69,4 @@ names to canonical schemas and actual wire encodings:
 Video requires WebCodecs over HTTPS or localhost; available codecs depend on the
 browser and device. Unsupported codecs report an error through `renderer.onError`.
 
-The package bundles its dependencies; their licenses are in
-`dist/THIRD_PARTY_LICENSES.md`. MIT licensed.
+MIT licensed.

package/dist/{types/core → core}/index.d.ts

@@ -1,6 +1,6 @@
 export { BlobSource, HttpSource, McapRecording } from "./mcap/index.js";
-export type { McapStreamSource, LoadOptions, ReadOptions, Recording, RecordingLoadState, ReplayMessage, TimeBounds, Topic, } from "./mcap/index.js";
-export { ReplayPlayer } from "./playback/index.js";
+export type { McapStreamSource, LoadOptions, ReadOptions, Recording, RecordingLoadState, Message, TimeBounds, Topic, } from "./mcap/index.js";
+export { Player } from "./playback/index.js";
 export type { PlaybackListener, PlaybackState, Scheduler, SubscriptionOptions, } from "./playback/index.js";
 export { ImageRenderer } from "./renderers/index.js";
 export type { ImageRendererOptions } from "./renderers/index.js";

package/dist/core/index.js

@@ -0,0 +1,3 @@
+export { BlobSource, HttpSource, McapRecording } from "./mcap/index.js";
+export { Player } from "./playback/index.js";
+export { ImageRenderer } from "./renderers/index.js";

package/dist/core/mcap/codecs/h264.js

@@ -0,0 +1,22 @@
+export function inspectAccessUnit(bytes) {
+    let keyframe = false;
+    let codec;
+    for (let index = 0; index + 3 < bytes.length; index++) {
+        if (bytes[index] !== 0 || bytes[index + 1] !== 0)
+            continue;
+        let header = -1;
+        if (bytes[index + 2] === 1)
+            header = index + 3;
+        else if (bytes[index + 2] === 0 && bytes[index + 3] === 1)
+            header = index + 4;
+        if (header < 0 || header >= bytes.length)
+            continue;
+        const kind = bytes[header] & 31;
+        if (kind === 5)
+            keyframe = true;
+        if (kind === 7 && header + 3 < bytes.length)
+            codec = `avc1.${Array.from(bytes.slice(header + 1, header + 4), (value) => value.toString(16).padStart(2, "0")).join("")}`;
+        index = header;
+    }
+    return { keyframe, codec };
+}

package/dist/{types/core → core}/mcap/codecs/video.d.ts

@@ -1,5 +1,6 @@
-export interface VideoAccessUnit {
+interface VideoAccessUnit {
     keyframe: boolean;
     codec?: string;
 }
 export declare function inspectVideo(bytes: Uint8Array, format: string): VideoAccessUnit;
+export {};

package/dist/core/mcap/codecs/video.js

@@ -0,0 +1,64 @@
+import { inspectAccessUnit } from "./h264.js";
+export function inspectVideo(bytes, format) {
+    if (format === "h264")
+        return inspectAccessUnit(bytes);
+    if (format !== "h265")
+        throw new Error(`Unsupported video format: ${format}`);
+    let keyframe = false;
+    let codec;
+    const units = [];
+    let begin = -1;
+    for (let index = 0; index + 3 < bytes.length; index++) {
+        if (bytes[index] !== 0 || bytes[index + 1] !== 0)
+            continue;
+        const length = bytes[index + 2] === 1
+            ? 3
+            : bytes[index + 2] === 0 && bytes[index + 3] === 1
+                ? 4
+                : 0;
+        if (!length)
+            continue;
+        if (begin >= 0)
+            units.push(bytes.subarray(begin, index));
+        begin = index + length;
+        index = begin - 1;
+    }
+    if (begin >= 0)
+        units.push(bytes.subarray(begin));
+    const parameterSets = new Set();
+    for (const unit of units) {
+        const kind = (unit[0] >> 1) & 63;
+        if (kind >= 16 && kind <= 21)
+            keyframe = true;
+        if (kind >= 32 && kind <= 34)
+            parameterSets.add(kind);
+        if (kind !== 33)
+            continue;
+        const rbsp = [];
+        for (let index = 2; index < unit.length; index++) {
+            if (index >= 4 &&
+                unit[index] === 3 &&
+                unit[index - 1] === 0 &&
+                unit[index - 2] === 0)
+                continue;
+            rbsp.push(unit[index]);
+        }
+        if (rbsp.length < 13)
+            continue;
+        const profile = rbsp[1];
+        let compatibility = 0;
+        for (let bit = 0; bit < 32; bit++)
+            compatibility +=
+                ((rbsp[2 + (bit >> 3)] >> (7 - (bit & 7))) & 1) * 2 ** bit;
+        const constraints = rbsp.slice(6, 12);
+        while (constraints.length && constraints.at(-1) === 0)
+            constraints.pop();
+        const suffix = constraints
+            .map((value) => value.toString(16).toUpperCase().padStart(2, "0"))
+            .join(".");
+        codec = `hvc1.${["", "A", "B", "C"][profile >> 6]}${profile & 31}.${compatibility.toString(16).toUpperCase()}.${profile & 32 ? "H" : "L"}${rbsp[12]}${suffix ? `.${suffix}` : ""}`;
+    }
+    if (parameterSets.size !== 3)
+        codec = undefined;
+    return { keyframe, codec };
+}

package/dist/{types/core → core}/mcap/index.d.ts

@@ -2,4 +2,4 @@ export { McapRecording } from "./recording.js";
 export { BlobSource, HttpSource } from "./source.js";
 export type { McapStreamSource, LoadOptions } from "./source.js";
 export type { ReadOptions } from "./reader.js";
-export type { Recording, RecordingLoadState, ReplayMessage, TimeBounds, Topic, } from "./types.js";
+export type { Recording, RecordingLoadState, Message, TimeBounds, Topic, } from "./types.js";

package/dist/core/mcap/index.js

@@ -0,0 +1,2 @@
+export { McapRecording } from "./recording.js";
+export { BlobSource, HttpSource } from "./source.js";

package/dist/core/mcap/loading.js

@@ -0,0 +1,50 @@
+export class RecordingLoad {
+    bufferedEnd;
+    error;
+    complete = false;
+    loaded;
+    controller = new AbortController();
+    resolve;
+    reject;
+    listeners = new Set();
+    constructor() {
+        this.loaded = new Promise((resolve, reject) => {
+            this.resolve = resolve;
+            this.reject = reject;
+        });
+        void this.loaded.catch(() => { });
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    advance(time) {
+        this.bufferedEnd = time;
+        this.emit();
+    }
+    finish() {
+        if (this.error)
+            return;
+        this.complete = true;
+        this.resolve();
+        this.emit();
+    }
+    fail(error) {
+        if (this.complete || this.error)
+            return;
+        this.error = error instanceof Error ? error : new Error(String(error));
+        this.reject(this.error);
+        this.emit();
+    }
+    close() {
+        if (this.complete || this.error)
+            return;
+        this.controller.abort(new DOMException("MCAP recording closed", "AbortError"));
+    }
+    emit() {
+        for (const listener of this.listeners)
+            listener();
+    }
+}

package/dist/{types/core → core}/mcap/reader.d.ts

@@ -3,6 +3,11 @@ import type { LoadOptions, McapStreamSource } from "./source.js";
 import { McapRecording } from "./recording.js";
 import type { TimeBounds } from "./types.js";
 export interface ReadOptions extends LoadOptions {
-    bounds?: TimeBounds;
+    /**
+     * Playback bounds. By default, the span MDA records in `mda` metadata
+     * (`start_ns`, exclusive `end_ns`), whose file starts at the preceding
+     * keyframe; `null` plays every message.
+     */
+    bounds?: TimeBounds | null;
 }
 export declare function readMcap(input: Blob | McapStreamSource, options?: ReadOptions): Promise<McapRecording>;

package/dist/core/mcap/reader.js

@@ -0,0 +1,141 @@
+import { McapStreamReader } from "@mcap/core";
+import protobuf from "protobufjs";
+import "protobufjs/ext/descriptor/index.js";
+import { ZSTDDecoder } from "zstddec";
+import { BlobSource } from "./source.js";
+import { RecordingLoad } from "./loading.js";
+import { McapRecording } from "./recording.js";
+const zstd = new ZSTDDecoder();
+/** Decode messages with their embedded Protobuf schema; other encodings stay raw bytes. */
+function decoder(channel, schema) {
+    if (channel.messageEncoding !== "protobuf" || schema?.encoding !== "protobuf")
+        return (bytes) => bytes;
+    const root = protobuf.Root;
+    const type = root.fromDescriptor(schema.data).lookupType(schema.name);
+    return (bytes) => type.toObject(type.decode(bytes), {
+        defaults: true,
+        longs: String,
+        bytes: Uint8Array,
+    });
+}
+export async function readMcap(input, options = {}) {
+    options.signal?.throwIfAborted();
+    await zstd.init();
+    options.signal?.throwIfAborted();
+    const loading = new RecordingLoad();
+    const signal = options.signal
+        ? AbortSignal.any([options.signal, loading.controller.signal])
+        : loading.controller.signal;
+    const source = input instanceof Blob ? new BlobSource(input) : input;
+    const reader = new McapStreamReader({
+        validateCrcs: true,
+        decompressHandlers: {
+            zstd: (bytes, size) => zstd.decode(bytes, Number(size)),
+        },
+    });
+    const schemas = new Map();
+    const channels = new Map();
+    const decoders = new Map();
+    const byTopic = new Map();
+    const messages = [];
+    const metadata = new Map();
+    let recording = new McapRecording(metadata, channels, messages, byTopic, loading, options.bounds ?? undefined);
+    let opened = false;
+    let resolveReady;
+    let rejectReady;
+    const ready = new Promise((resolve, reject) => {
+        resolveReady = resolve;
+        rejectReady = reject;
+    });
+    const open = () => {
+        opened = true;
+        resolveReady(recording);
+    };
+    // MDA writes its metadata before any message, so bounds are set before `open`.
+    const applyMdaBounds = (record) => {
+        if (options.bounds !== undefined || opened)
+            return;
+        const start = record.get("start_ns");
+        const end = record.get("end_ns");
+        if (start !== undefined && end !== undefined)
+            recording = recording.withBounds({
+                start: BigInt(start),
+                end: BigInt(end) - 1n,
+            });
+    };
+    async function consume() {
+        let lastTime;
+        for await (const bytes of source.stream({ signal })) {
+            signal.throwIfAborted();
+            if (!bytes.length)
+                continue;
+            reader.append(bytes);
+            let bufferedEnd = loading.bufferedEnd;
+            for (let record = reader.nextRecord(); record; record = reader.nextRecord()) {
+                signal.throwIfAborted();
+                if (record.type === "Schema")
+                    schemas.set(record.id, record);
+                else if (record.type === "Metadata") {
+                    metadata.set(record.name, record.metadata);
+                    if (record.name === "mda")
+                        applyMdaBounds(record.metadata);
+                }
+                else if (record.type === "Channel") {
+                    // The summary section repeats channels; keep the objects messages reference.
+                    if (channels.has(record.id))
+                        continue;
+                    const schema = schemas.get(record.schemaId);
+                    const channel = {
+                        id: record.id,
+                        topic: record.topic,
+                        schemaName: schema?.name,
+                        encoding: record.messageEncoding,
+                        schemaEncoding: schema?.encoding,
+                        schemaData: schema?.data,
+                        metadata: record.metadata,
+                    };
+                    channels.set(record.id, channel);
+                    decoders.set(record.id, decoder(record, schema));
+                    if (!byTopic.has(channel.topic))
+                        byTopic.set(channel.topic, []);
+                }
+                else if (record.type === "Message") {
+                    if (lastTime !== undefined && record.logTime < lastTime)
+                        throw new Error("MCAP messages must be ordered by logTime");
+                    if (lastTime !== undefined && record.logTime > lastTime)
+                        bufferedEnd = record.logTime - 1n;
+                    lastTime = record.logTime;
+                    const channel = channels.get(record.channelId);
+                    const decode = decoders.get(record.channelId);
+                    if (!channel || !decode)
+                        throw new Error(`Missing MCAP channel ${record.channelId}`);
+                    const message = {
+                        channel,
+                        time: record.logTime,
+                        publishTime: record.publishTime,
+                        sequence: record.sequence,
+                        value: decode(record.data),
+                        data: record.data,
+                    };
+                    messages.push(message);
+                    byTopic.get(channel.topic).push(message);
+                }
+            }
+            if (bufferedEnd !== undefined && bufferedEnd !== loading.bufferedEnd) {
+                loading.advance(bufferedEnd);
+                if (recording.bufferedEnd !== undefined)
+                    open();
+            }
+        }
+        signal.throwIfAborted();
+        if (!reader.done())
+            throw new Error("Incomplete MCAP recording");
+        loading.finish();
+        open();
+    }
+    void consume().catch((error) => {
+        loading.fail(error);
+        rejectReady(error);
+    });
+    return ready;
+}

package/dist/{types/core → core}/mcap/recording.d.ts

@@ -1,17 +1,17 @@
-import type { Recording, RecordingLoadState, ReplayMessage, TimeBounds, Topic } from "./types.js";
+import type { Recording, RecordingLoadState, Message, TimeBounds, Topic } from "./types.js";
 import type { ReadOptions } from "./reader.js";
 import type { McapStreamSource } from "./source.js";
 import type { RecordingLoad } from "./loading.js";
 export declare class McapRecording implements Recording {
     readonly metadata: ReadonlyMap<string, ReadonlyMap<string, string>>;
     readonly channels: ReadonlyMap<number, Topic>;
-    readonly messages: readonly ReplayMessage[];
-    readonly byTopic: ReadonlyMap<string, readonly ReplayMessage[]>;
+    readonly messages: readonly Message[];
+    readonly byTopic: ReadonlyMap<string, readonly Message[]>;
     private readonly loading;
     readonly bounds?: TimeBounds | undefined;
     /** Stream an MCAP file, URL, or byte source independently of a backend. */
     static open(input: Blob | McapStreamSource | string | URL, options?: ReadOptions): Promise<McapRecording>;
-    constructor(metadata: ReadonlyMap<string, ReadonlyMap<string, string>>, channels: ReadonlyMap<number, Topic>, messages: readonly ReplayMessage[], byTopic: ReadonlyMap<string, readonly ReplayMessage[]>, loading: RecordingLoad, bounds?: TimeBounds | undefined);
+    constructor(metadata: ReadonlyMap<string, ReadonlyMap<string, string>>, channels: ReadonlyMap<number, Topic>, messages: readonly Message[], byTopic: ReadonlyMap<string, readonly Message[]>, loading: RecordingLoad, bounds?: TimeBounds | undefined);
     get start(): bigint;
     get end(): bigint;
     get counts(): Readonly<Record<string, number>>;
@@ -21,7 +21,10 @@ export declare class McapRecording implements Recording {
     get loaded(): Promise<void>;
     /** Observe buffered playback coverage, completion, or a loading error. */
     subscribe(listener: (state: RecordingLoadState) => void): () => void;
-    /** Cancel the shared source load for this recording and all bounded views. */
+    /**
+     * Cancel the shared source load for this recording and all bounded views.
+     * Players attached to it stop without reporting an error.
+     */
     close(): void;
     /** Select playback bounds without removing samples needed for seeking. */
     withBounds(bounds: TimeBounds): McapRecording;

package/dist/core/mcap/recording.js

@@ -0,0 +1,72 @@
+import { readMcap } from "./reader.js";
+import { HttpSource } from "./source.js";
+export class McapRecording {
+    metadata;
+    channels;
+    messages;
+    byTopic;
+    loading;
+    bounds;
+    /** Stream an MCAP file, URL, or byte source independently of a backend. */
+    static async open(input, options = {}) {
+        const source = typeof input === "string" || input instanceof URL
+            ? new HttpSource(input)
+            : input;
+        return readMcap(source, options);
+    }
+    constructor(metadata, channels, messages, byTopic, loading, bounds) {
+        this.metadata = metadata;
+        this.channels = channels;
+        this.messages = messages;
+        this.byTopic = byTopic;
+        this.loading = loading;
+        this.bounds = bounds;
+        if (this.start > this.end)
+            throw new Error("Recording end must not precede its start");
+    }
+    get start() {
+        return this.bounds?.start ?? this.messages[0]?.time ?? 0n;
+    }
+    get end() {
+        return this.bounds?.end ?? this.messages.at(-1)?.time ?? this.start;
+    }
+    get counts() {
+        return Object.fromEntries([...this.byTopic].map(([topic, records]) => [topic, records.length]));
+    }
+    get bufferedEnd() {
+        if (this.complete)
+            return this.end;
+        const time = this.loading.bufferedEnd;
+        if (time === undefined || time < this.start)
+            return undefined;
+        return time > this.end ? this.end : time;
+    }
+    get complete() {
+        return this.loading.complete;
+    }
+    get error() {
+        return this.loading.error;
+    }
+    get loaded() {
+        return this.loading.loaded;
+    }
+    /** Observe buffered playback coverage, completion, or a loading error. */
+    subscribe(listener) {
+        return this.loading.subscribe(() => listener({
+            bufferedEnd: this.bufferedEnd,
+            complete: this.complete,
+            error: this.error,
+        }));
+    }
+    /**
+     * Cancel the shared source load for this recording and all bounded views.
+     * Players attached to it stop without reporting an error.
+     */
+    close() {
+        this.loading.close();
+    }
+    /** Select playback bounds without removing samples needed for seeking. */
+    withBounds(bounds) {
+        return new McapRecording(this.metadata, this.channels, this.messages, this.byTopic, this.loading, bounds);
+    }
+}

package/dist/core/mcap/source.js

@@ -0,0 +1,67 @@
+async function* streamBytes(stream, signal) {
+    const reader = stream.getReader();
+    const abort = () => void reader.cancel(signal?.reason).catch(() => { });
+    signal?.addEventListener("abort", abort, { once: true });
+    try {
+        if (signal?.aborted)
+            abort();
+        while (true) {
+            signal?.throwIfAborted();
+            const result = await reader.read();
+            signal?.throwIfAborted();
+            if (result.done)
+                return;
+            yield result.value;
+        }
+    }
+    finally {
+        signal?.removeEventListener("abort", abort);
+        await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}
+/** A local Blob or File, read incrementally. */
+export class BlobSource {
+    blob;
+    constructor(blob) {
+        this.blob = blob;
+    }
+    stream({ signal } = {}) {
+        return streamBytes(this.blob.stream(), signal);
+    }
+}
+/** Download a signed MCAP URL without forwarding control API credentials. */
+export class HttpSource {
+    url;
+    options;
+    constructor(url, options = {}) {
+        this.url = url;
+        this.options = options;
+    }
+    combinedSignal(signal) {
+        const constructorSignal = this.options.signal;
+        return constructorSignal && signal
+            ? AbortSignal.any([constructorSignal, signal])
+            : (constructorSignal ?? signal);
+    }
+    /** Stream the response body directly; no sizing request or full download is needed. */
+    async *stream({ signal } = {}) {
+        const combinedSignal = this.combinedSignal(signal);
+        combinedSignal?.throwIfAborted();
+        const response = await this.request(combinedSignal);
+        if (!response.body)
+            throw new Error("MCAP response has no body");
+        yield* streamBytes(response.body, combinedSignal);
+    }
+    async request(signal) {
+        signal?.throwIfAborted();
+        const response = await fetch(this.url, {
+            signal,
+            cache: "no-store",
+            credentials: "omit",
+        });
+        if (!response.ok)
+            throw new Error(`MCAP request failed (${response.status}): ${await response.text()}`);
+        return response;
+    }
+}

package/dist/{types/core → core}/mcap/types.d.ts

@@ -7,7 +7,7 @@ export interface Topic {
     readonly schemaData?: Uint8Array;
     readonly metadata: ReadonlyMap<string, string>;
 }
-export interface ReplayMessage<T = unknown> {
+export interface Message<T = unknown> {
     readonly channel: Topic;
     readonly time: bigint;
     readonly publishTime: bigint;
@@ -31,6 +31,6 @@ export interface Recording extends TimeBounds {
     readonly error?: Error;
     subscribe?(listener: (state: RecordingLoadState) => void): () => void;
     readonly channels: ReadonlyMap<number, Topic>;
-    readonly messages: readonly ReplayMessage[];
-    readonly byTopic: ReadonlyMap<string, readonly ReplayMessage[]>;
+    readonly messages: readonly Message[];
+    readonly byTopic: ReadonlyMap<string, readonly Message[]>;
 }

package/dist/core/mcap/types.js

@@ -0,0 +1 @@
+export {};

package/dist/{types/core → core}/playback/index.d.ts

@@ -1,2 +1,2 @@
-export { ReplayPlayer } from "./player.js";
+export { Player } from "./player.js";
 export type { PlaybackListener, PlaybackState, Scheduler, SubscriptionOptions, } from "./player.js";

package/dist/core/playback/index.js

@@ -0,0 +1 @@
+export { Player } from "./player.js";

package/dist/{types/core → core}/playback/player.d.ts

@@ -21,7 +21,7 @@ export interface SubscriptionOptions {
     topics?: readonly string[];
 }
 /** Local playback clock for a recording's native-timestamped video topics. */
-export declare class ReplayPlayer {
+export declare class Player {
     readonly recording: Recording;
     private readonly scheduler;
     time: bigint;
@@ -34,14 +34,20 @@ export declare class ReplayPlayer {
     private anchorTime;
     private anchorWall;
     private waitingForData;
+    private started;
     private seekController?;
     private readonly video;
     private readonly submitted;
     private readonly unsubscribeRecording?;
     private readonly listeners;
     constructor(recording: Recording, callbacks?: PlaybackListener, scheduler?: Scheduler);
-    /** Subscribe a view or renderer to the shared playback clock and selected topics. */
+    /**
+     * Subscribe a view or renderer to the shared playback clock and selected topics.
+     * It receives the current state, and once playback has started, a snapshot of
+     * the current frame. Call the returned function to unsubscribe.
+     */
     subscribe(listener: PlaybackListener, { topics }?: SubscriptionOptions): () => void;
+    private state;
     private emit;
     private publish;
     private cancelFrame;