@remedia/node 0.1.0-dev.3 → 0.1.0-dev.5

package/dist/native-binding.d.ts

@@ -0,0 +1,26 @@
+import { type FfmpegRuntimeInfo } from './ffmpeg-runtime.js';
+import type { NativeRemedia as NativeRemediaClass } from '../native.js';
+/** The Remedia native engine class, loaded after FFmpeg 9 was located. */
+export declare const NativeRemedia: typeof NativeRemediaClass;
+/** Instance type of the Remedia native engine. */
+export type NativeRemedia = NativeRemediaClass;
+/**
+ * Report the FFmpeg 9 installation `@remedia/node` loaded.
+ *
+ * Importing the package already selects and loads FFmpeg, so this never triggers a search or a
+ * download and is cheap to call. It is independent of Discord, playback and the standalone server.
+ *
+ * @returns The selected source and directory, the loaded library files and versions, and every
+ * candidate discovery examined. When the platform has no library bootstrap the source is
+ * `unmanaged` and the library list is empty.
+ * @throws {Error} Only if called before the native addon finished loading, which cannot happen
+ * after the package has been imported successfully.
+ * @example
+ * ```ts
+ * import { getFfmpegRuntime } from '@remedia/node';
+ *
+ * const { source, directory, libraries } = getFfmpegRuntime();
+ * console.log(source, directory, libraries.map((library) => `${library.name} ${library.version}`));
+ * ```
+ */
+export declare function getFfmpegRuntime(): FfmpegRuntimeInfo;

package/dist/native-binding.js

@@ -0,0 +1,80 @@
+import { createRequire } from 'node:module';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { UNIX_INSTALL_COMMAND, WINDOWS_INSTALL_COMMAND, selectFfmpeg, } from './ffmpeg-runtime.js';
+import { bootstrapCandidates, platformSuffixes } from './bootstrap-locator.js';
+const require = createRequire(import.meta.url);
+/** Interface version of the bootstrap addon this loader was written against. */
+const BOOTSTRAP_VERSION = 1;
+function locateBootstrap() {
+    const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+    const suffixes = platformSuffixes(process.platform, process.arch);
+    for (const candidate of bootstrapCandidates(packageRoot, suffixes)) {
+        try {
+            const binding = require(candidate);
+            if (binding.bootstrapVersion() === BOOTSTRAP_VERSION)
+                return binding;
+        }
+        catch {
+            // An unusable bootstrap is treated like a missing one; the OS loader is the fallback.
+        }
+    }
+    return null;
+}
+function looksLikeMissingLibrary(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /libav|libsw|avcodec|avformat|avutil|avfilter|swresample|ffmpeg|\.dylib|\.so\b|specified module|dll/i.test(message);
+}
+let runtime = null;
+async function loadNativeBinding() {
+    const bootstrap = locateBootstrap();
+    const selected = bootstrap
+        ? selectFfmpeg(bootstrap)
+        : { source: 'unmanaged', directory: null, libraries: [], considered: [] };
+    let binding;
+    try {
+        binding = await import('../native.js');
+    }
+    catch (error) {
+        const hint = selected.source === 'unmanaged' && looksLikeMissingLibrary(error)
+            ? `\n\nThis platform has no Remedia library bootstrap, so the system library loader must find FFmpeg 9 itself. ` +
+                `Install it with the Remedia installer (${process.platform === 'win32' ? WINDOWS_INSTALL_COMMAND : UNIX_INSTALL_COMMAND}) and add its library directory to your loader search path.`
+            : '';
+        const origin = selected.source === 'unmanaged'
+            ? 'The Remedia native addon could not be loaded'
+            : `FFmpeg 9 was loaded from ${selected.directory} (${selected.source}), but the Remedia native addon could not be loaded`;
+        throw new Error(`${origin}: ${error instanceof Error ? error.message : String(error)}${hint}`, {
+            cause: error,
+        });
+    }
+    // Only now that the engine addon has loaded against the libraries is the runtime reported.
+    runtime = Object.freeze({ ...selected });
+    return binding;
+}
+const binding = await loadNativeBinding();
+/** The Remedia native engine class, loaded after FFmpeg 9 was located. */
+export const NativeRemedia = binding.NativeRemedia;
+/**
+ * Report the FFmpeg 9 installation `@remedia/node` loaded.
+ *
+ * Importing the package already selects and loads FFmpeg, so this never triggers a search or a
+ * download and is cheap to call. It is independent of Discord, playback and the standalone server.
+ *
+ * @returns The selected source and directory, the loaded library files and versions, and every
+ * candidate discovery examined. When the platform has no library bootstrap the source is
+ * `unmanaged` and the library list is empty.
+ * @throws {Error} Only if called before the native addon finished loading, which cannot happen
+ * after the package has been imported successfully.
+ * @example
+ * ```ts
+ * import { getFfmpegRuntime } from '@remedia/node';
+ *
+ * const { source, directory, libraries } = getFfmpegRuntime();
+ * console.log(source, directory, libraries.map((library) => `${library.name} ${library.version}`));
+ * ```
+ */
+export function getFfmpegRuntime() {
+    if (!runtime)
+        throw new Error('The Remedia native addon has not finished loading.');
+    return runtime;
+}

