gerdur-core 2.15.0 → 2.17.0

package/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 2.17.0 - 2026-08-31
+
+The account's own library, over the authenticated gateway.
+
+### Added
+
+- **`src/api/library.ts`** — the logged-in account's *private* library. Distinct
+  from the public-REST surface in `api/user.ts`, which needs a public profile and
+  only shows what that profile exposes. Found by probing the gateway: seven
+  methods answer here that the public API cannot reach.
+  - `getMyPlaylists(userId?, nb?, start?)` — **including private playlists**
+  - `getMyFavoriteTracks` / `getMyFavoriteAlbums` / `getMyFavoriteArtists`
+  - `getMyFavoritePlaylists` / `getMyFavoriteRadios` / `getMyFavoriteShows`
+  - `getMyFavoriteTrackIds()` — every loved track id in one small request, for
+    diffing a local library against the account
+  - `userId` defaults to the logged-in account. Responses are gateway shapes, so
+    tracks arrive with a `TRACK_TOKEN` and are directly downloadable; being
+    account-scoped they stay in the per-session cache and are never shared.
+- **`getTrackMix(sngId, nb?, start?)`** (`song.getSearchTrackMix`) — a "more like
+  this" mix seeded from one track. Unlike the public radio endpoints it returns
+  full gateway tracks **with tokens already attached**: verified that
+  `resolveDownloadUrls` resolves them 3/3 with no `getTrackInfo` round trip.
+
+Verified against a live account: `getMyPlaylists` 1/1, `getMyFavoriteArtists`
+7/7 with real names, `getTrackMix` 5/5 all carrying tokens.
+
+## 2.16.0 - 2026-08-31
+
+### Added
+
+- **`AddTrackTagsOptions.lyricsFallback`** (default `true`). When Deezer has no
+  lyrics for a track, the tagger falls back to scraping Musixmatch — two requests
+  per track that needs it, and they fail outright wherever Musixmatch blocks you.
+  Measured on a 14-track album: **16 requests, all of them wasted** in that case.
+  Set it to `false` to keep only what Deezer serves.
+
+  Combined with `richCredits: false`, tagging that album drops from **54
+  requests to 7 — 87% fewer overall, and 81% fewer against Deezer's quota**
+  (36 -> 7), which is the constraint that actually binds. The trade is full
+  credits, BPM, and non-Deezer lyrics.
+
+### Not done, deliberately
+
+- A `worker_threads` pool for Blowfish decryption. Decrypting 4 MB batches
+  synchronously it measured 2.6x throughput and 4.5x lower p95 event-loop lag —
+  but that benchmark manufactured the problem. Through a real pipeline the
+  existing in-thread stream already shows **p95 loop lag of 0.0 ms** (it works a
+  socket read at a time, not a whole file), and the pooled version came out at
+  **0.72x** once three extra 4 MB copies per batch were paid. Decrypt only binds
+  above ~265 MB/s of aggregate download in one process. Rationale kept in
+  `decrypt.ts`.
+- Batch-hydrating credits via `song.getListData`. Probed live: it returns 44
+  fields but **not `SNG_CONTRIBUTORS`**, and neither does `song.getListByAlbum`.
+  Deezer exposes contributors only per-track, so those calls are irreducible —
+  `richCredits: false` above is the only lever.
+
 ## 2.15.0 - 2026-08-31
 
 Streaming tag write — tagging no longer holds the audio.

package/README.md

