@lox-audioserver/node-librespot 0.4.1 → 0.4.3

package/Cargo.lock

@@ -1135,6 +1135,7 @@ dependencies = [
 [[package]]
 name = "librespot-audio"
 version = "0.8.0"
+source = "git+https://github.com/librespot-org/librespot?rev=33bf3a77ed4b549df67e8347d7d6e55b007b3ec2#33bf3a77ed4b549df67e8347d7d6e55b007b3ec2"
 dependencies = [
  "aes",
  "bytes",
@@ -1153,6 +1154,7 @@ dependencies = [
 [[package]]
 name = "librespot-connect"
 version = "0.8.0"
+source = "git+https://github.com/librespot-org/librespot?rev=33bf3a77ed4b549df67e8347d7d6e55b007b3ec2#33bf3a77ed4b549df67e8347d7d6e55b007b3ec2"
 dependencies = [
  "futures-util",
  "librespot-core",
@@ -1171,6 +1173,7 @@ dependencies = [
 [[package]]
 name = "librespot-core"
 version = "0.8.0"
+source = "git+https://github.com/librespot-org/librespot?rev=33bf3a77ed4b549df67e8347d7d6e55b007b3ec2#33bf3a77ed4b549df67e8347d7d6e55b007b3ec2"
 dependencies = [
  "aes",
  "base64 0.22.1",
@@ -1227,6 +1230,7 @@ dependencies = [
 [[package]]
 name = "librespot-discovery"
 version = "0.8.0"
+source = "git+https://github.com/librespot-org/librespot?rev=33bf3a77ed4b549df67e8347d7d6e55b007b3ec2#33bf3a77ed4b549df67e8347d7d6e55b007b3ec2"
 dependencies = [
  "aes",
  "base64 0.22.1",
@@ -1253,6 +1257,7 @@ dependencies = [
 [[package]]
 name = "librespot-metadata"
 version = "0.8.0"
+source = "git+https://github.com/librespot-org/librespot?rev=33bf3a77ed4b549df67e8347d7d6e55b007b3ec2#33bf3a77ed4b549df67e8347d7d6e55b007b3ec2"
 dependencies = [
  "async-trait",
  "bytes",
@@ -1269,6 +1274,7 @@ dependencies = [
 [[package]]
 name = "librespot-oauth"
 version = "0.8.0"
+source = "git+https://github.com/librespot-org/librespot?rev=33bf3a77ed4b549df67e8347d7d6e55b007b3ec2#33bf3a77ed4b549df67e8347d7d6e55b007b3ec2"
 dependencies = [
  "log",
  "oauth2",
@@ -1281,6 +1287,7 @@ dependencies = [
 [[package]]
 name = "librespot-playback"
 version = "0.8.0"
+source = "git+https://github.com/librespot-org/librespot?rev=33bf3a77ed4b549df67e8347d7d6e55b007b3ec2#33bf3a77ed4b549df67e8347d7d6e55b007b3ec2"
 dependencies = [
  "form_urlencoded",
  "futures-util",
@@ -1301,6 +1308,7 @@ dependencies = [
 [[package]]
 name = "librespot-protocol"
 version = "0.8.0"
+source = "git+https://github.com/librespot-org/librespot?rev=33bf3a77ed4b549df67e8347d7d6e55b007b3ec2#33bf3a77ed4b549df67e8347d7d6e55b007b3ec2"
 dependencies = [
  "protobuf",
  "protobuf-codegen",

package/Cargo.toml

@@ -15,18 +15,20 @@ 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 = [
+# Pinned to a specific upstream commit (v0.8.0 + 14 dev commits) so source
+# builds are reproducible without a local ./librespot-dev checkout. See issue #4.
+librespot-core = { git = "https://github.com/librespot-org/librespot", rev = "33bf3a77ed4b549df67e8347d7d6e55b007b3ec2", default-features = false, features = [
     "rustls-tls-native-roots",
 ] }
-librespot-audio = { path = "./librespot-dev/audio", default-features = false, features = [
+librespot-audio = { git = "https://github.com/librespot-org/librespot", rev = "33bf3a77ed4b549df67e8347d7d6e55b007b3ec2", 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 = [
+librespot-playback = { git = "https://github.com/librespot-org/librespot", rev = "33bf3a77ed4b549df67e8347d7d6e55b007b3ec2", default-features = false }
+librespot-discovery = { git = "https://github.com/librespot-org/librespot", rev = "33bf3a77ed4b549df67e8347d7d6e55b007b3ec2", default-features = false, features = [
     "with-libmdns",
 ] }
-librespot-connect = { path = "./librespot-dev/connect", default-features = false }
-librespot-metadata = { path = "./librespot-dev/metadata", default-features = false }
+librespot-connect = { git = "https://github.com/librespot-org/librespot", rev = "33bf3a77ed4b549df67e8347d7d6e55b007b3ec2", default-features = false }
+librespot-metadata = { git = "https://github.com/librespot-org/librespot", rev = "33bf3a77ed4b549df67e8347d7d6e55b007b3ec2", default-features = false }
 serde_json = "1"
 tokio-stream = "0.1"
 log = { version = "0.4", features = ["std"] }

package/README.md

@@ -6,6 +6,8 @@ Used by [lox-audioserver](https://github.com/rudyberends/lox-audioserver) to han
 
 ## Features
 - Stream a Spotify track/episode to PCM buffers (`streamTrack`) using a Web API **access token**.
+- Pull raw decrypted audio bytes (Ogg/MP3) for a track/episode without decoding (`downloadTrack`).
+- Resolve a track's signed CDN URL + AES audio key without downloading, so the caller can fetch (HTTP Range) and decrypt itself (`resolveAudioFile`).
 - 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).
@@ -17,7 +19,9 @@ npm install
 ```
 
 ## Build
-Requires Rust (stable) and `@napi-rs/cli` (installed via devDependencies).
+Requires Rust (stable) and `@napi-rs/cli` (installed via devDependencies). The
+`librespot-*` crates are pulled as pinned git dependencies (a fixed upstream
+commit), so a from-source build works on a fresh clone with no local checkout.
 ```bash
 npm run build          # release build
 # or
@@ -89,6 +93,14 @@ const download = await downloadTrack(
 // download.stop() to cancel
 // Promise rejects on initial errors (invalid URI, unavailable track, key/file fetch failure).
 
+// Or resolve the CDN url + AES key without downloading (you fetch + decrypt yourself):
+const { cdnUrl, keyHex, format } = session.resolveAudioFile({ uri: 'spotify:track:...', bitrate: 320 });
+// - cdnUrl: signed, expiring CDN url for the encrypted file (GET with Range)
+// - keyHex: 16-byte AES-128 key, hex-encoded
+// - format: e.g. "OGG_VORBIS_320" or "MP3_320"
+// Decrypt with AES-128-CTR using the fixed Spotify audio IV (counter = byteOffset / 16).
+// For OGG, strip up to the first 'OggS' page (Spotify prepends a ~167-byte header).
+
 handle.stop();
 ```
 

package/dist/index.js

@@ -92,6 +92,9 @@ function wrapSession(session) {
             const handle = session.streamTrack(nativeOpts, onChunk, onEvent, onLog);
             return wrapStreamHandle(handle);
         },
+        resolveAudioFile: (opts) => {
+            return session.resolveAudioFile({ uri: opts.uri, bitrate: opts.bitrate });
+        },
         close: () => session.close(),
     };
 }

package/dist/types.d.ts

@@ -23,6 +23,15 @@ export interface DownloadTrackOpts {
     uri: string;
     bitrate?: number;
 }
+/** Result of resolving a track's CDN location + decryption key (no download). */
+export interface ResolveAudioFileResult {
+    /** Signed, expiring CDN URL for the encrypted audio file (GET with Range). */
+    cdnUrl: string;
+    /** 16-byte AES-128 audio key, hex-encoded (lowercase, 32 chars). */
+    keyHex: string;
+    /** Chosen Spotify audio format, e.g. "OGG_VORBIS_320" or "MP3_320". */
+    format: string;
+}
 /** Result of a credentials login flow. */
 export interface CredentialsResult {
     username: string;
@@ -76,6 +85,8 @@ export interface ConnectHandle {
 /** Handle to a librespot session. */
 export interface LibrespotSession {
     streamTrack(opts: StreamTrackOpts, onChunk: (chunk: Buffer) => void, onEvent?: (event: ConnectEvent) => void, onLog?: (event: LogEvent) => void): StreamHandle;
+    /** Resolve CDN URL + AES key for a track without downloading audio. */
+    resolveAudioFile(opts: DownloadTrackOpts): ResolveAudioFileResult;
     close(): Promise<void>;
 }
 export interface StreamHandle {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lox-audioserver/node-librespot",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "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

@@ -12,6 +12,7 @@ import type {
   StreamTrackOpts,
   DownloadTrackOpts,
   DownloadHandle,
+  ResolveAudioFileResult,
 } from './types';
 
 function detectLibc(): 'gnu' | 'musl' {
@@ -145,6 +146,9 @@ function wrapSession(session: LibrespotSession) {
       const handle = (session as any).streamTrack(nativeOpts, onChunk, onEvent, onLog);
       return wrapStreamHandle(handle);
     },
+    resolveAudioFile: (opts: DownloadTrackOpts): ResolveAudioFileResult => {
+      return (session as any).resolveAudioFile({ uri: opts.uri, bitrate: opts.bitrate });
+    },
     close: () => session.close(),
   };
 }

package/src/lib.rs

@@ -12,8 +12,8 @@ use bytes::Bytes;
 use librespot_audio::{AudioDecrypt, AudioFile};
 use librespot_connect::{ConnectConfig, Spirc};
 use librespot_core::{
-    authentication::Credentials, cache::Cache, config::SessionConfig, session::Session,
-    spotify_id::FileId, SpotifyId, SpotifyUri,
+    authentication::Credentials, cache::Cache, cdn_url::CdnUrl, config::SessionConfig,
+    session::Session, spotify_id::FileId, SpotifyId, SpotifyUri,
 };
 use librespot_discovery::{DeviceType, Discovery};
 use librespot_metadata::audio::{AudioFileFormat, AudioFiles, AudioItem};
@@ -144,6 +144,19 @@ pub struct DownloadTrackOpts {
     pub bitrate: Option<u32>,
 }
 
+/// Result of resolving a track's CDN location + decryption key, without
+/// downloading or decrypting any audio. Lets the caller fetch the signed
+/// (expiring) CDN URL directly with HTTP Range and AES-128-CTR decrypt itself.
+#[napi(object)]
+pub struct ResolveAudioFileResult {
+    /// Signed, expiring CDN URL for the encrypted audio file (GET with Range).
+    pub cdn_url: String,
+    /// 16-byte AES-128 audio key, hex-encoded (lowercase, 32 chars).
+    pub key_hex: String,
+    /// Chosen Spotify audio format, e.g. "OGG_VORBIS_320" or "MP3_320".
+    pub format: String,
+}
+
 /// Result of a credentials login flow.
 #[napi(object)]
 pub struct CredentialsResult {
@@ -1355,6 +1368,84 @@ impl LibrespotSession {
         })
     }
 
+    /// Resolve a track's signed CDN URL + AES audio key WITHOUT downloading or
+    /// decrypting any audio. The caller fetches the CDN URL directly (HTTP Range
+    /// supported) and decrypts with AES-128-CTR (fixed Spotify IV, counter =
+    /// byte_offset / 16). For OGG, strip up to the first `OggS` page before
+    /// decoding (Spotify prepends a ~167-byte header).
+    #[napi]
+    pub fn resolve_audio_file(&self, opts: DownloadTrackOpts) -> Result<ResolveAudioFileResult> {
+        let uri = opts.uri.clone();
+        if uri.is_empty() {
+            return Err(Error::from_reason("uri is required"));
+        }
+        let spotify_uri = SpotifyUri::from_uri(&uri)
+            .map_err(|e| Error::from_reason(format!("invalid spotify uri: {:?}", e)))?;
+        let track_id: SpotifyId = (&spotify_uri)
+            .try_into()
+            .map_err(|e| Error::from_reason(format!("invalid spotify id: {e:?}")))?;
+
+        let session = self.session.clone();
+        let bitrate_pref = opts.bitrate;
+
+        runtime().block_on(async move {
+            let audio_item = AudioItem::get_file(&session, spotify_uri.clone())
+                .await
+                .map_err(|e| Error::from_reason(format!("failed to load audio item: {e:?}")))?;
+
+            let select_format =
+                |files: &AudioFiles, bitrate: Option<u32>| -> Option<(AudioFileFormat, FileId)> {
+                    let prefer = match bitrate {
+                        Some(96) => {
+                            vec![AudioFileFormat::OGG_VORBIS_96, AudioFileFormat::MP3_96]
+                        }
+                        Some(160) => {
+                            vec![AudioFileFormat::OGG_VORBIS_160, AudioFileFormat::MP3_160]
+                        }
+                        _ => vec![
+                            AudioFileFormat::OGG_VORBIS_320,
+                            AudioFileFormat::MP3_320,
+                            AudioFileFormat::MP3_256,
+                        ],
+                    };
+                    for f in prefer {
+                        if let Some(id) = files.get(&f) {
+                            return Some((f, *id));
+                        }
+                    }
+                    files.iter().next().map(|(f, id)| (*f, *id))
+                };
+
+            let (format, file_id) = select_format(&audio_item.files, bitrate_pref)
+                .ok_or_else(|| Error::from_reason("no audio files available"))?;
+
+            let cdn = CdnUrl::new(file_id)
+                .resolve_audio(&session)
+                .await
+                .map_err(|e| Error::from_reason(format!("failed to resolve cdn url: {e:?}")))?;
+            let cdn_url = cdn
+                .try_get_urls()
+                .map_err(|e| Error::from_reason(format!("no cdn url available: {e:?}")))?
+                .into_iter()
+                .next()
+                .ok_or_else(|| Error::from_reason("no cdn url available"))?
+                .to_owned();
+
+            let key = session
+                .audio_key()
+                .request(track_id, file_id)
+                .await
+                .map_err(|e| Error::from_reason(format!("audio key unavailable: {e:?}")))?;
+            let key_hex = key.0.iter().map(|b| format!("{:02x}", b)).collect::<String>();
+
+            Ok(ResolveAudioFileResult {
+                cdn_url,
+                key_hex,
+                format: format!("{:?}", format),
+            })
+        })
+    }
+
     /// Download (stream) raw decrypted audio bytes for a track/episode.
     #[napi]
     pub fn download_track(
@@ -1865,12 +1956,21 @@ fn start_connect_device_inner(
         let player = Player::new(player_config, session.clone(), volume_getter, sink_builder);
         // Clone log_tsfn before it is moved into the player-event spawn below.
         let log_tsfn_for_disc = log_tsfn.clone();
+        // [issue #252] Bumped by the player-event observer on signals that
+        // prove audio is flowing (`playing` / `position_correction`). Read by
+        // the log observer further down to suppress transient `audio_key_error`
+        // events that fire while spirc is already recovering from an
+        // account-side dealer-disconnect burst. A permanent audio-key fault
+        // never produces a healthy event, so the error still surfaces after
+        // the grace window.
+        let healthy_seq = Arc::new(AtomicU64::new(0));
         // Forward player events to JS if requested.
         if let Some(tsfn_ev) = event_tsfn.clone() {
             let mut ev_rx = player.get_player_event_channel();
             let session_for_events = session.clone();
             let device_id_for_events = device_id.clone();
             let session_id_for_events = session_id.clone();
+            let healthy_seq_for_events = healthy_seq.clone();
             let last_pcm_for_health = last_pcm_at.clone();
             let stop_flag_for_health = stop_flag_for_block.clone();
             let device_id_for_health = device_id.clone();
@@ -2250,6 +2350,13 @@ fn start_connect_device_inner(
                         _ => {}
                     }
 
+                    // [issue #252] Signal "audio is actually flowing" to the
+                    // log observer. Excludes `paused` because a paused stream
+                    // can't prove the dealer/session is healthy.
+                    if matches!(payload.r#type.as_str(), "playing" | "position_correction") {
+                        healthy_seq_for_events.fetch_add(1, Ordering::AcqRel);
+                    }
+
                     let _ = tsfn_ev.call(payload, ThreadsafeFunctionCallMode::NonBlocking);
                 }
             });
@@ -2265,6 +2372,16 @@ fn start_connect_device_inner(
             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();
+            let healthy_seq_for_logs = healthy_seq.clone();
+            // [issue #252] Grace window before surfacing audio_key_error to JS.
+            // Account-side Spotify dealer-disconnect bursts cause every
+            // offload=false zone to emit a single audio-key-timeout log line,
+            // while spirc reconnects internally within seconds. Without this
+            // delay every burst trips the per-zone cooldown in
+            // SpotifyConnectInstance and produces ~5 minutes of unplayable
+            // state per zone. 5s is well above typical spirc recovery time
+            // and well below the cooldown window.
+            const AUDIO_KEY_GRACE_MS: u64 = 5000;
             runtime().spawn(async move {
                 while let Some(event) = log_rx.recv().await {
                     if stop_flag_for_logs.load(Ordering::Acquire) {
@@ -2322,7 +2439,28 @@ fn start_connect_device_inner(
                         metric_message: None,
                         credentials_json: None,
                     };
-                    let _ = tsfn_ev.call(payload, ThreadsafeFunctionCallMode::NonBlocking);
+                    // [issue #252] Defer the emit by AUDIO_KEY_GRACE_MS and
+                    // suppress it if a healthy event arrived in the meantime
+                    // (spirc finished its internal reconnect). Re-arm
+                    // `error_sent` on suppression so a *later* fault in the
+                    // same session can still surface.
+                    let baseline = healthy_seq_for_logs.load(Ordering::Acquire);
+                    let healthy_seq_for_check = healthy_seq_for_logs.clone();
+                    let stop_flag_for_grace = stop_flag_for_logs.clone();
+                    let error_sent_for_reset = error_sent.clone();
+                    let tsfn_ev_for_grace = tsfn_ev.clone();
+                    runtime().spawn(async move {
+                        tokio::time::sleep(Duration::from_millis(AUDIO_KEY_GRACE_MS)).await;
+                        if stop_flag_for_grace.load(Ordering::Acquire) {
+                            return;
+                        }
+                        if healthy_seq_for_check.load(Ordering::Acquire) != baseline {
+                            error_sent_for_reset.store(false, Ordering::Release);
+                            return;
+                        }
+                        let _ = tsfn_ev_for_grace
+                            .call(payload, ThreadsafeFunctionCallMode::NonBlocking);
+                    });
                 }
             });
         }

package/src/types.ts

@@ -28,6 +28,16 @@ export interface DownloadTrackOpts {
   bitrate?: number;
 }
 
+/** Result of resolving a track's CDN location + decryption key (no download). */
+export interface ResolveAudioFileResult {
+  /** Signed, expiring CDN URL for the encrypted audio file (GET with Range). */
+  cdnUrl: string;
+  /** 16-byte AES-128 audio key, hex-encoded (lowercase, 32 chars). */
+  keyHex: string;
+  /** Chosen Spotify audio format, e.g. "OGG_VORBIS_320" or "MP3_320". */
+  format: string;
+}
+
 /** Result of a credentials login flow. */
 export interface CredentialsResult {
   username: string;
@@ -120,6 +130,8 @@ export interface LibrespotSession {
     onEvent?: (event: ConnectEvent) => void,
     onLog?: (event: LogEvent) => void,
   ): StreamHandle;
+  /** Resolve CDN URL + AES key for a track without downloading audio. */
+  resolveAudioFile(opts: DownloadTrackOpts): ResolveAudioFileResult;
   close(): Promise<void>;
 }