gerdur-core 2.14.0 → 2.16.0

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # Changelog
 
+## 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.
+
+### Added
+
+- **`createTagStream(model, options?)`** — a `Transform` that rewrites a track's
+  tags as bytes flow through it. `addTrackTags` has to materialise the whole
+  file (`browser-id3-writer` allocates `audio.length + tag` and copies the audio
+  in, plus another copy to strip an existing ID3v2; the FLAC path concatenates
+  the same way), which is what caps concurrency on a server and what cancelled
+  `streamTrackDownload`'s constant-memory guarantee at the last step.
+
+  Both containers keep their metadata at the front, so none of that copying is
+  needed: MP3 emits a fresh ID3v2 and discards exactly the old tag's bytes as
+  they pass; FLAC buffers only the metadata block chain and passes the frames
+  through untouched. Peak memory is O(metadata), not O(file).
+
+  Measured, 40 MB tracks: **4 concurrent 239 MB -> 0 MB; 16 concurrent 965 MB ->
+  0 MB, and 6.5x faster** (986 ms -> 150 ms) from skipping the copies. Output is
+  byte-identical to `addTrackTags` — the tag bytes come from the same writers,
+  called with an empty / truncated source so they emit only the header.
+- **`resolveTagModel(track, options?)`** — the metadata resolution half of
+  `addTrackTags` (album, lyrics, cover, artist image, credits, BPM) without
+  touching audio, so a streaming caller can get a model to hand to
+  `createTagStream`. Same options, same coalescing. `addTrackTags` is now a thin
+  wrapper over it — no behaviour change.
+- **`probeAudioOffset(buffer)`** — where the audio starts in a source and which
+  container it is; exported for callers doing their own muxing.
+- `__tests__/tag-stream.ts` — byte-identical output asserted across chunk sizes
+  from 1 byte to whole-file, for MP3 and FLAC, with and without a pre-existing
+  tag.
+
+### Changed
+
+- README: streaming tag write documented under **Tag MP3 / FLAC** and in
+  **Running this on a server**.
+
 ## 2.14.0 - 2026-08-31
 
 Multi-tenant caching — for backends where many accounts share one process.

package/README.md

@@ -523,9 +523,33 @@ 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 |
 
