@remedia/node 0.1.0-dev.4 → 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 { 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/native-binding.d.ts

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

package/dist/native-binding.js

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

package/dist/remedia.d.ts

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

package/dist/remedia.js

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