@lox-audioserver/node-librespot 0.3.6 → 0.4.1

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.6",
+  "version": "0.4.1",
   "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.
@@ -507,6 +513,11 @@ impl Sink for ChannelSink {
     }
 
     fn stop(&mut self) -> SinkResult<()> {
+        // Reset pacing so the next start() (e.g. after Connect pause) is paced from now,
+        // not from the original stream_start. Without this the post-resume catch-up logic
+        // forwards minutes of decoded PCM at full speed.
+        self.start = None;
+        self.expected_elapsed = Duration::from_millis(0);
         Ok(())
     }
 
@@ -600,10 +611,20 @@ impl Sink for ChannelSink {
         if self.tx.try_send(bytes).is_err() {
             // Drop chunk if JS side is backpressured to avoid blocking the player thread.
         }
-        let start = self.start.get_or_insert_with(Instant::now);
-        self.expected_elapsed += duration;
-        let target = *start + self.expected_elapsed;
         let now = Instant::now();
+        // If wall-clock has drifted far ahead of our expected timeline (a pause that didn't
+        // route through stop()/start(), a decoder stall, etc.), rebase pacing onto `now`.
+        // Otherwise `sleep_dur` saturates to 0 for the duration of the gap and the sink
+        // dumps the catch-up backlog at full speed downstream.
+        if let Some(start) = self.start {
+            if now > start + self.expected_elapsed + Duration::from_millis(200) {
+                self.start = None;
+                self.expected_elapsed = Duration::from_millis(0);
+            }
+        }
+        let start = *self.start.get_or_insert(now);
+        self.expected_elapsed += duration;
+        let target = start + self.expected_elapsed;
         let sleep_dur = target.saturating_duration_since(now);
         if !sleep_dur.is_zero() {
             sleep(sleep_dur);
@@ -1515,6 +1536,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 +1587,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 +1610,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 +1642,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

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. */