@remedia/node 0.1.0-dev.4 → 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/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;
+}];