@lox-audioserver/node-librespot 0.3.2

package/Cargo.toml

@@ -0,0 +1,32 @@
+[package]
+name = "librespot-addon"
+version = "0.1.0"
+edition = "2021"
+description = "Rust-based librespot binding for Node via N-API."
+license = "Apache-2.0"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+napi = { version = "2", features = ["tokio_rt"] }
+napi-derive = "2"
+tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
+futures = "0.3"
+bytes = "1"
+bytemuck = { version = "1", features = ["extern_crate_alloc"] }
+librespot-core = { path = "./librespot-dev/core", default-features = false, features = [
+    "rustls-tls-native-roots",
+] }
+librespot-audio = { path = "./librespot-dev/audio", default-features = false, features = [
+    "rustls-tls-native-roots",
+] }
+librespot-playback = { path = "./librespot-dev/playback", default-features = false }
+librespot-discovery = { path = "./librespot-dev/discovery", default-features = false, features = [
+    "with-libmdns",
+] }
+librespot-connect = { path = "./librespot-dev/connect", default-features = false }
+librespot-metadata = { path = "./librespot-dev/metadata", default-features = false }
+serde_json = "1"
+tokio-stream = "0.1"
+log = { version = "0.4", features = ["std"] }

package/README.md

@@ -0,0 +1,105 @@
+# node-librespot
+
+Native Node.js bindings for [librespot](https://github.com/librespot-org/librespot) (Spotify Connect) using N-API. Streams PCM directly to JavaScript without spawning the librespot binary.
+
+Used by [lox-audioserver](https://github.com/rudyberends/lox-audioserver) to handle spotify traffic, but can be used by other software.
+
+## Features
+- Stream a Spotify track/episode to PCM buffers (`streamTrack`) using a Web API **access token**.
+- Host a Spotify Connect endpoint with a Web API access token + your own Spotify app client id (`startConnectDeviceWithToken`).
+- No disk cache required; everything stays in-memory.
+- Starts Connect hosts at max volume (volume control stays on the consumer side).
+- `startConnectDevice` (credential-blob based) is deprecated and will error.
+
+## Install
+```bash
+npm install
+```
+
+## Build
+Requires Rust (stable) and `@napi-rs/cli` (installed via devDependencies).
+```bash
+npm run build          # release build
+# or
+npm run build:debug    # debug build
+# or (for publishing) generate host prebuild + JS/types
+npm run build:prebuild
+```
+
+Runtime will load `librespot_addon.node` from `prebuilds/<platform-arch>/` when available, otherwise it falls back to `LOX_LIBRESPOT_ADDON_PATH` or the locally compiled `dist/librespot_addon.node`.
+
+## Usage
+```ts
+import { createSession, setLogLevel } from 'node-librespot';
+
+setLogLevel('debug'); // off|error|warn|info|debug|trace
+
+const session = await createSession({
+  accessToken,          // user Web API access token (PKCE/Authorization Code)
+  clientId,             // your Spotify app client id
+  deviceName: 'lox-zone-1',
+});
+
+const handle = session.streamTrack(
+  { uri: 'spotify:track:...', bitrate: 320 },
+  (chunk) => {
+    // chunk is a Buffer with PCM s16le frames (44.1kHz stereo)
+  },
+  (event) => {
+    // optional events: playing/paused/loading/stopped/end_of_track/error/health/metric
+    // error codes include: audio_key_error, no_pcm, end_of_track, pcm_missing, pcm_stalled, unavailable
+    // metric names include: first_pcm_ms, buffer_stall_ms, decode_error
+  },
+  (log) => {
+    // optional logging callback { level, message, scope }
+  },
+);
+
+// Host a Connect device with the same token
+import { startConnectDeviceWithToken } from 'node-librespot';
+
+const host = await startConnectDeviceWithToken(
+  accessToken,
+  clientId,
+  'Lox-AudioServer', // publish name
+  'lox-zone-1',      // device id
+  (chunk) => { /* PCM s16le frames */ },
+  (event) => { /* playing/paused/loading/end_of_track/error/health/metric with metadata */ },
+  (log) => { /* optional log callback */ },
+);
+
+host.play();
+host.pause();
+host.next();
+host.prev();
+host.stop();
+host.shutdown(); // alias for stop()
+host.close();    // alias for stop()
+
+// Or pull decrypted audio file bytes (Ogg/MP3) without decoding:
+const download = await downloadTrack(
+  { uri: 'spotify:track:...', bitrate: 320 },
+  (chunk) => {
+    // chunk is a Buffer with decrypted compressed audio data
+  },
+  (log) => {
+    // optional logging callback { level, message, scope }
+  },
+);
+// download.stop() to cancel
+// Promise rejects on initial errors (invalid URI, unavailable track, key/file fetch failure).
+
+handle.stop();
+```
+
+## Authentication
+- Only Web API access tokens are supported (bring your own PKCE/Authorization Code flow).
+- Supply your app’s client id via `clientId` or `LOX_LIBRESPOT_CLIENT_ID` env var.
+- `startConnectDevice` is removed; use `startConnectDeviceWithToken` instead.
+
+If the token is invalid/expired, playback/Connect hosting will fail; refresh the token in your host app and retry.
+
+## Development / publish
+- CI: `.github/workflows/prebuild.yml` runs on release creation, building prebuild artifacts for Linux x64 (glibc), Linux arm64 (glibc), and macOS arm64 before publishing to npm (requires `NPM_TOKEN` secret).
+- Local publish flow: `npm run build:prebuild` to generate host prebuild + JS/types, then `npm publish`.
+- Install from source: `npm install` will try to use an included prebuild; if none matches the host it will build from source automatically (set `LOX_LIBRESPOT_SKIP_BUILD=1` to skip).

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+import type { ConnectHandle, ConnectEvent, CreateSessionOpts, CredentialsResult, LibrespotSession, LogEvent, DownloadTrackOpts, DownloadHandle } from './types';
+declare const native: {
+    createSession(opts: CreateSessionOpts): Promise<LibrespotSession>;
+    setLogLevel(level: string): void;
+    loginWithAccessToken(accessToken: string, deviceName?: string): Promise<CredentialsResult>;
+    downloadTrack(opts: DownloadTrackOpts, onChunk: (chunk: Buffer) => void, onLog?: (event: LogEvent) => void): Promise<DownloadHandle>;
+    startZeroconfLogin(deviceId: string, name?: string | null, timeoutMs?: number | null): Promise<CredentialsResult>;
+    startConnectDevice(credentialsPath: string, name: string, deviceId: string, onChunk: (chunk: Buffer) => void, onEvent?: (event: ConnectEvent) => void, onLog?: (event: LogEvent) => void): Promise<ConnectHandle>;
+    startConnectDeviceWithToken(accessToken: string, clientId: string | undefined, name: string, deviceId: string, onChunk: (chunk: Buffer) => void, onEvent?: (event: ConnectEvent) => void, onLog?: (event: LogEvent) => void): Promise<ConnectHandle>;
+};
+export declare function createSession(opts: CreateSessionOpts): Promise<LibrespotSession>;
+export declare function loginWithAccessToken(accessToken: string, deviceName?: string): Promise<CredentialsResult>;
+export declare function startZeroconfLogin(deviceId: string, name?: string, timeoutMs?: number): Promise<CredentialsResult>;
+export declare function startConnectDevice(credentialsPath: string, name: string, deviceId: string, onChunk: (chunk: Buffer) => void, onEvent?: (event: ConnectEvent) => void, onLog?: (event: LogEvent) => void): Promise<ConnectHandle>;
+export declare function startConnectDeviceWithToken(accessToken: string, clientId: string | undefined, name: string, deviceId: string, onChunk: (chunk: Buffer) => void, onEvent?: (event: ConnectEvent) => void, onLog?: (event: LogEvent) => void): Promise<ConnectHandle>;
+export declare function setLogLevel(level: string): void;
+export declare function downloadTrack(opts: DownloadTrackOpts, onChunk: (chunk: Buffer) => void, onLog?: (event: LogEvent) => void): Promise<DownloadHandle>;
+export { native };
+export * from './types';

package/dist/index.js

@@ -0,0 +1,151 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.native = void 0;
+exports.createSession = createSession;
+exports.loginWithAccessToken = loginWithAccessToken;
+exports.startZeroconfLogin = startZeroconfLogin;
+exports.startConnectDevice = startConnectDevice;
+exports.startConnectDeviceWithToken = startConnectDeviceWithToken;
+exports.setLogLevel = setLogLevel;
+exports.downloadTrack = downloadTrack;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+function detectLibc() {
+    const glibcVersionRuntime = 
+    // @ts-expect-error
+    process.report?.getReport?.()?.header?.glibcVersionRuntime;
+    return glibcVersionRuntime ? 'gnu' : 'musl';
+}
+function platformArchABI() {
+    const { platform, arch } = process;
+    if (platform === 'linux') {
+        return `linux-${arch}-${detectLibc()}`;
+    }
+    if (platform === 'darwin') {
+        return `darwin-${arch}`;
+    }
+    if (platform === 'win32') {
+        return `win32-${arch}-msvc`;
+    }
+    throw new Error(`Unsupported platform ${platform}-${arch}`);
+}
+function resolveNativeBinding() {
+    const override = process.env.LOX_LIBRESPOT_ADDON_PATH;
+    if (override && node_fs_1.default.existsSync(override)) {
+        return override;
+    }
+    const prebuiltPath = node_path_1.default.join(__dirname, '..', 'prebuilds', platformArchABI(), 'librespot_addon.node');
+    if (node_fs_1.default.existsSync(prebuiltPath)) {
+        return prebuiltPath;
+    }
+    const localBuildPath = node_path_1.default.join(__dirname, 'librespot_addon.node');
+    if (node_fs_1.default.existsSync(localBuildPath)) {
+        return localBuildPath;
+    }
+    throw new Error(`librespot_addon.node not found for ${platformArchABI()}. ` +
+        'Install a prebuilt binary, build locally with "npm run build", ' +
+        'or point LOX_LIBRESPOT_ADDON_PATH to the compiled addon.');
+}
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const native = require(resolveNativeBinding());
+exports.native = native;
+function wrapStreamHandle(handle) {
+    return {
+        stop: () => handle.stop(),
+        get sampleRate() {
+            return handle.sampleRate ?? handle.sample_rate ?? handle.sampleRate;
+        },
+        get channels() {
+            return handle.channels ?? handle.channels;
+        },
+    };
+}
+function wrapSession(session) {
+    return {
+        streamTrack: (opts, onChunk, onEvent, onLog) => {
+            const nativeOpts = {
+                uri: opts.uri,
+                startPositionMs: opts.startPositionMs ?? opts.start_position_ms,
+                bitrate: opts.bitrate,
+                output: opts.output,
+                emitEvents: opts.emitEvents ?? opts.emit_events,
+            };
+            const handle = session.streamTrack(nativeOpts, onChunk, onEvent, onLog);
+            return wrapStreamHandle(handle);
+        },
+        close: () => session.close(),
+    };
+}
+function createSession(opts) {
+    const nativeOpts = {
+        accessToken: opts.accessToken ?? opts.access_token,
+        clientId: opts.clientId ?? opts.client_id,
+        deviceName: opts.deviceName ?? opts.device_name,
+    };
+    return native.createSession(nativeOpts).then((sess) => wrapSession(sess));
+}
+function loginWithAccessToken(accessToken, deviceName) {
+    return native.loginWithAccessToken(accessToken, deviceName).then((res) => {
+        const credentialsJson = res.credentialsJson ?? res.credentials_json;
+        return {
+            ...res,
+            credentialsJson,
+            credentials_json: credentialsJson ?? res.credentials_json,
+        };
+    });
+}
+function startZeroconfLogin(deviceId, name, timeoutMs) {
+    return native.startZeroconfLogin(deviceId, name, timeoutMs).then((res) => {
+        const credentialsJson = res.credentialsJson ?? res.credentials_json;
+        return {
+            ...res,
+            credentialsJson,
+            credentials_json: credentialsJson ?? res.credentials_json,
+        };
+    });
+}
+function startConnectDevice(credentialsPath, name, deviceId, onChunk, onEvent, onLog) {
+    // Legacy entrypoint kept for API compatibility; immediately fails.
+    return Promise.reject(new Error('startConnectDevice is deprecated; use startConnectDeviceWithToken(accessToken, clientId, ...)'));
+}
+function startConnectDeviceWithToken(accessToken, clientId, name, deviceId, onChunk, onEvent, onLog) {
+    return Promise.resolve(native.startConnectDeviceWithToken(accessToken, clientId, name, deviceId, onChunk, onEvent, onLog)).then((handle) => ({
+        stop: () => handle.stop(),
+        shutdown: () => handle.shutdown(),
+        close: () => handle.close(),
+        play: () => handle.play(),
+        pause: () => handle.pause(),
+        next: () => handle.next(),
+        prev: () => handle.prev(),
+        sampleRate: handle.sampleRate ?? handle.sample_rate ?? handle.sampleRate,
+        channels: handle.channels,
+    }));
+}
+function setLogLevel(level) {
+    native.setLogLevel(level);
+}
+function downloadTrack(opts, onChunk, onLog) {
+    const nativeOpts = {
+        uri: opts.uri,
+        bitrate: opts.bitrate,
+    };
+    return native.downloadTrack(nativeOpts, onChunk, onLog);
+}
+__exportStar(require("./types"), exports);

package/dist/types.d.ts

@@ -0,0 +1,83 @@
+/** Options used to create a librespot session. */
+export interface CreateSessionOpts {
+    accessToken?: string;
+    clientId?: string;
+    deviceName?: string;
+}
+/** Options for streaming a track. */
+export interface StreamTrackOpts {
+    uri: string;
+    startPositionMs?: number;
+    bitrate?: number;
+    output?: string;
+    emitEvents?: boolean;
+}
+/** Options for downloading raw (decrypted) audio bytes. */
+export interface DownloadTrackOpts {
+    uri: string;
+    bitrate?: number;
+}
+/** Result of a credentials login flow. */
+export interface CredentialsResult {
+    username: string;
+    credentialsJson: string;
+    credentials_json?: string;
+}
+/** Helper signature for OAuth-based credentials minting. */
+export type LoginWithAccessToken = (accessToken: string, deviceName?: string) => Promise<CredentialsResult>;
+export type LibrespotEventType = 'playing' | 'paused' | 'loading' | 'stopped' | 'end_of_track' | 'unavailable' | 'volume' | 'position_correction' | 'health' | 'error' | 'metric' | 'preloading' | 'time_to_preload' | 'play_request_id' | 'other';
+export type LibrespotErrorCode = 'audio_key_error' | 'no_pcm' | 'end_of_track' | 'pcm_missing' | 'pcm_stalled' | 'pcm_ok' | 'unavailable' | 'unknown';
+/** Event payload emitted by the connect host. */
+export interface ConnectEvent {
+    type: LibrespotEventType;
+    deviceId?: string;
+    sessionId?: string;
+    trackId?: string;
+    uri?: string;
+    title?: string;
+    artist?: string;
+    album?: string;
+    durationMs?: number;
+    positionMs?: number;
+    volume?: number;
+    errorCode?: LibrespotErrorCode;
+    errorMessage?: string;
+    metricName?: string;
+    metricValueMs?: number;
+    metricMessage?: string;
+}
+/** Log payload emitted by the native module. */
+export interface LogEvent {
+    level: string;
+    message: string;
+    scope?: string;
+    deviceId?: string;
+    sessionId?: string;
+}
+/** Handle returned when hosting a connect device. */
+export interface ConnectHandle {
+    stop(): void;
+    shutdown(): void;
+    close(): void;
+    play(): void;
+    pause(): void;
+    next(): void;
+    prev(): void;
+    sampleRate: number;
+    channels: number;
+}
+/** Handle to a librespot session. */
+export interface LibrespotSession {
+    streamTrack(opts: StreamTrackOpts, onChunk: (chunk: Buffer) => void, onEvent?: (event: ConnectEvent) => void, onLog?: (event: LogEvent) => void): StreamHandle;
+    close(): Promise<void>;
+}
+export interface StreamHandle {
+    stop(): void;
+    sampleRate: number;
+    channels: number;
+}
+/** Handle for a raw download stream. */
+export interface DownloadHandle {
+    stop(): void;
+}
+export declare function setLogLevel(level: string): void;

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+/* Auto-generated from the addon shape; keep in sync with N-API exports. */
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@lox-audioserver/node-librespot",
+  "version": "0.3.2",
+  "description": "Node.js bindings for librespot (Spotify Connect) via N-API with prebuild support.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*",
+    "prebuilds/**/*",
+    "index.d.ts",
+    "scripts/**/*",
+    "src/**/*",
+    "native/**/*",
+    "Cargo.toml",
+    "Cargo.lock",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "npm run clean && npm run build:native && npm run build:types",
+    "build:debug": "npm run clean && napi build && mkdir -p dist && mv -f librespot_addon.node dist/ && npm run build:types",
+    "build:native": "napi build --release --strip && mkdir -p dist && mv -f librespot_addon.node dist/",
+    "build:prebuild": "node scripts/prebuild.js",
+    "build:types": "tsc -p tsconfig.build.json && rm -f index.d.ts",
+    "build:types:clean": "rm -rf dist && npm run build:types",
+    "clean": "rm -rf build dist prebuilds *.log *.node target index.d.ts",
+    "test": "node scripts/test.js",
+    "test:connect": "node scripts/test-connect.js",
+    "test:service": "node scripts/test-service.js",
+    "update-librespot": "bash scripts/update-librespot.sh",
+    "prepublishOnly": "npm run build:types",
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "keywords": [
+    "spotify",
+    "connect",
+    "librespot",
+    "napi",
+    "audio"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lox-audioserver/node-librespot"
+  },
+  "author": "Rudy Berends",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.4",
+    "@tsconfig/node20": "^20.1.2",
+    "@types/node": "^22.19.3",
+    "typescript": "^5.4.0"
+  },
+  "dependencies": {
+    "node-addon-api": "^8.2.1"
+  },
+  "napi": {
+    "name": "librespot_addon",
+    "targets": [
+      "node"
+    ]
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,59 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const ROOT = path.resolve(__dirname, '..');
+const ADDON_NAME = 'librespot_addon.node';
+
+function detectLibc() {
+  const glibcVersionRuntime =
+    // @ts-expect-error
+    process.report?.getReport?.()?.header?.glibcVersionRuntime;
+  return glibcVersionRuntime ? 'gnu' : 'musl';
+}
+
+function platformArchABI() {
+  const { platform, arch } = process;
+  if (platform === 'linux') return `linux-${arch}-${detectLibc()}`;
+  if (platform === 'darwin') return `darwin-${arch}`;
+  if (platform === 'win32') return `win32-${arch}-msvc`;
+  return `${platform}-${arch}`;
+}
+
+function resolveAddonPaths() {
+  const prebuildPath = path.join(ROOT, 'prebuilds', platformArchABI(), ADDON_NAME);
+  const distPath = path.join(ROOT, 'dist', ADDON_NAME);
+  return { prebuildPath, distPath };
+}
+
+function addonExists() {
+  const { prebuildPath, distPath } = resolveAddonPaths();
+  return fs.existsSync(prebuildPath) || fs.existsSync(distPath);
+}
+
+function buildNative() {
+  const res = spawnSync('npm', ['run', 'build'], {
+    stdio: 'inherit',
+    cwd: ROOT,
+    env: process.env,
+  });
+  if (res.status !== 0) {
+    throw new Error(`npm run build failed with status ${res.status ?? 'unknown'}`);
+  }
+}
+
+function main() {
+  if (process.env.LOX_LIBRESPOT_SKIP_BUILD) {
+    console.warn('node-librespot: skipping native build because LOX_LIBRESPOT_SKIP_BUILD is set.');
+    return;
+  }
+
+  if (addonExists()) {
+    return;
+  }
+
+  console.info('node-librespot: no prebuild found for this platform, building from source...');
+  buildNative();
+}
+
+main();

package/scripts/prebuild.js

@@ -0,0 +1,23 @@
+const { execSync } = require('node:child_process');
+const path = require('node:path');
+const { preparePrebuilds } = require('./prepare-prebuilds');
+
+const run = (cmd, env = {}) =>
+  execSync(cmd, {
+    stdio: 'inherit',
+    env: { ...process.env, ...env },
+  });
+
+run('npm run clean');
+
+const args = ['napi', 'build', '--release', '--platform', '--strip'];
+if (process.env.USE_ZIG === '1') {
+  args.push('--zig');
+}
+if (process.env.RUST_TARGET) {
+  args.push('--target', process.env.RUST_TARGET);
+}
+
+run(args.join(' '));
+preparePrebuilds(path.resolve(process.cwd()));
+run('npm run build:types');

package/scripts/prepare-prebuilds.js

@@ -0,0 +1,44 @@
+const fs = require('node:fs');
+const path = require('node:path');
+
+const BINARY_NAME = 'librespot_addon';
+
+function preparePrebuilds(cwd = process.cwd()) {
+  const files = fs
+    .readdirSync(cwd)
+    .filter((file) => file.startsWith(`${BINARY_NAME}.`) && file.endsWith('.node'));
+
+  const moved = [];
+
+  for (const file of files) {
+    if (file === `${BINARY_NAME}.node`) {
+      continue;
+    }
+
+    const suffix = file.slice(BINARY_NAME.length + 1, -'.node'.length);
+    if (!suffix) {
+      continue;
+    }
+
+    const destDir = path.join(cwd, 'prebuilds', suffix);
+    fs.mkdirSync(destDir, { recursive: true });
+
+    const sourcePath = path.join(cwd, file);
+    const destPath = path.join(destDir, `${BINARY_NAME}.node`);
+    fs.renameSync(sourcePath, destPath);
+
+    moved.push(path.relative(cwd, destPath));
+  }
+
+  if (!moved.length) {
+    throw new Error(`No prebuild outputs found for ${BINARY_NAME}. Run "napi build --platform --release" first.`);
+  }
+
+  console.log(`Prebuilds ready:\n${moved.map((p) => ` - ${p}`).join('\n')}`);
+}
+
+if (require.main === module) {
+  preparePrebuilds();
+}
+
+module.exports = { preparePrebuilds };