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

package/README.md

@@ -34,18 +34,32 @@ Requires Node.js **22.18.0 or newer** (ESM).
 npm install @remedia/node
 ```
 
-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.
+Install FFmpeg 9 shared libraries separately on the Node.js host. npm does not install FFmpeg, and
+importing the package never downloads anything. The Remedia installer provisions FFmpeg 9.0.2 only
+(no server) into `~/.remedia/ffmpeg9`, which the package finds automatically:
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/twlite/remedia/main/scripts/install.sh | sh -s -- --ffmpeg-only
+```
+
+```powershell
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/twlite/remedia/main/scripts/install.ps1))) -FFmpegOnly
+```
+
+No `LD_LIBRARY_PATH`, `DYLD_LIBRARY_PATH`, `PATH` change, or launcher is needed. Discovery order:
+`REMEDIA_FFMPEG_DIR` (an explicit override that is never silently replaced), an existing system
+FFmpeg 9, then `~/.remedia/ffmpeg9`. Required ABI majors are avcodec 63, avformat 63, avutil 61,
+avfilter 12, and swresample 7. `getFfmpegRuntime()` reports which installation was loaded, and a
+failed import lists the paths considered. libopus is statically included; FFmpeg is dynamically linked.
+FFmpeg is needed on the Node.js host in embedded mode; in remote mode it is needed on the
+`remedia-server` host instead.
 
 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,
 Windows x86/ARM64 MSVC, and Android ARM64/ARMv7 (API 24). Build-only targets have no native runtime
 integration coverage. See the [distribution guide](https://github.com/twlite/remedia/blob/main/apps/docs/content/docs/node/distribution.mdx)
-for verification limits and library discovery: `LD_LIBRARY_PATH` on Linux/FreeBSD,
-`DYLD_LIBRARY_PATH` on macOS, and DLL directories on `PATH` on Windows. For load errors, check
-matching architecture/ABI, transitive FFmpeg dependencies, and that optional npm dependencies were
-installed. Windows also needs the Visual C++ v14 runtime.
+and [native library troubleshooting](https://github.com/twlite/remedia/blob/main/apps/docs/content/docs/node/troubleshooting.mdx)
+for verification limits and load errors. Windows also needs the Visual C++ v14 runtime.
 
 ```js
 import { Remedia } from '@remedia/node';

package/dist/bootstrap-locator.d.ts

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

package/dist/bootstrap-locator.js

@@ -0,0 +1,104 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+const require = createRequire(import.meta.url);
+/**
+ * Whether Linux uses musl rather than glibc, mirroring the generated napi-rs loader's decision so
+ * that the bootstrap comes from the same platform package as the engine addon.
+ */
+function isMusl() {
+    // @types/node does not declare `excludeNetwork`, which keeps the report from doing DNS lookups.
+    const report = process.report;
+    if (typeof report?.getReport === 'function') {
+        const previous = report.excludeNetwork;
+        try {
+            report.excludeNetwork = true;
+            const data = report.getReport();
+            if (data.header?.glibcVersionRuntime)
+                return false;
+            if (data.sharedObjects?.some((object) => object.includes('libc.musl-') || object.includes('ld-musl-'))) {
+                return true;
+            }
+        }
+        catch {
+            // Fall through to the filesystem check.
+        }
+        finally {
+            report.excludeNetwork = previous;
+        }
+    }
+    try {
+        return readFileSync('/usr/bin/ldd', 'utf8').includes('musl');
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * napi-rs platform suffixes that may hold this machine's addons, in the generated loader's order.
+ *
+ * @param platform - Node.js platform string.
+ * @param arch - Node.js architecture string.
+ * @param musl - Whether a Linux system uses musl; only consulted on Linux.
+ * @returns Suffixes such as `linux-x64-gnu` or `darwin-arm64`; empty when unsupported.
+ * @internal
+ */
+export function platformSuffixes(platform, arch, musl = isMusl) {
+    switch (platform) {
+        case 'linux': {
+            const libc = musl() ? 'musl' : 'gnu';
+            if (arch === 'x64')
+                return [`linux-x64-${libc}`];
+            if (arch === 'arm64')
+                return [`linux-arm64-${libc}`];
+            if (arch === 'arm')
+                return [libc === 'musl' ? 'linux-arm-musleabihf' : 'linux-arm-gnueabihf'];
+            return [];
+        }
+        case 'darwin':
+            return ['darwin-universal', `darwin-${arch}`];
+        case 'win32':
+            return arch === 'x64'
+                ? ['win32-x64-msvc']
+                : arch === 'ia32'
+                    ? ['win32-ia32-msvc']
+                    : arch === 'arm64'
+                        ? ['win32-arm64-msvc']
+                        : [];
+        case 'freebsd':
+            return [`freebsd-${arch}`];
+        case 'android':
+            return arch === 'arm64' ? ['android-arm64'] : arch === 'arm' ? ['android-arm-eabi'] : [];
+        default:
+            return [];
+    }
+}
+/**
+ * File locations where this platform's bootstrap addon could be: next to `native.js` in a source
+ * checkout, then inside the installed `@remedia/node-<suffix>` platform package.
+ *
+ * @param packageRoot - Directory of the `@remedia/node` package.
+ * @param suffixes - Platform suffixes from {@link platformSuffixes}.
+ * @param resolvePackage - Resolves a module specifier to a file path; throws if absent.
+ * @returns Existing file paths in preference order.
+ * @internal
+ */
+export function bootstrapCandidates(packageRoot, suffixes, resolvePackage = (specifier) => require.resolve(specifier)) {
+    const candidates = [];
+    for (const suffix of suffixes) {
+        const fileName = `bootstrap.${suffix}.node`;
+        const local = join(packageRoot, fileName);
+        if (existsSync(local))
+            candidates.push(local);
+        try {
+            const manifest = resolvePackage(`@remedia/node-${suffix}/package.json`);
+            const packaged = join(dirname(manifest), fileName);
+            if (existsSync(packaged))
+                candidates.push(packaged);
+        }
+        catch {
+            // The optional platform package is not installed.
+        }
+    }
+    return candidates;
+}

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/ffmpeg-runtime.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Where the loaded FFmpeg installation came from.
+ *
+ * - `explicit`: the `REMEDIA_FFMPEG_DIR` environment variable.
+ * - `system`: an installation the platform's library search finds (package manager, Homebrew,
+ *   `LD_LIBRARY_PATH`, `DYLD_LIBRARY_PATH`, `PATH`, ...).
+ * - `managed`: the Remedia installer's `~/.remedia/ffmpeg9` prefix.
+ * - `unmanaged`: the platform has no bootstrap addon, so the operating system's loader resolved
+ *   FFmpeg on its own and Remedia cannot report which installation it chose.
+ */
+export type FfmpegSource = 'explicit' | 'system' | 'managed' | 'unmanaged';
+/**
+ * Why an FFmpeg installation candidate was rejected, where that can be determined.
+ *
+ * - `not-found`: the directory does not exist.
+ * - `missing-libraries`: required FFmpeg libraries are absent from the directory.
+ * - `abi-mismatch`: libraries exist but have a different ABI major than FFmpeg 9 requires.
+ * - `architecture-mismatch`: the libraries were built for a different CPU architecture.
+ * - `unresolved-dependency`: a library or one of its own dependencies could not be resolved.
+ * - `mixed-installations`: the five libraries did not all come from one directory.
+ * - `load-failed`: the loader rejected a library for another reason.
+ */
+export type FfmpegFailureReason = 'not-found' | 'missing-libraries' | 'abi-mismatch' | 'architecture-mismatch' | 'unresolved-dependency' | 'mixed-installations' | 'load-failed';
+/** One FFmpeg shared library loaded by Remedia. */
+export interface FfmpegLibraryInfo {
+    /** FFmpeg library name without the `lib` prefix, for example `avcodec`. */
+    readonly name: string;
+    /** Absolute path of the loaded file as reported by the operating system. */
+    readonly path: string;
+    /** Library version reported by the library itself, as `major.minor.micro`. */
+    readonly version: string;
+    /** ABI major version, which must match the FFmpeg 9 requirement for `name`. */
+    readonly major: number;
+}
+/** What discovery concluded about one FFmpeg installation candidate. */
+export interface FfmpegCandidateReport {
+    /** Which discovery step produced this candidate. */
+    readonly source: Exclude<FfmpegSource, 'unmanaged'>;
+    /** Directory that was inspected, or `null` when the step looked at several directories. */
+    readonly directory: string | null;
+    /** Whether this candidate was loaded (`selected`) or not. */
+    readonly outcome: 'selected' | 'rejected';
+    /** Classified rejection cause when `outcome` is `rejected` and the cause is known. */
+    readonly reason?: FfmpegFailureReason;
+    /** Human-readable explanation, including the loader's own message where available. */
+    readonly detail?: string;
+}
+/** The FFmpeg runtime that `@remedia/node` loaded. */
+export interface FfmpegRuntimeInfo {
+    /** How the installation was found. */
+    readonly source: FfmpegSource;
+    /** Directory containing the loaded libraries, or `null` when `source` is `unmanaged`. */
+    readonly directory: string | null;
+    /** The five loaded libraries in load order; empty when `source` is `unmanaged`. */
+    readonly libraries: readonly FfmpegLibraryInfo[];
+    /** Every candidate discovery examined, in order, including the selected one. */
+    readonly considered: readonly FfmpegCandidateReport[];
+}
+/** Command that installs FFmpeg 9 on Linux and macOS with the Remedia installer. */
+export declare 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 declare 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 declare class FfmpegLoadError extends Error {
+    /** Every candidate that was examined, in order. */
+    readonly candidates: readonly FfmpegCandidateReport[];
+    /**
+     * @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: readonly FfmpegCandidateReport[], explicitOverride: boolean, platform?: NodeJS.Platform);
+}
+/** FFmpeg 9 shared libraries in dependency order (leaf libraries first) with their ABI majors. */
+export declare const FFMPEG_LIBRARIES: readonly [{
+    readonly name: "avutil";
+    readonly major: 61;
+}, {
+    readonly name: "swresample";
+    readonly major: 7;
+}, {
+    readonly name: "avcodec";
+    readonly major: 63;
+}, {
+    readonly name: "avformat";
+    readonly major: 63;
+}, {
+    readonly name: "avfilter";
+    readonly major: 12;
+}];