package/dist/playback.d.ts

@@ -1,6 +1,6 @@
 import { RemediaEventEmitter } from './events.js';
 import { type MediaSource } from './input.js';
-import { PlaybackHooks, type PlayOptions, type PlaybackSessionEventMap } from './lifecycle.js';
+import { PlaybackHooks, type PlayOptions, type PlaybackSessionEventMap, type StageNextOptions, type CrossfadeOptions, type StageSnapshot } from './lifecycle.js';
 import { type AudioStreamInfo, type PlaybackPosition, type PlaybackState } from './types.js';
 import { FilterControls } from './filters.js';
 /**
@@ -15,6 +15,24 @@ export declare class PlaybackSession<Metadata = unknown> extends RemediaEventEmi
     readonly filters: FilterControls;
     /** Stable opaque identity for this wrapper, suitable for correlating lifecycle events. */
     get sessionId(): string;
+    /** Enable continuous PCM playback before starting a source. */
+    /**
+     * Configure overlapping PCM playback while idle.
+     * @param options - Explicit opt-in settings, or false to retain ordinary playback.
+     * @returns Nothing; throws if settings are invalid or playback is active.
+     */
+    configureCrossfade(options: CrossfadeOptions | false): void;
+    /** Current preparation snapshot, or null when no stage is pending. */
+    get stagedSource(): StageSnapshot | null;
+    /** Cancel the queued stage and release its input. @returns Resolves after cancellation. */
+    clearStage(): Promise<void>;
+    /**
+     * Prepare one upcoming source without restarting playback or its output.
+     * @param source - Fresh media input; Readables and buffers require embedded execution.
+     * @param options - Queue occurrence, revision fencing, expiry and locally retained metadata.
+     * @returns Preparation snapshot; rejects disabled sessions, stale identities or invalid inputs.
+     */
+    stageNext(source: MediaSource, options: StageNextOptions<Metadata>): Promise<StageSnapshot>;
     /** Current playback lifecycle state. */
     get state(): PlaybackState;
     /** Latest source and output timeline measurements in milliseconds. */

package/dist/playback.js