+**On a server, tag as a stream instead.** `addTrackTags` must materialise the
+whole file, which is what caps concurrency. `createTagStream` produces
+byte-identical output without ever holding the audio — both containers keep
+their metadata at the front, so only the header is buffered (a few KB for MP3;
+the source's own metadata region for FLAC):
+
+```ts
+import {pipeline} from 'stream/promises';
+import {streamTrackDownload, resolveTagModel, createTagStream} from 'gerdur-core';
+
+const model = await resolveTagModel(track);          // the fetches, no audio
+const {stream} = await streamTrackDownload(track, 9);
+await pipeline(stream, createTagStream(model), createWriteStream('track.flac'));
+```
+
+| 40 MB tracks, concurrent | `addTrackTags` | `createTagStream` |
+| :--- | ---: | ---: |
+| 4 | +239 MB | **+0 MB** |
+| 16 | +965 MB, 986 ms | **+0 MB, 150 ms** |
+
+`resolveTagModel(track, options?)` does exactly what `addTrackTags` does minus
+the writing — same fetches, same coalescing, same `AddTrackTagsOptions`.
+
 Building blocks, if you want the model without writing tags:
 
 - **`getRichAlbum(albId)`** → merged gw + public album metadata (`RichAlbum`).
@@ -624,14 +648,21 @@ cacheStats(); // {shared: {size, maxSize, hits, misses, inFlight}} — for /metr
 
 ### Running this on a server
 
-- **Stream, don't buffer.** `downloadTrackBuffer` / `getTrackBuffer` hold the
-  whole file (and `Buffer.concat` doubles it briefly) — fine for a script, a
-  memory bomb at concurrency. Use `streamTrackDownload` in a request path.
+- **Stream, don't buffer — including the tags.** `downloadTrackBuffer` /
+  `getTrackBuffer` hold the whole file, and `addTrackTags` holds it again (the
+  tag writers allocate a second copy). Use `streamTrackDownload` +
+  `resolveTagModel` + `createTagStream` for an end-to-end constant-memory path:
+  measured at 16 concurrent 40 MB tracks, **965 MB → ~0 MB**, and 6.5x faster.
 - **Decryption runs on the event loop.** Blowfish costs ~33 ms per 8 MiB
   (~243 MiB/s), so heavy concurrent traffic will compete with everything else in
   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
@@ -777,7 +808,8 @@ import type {
 <details>
 <summary><b>Tagging</b></summary>
 
-`addTrackTags` · `buildTagModel` · `getRichAlbum` · `normalizeContributors` ·
+`addTrackTags` · `resolveTagModel` · `createTagStream` · `probeAudioOffset` ·
+`buildTagModel` · `getRichAlbum` · `normalizeContributors` ·
 `toLrc` · `downloadAlbumCover` · `downloadArtistImage` · `MAX_COVER_SIZE`
 </details>
 

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/lib/rate-limit.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Breaker tuning. A plain object — mutate it at startup to change the policy
+ * process-wide, the same way {@link RETRY_POLICY} works.
+ */
+export declare const BREAKER_POLICY: {
+    /** consecutive rate-limited rounds before the circuit opens */
+    trip: number;
+    /** how long the circuit stays open (requests fail fast) once tripped */
+    openMs: number;
+    /** shared cooldown after the first rate-limited round; doubles per round */
+    cooldownMs: number;
+    /** ceiling on the shared cooldown */
+    maxCooldownMs: number;
+};
+/** A read-only view of a session's rate-limit state, for metrics / health checks. */
+export interface RateLimitState {
+    /** consecutive rate-limited rounds; `0` when healthy */
+    consecutive: number;
+    /** the circuit is open — requests are failing fast */
+    open: boolean;
+    /** ms until the circuit closes again (`0` when not open) */
+    openForMs: number;
+    /** a shared cooldown is in progress and new requests will wait on it */
+    cooling: boolean;
+}
+export declare class RateLimitGate {
+    private gate;
+    private consecutive;
+    private openUntil;
+    /**
+     * Called before every attempt. Throws when the circuit is open; otherwise
+     * waits out any cooldown already in progress.
+     */
+    pass(): Promise<void>;
+    /**
+     * Report a rate-limited response. The first caller in a round opens the shared
+     * cooldown; the rest join it. Returns the cooldown to await.
+     */
+    trip(): Promise<void>;
+    /** Report a clean response — the endpoint is healthy again. */
+    succeed(): void;
+    /** Current state, for `cacheStats`-style reporting. */
+    get state(): RateLimitState;
+    /** Forget everything (used by tests and by `Session.init` on an account change). */
+    reset(): void;
+}

package/dist/lib/rate-limit.js

@@ -0,0 +1,113 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimitGate = exports.BREAKER_POLICY = void 0;
+/**
+ * Coordinated rate-limit handling for a {@link Session}.
+ *
+ * The retry loop already backs off when Deezer answers `code: 4` ("quota limit
+ * exceeded"). The problem is that it backs off *per request*: a session with 60
+ * concurrent gateway calls — tagging a long playlist, say — has all 60
+ * independently discover the limit, independently sleep, and independently
+ * retry, so the limiter keeps getting hit by the full fan-out and every caller
+ * burns its whole 30 s deadline before failing.
+ *
+ * This coordinates them:
+ *
+ * - **One shared cooldown.** The first request to see a rate limit opens a gate;
+ *   every other request in that round waits on the *same* timer instead of
+ *   starting its own. During a cooldown the wire sees nothing, rather than N
+ *   retries. The cooldown escalates per consecutive round and is jittered.
+ * - **A breaker.** After {@link BREAKER_POLICY}`.trip` consecutive rounds the
+ *   circuit opens and requests fail fast with a `DeezerError` for
+ *   `openMs`, instead of each holding a socket and a promise chain for the full
+ *   deadline. The next request after that window is the half-open probe: one
+ *   success resets everything.
+ *
+ * Scope is **per session**, which is the granularity Deezer's per-account quota
+ * uses and keeps one noisy tenant from failing everyone else's requests. If you
+ * also need to respect an IP-level limit shared by many sessions, coordinate
+ * that above this library.
+ */
+const delay_1 = __importDefault(require("delay"));
+const errors_1 = require("./errors");
+/**
+ * Breaker tuning. A plain object — mutate it at startup to change the policy
+ * process-wide, the same way {@link RETRY_POLICY} works.
+ */
+exports.BREAKER_POLICY = {
+    /** consecutive rate-limited rounds before the circuit opens */
+    trip: 5,
+    /** how long the circuit stays open (requests fail fast) once tripped */
+    openMs: 10000,
+    /** shared cooldown after the first rate-limited round; doubles per round */
+    cooldownMs: 1000,
+    /** ceiling on the shared cooldown */
+    maxCooldownMs: 15000,
+};
+class RateLimitGate {
+    constructor() {
+        this.gate = null;
+        this.consecutive = 0;
+        this.openUntil = 0;
+    }
+    /**
+     * Called before every attempt. Throws when the circuit is open; otherwise
+     * waits out any cooldown already in progress.
+     */
+    async pass() {
+        const openForMs = this.openUntil - Date.now();
+        if (openForMs > 0) {
+            throw new errors_1.DeezerError({
+                code: 4,
+                RATE_LIMIT_CIRCUIT_OPEN: `Deezer rate-limited this session; retrying in ${Math.ceil(openForMs / 1000)}s`,
+            });
+        }
+        if (this.gate) {
+            await this.gate;
+        }
+    }
+    /**
+     * Report a rate-limited response. The first caller in a round opens the shared
+     * cooldown; the rest join it. Returns the cooldown to await.
+     */
+    trip() {
+        if (!this.gate) {
+            // one increment per round, not per concurrent failure
+            this.consecutive++;
+            if (this.consecutive >= exports.BREAKER_POLICY.trip) {
+                this.openUntil = Date.now() + exports.BREAKER_POLICY.openMs;
+            }
+            const window = Math.min(exports.BREAKER_POLICY.cooldownMs * 2 ** (this.consecutive - 1), exports.BREAKER_POLICY.maxCooldownMs);
+            const jittered = window / 2 + Math.random() * (window / 2);
+            this.gate = (0, delay_1.default)(jittered).then(() => {
+                this.gate = null;
+            });
+        }
+        return this.gate;
+    }
+    /** Report a clean response — the endpoint is healthy again. */
+    succeed() {
+        this.consecutive = 0;
+        this.openUntil = 0;
+    }
+    /** Current state, for `cacheStats`-style reporting. */
+    get state() {
+        const openForMs = Math.max(0, this.openUntil - Date.now());
+        return {
+            consecutive: this.consecutive,
+            open: openForMs > 0,
+            openForMs,
+            cooling: this.gate !== null,
+        };
+    }
+    /** Forget everything (used by tests and by `Session.init` on an account change). */
+    reset() {
+        this.consecutive = 0;
+        this.openUntil = 0;
+        this.gate = null;
+    }
+}
+exports.RateLimitGate = RateLimitGate;

package/dist/lib/session.js

@@ -34,6 +34,22 @@ exports.RETRY_POLICY = {
     /** overall wall-clock budget from the first attempt */
     deadlineMs: 30000,
 };
+// A shared cooldown + circuit breaker across a session's concurrent requests was
+// built and measured against this loop, then dropped. Numbers, 60 concurrent
+// requests against a permanently rate-limited endpoint (baseline 420 wire calls
+// / 8.5s):
+//   - as first written (trip after 5 rounds, escalating shared cooldown):
+//     420 calls / 36s — strictly worse. The retry cap is per request, so
+//     synchronising the waits changes nothing about total calls and only
+//     lengthens them.
+//   - tuned hard (open on the first rate-limited round, 300ms cooldown):
+//     60 calls / 0.2s, but a *single* request meeting one transient `code: 4`
+//     then fails outright, where this loop retries and succeeds.
+// The flaw is structural: the request that trips the breaker is immediately
+// blocked by its own trip. A correct version has to tell new work apart from an
+// in-flight retry — shed the former, never the latter — which means threading
+// per-request attempt state through the gate. Worth doing only with a real
+// workload to tune against; guessing made it worse twice.
 /** Exponential backoff (ms) with full jitter on the top half of the window. */
 const backoffDelay = (attempt) => {
     const windowMs = Math.min(exports.RETRY_POLICY.baseMs * 2 ** attempt, exports.RETRY_POLICY.maxDelayMs);

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

@@ -10,6 +10,7 @@ export type { RichAlbum } from './rich-album';
 export { buildTagModel } from './model';
 export type { TrackTagModel, Person } from './model';
 export { downloadAlbumCover, downloadArtistImage, MAX_COVER_SIZE } from './abumCover';
+export { createTagStream, probeAudioOffset } from './tag-stream';
 export interface AddTrackTagsOptions {
     /** embedded cover size in px, 56–1800 (default 1000) */
     coverSize?: number;
@@ -29,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;
     /**
@@ -48,6 +55,20 @@ export interface TaggedTrack {
     /** everything gerdur pulled together for this track — use `model.lyricsSynced` for a `.lrc` sidecar */
     model: TrackTagModel;
 }
+/**
+ * Resolve everything Deezer has for a track into the canonical tag model —
+ * without touching any audio.
+ *
+ * Fetches album info, lyrics, cover, artist image and (for album/playlist
+ * tracks, which ship without them) full credits + BPM, all in parallel; every
+ * call is memoised and in-flight-coalesced, so resolving all tracks of one album
+ * hits each metadata endpoint once. Pass any of
+ * `options.{album,lyrics,cover,publicTrack}` to skip the corresponding fetch.
+ *
+ * Feed the result to `createTagStream(model)` to tag a stream, or use
+ * {@link addTrackTags} to tag a `Buffer` in one call.
+ */
+export declare const resolveTagModel: (trackInput: trackType, options?: AddTrackTagsOptions) => Promise<TrackTagModel>;
 /**
  * Pull together everything Deezer has for a track and write it into the audio.
  *
@@ -57,6 +78,10 @@ export interface TaggedTrack {
  * tracks of one album hits each metadata endpoint once. Pass any of
  * `options.{album,lyrics,cover,publicTrack}` to skip the corresponding fetch.
  *
+ * This holds the whole file in memory (and the tag writers allocate another
+ * copy). On a server, prefer {@link resolveTagModel} + `createTagStream`, which
+ * produces byte-identical output without buffering the audio.
+ *
  * @returns `{buffer, model}` — `model` carries the structured metadata and,
  *   when available, `model.lyricsSynced` (an LRC document for a sidecar file).
  */

package/dist/metadata-writer/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.addTrackTags = exports.MAX_COVER_SIZE = exports.downloadArtistImage = exports.downloadAlbumCover = exports.buildTagModel = exports.getRichAlbum = exports.toLrc = exports.normalizeContributors = void 0;
+exports.addTrackTags = exports.resolveTagModel = exports.probeAudioOffset = exports.createTagStream = exports.MAX_COVER_SIZE = exports.downloadArtistImage = exports.downloadAlbumCover = exports.buildTagModel = exports.getRichAlbum = exports.toLrc = exports.normalizeContributors = void 0;
 const abumCover_1 = require("./abumCover");
 const getTrackLyrics_1 = require("./getTrackLyrics");
 const id3_1 = require("./id3");
@@ -20,16 +20,26 @@ var abumCover_2 = require("./abumCover");
 Object.defineProperty(exports, "downloadAlbumCover", { enumerable: true, get: function () { return abumCover_2.downloadAlbumCover; } });
 Object.defineProperty(exports, "downloadArtistImage", { enumerable: true, get: function () { return abumCover_2.downloadArtistImage; } });
 Object.defineProperty(exports, "MAX_COVER_SIZE", { enumerable: true, get: function () { return abumCover_2.MAX_COVER_SIZE; } });
+var tag_stream_1 = require("./tag-stream");
+Object.defineProperty(exports, "createTagStream", { enumerable: true, get: function () { return tag_stream_1.createTagStream; } });
+Object.defineProperty(exports, "probeAudioOffset", { enumerable: true, get: function () { return tag_stream_1.probeAudioOffset; } });
 const DEFAULTS = {
     coverSize: 1000,
     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) {
@@ -55,18 +65,19 @@ const hydrate = async (track) => {
     }
 };
 /**
- * Pull together everything Deezer has for a track and write it into the audio.
+ * Resolve everything Deezer has for a track into the canonical tag model —
+ * without touching any audio.
  *
- * Sniffs `fLaC` vs MP3 and dispatches to the FLAC / ID3 writer. Fetches album
- * info, lyrics, cover and (for album/playlist tracks) full credits + BPM in
- * parallel — every call is memoised and in-flight-coalesced, so tagging all
- * tracks of one album hits each metadata endpoint once. Pass any of
+ * Fetches album info, lyrics, cover, artist image and (for album/playlist
+ * tracks, which ship without them) full credits + BPM, all in parallel; every
+ * call is memoised and in-flight-coalesced, so resolving all tracks of one album
+ * hits each metadata endpoint once. Pass any of
  * `options.{album,lyrics,cover,publicTrack}` to skip the corresponding fetch.
  *
- * @returns `{buffer, model}` — `model` carries the structured metadata and,
- *   when available, `model.lyricsSynced` (an LRC document for a sidecar file).
+ * Feed the result to `createTagStream(model)` to tag a stream, or use
+ * {@link addTrackTags} to tag a `Buffer` in one call.
  */
-const addTrackTags = async (trackBuffer, trackInput, options = {}) => {
+const resolveTagModel = async (trackInput, options = {}) => {
     const opt = { ...DEFAULTS, ...options };
     const track = opt.richCredits ? await hydrate(trackInput) : trackInput;
     const [album, lyrics, publicTrack, cover, artistImage] = await Promise.all([
@@ -74,7 +85,7 @@ const addTrackTags = async (trackBuffer, 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)
@@ -106,6 +117,28 @@ const addTrackTags = async (trackBuffer, trackInput, options = {}) => {
         deezerIds: opt.deezerIds,
         includeRank: opt.includeRank,
     });
+    return model;
+};
+exports.resolveTagModel = resolveTagModel;
+/**
+ * Pull together everything Deezer has for a track and write it into the audio.
+ *
+ * Sniffs `fLaC` vs MP3 and dispatches to the FLAC / ID3 writer. Fetches album
+ * info, lyrics, cover and (for album/playlist tracks) full credits + BPM in
+ * parallel — every call is memoised and in-flight-coalesced, so tagging all
+ * tracks of one album hits each metadata endpoint once. Pass any of
+ * `options.{album,lyrics,cover,publicTrack}` to skip the corresponding fetch.
+ *
+ * This holds the whole file in memory (and the tag writers allocate another
+ * copy). On a server, prefer {@link resolveTagModel} + `createTagStream`, which
+ * produces byte-identical output without buffering the audio.
+ *
+ * @returns `{buffer, model}` — `model` carries the structured metadata and,
+ *   when available, `model.lyricsSynced` (an LRC document for a sidecar file).
+ */
+const addTrackTags = async (trackBuffer, trackInput, options = {}) => {
+    const model = await (0, exports.resolveTagModel)(trackInput, options);
+    const opt = { ...DEFAULTS, ...options };
     const isFlac = trackBuffer.slice(0, 4).toString('ascii') === 'fLaC';
     const buffer = isFlac
         ? (0, flacmetata_1.writeMetadataFlac)(trackBuffer, model, { embedSyncedLyrics: opt.embedSyncedLyrics })

package/dist/metadata-writer/tag-stream.d.ts

@@ -0,0 +1,64 @@
+/// <reference types="node" />
+/**
+ * Streaming tag writer — rewrite a track's tags as bytes flow through, without
+ * ever holding the audio.
+ *
+ * `addTrackTags` has to materialise the whole file: `browser-id3-writer`
+ * allocates `audio.length + tag` and copies the audio into it (and copies again
+ * to strip an existing ID3v2), and the FLAC path concatenates the same way. That
+ * is ~2–3× the file size per concurrent call — measured at **+121 MB retained
+ * for a 40 MB MP3** — which is what caps concurrency on a server and what
+ * quietly cancels `streamTrackDownload`'s constant-memory guarantee at the last
+ * step.
+ *
+ * Both container formats put their metadata at the *front*, so none of that
+ * copying is necessary:
+ *
+ * - **MP3** — an ID3v2 tag is a 10-byte header plus a syncsafe length. Emit a
+ *   freshly built tag, discard exactly that many bytes of the source as they go
+ *   past, pass the rest through. Nothing is buffered at all.
+ * - **FLAC** — `fLaC` then a chain of metadata blocks, the last flagged. Buffer
+ *   only that chain (to parse STREAMINFO and friends), emit the rebuilt blocks,
+ *   pass the frames through untouched.
+ *
+ * Peak memory becomes O(metadata) instead of O(file): a few KB for MP3, and for
+ * FLAC whatever the source's own metadata region is.
+ *
+ * The tag bytes come from the exact same writers `addTrackTags` uses — called
+ * with an empty / truncated source so they emit only the header — so output is
+ * byte-identical to the buffered path.
+ *
+ * ```ts
+ * import {pipeline} from 'stream/promises';
+ * const {stream} = await streamTrackDownload(track, 9);
+ * await pipeline(stream, createTagStream(model), createWriteStream('out.flac'));
+ * ```
+ */
+import { Transform } from 'stream';
+import type { FlacWriteOptions } from './flacmetata';
+import type { TrackTagModel } from './model';
+type Probe = {
+    ready: false;
+} | {
+    ready: true;
+    audioOffset: number;
+    flac: boolean;
+};
+/**
+ * Where the audio starts in the source, and which container it is.
+ * `{ready: false}` means "need more bytes".
+ */
+export declare const probeAudioOffset: (buf: Buffer) => Probe;
+/**
+ * A `Transform` that replaces the tags on a track as it streams through.
+ *
+ * Feed it the decrypted audio (e.g. from {@link streamTrackDownload}); it emits
+ * the same bytes {@link addTrackTags} would produce, without buffering the file.
+ * Detects MP3 vs FLAC from the source itself.
+ *
+ * @param model   the canonical tag model — from `buildTagModel`, or the `model`
+ *                an earlier `addTrackTags` call returned
+ * @param options forwarded to the FLAC writer (e.g. `embedSyncedLyrics`)
+ */
+export declare const createTagStream: (model: TrackTagModel, options?: FlacWriteOptions) => Transform;
+export {};

package/dist/metadata-writer/tag-stream.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createTagStream = exports.probeAudioOffset = void 0;
+/**
+ * Streaming tag writer — rewrite a track's tags as bytes flow through, without
+ * ever holding the audio.
+ *
+ * `addTrackTags` has to materialise the whole file: `browser-id3-writer`
+ * allocates `audio.length + tag` and copies the audio into it (and copies again
+ * to strip an existing ID3v2), and the FLAC path concatenates the same way. That
+ * is ~2–3× the file size per concurrent call — measured at **+121 MB retained
+ * for a 40 MB MP3** — which is what caps concurrency on a server and what
+ * quietly cancels `streamTrackDownload`'s constant-memory guarantee at the last
+ * step.
+ *
+ * Both container formats put their metadata at the *front*, so none of that
+ * copying is necessary:
+ *
+ * - **MP3** — an ID3v2 tag is a 10-byte header plus a syncsafe length. Emit a
+ *   freshly built tag, discard exactly that many bytes of the source as they go
+ *   past, pass the rest through. Nothing is buffered at all.
+ * - **FLAC** — `fLaC` then a chain of metadata blocks, the last flagged. Buffer
+ *   only that chain (to parse STREAMINFO and friends), emit the rebuilt blocks,
+ *   pass the frames through untouched.
+ *
+ * Peak memory becomes O(metadata) instead of O(file): a few KB for MP3, and for
+ * FLAC whatever the source's own metadata region is.
+ *
+ * The tag bytes come from the exact same writers `addTrackTags` uses — called
+ * with an empty / truncated source so they emit only the header — so output is
+ * byte-identical to the buffered path.
+ *
+ * ```ts
+ * import {pipeline} from 'stream/promises';
+ * const {stream} = await streamTrackDownload(track, 9);
+ * await pipeline(stream, createTagStream(model), createWriteStream('out.flac'));
+ * ```
+ */
+const stream_1 = require("stream");
+const flacmetata_1 = require("./flacmetata");
+const id3_1 = require("./id3");
+/**
+ * Cap on how much of the source is buffered while looking for the end of its
+ * metadata region. Only FLAC ever gets here, and only for its own metadata
+ * (STREAMINFO + SEEKTABLE + any embedded art). Past this the stream errors
+ * rather than growing without bound.
+ */
+const MAX_HEADER_BYTES = 16 * 1024 * 1024;
+/**
+ * Where the audio starts in the source, and which container it is.
+ * `{ready: false}` means "need more bytes".
+ */
+const probeAudioOffset = (buf) => {
+    if (buf.length >= 4 && buf.toString('ascii', 0, 4) === 'fLaC') {
+        // fLaC | (1 byte: last-block flag + type)(3 bytes: length)[body] ...
+        let offset = 4;
+        for (;;) {
+            if (offset + 4 > buf.length) {
+                return { ready: false };
+            }
+            const isLast = buf.readUInt8(offset) >= 128;
+            offset += 4 + buf.readUIntBE(offset + 1, 3);
+            if (isLast) {
+                // the whole chain must be present for the FLAC parser to walk it
+                return offset <= buf.length ? { ready: true, audioOffset: offset, flac: true } : { ready: false };
+            }
+        }
+    }
+    if (buf.length < 10) {
+        return { ready: false };
+    }
+    if (buf.toString('ascii', 0, 3) !== 'ID3') {
+        return { ready: true, audioOffset: 0, flac: false }; // no existing tag — audio from byte 0
+    }
+    // ID3v2 size is 4 syncsafe bytes (7 bits each) at offset 6
+    const size = (buf[6] << 21) | (buf[7] << 14) | (buf[8] << 7) | buf[9];
+    return { ready: true, audioOffset: 10 + size, flac: false };
+};
+exports.probeAudioOffset = probeAudioOffset;
+/**
+ * A `Transform` that replaces the tags on a track as it streams through.
+ *
+ * Feed it the decrypted audio (e.g. from {@link streamTrackDownload}); it emits
+ * the same bytes {@link addTrackTags} would produce, without buffering the file.
+ * Detects MP3 vs FLAC from the source itself.
+ *
+ * @param model   the canonical tag model — from `buildTagModel`, or the `model`
+ *                an earlier `addTrackTags` call returned
+ * @param options forwarded to the FLAC writer (e.g. `embedSyncedLyrics`)
+ */
+const createTagStream = (model, options = {}) => {
+    let head = [];
+    let headLength = 0;
+    /** 'probing' → reading the source header; 'skipping' → dropping its old tag; 'passthrough' → audio */
+    let mode = 'probing';
+    let toSkip = 0;
+    return new stream_1.Transform({
+        transform(chunk, _encoding, callback) {
+            const part = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            if (mode === 'passthrough') {
+                this.push(part);
+                return callback();
+            }
+            if (mode === 'skipping') {
+                if (part.length <= toSkip) {
+                    toSkip -= part.length;
+                }
+                else {
+                    this.push(part.subarray(toSkip));
+                    toSkip = 0;
+                    mode = 'passthrough';
+                }
+                return callback();
+            }
+            head.push(part);
+            headLength += part.length;
+            if (headLength > MAX_HEADER_BYTES) {
+                return callback(new Error(`No audio found in the first ${MAX_HEADER_BYTES} bytes — is this a track?`));
+            }
+            const buffered = head.length === 1 ? head[0] : Buffer.concat(head, headLength);
+            const probe = (0, exports.probeAudioOffset)(buffered);
+            if (!probe.ready) {
+                head = [buffered];
+                return callback();
+            }
+            try {
+                if (probe.flac) {
+                    // truncating at audioOffset makes the writer's own `slice(framesOffset)`
+                    // empty, so it returns exactly `fLaC` + the rebuilt metadata blocks
+                    this.push((0, flacmetata_1.writeMetadataFlac)(buffered.subarray(0, probe.audioOffset), model, options));
+                    this.push(buffered.subarray(probe.audioOffset));
+                    mode = 'passthrough';
+                }
+                else {
+                    // an empty source makes the ID3 writer emit only the tag
+                    this.push((0, id3_1.writeMetadataMp3)(Buffer.alloc(0), model));
+                    if (buffered.length > probe.audioOffset) {
+                        this.push(buffered.subarray(probe.audioOffset));
+                        mode = 'passthrough';
+                    }
+                    else {
+                        toSkip = probe.audioOffset - buffered.length;
+                        mode = 'skipping';
+                    }
+                }
+            }
+            catch (err) {
+                return callback(err);
+            }
+            head = [];
+            headLength = 0;
+            return callback();
+        },
+        flush(callback) {
+            // a source too short to probe (or one that never closed its metadata
+            // chain) — tag what we have rather than dropping it
+            if (mode === 'probing' && headLength > 0) {
+                const buffered = head.length === 1 ? head[0] : Buffer.concat(head, headLength);
+                try {
+                    this.push((0, id3_1.writeMetadataMp3)(Buffer.alloc(0), model));
+                    this.push(buffered);
+                }
+                catch (err) {
+                    return callback(err);
+                }
+            }
+            return callback();
+        },
+    });
+};
+exports.createTagStream = createTagStream;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gerdur-core",
-  "version": "2.14.0",
+  "version": "2.16.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",