@remedia/node 0.1.0-dev.2 → 0.1.0-dev.4

package/README.md

@@ -34,9 +34,9 @@ Requires Node.js **22.18.0 or newer** (ESM).
 npm install @remedia/node
 ```
 
-Install FFmpeg 7 shared libraries separately before importing the package. npm does not install
-FFmpeg or compile the addon. Required ABI majors are avcodec 61, avformat 61, avutil 59,
-avfilter 10, and swresample 5. libopus is statically included; FFmpeg is dynamically linked.
+Install FFmpeg 9 shared libraries separately before importing the package. npm does not install
+FFmpeg or compile the addon. Required ABI majors are avcodec 63, avformat 63, avutil 61,
+avfilter 12, and swresample 7. libopus is statically included; FFmpeg is dynamically linked.
 
 Native runtime CI covers Linux x64/ARM64 glibc, macOS x64/ARM64, Windows x64 MSVC, and
 FreeBSD x64. Additional build-only packages cover Linux x64/ARM64 musl, Linux ARMv7 hard-float GNU,

package/dist/discord.d.ts

@@ -1,5 +1,5 @@
 import { RemediaEventEmitter } from './events.js';
-import { PlaybackHooks, type PlayOptions, type SessionLifecycleEvents } from './lifecycle.js';
+import { PlaybackHooks, type PlayOptions, type SessionLifecycleEvents, type CrossfadeOptions, type StageNextOptions, type StageSnapshot } from './lifecycle.js';
 import { FilterControls } from './filters.js';
 import type { MediaSource } from './input.js';
 import type { AudioStreamInfo, PlaybackPosition, PlaybackState, VoiceConnectionState } from './types.js';
@@ -21,6 +21,8 @@ export interface DiscordSessionOptions {
     volume?: number;
     /** Trusted raw FFmpeg audio filtergraph; defaults to null. Native syntax validation occurs during backend configuration before playback. */
     filterGraph?: string | null;
+    /** Explicit PCM crossfade opt-in; disabled by default. */
+    crossfade?: CrossfadeOptions | false;
 }
 /** Cancellation and timeout controls for obtaining credentials and establishing a voice transport. */
 export interface DiscordConnectOptions {
@@ -113,6 +115,17 @@ export declare class DiscordSession<Metadata = unknown> extends RemediaEventEmit
      * Pause the current playback without replacing its decoder or source generation.
      * @returns Resolves when the backend accepts the pause request.
      */
+    /**
+     * 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>;
+    /** Cancel the queued stage and release its input. @returns Resolves after cancellation. */
+    clearStage(): Promise<void>;
+    /** Current preparation snapshot, or null when no stage is pending. */
+    get stagedSource(): StageSnapshot | null;
     pause(): Promise<void>;
     /**
      * Resume paused playback on its existing source generation.

package/dist/discord.js

@@ -51,6 +51,7 @@ export class DiscordSession extends RemediaEventEmitter {
     #disposed = false;
     #filterGraph = null;
     #volume = 1;
+    #crossfade;
     #configurationWork = Promise.resolve();
     #nativeStateTimer;
     /**
@@ -66,6 +67,7 @@ export class DiscordSession extends RemediaEventEmitter {
         this.#channelId = validateSnowflake('channelId', options.channelId);
         this.userId = validateSnowflake('userId', options.userId);
         validateVolume(options.volume ?? 1);
+        this.#crossfade = options.crossfade;
         if (options.filterGraph !== undefined &&
             options.filterGraph !== null &&
             (typeof options.filterGraph !== 'string' || !options.filterGraph.trim()))
@@ -310,6 +312,24 @@ export class DiscordSession extends RemediaEventEmitter {
      * Pause the current playback without replacing its decoder or source generation.
      * @returns Resolves when the backend accepts the pause request.
      */
+    /**
+     * 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) {
+        await this.#configurationWork;
+        return this.#requireExistingPlayback().stageNext(source, options);
+    }
+    /** Cancel the queued stage and release its input. @returns Resolves after cancellation. */
+    clearStage() {
+        return this.#requireExistingPlayback().clearStage();
+    }
+    /** Current preparation snapshot, or null when no stage is pending. */
+    get stagedSource() {
+        return this.#playback?.stagedSource ?? null;
+    }
     pause() {
         return this.#requireExistingPlayback().pause();
     }
@@ -694,6 +714,8 @@ export class DiscordSession extends RemediaEventEmitter {
                 const createdPlayback = new PlaybackSession(this.#native, nativeSession.playbackId, undefined, this.guildId, this.hooks);
                 playback = createdPlayback;
                 this.#playback = createdPlayback;
+                if (this.#crossfade)
+                    createdPlayback.configureCrossfade(this.#crossfade);
                 await this.#serializeConfiguration(async () => {
                     if (this.#playback !== createdPlayback)
                         return;
@@ -1133,6 +1155,41 @@ export class DiscordSession extends RemediaEventEmitter {
                 guildId: this.guildId,
             });
         });
+        forward(PlaybackEvent.prepareRequested, (event) => {
+            this.emit(PlaybackEvent.prepareRequested, {
+                ...event,
+                sessionId: this.sessionId,
+                guildId: this.guildId,
+            });
+        });
+        forward(PlaybackEvent.stageReady, (event) => {
+            this.emit(PlaybackEvent.stageReady, {
+                ...event,
+                sessionId: this.sessionId,
+                guildId: this.guildId,
+            });
+        });
+        forward(PlaybackEvent.stageFailed, (event) => {
+            this.emit(PlaybackEvent.stageFailed, {
+                ...event,
+                sessionId: this.sessionId,
+                guildId: this.guildId,
+            });
+        });
+        forward(PlaybackEvent.stageInvalidated, (event) => {
+            this.emit(PlaybackEvent.stageInvalidated, {
+                ...event,
+                sessionId: this.sessionId,
+                guildId: this.guildId,
+            });
+        });
+        forward(PlaybackEvent.transitionCancelled, (event) => {
+            this.emit(PlaybackEvent.transitionCancelled, {
+                ...event,
+                sessionId: this.sessionId,
+                guildId: this.guildId,
+            });
+        });
         this.#playbackSubscriptions = {
             playback,
             detach: () => {

package/dist/index.d.ts

@@ -6,4 +6,4 @@ export { PlaybackHooks, PlaybackSessionEvents, RemediaEvents, VoiceSessionEvents
 export { Remedia, type ProbeOptions, type RemediaOptions } from './remedia.js';
 export type { MediaSource } from './input.js';
 export type { AudioStreamInfo, DebugListener, DiagnosticEvent, DiagnosticFieldValue, DiagnosticSeverity, PlaybackPosition, PlaybackState, VoiceConnectionState, } from './types.js';
-export type { BeforePlayContext, BeforePlayHook, BeforePlayResult, LifecycleVoiceState, PlayOptions, PlaybackEventIdentity, PlaybackLifecycleEvents, PlaybackSessionEventMap, RemediaLifecycleEvents, SessionLifecycleEvents, VoiceEventIdentity, VoiceLifecycleEvents, } from './lifecycle.js';
+export type { CrossfadeOptions, CrossfadeContinuation, CrossfadeTransition, CrossfadeStageEvent, StageNextOptions, StageSnapshot, BeforePlayContext, BeforePlayHook, BeforePlayResult, LifecycleVoiceState, PlayOptions, PlaybackEventIdentity, PlaybackLifecycleEvents, PlaybackSessionEventMap, RemediaLifecycleEvents, SessionLifecycleEvents, VoiceEventIdentity, VoiceLifecycleEvents, } from './lifecycle.js';

package/dist/input.d.ts

@@ -15,7 +15,9 @@ export type MediaSource = {
     buffer: Buffer | Uint8Array;
 } | {
     /**
-     * Caller-owned binary Readable, consumed with bounded backpressure in embedded mode; Remedia does not destroy it.
+     * Caller-owned binary Readable, consumed with bounded backpressure in embedded mode.
+     * Playback can seek forward, not backward, without caching prior input.
+     * Remedia does not destroy the caller-owned stream.
      */
     stream: Readable;
 };

package/dist/lifecycle.d.ts

@@ -16,6 +16,11 @@ export declare const PlaybackSessionEvents: {
     readonly playbackResumed: "playbackResumed";
     /** Emitted after seeking to a source timeline position. */
     readonly playbackSeeked: "playbackSeeked";
+    readonly prepareRequested: "prepareRequested";
+    readonly stageReady: "stageReady";
+    readonly stageFailed: "stageFailed";
+    readonly stageInvalidated: "stageInvalidated";
+    readonly transitionCancelled: "transitionCancelled";
     /** Emitted when the configured session filtergraph changes. */
     readonly filterChanged: "filterChanged";
     /** Emitted when the configured session linear gain changes. */
@@ -56,6 +61,11 @@ export declare const RemediaEvents: {
     readonly playbackResumed: "playbackResumed";
     /** Emitted after seeking to a source timeline position. */
     readonly playbackSeeked: "playbackSeeked";
+    readonly prepareRequested: "prepareRequested";
+    readonly stageReady: "stageReady";
+    readonly stageFailed: "stageFailed";
+    readonly stageInvalidated: "stageInvalidated";
+    readonly transitionCancelled: "transitionCancelled";
     /** Emitted when the configured session filtergraph changes. */
     readonly filterChanged: "filterChanged";
     /** Emitted when the configured session linear gain changes. */
@@ -69,6 +79,80 @@ export type RemediaEvents = (typeof RemediaEvents)[keyof typeof RemediaEvents];
  * Correlation fields identifying the session and source generation that produced a playback event.
  * @typeParam Metadata - Application-owned metadata attached to playback generations.
  */
+/** Session opt-in for continuous PCM crossfade playback. */
+export interface CrossfadeOptions {
+    /** Explicit enablement; omitted sessions retain ordinary playback. */
+    enabled: true;
+    /** Overlap duration in milliseconds, 1000–30000; defaults to 5000. */
+    durationMs?: number;
+    /** Lead before overlap in milliseconds, 5000–120000; defaults to 30000. */
+    prepareBeforeMs?: number;
+    /** Equal-power curve; the only supported curve. */
+    curve?: 'equalPower';
+}
+/** Identify a particular queued occurrence. Revisions prevent stale stage
+ * responses from replacing newer queue decisions.
+ */
+export interface StageNextOptions<Metadata = unknown> {
+    /** Stable ID of this queued occurrence, including repeated tracks. */
+    entryId: string;
+    /** Monotonically increasing queue decision revision; non-negative safe integer. */
+    queueRevision: number;
+    /** Revision of the resolved source for this entry; defaults to zero. */
+    sourceRevision?: number;
+    /** Absolute Unix time in milliseconds after which a prepared source must not be promoted. */
+    expiresAtMs?: number;
+    /** Current source generation to fence delayed preparation results; defaults to the active generation. */
+    expectedGeneration?: number;
+    /** Application-owned metadata retained locally and attached to incoming lifecycle events. */
+    customMetadata?: Metadata;
+}
+/** Crossfade playback identity, state, or capability metadata. */
+export interface StageSnapshot {
+    /** Current source generation to fence delayed preparation results; defaults to the active generation. */
+    expectedGeneration: number;
+    /** Stable ID of this queued occurrence, including repeated tracks. */
+    entryId: string;
+    /** Monotonically increasing queue decision revision; non-negative safe integer. */
+    queueRevision: number;
+    /** Revision of the resolved source for this entry; defaults to zero. */
+    sourceRevision: number;
+    /** Current preparation state; failed sources cannot be promoted. */
+    state: 'preparing' | 'ready' | 'failed';
+    /** Decoded PCM currently buffered, in milliseconds; bounded to two seconds. */
+    bufferedMs: number;
+    /** Selected stream metadata, or null until the decoder opens. */
+    info: AudioStreamInfo | null;
+    /** Preparation failure message, or null. */
+    error: string | null;
+}
+/** Crossfade playback identity, state, or capability metadata. */
+export interface CrossfadeContinuation {
+    /** Discriminator identifying this lifecycle transition. */
+    type: 'promoted';
+    /** Source generation identifying the promoted playback. */
+    generation: number;
+    /** Stable ID of this queued occurrence, including repeated tracks. */
+    entryId: string;
+}
+/** Crossfade playback identity, state, or capability metadata. */
+export interface CrossfadeTransition {
+    /** Discriminator identifying this lifecycle transition. */
+    type: 'crossfade';
+    /** Source generation that remains audible during the fade. */
+    outgoingGeneration: number;
+    /** Stable ID of this queued occurrence, including repeated tracks. */
+    entryId: string;
+}
+/** Crossfade playback identity, state, or capability metadata. */
+export interface CrossfadeStageEvent extends PlaybackEventIdentity {
+    /** Stable ID of this queued occurrence, including repeated tracks. */
+    entryId: string;
+    /** Monotonically increasing queue decision revision; non-negative safe integer. */
+    queueRevision: number;
+    /** Revision of the resolved source for this entry; defaults to zero. */
+    sourceRevision: number;
+}
 export interface PlaybackEventIdentity<Metadata = unknown> {
     /** Opaque Remedia session identity used to correlate events; distinct from the Discord bot user ID. */
     sessionId: string;
@@ -95,6 +179,7 @@ export type PlaybackLifecycleEvents<Metadata = unknown> = {
             state: 'playing';
             /** Metadata for the audio stream that started playback. */
             info: AudioStreamInfo;
+            transition?: CrossfadeTransition;
         }
     ];
     /** Emitted when a source generation reaches natural end-of-stream. */
@@ -104,6 +189,7 @@ export type PlaybackLifecycleEvents<Metadata = unknown> = {
             state: 'completed';
             /** Latest source and output timeline measurements in milliseconds. */
             position: PlaybackPosition;
+            continuation?: CrossfadeContinuation;
         }
     ];
     /** Emitted when a source generation is explicitly stopped or cancelled. */
@@ -125,6 +211,23 @@ export type PlaybackLifecycleEvents<Metadata = unknown> = {
         }
     ];
     /** Emitted when playback is paused without replacing its source generation. */
+    [PlaybackSessionEvents.prepareRequested]: [
+        PlaybackEventIdentity<Metadata> & {
+            remainingMs: number;
+            transitionInMs: number;
+        }
+    ];
+    [PlaybackSessionEvents.stageReady]: [CrossfadeStageEvent];
+    [PlaybackSessionEvents.stageFailed]: [CrossfadeStageEvent & {
+        reason: string;
+    }];
+    [PlaybackSessionEvents.stageInvalidated]: [CrossfadeStageEvent];
+    [PlaybackSessionEvents.transitionCancelled]: [
+        PlaybackEventIdentity<Metadata> & {
+            failedGeneration: number;
+            entryId: string;
+        }
+    ];
     [PlaybackSessionEvents.playbackPaused]: [
         PlaybackEventIdentity<Metadata> & {
             /** Playback or transport lifecycle state before this transition. */

package/dist/lifecycle.js

@@ -14,6 +14,11 @@ export const PlaybackSessionEvents = {
     playbackResumed: 'playbackResumed',
     /** Emitted after seeking to a source timeline position. */
     playbackSeeked: 'playbackSeeked',
+    prepareRequested: 'prepareRequested',
+    stageReady: 'stageReady',
+    stageFailed: 'stageFailed',
+    stageInvalidated: 'stageInvalidated',
+    transitionCancelled: 'transitionCancelled',
     /** Emitted when the configured session filtergraph changes. */
     filterChanged: 'filterChanged',
     /** Emitted when the configured session linear gain changes. */

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. */
@@ -50,7 +68,9 @@ export declare class PlaybackSession<Metadata = unknown> extends RemediaEventEmi
      */
     resume(): Promise<void>;
     /**
-     * Seek on the original media timeline; non-seekable and one-shot sources may reject.
+     * Seek on the original media timeline. Binary Readable inputs support forward-only
+     * seeking by decoding and discarding skipped audio; backwards seeking rejects.
+     * Large forward jumps may wait for the producer to supply the skipped bytes.
      * @param positionMs - Non-negative finite position on the original media timeline, in milliseconds.
      * @returns Resolves after the backend accepts the seek; rejects for invalid positions or unsupported inputs.
      */

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) {
@@ -222,7 +350,9 @@ export class PlaybackSession extends RemediaEventEmitter {
         }
     }
     /**
-     * Seek on the original media timeline; non-seekable and one-shot sources may reject.
+     * Seek on the original media timeline. Binary Readable inputs support forward-only
+     * seeking by decoding and discarding skipped audio; backwards seeking rejects.
+     * Large forward jumps may wait for the producer to supply the skipped bytes.
      * @param positionMs - Non-negative finite position on the original media timeline, in milliseconds.
      * @returns Resolves after the backend accepts the seek; rejects for invalid positions or unsupported inputs.
      */
@@ -230,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,
@@ -245,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') {
@@ -287,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, {
@@ -331,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) {
@@ -349,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;
@@ -374,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.js

@@ -172,6 +172,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/native.d.ts

@@ -68,6 +68,22 @@ export declare class NativeRemedia {
   createPlaybackSession(): string
   /** Start decoding into the null output or the associated Discord Opus sender. */
   play(playbackId: string, source: NativeMediaSource): Promise<NativeStreamInfo>
+  /** Configure the optional continuous PCM transition worker before playback. */
+  playbackConfigureCrossfade(playbackId: string, enabled: boolean, durationMs: number, prepareBeforeMs: number): void
+  /**
+   * Open an independent decoder and stage a queue occurrence without
+   * interrupting current playback.
+   */
+  playbackStageNext(playbackId: string, source: NativeMediaSource, expectedGeneration: string, entryId: string, queueRevision: string, sourceRevision: string, expiresAtMs?: string | undefined | null): Promise<NativeStageSnapshot>
+  /** Return the current stage without opening a new decoder. */
+  playbackStagedSource(playbackId: string): NativeStageSnapshot | null
+  playbackClearStage(playbackId: string): Promise<void>
+  /**
+   * Drain native transition events; embedded wrappers forward these to JS
+   * using the same event names and generation semantics as remote mode.
+   */
+  playbackTakeCrossfadeEvents(playbackId: string): Array<NativeCrossfadeEvent>
+  playbackSourceGeneration(playbackId: string): string
   /** Request playback pause at the current output frame boundary. */
   pause(playbackId: string): Promise<void>
   /** Resume a paused playback session. */
@@ -122,6 +138,19 @@ export declare class NativeRemedia {
   probe(id: string, source: NativeMediaSource, timeoutMs: number): Promise<NativeStreamInfo>
 }
 
+/** One ordered event emitted by the native staged-source worker. */
+export interface NativeCrossfadeEvent {
+  kind: string
+  generation: string
+  previousGeneration?: string
+  entryId?: string
+  queueRevision?: string
+  sourceRevision?: string
+  remainingMs?: number
+  reason?: string
+  info?: NativeStreamInfo
+}
+
 export interface NativeDiagnosticEvent {
   timestamp: number
   severity: string
@@ -154,6 +183,18 @@ export interface NativePlaybackPosition {
   playedMs?: number
 }
 
+/** A bounded native stage with an application-owned queue occurrence identity. */
+export interface NativeStageSnapshot {
+  expectedGeneration: string
+  entryId: string
+  queueRevision: string
+  sourceRevision: string
+  state: string
+  bufferedMs: number
+  info?: NativeStreamInfo
+  error?: string
+}
+
 export interface NativeStreamInfo {
   streamIndex: number
   codec: string

package/native.js

@@ -97,8 +97,8 @@ function requireNative() {
       try {
         const binding = require('@remedia/node-android-arm64')
         const bindingPackageVersion = require('@remedia/node-android-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -113,8 +113,8 @@ function requireNative() {
       try {
         const binding = require('@remedia/node-android-arm-eabi')
         const bindingPackageVersion = require('@remedia/node-android-arm-eabi/package.json').version
-        if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -134,8 +134,8 @@ function requireNative() {
         try {
           const binding = require('@remedia/node-win32-x64-gnu')
           const bindingPackageVersion = require('@remedia/node-win32-x64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -150,8 +150,8 @@ function requireNative() {
         try {
           const binding = require('@remedia/node-win32-x64-msvc')
           const bindingPackageVersion = require('@remedia/node-win32-x64-msvc/package.json').version
-          if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -167,8 +167,8 @@ function requireNative() {
       try {
         const binding = require('@remedia/node-win32-ia32-msvc')
         const bindingPackageVersion = require('@remedia/node-win32-ia32-msvc/package.json').version
-        if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -183,8 +183,8 @@ function requireNative() {
       try {
         const binding = require('@remedia/node-win32-arm64-msvc')
         const bindingPackageVersion = require('@remedia/node-win32-arm64-msvc/package.json').version
-        if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -202,8 +202,8 @@ function requireNative() {
     try {
       const binding = require('@remedia/node-darwin-universal')
       const bindingPackageVersion = require('@remedia/node-darwin-universal/package.json').version
-      if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-        throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
       }
       return binding
     } catch (e) {
@@ -218,8 +218,8 @@ function requireNative() {
       try {
         const binding = require('@remedia/node-darwin-x64')
         const bindingPackageVersion = require('@remedia/node-darwin-x64/package.json').version
-        if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -234,8 +234,8 @@ function requireNative() {
       try {
         const binding = require('@remedia/node-darwin-arm64')
         const bindingPackageVersion = require('@remedia/node-darwin-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -254,8 +254,8 @@ function requireNative() {
       try {
         const binding = require('@remedia/node-freebsd-x64')
         const bindingPackageVersion = require('@remedia/node-freebsd-x64/package.json').version
-        if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -270,8 +270,8 @@ function requireNative() {
       try {
         const binding = require('@remedia/node-freebsd-arm64')
         const bindingPackageVersion = require('@remedia/node-freebsd-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -286,8 +286,8 @@ function requireNative() {
       try {
         const binding = require('@remedia/node-freebsd-ppc64')
         const bindingPackageVersion = require('@remedia/node-freebsd-ppc64/package.json').version
-        if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -307,8 +307,8 @@ function requireNative() {
         try {
           const binding = require('@remedia/node-linux-x64-musl')
           const bindingPackageVersion = require('@remedia/node-linux-x64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -323,8 +323,8 @@ function requireNative() {
         try {
           const binding = require('@remedia/node-linux-x64-gnu')
           const bindingPackageVersion = require('@remedia/node-linux-x64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -341,8 +341,8 @@ function requireNative() {
         try {
           const binding = require('@remedia/node-linux-arm64-musl')
           const bindingPackageVersion = require('@remedia/node-linux-arm64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -357,8 +357,8 @@ function requireNative() {
         try {
           const binding = require('@remedia/node-linux-arm64-gnu')
           const bindingPackageVersion = require('@remedia/node-linux-arm64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -375,8 +375,8 @@ function requireNative() {
         try {
           const binding = require('@remedia/node-linux-arm-musleabihf')
           const bindingPackageVersion = require('@remedia/node-linux-arm-musleabihf/package.json').version
-          if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -391,8 +391,8 @@ function requireNative() {
         try {
           const binding = require('@remedia/node-linux-arm-gnueabihf')
           const bindingPackageVersion = require('@remedia/node-linux-arm-gnueabihf/package.json').version
-          if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -409,8 +409,8 @@ function requireNative() {
         try {
           const binding = require('@remedia/node-linux-loong64-musl')
           const bindingPackageVersion = require('@remedia/node-linux-loong64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -425,8 +425,8 @@ function requireNative() {
         try {
           const binding = require('@remedia/node-linux-loong64-gnu')
           const bindingPackageVersion = require('@remedia/node-linux-loong64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -443,8 +443,8 @@ function requireNative() {
         try {
           const binding = require('@remedia/node-linux-riscv64-musl')
           const bindingPackageVersion = require('@remedia/node-linux-riscv64-musl/package.json').version
-          if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -459,8 +459,8 @@ function requireNative() {
         try {
           const binding = require('@remedia/node-linux-riscv64-gnu')
           const bindingPackageVersion = require('@remedia/node-linux-riscv64-gnu/package.json').version
-          if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
           return binding
         } catch (e) {
@@ -476,8 +476,8 @@ function requireNative() {
       try {
         const binding = require('@remedia/node-linux-ppc64-gnu')
         const bindingPackageVersion = require('@remedia/node-linux-ppc64-gnu/package.json').version
-        if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -492,8 +492,8 @@ function requireNative() {
       try {
         const binding = require('@remedia/node-linux-s390x-gnu')
         const bindingPackageVersion = require('@remedia/node-linux-s390x-gnu/package.json').version
-        if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -512,8 +512,8 @@ function requireNative() {
       try {
         const binding = require('@remedia/node-openharmony-arm64')
         const bindingPackageVersion = require('@remedia/node-openharmony-arm64/package.json').version
-        if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -528,8 +528,8 @@ function requireNative() {
       try {
         const binding = require('@remedia/node-openharmony-x64')
         const bindingPackageVersion = require('@remedia/node-openharmony-x64/package.json').version
-        if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -544,8 +544,8 @@ function requireNative() {
       try {
         const binding = require('@remedia/node-openharmony-arm')
         const bindingPackageVersion = require('@remedia/node-openharmony-arm/package.json').version
-        if (bindingPackageVersion !== '0.1.0-dev.2' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
-          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        if (bindingPackageVersion !== '0.1.0-dev.4' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
         }
         return binding
       } catch (e) {
@@ -686,8 +686,8 @@ if (!nativeBinding || forceWasi) {
       if (!candidateFailed) {
         if (process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
           const bindingPackageVersion = require('@remedia/node-wasm32-wasi/package.json').version
-          if (bindingPackageVersion !== '0.1.0-dev.2') {
-            throw new Error(`WASI binding package version mismatch, expected 0.1.0-dev.2 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          if (bindingPackageVersion !== '0.1.0-dev.4') {
+            throw new Error(`WASI binding package version mismatch, expected 0.1.0-dev.4 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
           }
         }
         wasiBinding = require('@remedia/node-wasm32-wasi')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remedia/node",
-  "version": "0.1.0-dev.2",
+  "version": "0.1.0-dev.4",
   "description": "Native Node.js playback and Discord voice bindings for Remedia",
   "license": "MIT",
   "author": "Twilight <hello@twlite.dev>",
@@ -61,19 +61,19 @@
   },
   "private": false,
   "optionalDependencies": {
-    "@remedia/node-linux-x64-gnu": "0.1.0-dev.2",
-    "@remedia/node-linux-arm64-gnu": "0.1.0-dev.2",
-    "@remedia/node-darwin-x64": "0.1.0-dev.2",
-    "@remedia/node-darwin-arm64": "0.1.0-dev.2",
-    "@remedia/node-win32-x64-msvc": "0.1.0-dev.2",
-    "@remedia/node-linux-x64-musl": "0.1.0-dev.2",
-    "@remedia/node-linux-arm64-musl": "0.1.0-dev.2",
-    "@remedia/node-linux-arm-gnueabihf": "0.1.0-dev.2",
-    "@remedia/node-win32-ia32-msvc": "0.1.0-dev.2",
-    "@remedia/node-win32-arm64-msvc": "0.1.0-dev.2",
-    "@remedia/node-android-arm64": "0.1.0-dev.2",
-    "@remedia/node-android-arm-eabi": "0.1.0-dev.2",
-    "@remedia/node-freebsd-x64": "0.1.0-dev.2"
+    "@remedia/node-linux-x64-gnu": "0.1.0-dev.4",
+    "@remedia/node-linux-arm64-gnu": "0.1.0-dev.4",
+    "@remedia/node-darwin-x64": "0.1.0-dev.4",
+    "@remedia/node-darwin-arm64": "0.1.0-dev.4",
+    "@remedia/node-win32-x64-msvc": "0.1.0-dev.4",
+    "@remedia/node-linux-x64-musl": "0.1.0-dev.4",
+    "@remedia/node-linux-arm64-musl": "0.1.0-dev.4",
+    "@remedia/node-linux-arm-gnueabihf": "0.1.0-dev.4",
+    "@remedia/node-win32-ia32-msvc": "0.1.0-dev.4",
+    "@remedia/node-win32-arm64-msvc": "0.1.0-dev.4",
+    "@remedia/node-android-arm64": "0.1.0-dev.4",
+    "@remedia/node-android-arm-eabi": "0.1.0-dev.4",
+    "@remedia/node-freebsd-x64": "0.1.0-dev.4"
   },
   "scripts": {
     "build": "pnpm run build:native && pnpm run build:types",