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

package/dist/ffmpeg-runtime.js

@@ -0,0 +1,499 @@
+import { closeSync, existsSync, openSync, readFileSync, readSync, readdirSync, realpathSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, dirname, isAbsolute, join, resolve } from 'node:path';
+/** Command that installs FFmpeg 9 on Linux and macOS with the Remedia installer. */
+export const UNIX_INSTALL_COMMAND = 'curl -fsSL https://raw.githubusercontent.com/twlite/remedia/main/scripts/install.sh | sh -s -- --ffmpeg-only';
+/** Command that installs FFmpeg 9 on Windows PowerShell with the Remedia installer. */
+export const WINDOWS_INSTALL_COMMAND = '& ([scriptblock]::Create((irm https://raw.githubusercontent.com/twlite/remedia/main/scripts/install.ps1))) -FFmpegOnly';
+/**
+ * Raised when no compatible FFmpeg 9 installation could be loaded, or when an explicit
+ * `REMEDIA_FFMPEG_DIR` override is unusable. The message lists every path considered and how to
+ * install or point to FFmpeg.
+ */
+export class FfmpegLoadError extends Error {
+    /** Every candidate that was examined, in order. */
+    candidates;
+    /**
+     * @param candidates - Reports for each installation candidate that was examined.
+     * @param explicitOverride - Whether `REMEDIA_FFMPEG_DIR` was set, which disables fallbacks.
+     * @param platform - Platform used to choose the install command shown in the message.
+     */
+    constructor(candidates, explicitOverride, platform = process.platform) {
+        super(describeFailure(candidates, explicitOverride, platform));
+        this.name = 'FfmpegLoadError';
+        this.candidates = candidates;
+    }
+}
+/** FFmpeg 9 shared libraries in dependency order (leaf libraries first) with their ABI majors. */
+export const FFMPEG_LIBRARIES = [
+    { name: 'avutil', major: 61 },
+    { name: 'swresample', major: 7 },
+    { name: 'avcodec', major: 63 },
+    { name: 'avformat', major: 63 },
+    { name: 'avfilter', major: 12 },
+];
+/**
+ * The current process as a {@link DiscoveryEnvironment}.
+ *
+ * @returns Facts read from `process` and the operating system.
+ * @internal
+ */
+export function currentEnvironment() {
+    return {
+        platform: process.platform,
+        arch: process.arch,
+        env: process.env,
+        homeDirectory: homedir(),
+        execPath: process.execPath,
+    };
+}
+/**
+ * File name of one FFmpeg library at its ABI major on a platform.
+ *
+ * @param name - FFmpeg library name without the `lib` prefix.
+ * @param major - ABI major version.
+ * @param platform - Node.js platform string.
+ * @returns For example `libavcodec.so.63`, `libavcodec.63.dylib` or `avcodec-63.dll`.
+ * @internal
+ */
+export function libraryFileName(name, major, platform) {
+    if (platform === 'win32')
+        return `${name}-${major}.dll`;
+    if (platform === 'darwin')
+        return `lib${name}.${major}.dylib`;
+    return `lib${name}.so.${major}`;
+}
+/**
+ * Directories of a prefix that may hold the shared libraries, most specific first.
+ *
+ * @param root - A prefix such as `~/.remedia/ffmpeg9`, or the library directory itself.
+ * @param platform - Node.js platform string.
+ * @returns Candidate library directories inside `root`.
+ * @internal
+ */
+export function layoutDirectories(root, platform) {
+    if (platform === 'win32')
+        return [join(root, 'Library', 'bin'), join(root, 'bin'), root];
+    return [join(root, 'lib'), join(root, 'lib64'), root];
+}
+/**
+ * Default location of the installer-managed FFmpeg prefix for the executing user.
+ *
+ * @param environment - Process facts; only the home directory is used.
+ * @returns `<home>/.remedia/ffmpeg9`.
+ * @internal
+ */
+export function managedPrefix(environment) {
+    return join(environment.homeDirectory, '.remedia', 'ffmpeg9');
+}
+function splitPathList(value) {
+    return (value ?? '')
+        .split(delimiter)
+        .map((entry) => entry.trim().replace(/^"(.*)"$/, '$1'))
+        .filter((entry) => entry.length > 0 && isAbsolute(entry));
+}
+function readLoaderConfiguration(file, depth = 0) {
+    if (depth > 4)
+        return [];
+    let contents;
+    try {
+        contents = readFileSync(file, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const directories = [];
+    for (const rawLine of contents.split('\n')) {
+        const line = rawLine.replace(/#.*$/, '').trim();
+        if (line.length === 0)
+            continue;
+        if (line.startsWith('include ')) {
+            const pattern = line.slice('include '.length).trim();
+            const directory = dirname(pattern);
+            const matcher = new RegExp(`^${pattern
+                .slice(directory.length + 1)
+                .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+                .replace(/\*/g, '.*')
+                .replace(/\?/g, '.')}$`);
+            try {
+                for (const entry of readdirSync(directory).sort()) {
+                    if (matcher.test(entry)) {
+                        directories.push(...readLoaderConfiguration(join(directory, entry), depth + 1));
+                    }
+                }
+            }
+            catch {
+                // A missing include directory is normal.
+            }
+        }
+        else if (isAbsolute(line)) {
+            directories.push(line);
+        }
+    }
+    return directories;
+}
+/**
+ * Directories the platform's own library search would consult, for finding an existing
+ * system-wide FFmpeg without invoking the loader (which could half-load a broken installation).
+ *
+ * The current directory is never included, so a planted library there cannot be selected.
+ *
+ * @param environment - Process facts.
+ * @returns De-duplicated absolute directories in search order.
+ * @internal
+ */
+export function systemDirectories(environment) {
+    const { platform, arch, env } = environment;
+    let directories = [];
+    if (platform === 'win32') {
+        directories = [dirname(environment.execPath), ...splitPathList(env.PATH ?? env.Path)];
+    }
+    else if (platform === 'darwin') {
+        directories = [
+            ...splitPathList(env.DYLD_LIBRARY_PATH),
+            ...splitPathList(env.DYLD_FALLBACK_LIBRARY_PATH),
+            '/opt/homebrew/opt/ffmpeg/lib',
+            '/usr/local/opt/ffmpeg/lib',
+            '/opt/homebrew/lib',
+            '/usr/local/lib',
+        ];
+    }
+    else if (platform === 'linux') {
+        const multiarch = arch === 'x64'
+            ? 'x86_64-linux-gnu'
+            : arch === 'arm64'
+                ? 'aarch64-linux-gnu'
+                : arch === 'arm'
+                    ? 'arm-linux-gnueabihf'
+                    : null;
+        directories = [
+            ...splitPathList(env.LD_LIBRARY_PATH),
+            ...readLoaderConfiguration('/etc/ld.so.conf'),
+            '/usr/local/lib',
+            ...(multiarch ? [`/usr/lib/${multiarch}`, `/lib/${multiarch}`] : []),
+            '/usr/lib64',
+            '/usr/lib',
+            '/lib64',
+            '/lib',
+        ];
+    }
+    else if (platform === 'freebsd') {
+        directories = [...splitPathList(env.LD_LIBRARY_PATH), '/usr/local/lib', '/usr/lib', '/lib'];
+    }
+    else {
+        directories = splitPathList(env.LD_LIBRARY_PATH);
+    }
+    return [...new Set(directories.map((directory) => resolve(directory)))];
+}
+/**
+ * Architectures a native binary is built for, read from its file header.
+ *
+ * @param file - Path to an ELF, Mach-O (thin or universal) or PE file.
+ * @returns Node.js `process.arch` names, or `null` when the format is not recognized.
+ * @internal
+ */
+export function binaryArchitectures(file) {
+    const header = Buffer.alloc(65_536);
+    let length;
+    let descriptor = null;
+    try {
+        descriptor = openSync(file, 'r');
+        length = readSync(descriptor, header, 0, header.length, 0);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (descriptor !== null)
+            closeSync(descriptor);
+    }
+    if (length < 20)
+        return null;
+    const mapCpu = (table, value) => table[value] ? [table[value]] : [];
+    // ELF
+    if (header.readUInt32BE(0) === 0x7f454c46) {
+        const little = header[5] === 1;
+        const machine = little ? header.readUInt16LE(18) : header.readUInt16BE(18);
+        return mapCpu({ 62: 'x64', 183: 'arm64', 3: 'ia32', 40: 'arm' }, machine);
+    }
+    // Mach-O thin (little endian host order for every supported Apple CPU)
+    const magic = header.readUInt32LE(0);
+    if (magic === 0xfeedfacf || magic === 0xfeedface) {
+        return mapCpu({ 0x01000007: 'x64', 0x0100000c: 'arm64', 7: 'ia32', 12: 'arm' }, header.readUInt32LE(4));
+    }
+    // Mach-O universal (always big endian)
+    if (header.readUInt32BE(0) === 0xcafebabe || header.readUInt32BE(0) === 0xcafebabf) {
+        const wide = header.readUInt32BE(0) === 0xcafebabf;
+        const count = header.readUInt32BE(4);
+        const size = wide ? 32 : 20;
+        if (count === 0 || count > 16)
+            return null;
+        const architectures = [];
+        for (let index = 0; index < count && 8 + (index + 1) * size <= length; index += 1) {
+            architectures.push(...mapCpu({ 0x01000007: 'x64', 0x0100000c: 'arm64', 7: 'ia32', 12: 'arm' }, header.readUInt32BE(8 + index * size)));
+        }
+        return architectures;
+    }
+    // PE
+    if (header[0] === 0x4d && header[1] === 0x5a && length >= 0x40) {
+        const offset = header.readUInt32LE(0x3c);
+        if (offset + 6 <= length && header.readUInt32LE(offset) === 0x00004550) {
+            return mapCpu({ 0x8664: 'x64', 0xaa64: 'arm64', 0x14c: 'ia32', 0x1c4: 'arm' }, header.readUInt16LE(offset + 4));
+        }
+    }
+    return null;
+}
+function inspectDirectory(directory, platform) {
+    const missing = [];
+    const otherMajors = [];
+    const files = [];
+    let entries = [];
+    try {
+        entries = readdirSync(directory);
+    }
+    catch {
+        // Reported as missing libraries below.
+    }
+    for (const { name, major } of FFMPEG_LIBRARIES) {
+        const fileName = libraryFileName(name, major, platform);
+        const path = join(directory, fileName);
+        if (existsSync(path)) {
+            files.push({ name, major, path });
+            continue;
+        }
+        missing.push(fileName);
+        const pattern = platform === 'win32'
+            ? new RegExp(`^${name}-(\\d+)\\.dll$`, 'i')
+            : platform === 'darwin'
+                ? new RegExp(`^lib${name}\\.(\\d+)\\.dylib$`)
+                : new RegExp(`^lib${name}\\.so\\.(\\d+)`);
+        for (const entry of entries) {
+            const match = pattern.exec(entry);
+            if (match)
+                otherMajors.push(`lib${name} ABI ${match[1]} (requires ${major})`);
+        }
+    }
+    return {
+        files: missing.length === 0 ? files : null,
+        missing,
+        otherMajors: [...new Set(otherMajors)],
+        found: FFMPEG_LIBRARIES.length - missing.length,
+    };
+}
+function classifyLoaderFailure(result) {
+    const message = result.message ?? '';
+    // Only Windows reports numeric codes (ERROR_MOD_NOT_FOUND and ERROR_BAD_EXE_FORMAT); Unix
+    // loaders report text, matched below.
+    if (result.code === 126)
+        return 'unresolved-dependency';
+    if (result.code === 193)
+        return 'architecture-mismatch';
+    if (/wrong ELF class|invalid ELF header|incompatible architecture|not a mach-o|bad image/i.test(message)) {
+        return 'architecture-mismatch';
+    }
+    if (/cannot open shared object file|library not loaded|image not found|module could not be found/i.test(message)) {
+        return 'unresolved-dependency';
+    }
+    return 'load-failed';
+}
+function stripExtendedPathPrefix(path) {
+    return path.startsWith('\\\\?\\') ? path.slice(4) : path;
+}
+function formatVersion(packed) {
+    return `${packed >>> 16}.${(packed >>> 8) & 0xff}.${packed & 0xff}`;
+}
+/**
+ * Load one directory's FFmpeg libraries through the bootstrap, all or nothing.
+ *
+ * Nothing stays loaded after a failure, so a later candidate can never bind to libraries left over
+ * from a rejected one.
+ *
+ * @param bootstrap - The FFmpeg-free native bootstrap.
+ * @param directory - Directory that should contain all five libraries.
+ * @param environment - Process facts.
+ * @returns The loaded libraries, or the classified rejection.
+ * @internal
+ */
+export function loadDirectory(bootstrap, directory, environment) {
+    const inspection = inspectDirectory(directory, environment.platform);
+    if (!inspection.files) {
+        const others = inspection.otherMajors.length > 0 ? ` Found: ${inspection.otherMajors.join(', ')}.` : '';
+        return {
+            ok: false,
+            reason: inspection.otherMajors.length > 0 ? 'abi-mismatch' : 'missing-libraries',
+            detail: `Missing ${inspection.missing.join(', ')}.${others}`,
+        };
+    }
+    for (const { path } of inspection.files) {
+        const architectures = binaryArchitectures(path);
+        if (architectures !== null && !architectures.includes(environment.arch)) {
+            return {
+                ok: false,
+                reason: 'architecture-mismatch',
+                detail: `${path} is built for ${architectures.join('/') || 'an unknown CPU'}, but this process is ${environment.arch}.`,
+            };
+        }
+    }
+    const libraries = [];
+    const fail = (rejection) => {
+        bootstrap.rollbackLoaded();
+        return { ok: false, ...rejection };
+    };
+    for (const { name, major, path } of inspection.files) {
+        const result = bootstrap.loadLibrary(path, `${name}_version`);
+        if (!result.ok) {
+            return fail({
+                reason: classifyLoaderFailure(result),
+                detail: `${path}: ${result.message ?? 'the loader rejected the library'}`,
+            });
+        }
+        const packed = result.version ?? 0;
+        if (packed >>> 16 !== major) {
+            return fail({
+                reason: 'abi-mismatch',
+                detail: `${path} reports lib${name} ABI ${packed >>> 16}, but ${major} is required.`,
+            });
+        }
+        let loadedPath = stripExtendedPathPrefix(result.path ?? path);
+        try {
+            loadedPath = realpathSync(loadedPath);
+        }
+        catch {
+            // Keep the reported path.
+        }
+        libraries.push({ name, path: loadedPath, version: formatVersion(packed), major });
+    }
+    const directories = new Set(libraries.map((library) => dirname(library.path)));
+    if (directories.size > 1) {
+        return fail({
+            reason: 'mixed-installations',
+            detail: `The FFmpeg libraries resolved to different directories: ${[...directories].join(', ')}.`,
+        });
+    }
+    bootstrap.commitLoaded();
+    return { ok: true, libraries, directory: dirname(libraries[0].path) };
+}
+/**
+ * Choose and load an FFmpeg 9 installation.
+ *
+ * Precedence: `REMEDIA_FFMPEG_DIR`, then an installation visible to the system, then the managed
+ * prefix `~/.remedia/ffmpeg9`. An explicit override that cannot be loaded is an error; the other
+ * steps are never consulted in that case.
+ *
+ * @param bootstrap - The FFmpeg-free native bootstrap.
+ * @param environment - Process facts; defaults to the current process.
+ * @returns The selected runtime.
+ * @throws {FfmpegLoadError} If no compatible installation can be loaded.
+ * @internal
+ */
+export function selectFfmpeg(bootstrap, environment = currentEnvironment()) {
+    const considered = [];
+    const attempt = (source, directory) => {
+        const result = loadDirectory(bootstrap, directory, environment);
+        if (result.ok) {
+            considered.push({ source, directory, outcome: 'selected' });
+            return {
+                source,
+                directory: result.directory,
+                libraries: result.libraries,
+                considered,
+            };
+        }
+        considered.push({
+            source,
+            directory,
+            outcome: 'rejected',
+            reason: result.reason,
+            detail: result.detail,
+        });
+        return null;
+    };
+    const override = environment.env.REMEDIA_FFMPEG_DIR?.trim();
+    if (override) {
+        const root = resolve(override);
+        if (!existsSync(root)) {
+            considered.push({
+                source: 'explicit',
+                directory: root,
+                outcome: 'rejected',
+                reason: 'not-found',
+                detail: 'REMEDIA_FFMPEG_DIR does not exist.',
+            });
+            throw new FfmpegLoadError(considered, true, environment.platform);
+        }
+        // The override may name the installation prefix or the library directory itself. A directory
+        // that is already complete wins; otherwise the first layout is used so its report is shown.
+        const layouts = layoutDirectories(root, environment.platform);
+        const directory = layouts.find((candidate) => inspectDirectory(candidate, environment.platform).files) ??
+            layouts.find((candidate) => existsSync(candidate)) ??
+            root;
+        const selected = attempt('explicit', directory);
+        if (selected)
+            return selected;
+        throw new FfmpegLoadError(considered, true, environment.platform);
+    }
+    const searched = environment.systemDirectories
+        ? [...environment.systemDirectories]
+        : systemDirectories(environment);
+    // A directory is worth reporting if it holds any FFmpeg library, including other ABI majors, so
+    // that an FFmpeg 7 installation is explained rather than looking like "nothing installed".
+    const withLibraries = searched.filter((directory) => {
+        const inspection = inspectDirectory(directory, environment.platform);
+        return inspection.found > 0 || inspection.otherMajors.length > 0;
+    });
+    for (const directory of withLibraries) {
+        const selected = attempt('system', directory);
+        if (selected)
+            return selected;
+    }
+    if (withLibraries.length === 0) {
+        considered.push({
+            source: 'system',
+            directory: null,
+            outcome: 'rejected',
+            reason: 'not-found',
+            detail: `No FFmpeg 9 libraries in ${searched.length} system library directories (${searched.join(', ')}).`,
+        });
+    }
+    const managed = managedPrefix(environment);
+    if (!existsSync(managed)) {
+        considered.push({
+            source: 'managed',
+            directory: managed,
+            outcome: 'rejected',
+            reason: 'not-found',
+            detail: 'The Remedia installer has not installed FFmpeg here.',
+        });
+    }
+    else {
+        const layouts = layoutDirectories(managed, environment.platform);
+        const directory = layouts.find((candidate) => inspectDirectory(candidate, environment.platform).files) ??
+            layouts[0];
+        const selected = attempt('managed', directory);
+        if (selected)
+            return selected;
+    }
+    throw new FfmpegLoadError(considered, false, environment.platform);
+}
+function describeFailure(candidates, explicitOverride, platform) {
+    const required = FFMPEG_LIBRARIES.map(({ name, major }) => `lib${name} ${major}`).join(', ');
+    const lines = [
+        explicitOverride
+            ? 'REMEDIA_FFMPEG_DIR does not point to a loadable FFmpeg 9 installation, and no other installation was tried.'
+            : 'Remedia could not load a compatible FFmpeg 9 runtime.',
+        `Required ABI majors: ${required}.`,
+        'Considered:',
+    ];
+    for (const candidate of candidates) {
+        const label = candidate.source === 'explicit' ? 'REMEDIA_FFMPEG_DIR' : candidate.source;
+        const location = candidate.directory ?? '(see detail)';
+        const status = candidate.outcome === 'selected'
+            ? 'selected'
+            : `rejected${candidate.reason ? ` (${candidate.reason})` : ''}`;
+        lines.push(`  - ${label}: ${location} -> ${status}${candidate.detail ? `: ${candidate.detail}` : ''}`);
+    }
+    lines.push('', 'Install FFmpeg 9 with the Remedia installer:', `  ${platform === 'win32' ? WINDOWS_INSTALL_COMMAND : UNIX_INSTALL_COMMAND}`, platform === 'win32'
+        ? 'To use another FFmpeg 9 prefix, set REMEDIA_FFMPEG_DIR to the directory that contains Library\\bin.'
+        : 'To use another FFmpeg 9 prefix, set REMEDIA_FFMPEG_DIR to the directory that contains lib/.');
+    return lines.join('\n');
+}

package/dist/index.d.ts

@@ -4,6 +4,10 @@ export type { DiscordGatewayPacket, DiscordGatewaySend, DiscordGatewayVoicePaylo
 export { PlaybackSession } from './playback.js';
 export { PlaybackHooks, PlaybackSessionEvents, RemediaEvents, VoiceSessionEvents, } from './lifecycle.js';
 export { Remedia, type ProbeOptions, type RemediaOptions } from './remedia.js';
+export { getFfmpegRuntime } from './native-binding.js';
+export { FfmpegLoadError } from './ffmpeg-runtime.js';
+export type { FfmpegCandidateReport, FfmpegFailureReason, FfmpegLibraryInfo, FfmpegRuntimeInfo, FfmpegSource, } from './ffmpeg-runtime.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';
+export type { ResourceMemory, ResourceCpu, ProcessResourceStatistics } from './resources.js';

package/dist/index.js

@@ -2,3 +2,5 @@ export { DiscordSession } from './discord.js';
 export { PlaybackSession } from './playback.js';
 export { PlaybackHooks, PlaybackSessionEvents, RemediaEvents, VoiceSessionEvents, } from './lifecycle.js';
 export { Remedia } from './remedia.js';
+export { getFfmpegRuntime } from './native-binding.js';
+export { FfmpegLoadError } from './ffmpeg-runtime.js';

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. */