@@ -26,6 +26,14 @@ export class PlaybackSession extends RemediaEventEmitter {
     #abortListener;
     #latestGeneration = 0;
     #guildId;
+    #crossfadeEnabled = false;
+    #fadeDurationMs = 5000;
+    #crossfadeTimer;
+    #stageInput;
+    #stageEntryId;
+    #stageWork = Promise.resolve();
+    #stages = new Map();
+    #outgoingInput;
     /**
      * Construct this wrapper with its owning services. Use the owning engine or client factory for application code.
      *
@@ -53,6 +61,123 @@ export class PlaybackSession extends RemediaEventEmitter {
     get currentGeneration() {
         return this.#latestGeneration;
     }
+    /** Enable continuous PCM playback before starting a source. */
+    /**
+     * Configure overlapping PCM playback while idle.
+     * @param options - Explicit opt-in settings, or false to retain ordinary playback.
+     * @returns Nothing; throws if settings are invalid or playback is active.
+     */
+    configureCrossfade(options) {
+        this.#assertActive();
+        if (options) {
+            if (options.enabled !== true ||
+                (options.curve !== undefined && options.curve !== 'equalPower')) {
+                throw new TypeError('crossfade requires enabled: true and the equalPower curve');
+            }
+            const durationMs = options.durationMs ?? 5000;
+            this.#native.playbackConfigureCrossfade(this.#playbackId, true, durationMs, options.prepareBeforeMs ?? 30000);
+            this.#fadeDurationMs = durationMs;
+            this.#crossfadeEnabled = true;
+        }
+        else {
+            this.#native.playbackConfigureCrossfade(this.#playbackId, false, 0, 0);
+            this.#crossfadeEnabled = false;
+        }
+    }
+    /** Current preparation snapshot, or null when no stage is pending. */
+    get stagedSource() {
+        const stage = this.#native.playbackStagedSource(this.#playbackId);
+        return stage ? this.#normalizeStage(stage) : null;
+    }
+    /** Cancel the queued stage and release its input. @returns Resolves after cancellation. */
+    async clearStage() {
+        const work = this.#stageWork.then(() => this.#clearStage());
+        this.#stageWork = work.then(() => { }, () => { });
+        return work;
+    }
+    async #clearStage() {
+        await this.#native.playbackClearStage(this.#playbackId);
+        this.#drainCrossfadeEvents();
+        await this.#stageInput?.cancel();
+        this.#stageInput = undefined;
+        this.#stageEntryId = undefined;
+    }
+    /**
+     * Prepare one upcoming source without restarting playback or its output.
+     * @param source - Fresh media input; Readables and buffers require embedded execution.
+     * @param options - Queue occurrence, revision fencing, expiry and locally retained metadata.
+     * @returns Preparation snapshot; rejects disabled sessions, stale identities or invalid inputs.
+     */
+    async stageNext(source, options) {
+        const work = this.#stageWork.then(() => this.#submitStage(source, options));
+        this.#stageWork = work.then(() => { }, () => { });
+        return work;
+    }
+    async #submitStage(source, options) {
+        this.#assertActive();
+        this.#drainCrossfadeEvents();
+        if (!this.#crossfadeEnabled)
+            throw new Error('crossfade is disabled for this session');
+        if (!options.entryId?.trim())
+            throw new TypeError('entryId is required');
+        if (!Number.isSafeInteger(options.queueRevision) || options.queueRevision < 0) {
+            throw new RangeError('queueRevision must be a non-negative safe integer');
+        }
+        const sourceRevision = options.sourceRevision ?? 0;
+        if (!Number.isSafeInteger(sourceRevision) || sourceRevision < 0) {
+            throw new RangeError('sourceRevision must be a non-negative safe integer');
+        }
+        if (options.expiresAtMs !== undefined &&
+            (!Number.isSafeInteger(options.expiresAtMs) || options.expiresAtMs < 0)) {
+            throw new RangeError('expiresAtMs must be a non-negative safe integer');
+        }
+        const expectedGeneration = options.expectedGeneration ??
+            numericGeneration(this.#native.playbackSourceGeneration(this.#playbackId));
+        const existing = this.stagedSource;
+        if (existing &&
+            existing.expectedGeneration === expectedGeneration &&
+            existing.entryId === options.entryId &&
+            existing.queueRevision === options.queueRevision &&
+            existing.sourceRevision === sourceRevision)
+            return existing;
+        let input;
+        const nativeSource = 'stream' in source
+            ? (input = createReadableInput(this.#native, source.stream)).source
+            : toNativeSource(source);
+        const key = JSON.stringify([
+            expectedGeneration,
+            options.entryId,
+            options.queueRevision,
+            sourceRevision,
+        ]);
+        this.#stages.set(key, { input, metadata: options.customMetadata });
+        try {
+            const result = await this.#native.playbackStageNext(this.#playbackId, nativeSource, String(expectedGeneration), options.entryId, String(options.queueRevision), String(sourceRevision), options.expiresAtMs === undefined ? undefined : String(options.expiresAtMs));
+            this.#drainCrossfadeEvents();
+            if (this.#stages.has(key)) {
+                this.#stageInput = input;
+                this.#stageEntryId = key;
+            }
+            return this.#normalizeStage(result);
+        }
+        catch (error) {
+            this.#stages.delete(key);
+            await input?.cancel();
+            throw error;
+        }
+    }
+    #normalizeStage(stage) {
+        return {
+            expectedGeneration: numericGeneration(stage.expectedGeneration),
+            entryId: stage.entryId,
+            queueRevision: numericGeneration(stage.queueRevision),
+            sourceRevision: numericGeneration(stage.sourceRevision),
+            state: stage.state,
+            bufferedMs: stage.bufferedMs,
+            info: stage.info ? toStreamInfo(stage.info) : null,
+            error: stage.error ?? null,
+        };
+    }
     /** Current playback lifecycle state. */
     get state() {
         return this.#native.playbackState(this.#playbackId);
@@ -153,7 +278,8 @@ export class PlaybackSession extends RemediaEventEmitter {
                 throw abortError(controller.signal.reason);
             nativeAttempted = true;
             const info = toStreamInfo(await this.#native.play(this.#playbackId, nativeSource));
-            const generation = numericGeneration(this.#native.playbackGeneration(this.#playbackId));
+            const workerGeneration = numericGeneration(this.#native.playbackGeneration(this.#playbackId));
+            const generation = numericGeneration(this.#native.playbackSourceGeneration(this.#playbackId));
             this.#latestGeneration = generation;
             this.#metadata.set(generation, options.customMetadata);
             this.#boundMetadata(generation);
@@ -164,7 +290,9 @@ export class PlaybackSession extends RemediaEventEmitter {
                 info,
             });
             this.#starting = false;
-            void this.#observeGeneration(generation, input);
+            if (this.#crossfadeEnabled)
+                this.#startCrossfadePoll();
+            void this.#observeGeneration(workerGeneration, input);
             return info;
         }
         catch (error) {
@@ -232,7 +360,8 @@ export class PlaybackSession extends RemediaEventEmitter {
         this.#assertActive();
         const previousPositionMs = this.position.mediaMs;
         await this.#native.seek(this.#playbackId, positionMs);
-        if (previousPositionMs !== positionMs) {
+        this.#drainCrossfadeEvents();
+        if (previousPositionMs !== positionMs || this.#crossfadeEnabled) {
             this.emit(PlaybackEvent.playbackSeeked, {
                 ...this.#eventContext(),
                 positionMs,
@@ -247,7 +376,7 @@ export class PlaybackSession extends RemediaEventEmitter {
     async stop() {
         this.#assertActive();
         const previousState = this.state;
-        const generation = numericGeneration(this.#native.playbackGeneration(this.#playbackId));
+        const generation = this.#latestGeneration;
         try {
             await this.#native.stop(this.#playbackId);
             if (isPlaybackActive(previousState) && this.state === 'stopped') {
@@ -289,6 +418,9 @@ export class PlaybackSession extends RemediaEventEmitter {
         finally {
             await this.#releaseInput();
             this.#disposed = true;
+            this.#stopCrossfadePoll();
+            await this.#stageInput?.cancel();
+            await this.#outgoingInput?.cancel();
             this.hooks.clear();
             this.#metadata.clear();
             this.emit(PlaybackEvent.sessionDisposed, {
@@ -333,8 +465,9 @@ export class PlaybackSession extends RemediaEventEmitter {
         try {
             const state = (await this.#native.wait(this.#playbackId, String(generation)));
             if (state === 'completed' || state === 'failed' || state === 'stopped') {
+                this.#drainCrossfadeEvents();
                 const error = state === 'failed' ? new Error(this.error ?? 'playback failed') : undefined;
-                this.#emitTerminal(state, generation, error);
+                this.#emitTerminal(state, this.#latestGeneration, error);
             }
         }
         catch (error) {
@@ -351,19 +484,168 @@ export class PlaybackSession extends RemediaEventEmitter {
                     state = undefined;
                 }
                 if (state === 'failed')
-                    this.#emitTerminal('failed', generation, asError(error));
+                    this.#emitTerminal('failed', this.#latestGeneration, asError(error));
             }
         }
         finally {
-            this.#metadata.delete(generation);
-            this.#startedGenerations.delete(generation);
-            if (this.#latestGeneration === generation) {
-                this.#clearAbortBinding(this.#playController);
+            this.#stopCrossfadePoll();
+            this.#clearAbortBinding(this.#playController);
+            await this.#outgoingInput?.cancel();
+            this.#outgoingInput = undefined;
+            await this.#stageInput?.cancel();
+            this.#stageInput = undefined;
+            for (const stage of this.#stages.values())
+                await stage.input?.cancel();
+            this.#stages.clear();
+            await this.#releaseInput();
+            if (input !== this.#input)
+                await input?.cancel();
+        }
+    }
+    #startCrossfadePoll() {
+        if (this.#crossfadeTimer)
+            return;
+        this.#crossfadeTimer = setInterval(() => this.#drainCrossfadeEvents(), 25);
+        this.#crossfadeTimer.unref?.();
+    }
+    #stopCrossfadePoll() {
+        if (this.#crossfadeTimer)
+            clearInterval(this.#crossfadeTimer);
+        this.#crossfadeTimer = undefined;
+    }
+    #drainCrossfadeEvents() {
+        if (!this.#crossfadeEnabled || this.#disposed)
+            return;
+        let events;
+        try {
+            events = this.#native.playbackTakeCrossfadeEvents(this.#playbackId);
+        }
+        catch {
+            return;
+        }
+        for (const event of events) {
+            const generation = numericGeneration(event.generation);
+            const stage = event.entryId === undefined
+                ? null
+                : {
+                    entryId: event.entryId,
+                    queueRevision: numericGeneration(event.queueRevision ?? '0'),
+                    sourceRevision: numericGeneration(event.sourceRevision ?? '0'),
+                };
+            const stageKey = JSON.stringify([
+                event.kind === 'transition_started'
+                    ? numericGeneration(event.previousGeneration ?? '0')
+                    : generation,
+                stage?.entryId,
+                stage?.queueRevision,
+                stage?.sourceRevision,
+            ]);
+            switch (event.kind) {
+                case 'timeline_changed': {
+                    const previous = numericGeneration(event.previousGeneration ?? '0');
+                    this.#metadata.set(generation, this.#metadata.get(previous));
+                    this.#startedGenerations.add(generation);
+                    this.#latestGeneration = generation;
+                    break;
+                }
+                case 'prepare_requested': {
+                    const remainingMs = event.remainingMs ?? 0;
+                    this.emit(PlaybackEvent.prepareRequested, {
+                        ...this.#eventContext(generation),
+                        remainingMs,
+                        transitionInMs: Math.max(0, remainingMs - this.#fadeDurationMs),
+                    });
+                    break;
+                }
+                case 'stage_ready':
+                    if (stage)
+                        this.emit(PlaybackEvent.stageReady, {
+                            ...this.#eventContext(generation),
+                            ...stage,
+                        });
+                    break;
+                case 'stage_failed':
+                    void this.#stages.get(stageKey)?.input?.cancel();
+                    this.#stages.delete(stageKey);
+                    if (stage)
+                        this.emit(PlaybackEvent.stageFailed, {
+                            ...this.#eventContext(generation),
+                            ...stage,
+                            reason: event.reason ?? 'staged source failed',
+                        });
+                    break;
+                case 'stage_invalidated':
+                    void this.#stages.get(stageKey)?.input?.cancel();
+                    this.#stages.delete(stageKey);
+                    if (stage) {
+                        this.emit(PlaybackEvent.stageInvalidated, {
+                            ...this.#eventContext(generation),
+                            ...stage,
+                        });
+                        if (this.#stageEntryId === stageKey) {
+                            void this.#stageInput?.cancel();
+                            this.#stageInput = undefined;
+                            this.#stageEntryId = undefined;
+                        }
+                    }
+                    break;
+                case 'transition_started': {
+                    if (!stage || !event.info)
+                        break;
+                    const previous = numericGeneration(event.previousGeneration ?? '0');
+                    const prepared = this.#stages.get(stageKey);
+                    this.#stages.delete(stageKey);
+                    this.#metadata.set(generation, prepared?.metadata);
+                    this.#boundMetadata(generation);
+                    this.#startedGenerations.add(generation);
+                    this.#latestGeneration = generation;
+                    this.#outgoingInput = this.#input;
+                    this.#input = prepared?.input;
+                    if (this.#stageEntryId === stageKey) {
+                        this.#stageInput = undefined;
+                        this.#stageEntryId = undefined;
+                    }
+                    this.emit(PlaybackEvent.playbackStarted, {
+                        ...this.#eventContext(generation),
+                        state: 'playing',
+                        info: toStreamInfo(event.info),
+                        transition: { type: 'crossfade', outgoingGeneration: previous, entryId: stage.entryId },
+                    });
+                    break;
+                }
+                case 'transition_completed': {
+                    if (!stage)
+                        break;
+                    const promoted = numericGeneration(event.previousGeneration ?? '0');
+                    this.#emitTerminal('completed', generation, undefined, undefined, {
+                        type: 'promoted',
+                        generation: promoted,
+                        entryId: stage.entryId,
+                    });
+                    void this.#outgoingInput?.cancel();
+                    this.#outgoingInput = undefined;
+                    break;
+                }
+                case 'transition_cancelled': {
+                    if (!stage)
+                        break;
+                    const failedGeneration = numericGeneration(event.previousGeneration ?? '0');
+                    const abandoned = this.#input;
+                    this.#input = this.#outgoingInput;
+                    this.#outgoingInput = undefined;
+                    void abandoned?.cancel();
+                    this.#latestGeneration = generation;
+                    this.emit(PlaybackEvent.transitionCancelled, {
+                        ...this.#eventContext(generation),
+                        failedGeneration,
+                        entryId: stage.entryId,
+                    });
+                    break;
+                }
             }
-            await this.#releaseInput(input, generation);
         }
     }
-    #emitTerminal(state, generation, error, reason) {
+    #emitTerminal(state, generation, error, reason, continuation) {
         if ((state !== 'failed' && !this.#startedGenerations.has(generation)) ||
             this.#terminalGenerations.has(generation))
             return;
@@ -376,7 +658,12 @@ export class PlaybackSession extends RemediaEventEmitter {
         }
         const base = this.#eventContext(generation);
         if (state === 'completed') {
-            this.emit(PlaybackEvent.playbackCompleted, { ...base, state, position: this.position });
+            this.emit(PlaybackEvent.playbackCompleted, {
+                ...base,
+                state,
+                position: this.position,
+                ...(continuation ? { continuation } : {}),
+            });
         }
         else if (state === 'stopped') {
             this.emit(PlaybackEvent.playbackStopped, reason ? { ...base, state, reason } : { ...base, state });

package/dist/remedia.d.ts

@@ -31,6 +31,12 @@ export declare class Remedia extends RemediaEventEmitter<RemediaLifecycleEvents>
      * @returns An initialized independent native engine context.
      */
     static create(options?: RemediaOptions): Promise<Remedia>;
+    /**
+     * Read cached native resources for the shared Node.js process. Refresh runs off
+     * the calling thread at most once per second; the first snapshot has null counters.
+     * @returns Process-wide byte and CPU-time counters, shared by all embedded instances.
+     */
+    processResources(): import('./resources.js').ProcessResourceStatistics;
     /**
      * Inspect a disposable source without creating playback or voice resources. Readables may be partially or fully consumed.
      * @param source - Encoded input; acquire a fresh source for subsequent playback.

package/dist/remedia.js

@@ -1,7 +1,7 @@
 import { createReadableInput, toNativeSource } from './input.js';
 import { toStreamInfo } from './types.js';
 import { RemediaEventEmitter } from './events.js';
-import { NativeRemedia } from '../native.js';
+import { NativeRemedia } from './native-binding.js';
 import { DiscordSession } from './discord.js';
 import { DiscordGatewayAdapter } from './gateway.js';
 import { PlaybackSessionEvents as PlaybackEvent, RemediaEvents as RemediaEvent, VoiceSessionEvents as VoiceEvent, } from './lifecycle.js';
@@ -35,6 +35,15 @@ export class Remedia extends RemediaEventEmitter {
     static async create(options) {
         return new Remedia(await NativeRemedia.create(), options);
     }
+    /**
+     * Read cached native resources for the shared Node.js process. Refresh runs off
+     * the calling thread at most once per second; the first snapshot has null counters.
+     * @returns Process-wide byte and CPU-time counters, shared by all embedded instances.
+     */
+    processResources() {
+        this.#assertOpen();
+        return JSON.parse(this.#native.processResourcesJson());
+    }
     /**
      * Inspect a disposable source without creating playback or voice resources. Readables may be partially or fully consumed.
      * @param source - Encoded input; acquire a fresh source for subsequent playback.
@@ -172,6 +181,11 @@ function forwardLifecycleEvents(source, target) {
         PlaybackEvent.playbackPaused,
         PlaybackEvent.playbackResumed,
         PlaybackEvent.playbackSeeked,
+        PlaybackEvent.prepareRequested,
+        PlaybackEvent.stageReady,
+        PlaybackEvent.stageFailed,
+        PlaybackEvent.stageInvalidated,
+        PlaybackEvent.transitionCancelled,
         PlaybackEvent.filterChanged,
         PlaybackEvent.volumeChanged,
         PlaybackEvent.sessionDisposed,

package/dist/resources.d.ts

@@ -0,0 +1,51 @@
+/** Native process memory accounting in bytes. Missing fields indicate an older server; null indicates unavailable data. */
+export interface ResourceMemory {
+    /** Resident bytes including shared pages. */
+    residentBytes?: number | null;
+    /** Private resident bytes (USS); excludes shared pages, distinct from private commit. */
+    privateResidentBytes?: number | null;
+    /** Proportional resident bytes (PSS), including shared pages proportionally. */
+    proportionalResidentBytes?: number | null;
+    /** Private committed bytes, including potentially nonresident pages. */
+    committedPrivateBytes?: number | null;
+    /** Mapped virtual address bytes; not physical RAM. */
+    virtualBytes?: number | null;
+    /** Reserved but uncommitted virtual address bytes; not RAM. */
+    reservedVirtualBytes?: number | null;
+    /** Lifetime peak resident bytes. */
+    peakResidentBytes?: number | null;
+    /** macOS physical footprint bytes; distinct from USS and RSS. */
+    footprintBytes?: number | null;
+}
+/** Native process CPU accounting. Missing fields indicate an older server; null indicates unavailable data. */
+export interface ResourceCpu {
+    /** Process utilization: 100 means one logical CPU; can exceed 100. Null on the first sample. */
+    processPercent?: number | null;
+    /** Cumulative process user CPU time in milliseconds. */
+    userTimeMs?: number | null;
+    /** Cumulative process system CPU time in milliseconds. */
+    systemTimeMs?: number | null;
+    /** Available logical CPU parallelism estimate. */
+    availableParallelism?: number | null;
+    /** Actual process OS thread count, including nonaudio threads. */
+    threadCount?: number | null;
+    /** System one-minute load average; not process CPU usage. */
+    loadAverage1m?: number | null;
+}
+/** Cached native measurements for the whole host process, shared by all embedded instances. */
+export interface ProcessResourceStatistics {
+    /** Process memory counters in bytes. */
+    memory: ResourceMemory;
+    /** Process CPU and system load counters. */
+    cpu: ResourceCpu;
+    /** Collection completion timestamp as Unix milliseconds; null before the first collection. */
+    collectedAtUnixMs: number | null;
+    /** Wall interval used for process utilization in milliseconds; null on the first sample. */
+    cpuSampleIntervalMs: number | null;
+    /** Demand-driven cache refresh interval in milliseconds; concurrent requests share stale snapshots. */
+    samplingIntervalMs: number;
+    /** Native collection duration in milliseconds, or null before collection. */
+    collectionDurationMs: number | null;
+    /** Unix descriptors or Windows handles owned by the process, or null if unavailable. */
+    openHandles: number | null;
+}

package/dist/resources.js

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