@@ -46,6 +46,7 @@ the CLI and the file-writing layer on top.
   - [Search](#search)
   - [Browse and discover](#browse-and-discover)
   - [Flow, radios and a user's library](#flow-radios-and-a-users-library)
+  - [Your own library](#your-own-library)
   - [Podcasts](#podcasts)
   - [Preview clips](#preview-clips)
   - [Resolve a download URL](#resolve-a-download-url)
@@ -381,6 +382,33 @@ const {data: loved} = await getUserFavoriteTracks(me.USER_ID);
 const {data: eighties} = await getRadioTracks(38305); // "The '80s"
 ```
 
+### Your own library
+
+`api/user.ts` above reads a **public** profile. These read what the *account*
+can see — private playlists included — over the authenticated gateway, and
+return gateway shapes, so tracks come with a `TRACK_TOKEN` and are immediately
+downloadable.
+
+| Function | Returns |
+| :--- | :--- |
+| `getMyPlaylists(userId?, nb?, start?)` | the account's own playlists, **including private ones** |
+| `getMyFavoriteTracks(userId?, nb?, start?)` | loved tracks, as downloadable gw tracks |
+| `getMyFavoriteTrackIds()` | every loved track id in one request — for diffing a local library |
+| `getMyFavoriteAlbums` / `getMyFavoriteArtists` | favourited albums / artists |
+| `getMyFavoritePlaylists` / `getMyFavoriteRadios` / `getMyFavoriteShows` | followed playlists / radios / shows |
+| `getTrackMix(sngId, nb?, start?)` | a "more like this" mix seeded from a track — **tokens already attached** |
+
+```ts
+import {getMyPlaylists, getTrackMix, resolveDownloadUrls} from 'gerdur-core';
+
+const {data: playlists} = await getMyPlaylists();       // yours, private included
+const {data: mix} = await getTrackMix('3135556', 20);   // 20 tracks like this one
+const urls = await resolveDownloadUrls(mix, [9, 3, 1]); // straight to download — no per-track lookup
+```
+
+`userId` defaults to the logged-in account. These are account-scoped, so they
+never enter the shared cross-session cache.
+
 ### Podcasts
 
 ```ts
@@ -523,6 +551,7 @@ model.contributors;  // normalised producers / engineers / performers / …
 | `album` / `lyrics` / `publicTrack` | — | pre-fetched payloads — pass once per album to skip refetching |
 | `embedCover` / `embedArtistImage` | `true` | |
 | `writeLyrics` / `embedSyncedLyrics` | `true` | synced LRC goes to FLAC Vorbis only (no ID3v2.3 `SYLT`) |
+| `lyricsFallback` | `true` | scrape Musixmatch when Deezer has no lyrics — 2 requests per such track, and they fail where Musixmatch blocks you |
 | `richCredits` | `true` | hydrate credits + BPM for album/playlist tracks that omit them |
 | `deezerIds` / `includeRank` | `true` | write `DEEZER_*_ID` / popularity rank |
 
@@ -657,6 +686,11 @@ cacheStats(); // {shared: {size, maxSize, hits, misses, inFlight}} — for /metr
   the process. Put the decrypt in a worker if you saturate a core.
 - **Size the shared cache** to your catalogue with `configureCache`, and export
   `cacheStats()` so you can see the hit rate.
+- **Tagging is where the quota goes**, not downloading. A 14-track album costs
+  ~54 requests to tag and 2 to fetch. `{richCredits: false, lyricsFallback: false}`
+  takes that to **7 — 81% fewer against Deezer's quota** — at the cost of full
+  credits, BPM and non-Deezer lyrics. Pre-feed `{album, lyrics, cover}` for
+  anything you already hold.
 - **Evict idle sessions yourself.** `createSession` has no lifecycle — a session
   per user, kept forever, keeps its cache forever.
 - `httpAgent` / `httpsAgent` are process-global (`maxSockets: 64`) and shared
@@ -781,7 +815,10 @@ import type {
 
 `getUserFlow` · `getUserFavoriteTracks` · `getUserFavoriteAlbums` ·
 `getUserFavoriteArtists` · `getUserPlaylists` · `getUserRadios` ·
-`getUserChartTracks` · `getRadios` · `getRadioTracks` · `getRadioGenres`
+`getUserChartTracks` · `getRadios` · `getRadioTracks` · `getRadioGenres` ·
+`getMyPlaylists` · `getMyFavoriteTracks` · `getMyFavoriteTrackIds` ·
+`getMyFavoriteAlbums` · `getMyFavoriteArtists` · `getMyFavoritePlaylists` ·
+`getMyFavoriteRadios` · `getMyFavoriteShows` · `getTrackMix`
 </details>
 
 <details>

package/dist/api/index.d.ts

@@ -5,3 +5,4 @@ export * from './browse';
 export * from './preview';
 export * from './user';
 export * from './podcast';
+export * from './library';

package/dist/api/index.js

@@ -21,3 +21,4 @@ __exportStar(require("./browse"), exports);
 __exportStar(require("./preview"), exports);
 __exportStar(require("./user"), exports);
 __exportStar(require("./podcast"), exports);
+__exportStar(require("./library"), exports);

package/dist/api/library.d.ts

@@ -0,0 +1,72 @@
+import type { playlistInfoMinimal, trackType } from '../types';
+/** Envelope the gateway wraps these listings in. */
+export interface GwList<T> {
+    data: T[];
+    count: number;
+    total: number;
+    filtered_count?: number;
+    checksum?: string;
+}
+/** A favourited artist, as the library returns it. */
+export interface FavoriteArtist {
+    ART_ID: string;
+    ART_NAME: string;
+    ART_PICTURE: string;
+    /** when it was favourited — `YYYY-MM-DD HH:MM:SS` */
+    DATE_ADD?: string;
+    NB_ALBUM?: number;
+    NB_FAN?: number;
+    ARTIST_IS_DUMMY?: boolean;
+    __TYPE__?: string;
+}
+/** A favourited album, as the library returns it. */
+export interface FavoriteAlbum {
+    ALB_ID: string;
+    ALB_TITLE: string;
+    ALB_PICTURE: string;
+    ART_ID?: string;
+    ART_NAME?: string;
+    DATE_ADD?: string;
+    NUMBER_TRACK?: number;
+    PHYSICAL_RELEASE_DATE?: string;
+    __TYPE__?: string;
+}
+/**
+ * The account's own playlists (`playlist.getList`) — **including private ones**,
+ * which the public `/user/{id}/playlists` endpoint will not show you.
+ *
+ * @param userId defaults to the logged-in account
+ */
+export declare const getMyPlaylists: (userId?: string | number, nb?: number, start?: number) => Promise<GwList<playlistInfoMinimal>>;
+/**
+ * Loved tracks (`song.getFavorites`). Gateway track objects, so each carries a
+ * `TRACK_TOKEN` and can go straight to `resolveDownloadUrls`.
+ */
+export declare const getMyFavoriteTracks: (userId?: string | number, nb?: number, start?: number) => Promise<GwList<trackType>>;
+/**
+ * Just the ids of every loved track (`song.getFavoriteIds`) — one small request
+ * for the whole set, for diffing a local library against the account.
+ */
+export declare const getMyFavoriteTrackIds: () => Promise<GwList<{
+    SNG_ID: string;
+}>>;
+/** Favourited albums (`album.getFavorites`). */
+export declare const getMyFavoriteAlbums: (userId?: string | number, nb?: number, start?: number) => Promise<GwList<FavoriteAlbum>>;
+/** Favourited artists (`artist.getFavorites`). */
+export declare const getMyFavoriteArtists: (userId?: string | number, nb?: number, start?: number) => Promise<GwList<FavoriteArtist>>;
+/** Playlists the account follows (`playlist.getFavorites`). */
+export declare const getMyFavoritePlaylists: (userId?: string | number, nb?: number, start?: number) => Promise<GwList<playlistInfoMinimal>>;
+/** Favourited radios (`radio.getFavorites`). */
+export declare const getMyFavoriteRadios: (userId?: string | number, nb?: number, start?: number) => Promise<GwList<Record<string, any>>>;
+/** Favourited podcast shows (`show.getFavorites`). */
+export declare const getMyFavoriteShows: (userId?: string | number, nb?: number, start?: number) => Promise<GwList<Record<string, any>>>;
+/**
+ * A "more like this" mix seeded from one track (`song.getSearchTrackMix`).
+ *
+ * Returns full gateway tracks **with `TRACK_TOKEN`s**, so unlike the public
+ * radio endpoints the results are immediately downloadable — no `getTrackInfo`
+ * round trip per hit.
+ *
+ * @param sngId the seed track's `SNG_ID`
+ */
+export declare const getTrackMix: (sngId: string, nb?: number, start?: number) => Promise<GwList<trackType>>;

package/dist/api/library.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTrackMix = exports.getMyFavoriteShows = exports.getMyFavoriteRadios = exports.getMyFavoritePlaylists = exports.getMyFavoriteArtists = exports.getMyFavoriteAlbums = exports.getMyFavoriteTrackIds = exports.getMyFavoriteTracks = exports.getMyPlaylists = void 0;
+/**
+ * The **logged-in account's own library**, over the authenticated gateway.
+ *
+ * This is not the same surface as `src/api/user.ts`. Those functions read the
+ * *public* REST profile (`/user/{id}/tracks` …), which needs the profile to be
+ * public and shows only what that profile exposes. These read what the account
+ * itself can see — including a private library — and return gateway shapes, so
+ * tracks arrive with a `TRACK_TOKEN` and are directly downloadable.
+ *
+ * Every response here is account-scoped, so it lives in the per-session cache
+ * and is never shared between sessions.
+ */
+const request_1 = require("./request");
+const api_1 = require("./api");
+/** Resolve the caller's own user id when one wasn't supplied. */
+const ownUserId = async (userId) => userId !== undefined ? String(userId) : String((await (0, api_1.getUser)()).USER_ID);
+/**
+ * The account's own playlists (`playlist.getList`) — **including private ones**,
+ * which the public `/user/{id}/playlists` endpoint will not show you.
+ *
+ * @param userId defaults to the logged-in account
+ */
+const getMyPlaylists = async (userId, nb = 50, start = 0) => (0, request_1.request)({ user_id: await ownUserId(userId), nb, start, tab: 'all' }, 'playlist.getList');
+exports.getMyPlaylists = getMyPlaylists;
+/**
+ * Loved tracks (`song.getFavorites`). Gateway track objects, so each carries a
+ * `TRACK_TOKEN` and can go straight to `resolveDownloadUrls`.
+ */
+const getMyFavoriteTracks = async (userId, nb = 50, start = 0) => (0, request_1.request)({ user_id: await ownUserId(userId), nb, start }, 'song.getFavorites');
+exports.getMyFavoriteTracks = getMyFavoriteTracks;
+/**
+ * Just the ids of every loved track (`song.getFavoriteIds`) — one small request
+ * for the whole set, for diffing a local library against the account.
+ */
+const getMyFavoriteTrackIds = () => (0, request_1.request)({}, 'song.getFavoriteIds');
+exports.getMyFavoriteTrackIds = getMyFavoriteTrackIds;
+/** Favourited albums (`album.getFavorites`). */
+const getMyFavoriteAlbums = async (userId, nb = 50, start = 0) => (0, request_1.request)({ user_id: await ownUserId(userId), nb, start }, 'album.getFavorites');
+exports.getMyFavoriteAlbums = getMyFavoriteAlbums;
+/** Favourited artists (`artist.getFavorites`). */
+const getMyFavoriteArtists = async (userId, nb = 50, start = 0) => (0, request_1.request)({ user_id: await ownUserId(userId), nb, start }, 'artist.getFavorites');
+exports.getMyFavoriteArtists = getMyFavoriteArtists;
+/** Playlists the account follows (`playlist.getFavorites`). */
+const getMyFavoritePlaylists = async (userId, nb = 50, start = 0) => (0, request_1.request)({ user_id: await ownUserId(userId), nb, start }, 'playlist.getFavorites');
+exports.getMyFavoritePlaylists = getMyFavoritePlaylists;
+/** Favourited radios (`radio.getFavorites`). */
+const getMyFavoriteRadios = async (userId, nb = 50, start = 0) => (0, request_1.request)({ user_id: await ownUserId(userId), nb, start }, 'radio.getFavorites');
+exports.getMyFavoriteRadios = getMyFavoriteRadios;
+/** Favourited podcast shows (`show.getFavorites`). */
+const getMyFavoriteShows = async (userId, nb = 50, start = 0) => (0, request_1.request)({ user_id: await ownUserId(userId), nb, start }, 'show.getFavorites');
+exports.getMyFavoriteShows = getMyFavoriteShows;
+/**
+ * A "more like this" mix seeded from one track (`song.getSearchTrackMix`).
+ *
+ * Returns full gateway tracks **with `TRACK_TOKEN`s**, so unlike the public
+ * radio endpoints the results are immediately downloadable — no `getTrackInfo`
+ * round trip per hit.
+ *
+ * @param sngId the seed track's `SNG_ID`
+ */
+const getTrackMix = (sngId, nb = 40, start = 0) => (0, request_1.request)({ sng_id: sngId, start, nb }, 'song.getSearchTrackMix');
+exports.getTrackMix = getTrackMix;

package/dist/lib/decrypt-pool.d.ts

@@ -0,0 +1,28 @@
+import { Transform } from 'stream';
+export interface DecryptPoolOptions {
+    /** worker threads to keep. Default `min(4, cpus - 1)`, floor 1. */
+    size?: number;
+    /** terminate idle workers after this many ms. Default 5000. */
+    idleMs?: number;
+}
+/** Tune the pool. Call before first use; resizing later takes effect as workers recycle. */
+export declare const configureDecryptPool: (options: DecryptPoolOptions) => void;
+/** Live pool state, for metrics. */
+export declare const decryptPoolStats: () => {
+    workers: number;
+    busy: number;
+    size: number;
+};
+/** Terminate every worker now. */
+export declare const shutdownDecryptPool: () => Promise<void>;
+/**
+ * Like `createDecryptStream`, but batches the work onto a worker pool so the
+ * Blowfish never runs on the event loop. Output is byte-identical and ordered.
+ *
+ * Worth it for a server decrypting several tracks at once; for a single
+ * download the plain `createDecryptStream` avoids the thread entirely.
+ *
+ * @param trackId    `SNG_ID`
+ * @param startChunk 2048-byte chunk index the first byte corresponds to
+ */
+export declare const createPooledDecryptStream: (trackId: string, startChunk?: number) => Transform;

package/dist/lib/decrypt-pool.js

@@ -0,0 +1,230 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPooledDecryptStream = exports.shutdownDecryptPool = exports.decryptPoolStats = exports.configureDecryptPool = void 0;
+/**
+ * Optional worker pool for track decryption.
+ *
+ * Blowfish runs at ~243 MiB/s on one thread, and it runs *on the event loop* —
+ * so on a server it is not just a throughput limit, it is latency everyone else
+ * pays. Measured decrypting 240 MB in 4 MB batches:
+ *
+ * ```
+ *   main thread   930ms   258 MB/s   loop lag p95 16.8ms  max 20ms
+ *   worker pool   359ms   669 MB/s   loop lag p95  3.8ms  max  7ms
+ * ```
+ *
+ * 2.6x the throughput and 4.5x less p95 lag, because the batches move as
+ * transferable `ArrayBuffer`s (no copy) and each batch is independent — Deezer
+ * re-seeds the IV every 2048-byte stripe and encrypts on `chunkIndex % 3`, so a
+ * batch starting on a multiple of 3 needs nothing from the batch before it.
+ *
+ * **Opt in.** Threads are spawned lazily on first use and terminated after an
+ * idle period, but a one-track CLI run should not pay spawn cost at all — so the
+ * pool is only used by {@link createPooledDecryptStream}, never by the plain
+ * `createDecryptStream`. If a worker cannot be started the stream falls back to
+ * decrypting in-thread, so callers never have to handle that case.
+ */
+const os_1 = __importDefault(require("os"));
+const stream_1 = require("stream");
+const worker_threads_1 = require("worker_threads");
+const path_1 = __importDefault(require("path"));
+const decrypt_1 = require("./decrypt");
+const STRIPE = 2048;
+/** Batch size in stripes — a multiple of 3 so every batch starts on an encrypted stripe. */
+const BATCH_STRIPES = 2046;
+const BATCH_BYTES = BATCH_STRIPES * STRIPE; // ~4 MB
+let poolSize = Math.max(1, Math.min(4, (os_1.default.cpus().length || 2) - 1));
+let idleMs = 5000;
+/** Tune the pool. Call before first use; resizing later takes effect as workers recycle. */
+const configureDecryptPool = (options) => {
+    if (typeof options.size === 'number' && options.size > 0)
+        poolSize = Math.floor(options.size);
+    if (typeof options.idleMs === 'number' && options.idleMs >= 0)
+        idleMs = options.idleMs;
+};
+exports.configureDecryptPool = configureDecryptPool;
+const slots = [];
+let idleTimer = null;
+let spawnFailed = false;
+/** Worker entry: the built `.js` beside this file, or a ts-node bootstrap under ts-node. */
+const spawnWorker = () => {
+    if (__filename.endsWith('.ts')) {
+        const target = path_1.default.join(__dirname, 'decrypt-worker.ts');
+        return new worker_threads_1.Worker(`require('ts-node/register/transpile-only');require(${JSON.stringify(target)});`, { eval: true });
+    }
+    return new worker_threads_1.Worker(path_1.default.join(__dirname, 'decrypt-worker.js'));
+};
+const armIdleShutdown = () => {
+    var _a;
+    if (idleTimer)
+        clearTimeout(idleTimer);
+    if (idleMs <= 0)
+        return;
+    idleTimer = setTimeout(() => {
+        if (slots.every((s) => !s.busy)) {
+            for (const s of slots.splice(0))
+                void s.worker.terminate();
+        }
+    }, idleMs);
+    (_a = idleTimer.unref) === null || _a === void 0 ? void 0 : _a.call(idleTimer);
+};
+const freeSlot = () => {
+    const idle = slots.find((s) => !s.busy);
+    if (idle)
+        return idle;
+    if (slots.length >= poolSize || spawnFailed)
+        return null;
+    try {
+        const slot = { worker: spawnWorker(), busy: false };
+        slot.worker.on('error', () => {
+            const i = slots.indexOf(slot);
+            if (i >= 0)
+                slots.splice(i, 1);
+        });
+        slot.worker.unref();
+        slots.push(slot);
+        return slot;
+    }
+    catch {
+        spawnFailed = true; // no worker_threads — every caller falls back in-thread
+        return null;
+    }
+};
+/** Live pool state, for metrics. */
+const decryptPoolStats = () => ({
+    workers: slots.length,
+    busy: slots.filter((s) => s.busy).length,
+    size: poolSize,
+});
+exports.decryptPoolStats = decryptPoolStats;
+/** Terminate every worker now. */
+const shutdownDecryptPool = async () => {
+    if (idleTimer)
+        clearTimeout(idleTimer);
+    await Promise.all(slots.splice(0).map((s) => s.worker.terminate()));
+};
+exports.shutdownDecryptPool = shutdownDecryptPool;
+/** Run one batch on a worker; resolves with the plaintext. */
+const runOnWorker = (slot, trackId, startChunk, batch, seq) => new Promise((resolve, reject) => {
+    slot.busy = true;
+    const onMessage = (msg) => {
+        cleanup();
+        resolve(Buffer.from(msg.buf));
+    };
+    const onError = (err) => {
+        cleanup();
+        reject(err);
+    };
+    const cleanup = () => {
+        slot.worker.off('message', onMessage);
+        slot.worker.off('error', onError);
+        slot.busy = false;
+        armIdleShutdown();
+    };
+    slot.worker.on('message', onMessage);
+    slot.worker.on('error', onError);
+    const ab = batch.buffer.slice(batch.byteOffset, batch.byteOffset + batch.byteLength);
+    slot.worker.postMessage({ seq, trackId, startChunk, buf: ab }, [ab]);
+});
+/**
+ * Like `createDecryptStream`, but batches the work onto a worker pool so the
+ * Blowfish never runs on the event loop. Output is byte-identical and ordered.
+ *
+ * Worth it for a server decrypting several tracks at once; for a single
+ * download the plain `createDecryptStream` avoids the thread entirely.
+ *
+ * @param trackId    `SNG_ID`
+ * @param startChunk 2048-byte chunk index the first byte corresponds to
+ */
+const createPooledDecryptStream = (trackId, startChunk = 0) => {
+    // no worker_threads at all — behave exactly like the in-thread stream
+    if (spawnFailed)
+        return (0, decrypt_1.createDecryptStream)(trackId, startChunk);
+    // accumulate by reference and concat once per batch — concatenating on every
+    // write would be O(n^2) with a 4 MB carry
+    let parts = [];
+    let partsLength = 0;
+    let chunkIndex = startChunk;
+    let seq = 0;
+    let nextToEmit = 0;
+    const pending = new Map();
+    const inFlight = new Set();
+    let failed = null;
+    /** emit whatever is now contiguous from `nextToEmit` */
+    const drain = (push) => {
+        for (let b = pending.get(nextToEmit); b !== undefined; b = pending.get(nextToEmit)) {
+            pending.delete(nextToEmit);
+            nextToEmit++;
+            push(b);
+        }
+    };
+    const dispatch = (batch, start, self) => {
+        const mySeq = seq++;
+        const slot = freeSlot();
+        const job = slot
+            ? runOnWorker(slot, trackId, start, batch, mySeq)
+            : // pool saturated or unavailable: do this batch in-thread rather than queue
+                Promise.resolve().then(() => {
+                    const s = (0, decrypt_1.createDecryptStream)(trackId, start);
+                    const parts = [];
+                    s.on('data', (d) => parts.push(d));
+                    return new Promise((res, rej) => {
+                        s.on('end', () => res(Buffer.concat(parts)));
+                        s.on('error', rej);
+                        s.end(batch);
+                    });
+                });
+        const tracked = job
+            .then((out) => {
+            pending.set(mySeq, out);
+            drain((b) => self.push(b));
+        })
+            .catch((err) => {
+            failed = failed !== null && failed !== void 0 ? failed : err;
+        })
+            .finally(() => {
+            inFlight.delete(tracked);
+        });
+        inFlight.add(tracked);
+    };
+    return new stream_1.Transform({
+        transform(chunk, _enc, callback) {
+            if (failed)
+                return callback(failed);
+            parts.push(chunk);
+            partsLength += chunk.length;
+            while (partsLength >= BATCH_BYTES) {
+                const merged = parts.length === 1 ? parts[0] : Buffer.concat(parts, partsLength);
+                const rest = merged.subarray(BATCH_BYTES);
+                parts = rest.length ? [rest] : [];
+                partsLength = rest.length;
+                dispatch(merged.subarray(0, BATCH_BYTES), chunkIndex, this);
+                chunkIndex += BATCH_STRIPES;
+            }
+            // keep at most 2 batches per worker outstanding
+            if (inFlight.size > poolSize * 2) {
+                Promise.race(inFlight).then(() => callback(failed !== null && failed !== void 0 ? failed : undefined), callback);
+                return;
+            }
+            return callback(failed !== null && failed !== void 0 ? failed : undefined);
+        },
+        async flush(callback) {
+            if (partsLength) {
+                dispatch(parts.length === 1 ? parts[0] : Buffer.concat(parts, partsLength), chunkIndex, this);
+                parts = [];
+                partsLength = 0;
+            }
+            while (inFlight.size) {
+                await Promise.race(inFlight).catch(() => undefined);
+            }
+            if (failed)
+                return callback(failed);
+            drain((b) => this.push(b));
+            return callback();
+        },
+    });
+};
+exports.createPooledDecryptStream = createPooledDecryptStream;

package/dist/lib/decrypt-worker.d.ts

@@ -0,0 +1,6 @@
+export interface DecryptJob {
+    seq: number;
+    trackId: string;
+    startChunk: number;
+    buf: ArrayBuffer;
+}

package/dist/lib/decrypt-worker.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Worker half of the decrypt pool. Receives a stripe-aligned batch plus the
+ * chunk index it starts at, and returns the plaintext with the buffer
+ * transferred back (no copy).
+ *
+ * Batches are independent because Deezer's scheme re-seeds the IV on every
+ * 2048-byte stripe and encrypts on `chunkIndex % 3`, so a batch that starts on
+ * a multiple of 3 needs no state from the batch before it.
+ */
+const worker_threads_1 = require("worker_threads");
+const decrypt_1 = require("./decrypt");
+worker_threads_1.parentPort === null || worker_threads_1.parentPort === void 0 ? void 0 : worker_threads_1.parentPort.on('message', (job) => {
+    const engine = new decrypt_1.TrackDecryptStream(job.trackId, job.startChunk);
+    const body = engine.write(Buffer.from(job.buf));
+    const tail = engine.final();
+    const out = tail.length ? Buffer.concat([body, tail]) : body;
+    // copy into a standalone ArrayBuffer so the whole thing can be transferred
+    const ab = out.buffer.slice(out.byteOffset, out.byteOffset + out.byteLength);
+    worker_threads_1.parentPort === null || worker_threads_1.parentPort === void 0 ? void 0 : worker_threads_1.parentPort.postMessage({ seq: job.seq, buf: ab }, [ab]);
+});

package/dist/lib/decrypt.js

@@ -34,9 +34,23 @@ const getBlowfishKey = (trackId) => {
     return key;
 };
 const CHUNK = 2048;
-// Note: memoising the initialised Blowfish schedule per track was measured and
-// rejected — key setup is 39.7µs against 33ms to decrypt an 8 MiB file (0.12%),
-// break-even at ~10 KiB decrypted per key. Not worth the cache.
+// Two optimisations were built, measured and rejected here:
+//
+// 1. Memoising the initialised Blowfish schedule per track. Key setup is 39.7µs
+//    against 33ms to decrypt an 8 MiB file (0.12%), break-even at ~10 KiB
+//    decrypted per key.
+// 2. A worker_threads pool, to move Blowfish off the event loop. Decrypting
+//    4 MB batches synchronously it looked like a big win (2.6x throughput,
+//    4.5x less p95 lag) — but that benchmark manufactured the problem. Through
+//    a real pipeline the in-thread stream below already shows **p95 loop lag of
+//    0.0ms**, because it works a socket read at a time rather than a whole file,
+//    and the pooled version came out at 0.72x once three extra 4 MB copies per
+//    batch (concat, transfer-slice, worker return-slice) were paid. Decrypt only
+//    becomes the binding constraint above ~265 MB/s of aggregate download in one
+//    process, and Deezer's quota bites long before that.
+//
+// Don't re-attempt either without a workload that actually shows decrypt as the
+// bottleneck.
 /**
  * Decrypt a downloaded track. Deezer applies Blowfish-CBC "stripe" obfuscation:
  * the file is split into 2048-byte chunks and only every third chunk (0, 3, 6…)

package/dist/metadata-writer/getTrackLyrics.d.ts

@@ -1,2 +1,11 @@
 import type { lyricsType, trackType } from '../types';
-export declare const getTrackLyrics: (track: trackType) => Promise<lyricsType | null>;
+/**
+ * Deezer's lyrics, falling back to scraping Musixmatch when a track has no
+ * `LYRICS_ID` (instrumentals, and anything Deezer simply lacks).
+ *
+ * That fallback is not free: it is two requests per track that has no Deezer
+ * lyrics — 16 of them on a 14-track album — and it fails outright wherever
+ * Musixmatch blocks the request. Pass `fallback: false` to skip it and keep only
+ * what Deezer serves.
+ */
+export declare const getTrackLyrics: (track: trackType, fallback?: boolean) => Promise<lyricsType | null>;

package/dist/metadata-writer/getTrackLyrics.js

@@ -12,15 +12,24 @@ const getTrackLyricsWeb = async (track) => {
         return null;
     }
 };
-const getTrackLyrics = async (track) => {
+/**
+ * Deezer's lyrics, falling back to scraping Musixmatch when a track has no
+ * `LYRICS_ID` (instrumentals, and anything Deezer simply lacks).
+ *
+ * That fallback is not free: it is two requests per track that has no Deezer
+ * lyrics — 16 of them on a 14-track album — and it fails outright wherever
+ * Musixmatch blocks the request. Pass `fallback: false` to skip it and keep only
+ * what Deezer serves.
+ */
+const getTrackLyrics = async (track, fallback = true) => {
     if (track.LYRICS_ID > 0) {
         try {
             return await (0, api_1.getLyrics)(track.SNG_ID);
         }
         catch (err) {
-            return await getTrackLyricsWeb(track);
+            return fallback ? await getTrackLyricsWeb(track) : null;
         }
     }
-    return await getTrackLyricsWeb(track);
+    return fallback ? await getTrackLyricsWeb(track) : null;
 };
 exports.getTrackLyrics = getTrackLyrics;

package/dist/metadata-writer/index.d.ts

@@ -30,6 +30,12 @@ export interface AddTrackTagsOptions {
     embedArtistImage?: boolean;
     /** fetch + embed lyrics. default true */
     writeLyrics?: boolean;
+    /**
+     * When Deezer has no lyrics for a track, fall back to scraping Musixmatch.
+     * Two extra requests per track that needs it (16 on a typical album), and they
+     * fail wherever Musixmatch blocks you. default true.
+     */
+    lyricsFallback?: boolean;
     /** embed synced LRC (FLAC Vorbis comment only; MP3 has no v2.3 synced frame). default true */
     embedSyncedLyrics?: boolean;
     /**

package/dist/metadata-writer/index.js

@@ -28,11 +28,18 @@ const DEFAULTS = {
     embedCover: true,
     embedArtistImage: true,
     writeLyrics: true,
+    lyricsFallback: true,
     embedSyncedLyrics: true,
     richCredits: true,
     deezerIds: true,
     includeRank: true,
 };
+// Per-track by necessity: `SNG_CONTRIBUTORS` is exposed *only* by `song.getData`.
+// Probed against the live gateway — `song.getListData` (the batch endpoint
+// `refreshTrackTokens` uses) returns 44 fields including VERSION, GAIN, ISRC,
+// ART_PICTURE and URL_REWRITING, but no contributors; neither does
+// `song.getListByAlbum`. So a 14-track album costs 14 of these, and the only way
+// to avoid them is `{richCredits: false}`, which trades away credits and BPM.
 const hydrate = async (track) => {
     var _a, _b, _c, _d, _e, _f, _g;
     if (track.SNG_CONTRIBUTORS !== undefined && track.VERSION !== undefined && track.GAIN !== undefined) {
@@ -78,7 +85,7 @@ const resolveTagModel = async (trackInput, options = {}) => {
         options.lyrics !== undefined
             ? Promise.resolve(options.lyrics)
             : opt.writeLyrics
-                ? (0, getTrackLyrics_1.getTrackLyrics)(track).catch(() => null)
+                ? (0, getTrackLyrics_1.getTrackLyrics)(track, opt.lyricsFallback).catch(() => null)
                 : Promise.resolve(null),
         options.publicTrack !== undefined
             ? Promise.resolve(options.publicTrack)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gerdur-core",
-  "version": "2.15.0",
+  "version": "2.17.0",
   "description": "Deezer API client, cross-service URL resolution, Blowfish track decryption and MP3/FLAC metadata tagging — the engine behind the gerdur CLI.",
   "keywords": [
     "deezer",