@lox-audioserver/node-librespot 0.3.5 → 0.4.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import type { ConnectHandle, ConnectEvent, CreateSessionOpts, CredentialsResult, LibrespotSession, LogEvent, DownloadTrackOpts, DownloadHandle } from './types';
 declare const native: {
     createSession(opts: CreateSessionOpts): Promise<LibrespotSession>;
-    createSessionWithCredentials(credentialsPath: string, deviceName?: string | null): Promise<LibrespotSession>;
+    createSessionWithCredentials(credentialsPath: string, deviceName?: string | null, cacheDir?: string | null, cacheSizeLimitMb?: number | null): 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>;
@@ -11,7 +11,7 @@ declare const native: {
     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 createSessionWithCredentials(credentialsPathOrJson: string, deviceName?: string | null): Promise<LibrespotSession>;
+export declare function createSessionWithCredentials(credentialsPathOrJson: string, deviceName?: string | null, cacheDir?: string | null, cacheSizeLimitMb?: number | null): 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>;

package/dist/index.js

@@ -100,12 +100,14 @@ function createSession(opts) {
         accessToken: opts.accessToken ?? opts.access_token,
         clientId: opts.clientId ?? opts.client_id,
         deviceName: opts.deviceName ?? opts.device_name,
+        cacheDir: opts.cacheDir,
+        cacheSizeLimitMb: opts.cacheSizeLimitMb,
     };
     return native.createSession(nativeOpts).then((sess) => wrapSession(sess));
 }
-function createSessionWithCredentials(credentialsPathOrJson, deviceName) {
+function createSessionWithCredentials(credentialsPathOrJson, deviceName, cacheDir, cacheSizeLimitMb) {
     return native
-        .createSessionWithCredentials(credentialsPathOrJson, deviceName ?? null)
+        .createSessionWithCredentials(credentialsPathOrJson, deviceName ?? null, cacheDir ?? null, cacheSizeLimitMb ?? null)
         .then((sess) => wrapSession(sess));
 }
 function loginWithAccessToken(accessToken, deviceName) {

package/dist/types.d.ts

@@ -3,6 +3,12 @@ export interface CreateSessionOpts {
     accessToken?: string;
     clientId?: string;
     deviceName?: string;
+    /** Directory for the audio file cache.  When set, decoded audio is stored so
+     *  subsequent plays of the same track skip the CDN download. */
+    cacheDir?: string;
+    /** Maximum size of the audio cache in megabytes.  Only meaningful when
+     *  `cacheDir` is set.  Omit for no limit. */
+    cacheSizeLimitMb?: number;
 }
 /** Options for streaming a track. */
 export interface StreamTrackOpts {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lox-audioserver/node-librespot",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "Node.js bindings for librespot (Spotify Connect) via N-API with prebuild support.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/index.ts

@@ -70,6 +70,8 @@ const native = require(resolveNativeBinding()) as {
   createSessionWithCredentials(
     credentialsPath: string,
     deviceName?: string | null,
+    cacheDir?: string | null,
+    cacheSizeLimitMb?: number | null,
   ): Promise<LibrespotSession>;
   setLogLevel(level: string): void;
   loginWithAccessToken(
@@ -148,20 +150,24 @@ function wrapSession(session: LibrespotSession) {
 }
 
 export function createSession(opts: CreateSessionOpts): Promise<LibrespotSession> {
-  const nativeOpts = {
+  const nativeOpts: CreateSessionOpts = {
     accessToken: (opts as any).accessToken ?? (opts as any).access_token,
     clientId: (opts as any).clientId ?? (opts as any).client_id,
     deviceName: (opts as any).deviceName ?? (opts as any).device_name,
+    cacheDir: opts.cacheDir,
+    cacheSizeLimitMb: opts.cacheSizeLimitMb,
   };
-  return native.createSession(nativeOpts as CreateSessionOpts).then((sess) => wrapSession(sess) as any);
+  return native.createSession(nativeOpts).then((sess) => wrapSession(sess) as any);
 }
 
 export function createSessionWithCredentials(
   credentialsPathOrJson: string,
   deviceName?: string | null,
+  cacheDir?: string | null,
+  cacheSizeLimitMb?: number | null,
 ): Promise<LibrespotSession> {
   return native
-    .createSessionWithCredentials(credentialsPathOrJson, deviceName ?? null)
+    .createSessionWithCredentials(credentialsPathOrJson, deviceName ?? null, cacheDir ?? null, cacheSizeLimitMb ?? null)
     .then((sess) => wrapSession(sess) as any);
 }
 

package/src/lib.rs

@@ -120,6 +120,12 @@ pub struct CreateSessionOpts {
     pub access_token: Option<String>,
     pub client_id: Option<String>,
     pub device_name: Option<String>,
+    /// Directory for the librespot audio file cache.  When set, decoded audio
+    /// is written here so subsequent plays avoid a CDN round-trip.
+    pub cache_dir: Option<String>,
+    /// Maximum size of the audio cache in megabytes.  Only used when
+    /// `cache_dir` is set.  None means no size limit is enforced.
+    pub cache_size_limit_mb: Option<u32>,
 }
 
 /// Options for streaming a track.
@@ -1515,6 +1521,29 @@ impl LibrespotSession {
     }
 }
 
+/// Build a librespot `Cache` for audio file storage.
+/// Returns `None` if `cache_dir` is absent, the directory cannot be created,
+/// or `Cache::new` fails — in which case streaming still works without cache.
+fn build_audio_cache(cache_dir: Option<&str>, cache_size_limit_mb: Option<u32>) -> Option<Cache> {
+    let dir = cache_dir?;
+    if dir.trim().is_empty() {
+        return None;
+    }
+    let path = std::path::Path::new(dir);
+    if let Err(e) = fs::create_dir_all(path) {
+        eprintln!("[lox-librespot] could not create cache dir {dir}: {e}");
+        return None;
+    }
+    let size_limit = cache_size_limit_mb.map(|mb| mb as u64 * 1024 * 1024);
+    Cache::new(
+        Some(path),
+        None::<&std::path::Path>,
+        None::<&std::path::Path>,
+        size_limit,
+    )
+    .ok()
+}
+
 /// Create a session using a Web API access token (client id optional via opts or env).
 #[napi]
 pub async fn create_session(opts: CreateSessionOpts) -> Result<LibrespotSession> {
@@ -1543,7 +1572,8 @@ pub async fn create_session(opts: CreateSessionOpts) -> Result<LibrespotSession>
         }
     }
 
-    let session = Session::new(session_config, None);
+    let cache = build_audio_cache(opts.cache_dir.as_deref(), opts.cache_size_limit_mb);
+    let session = Session::new(session_config, cache);
     session
         .connect(credentials, false)
         .await
@@ -1565,6 +1595,8 @@ pub async fn create_session(opts: CreateSessionOpts) -> Result<LibrespotSession>
 pub async fn create_session_with_credentials(
     credentials_path: String,
     device_name: Option<String>,
+    cache_dir: Option<String>,
+    cache_size_limit_mb: Option<u32>,
 ) -> Result<LibrespotSession> {
     if credentials_path.trim().is_empty() {
         return Err(Error::from_reason("credentials payload is required"));
@@ -1595,7 +1627,8 @@ pub async fn create_session_with_credentials(
         }
     }
 
-    let session = Session::new(session_config, None);
+    let cache = build_audio_cache(cache_dir.as_deref(), cache_size_limit_mb);
+    let session = Session::new(session_config, cache);
     session
         .connect(credentials, false)
         .await
@@ -2207,6 +2240,78 @@ fn start_connect_device_inner(
             });
         }
 
+        // Log observer: detect audio_key_error and decoder errors from librespot log output.
+        // This mirrors the same pattern used in stream_track to ensure the JS layer receives
+        // error events and can trigger recovery (e.g. re-authentication, skip to next track).
+        if let Some(tsfn_ev) = event_tsfn.clone() {
+            let mut log_rx = subscribe_log_events();
+            let error_sent = Arc::new(AtomicBool::new(false));
+            let decoder_metric_sent = Arc::new(AtomicBool::new(false));
+            let stop_flag_for_logs = stop_flag_for_block.clone();
+            let device_id_for_logs = device_id.clone();
+            let session_id_for_logs = session_id.clone();
+            runtime().spawn(async move {
+                while let Some(event) = log_rx.recv().await {
+                    if stop_flag_for_logs.load(Ordering::Acquire) {
+                        break;
+                    }
+                    if is_decoder_error(&event) {
+                        if !decoder_metric_sent.swap(true, Ordering::AcqRel) {
+                            let payload = ConnectEvent {
+                                r#type: "metric".into(),
+                                device_id: Some(device_id_for_logs.clone()),
+                                session_id: Some(session_id_for_logs.clone()),
+                                track_id: None,
+                                uri: None,
+                                title: None,
+                                artist: None,
+                                album: None,
+                                duration_ms: None,
+                                position_ms: None,
+                                volume: None,
+                                error_code: None,
+                                error_message: None,
+                                metric_name: Some("decode_error".into()),
+                                metric_value_ms: None,
+                                metric_message: Some(event.message.clone()),
+                                credentials_json: None,
+                            };
+                            let _ = tsfn_ev.call(payload, ThreadsafeFunctionCallMode::NonBlocking);
+                        }
+                    }
+                    if error_sent.load(Ordering::Acquire) {
+                        continue;
+                    }
+                    if !is_audio_key_error(&event) {
+                        continue;
+                    }
+                    if error_sent.swap(true, Ordering::AcqRel) {
+                        continue;
+                    }
+                    let payload = ConnectEvent {
+                        r#type: "error".into(),
+                        device_id: Some(device_id_for_logs.clone()),
+                        session_id: Some(session_id_for_logs.clone()),
+                        track_id: None,
+                        uri: None,
+                        title: None,
+                        artist: None,
+                        album: None,
+                        duration_ms: None,
+                        position_ms: None,
+                        volume: None,
+                        error_code: Some("audio_key_error".into()),
+                        error_message: Some(event.message.clone()),
+                        metric_name: None,
+                        metric_value_ms: None,
+                        metric_message: None,
+                        credentials_json: None,
+                    };
+                    let _ = tsfn_ev.call(payload, ThreadsafeFunctionCallMode::NonBlocking);
+                }
+            });
+        }
+
         let (spirc, spirc_task) = Spirc::new(
             connect_config,
             session,

package/src/types.ts

@@ -5,6 +5,12 @@ export interface CreateSessionOpts {
   accessToken?: string;
   clientId?: string;
   deviceName?: string;
+  /** Directory for the audio file cache.  When set, decoded audio is stored so
+   *  subsequent plays of the same track skip the CDN download. */
+  cacheDir?: string;
+  /** Maximum size of the audio cache in megabytes.  Only meaningful when
+   *  `cacheDir` is set.  Omit for no limit. */
+  cacheSizeLimitMb?: number;
 }
 
 /** Options for streaming a track. */