gerdur-core 2.14.0 → 2.15.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 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

@@ -526,6 +526,29 @@ model.contributors;  // normalised producers / engineers / performers / …
 | `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,9 +647,11 @@ 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.
@@ -777,7 +802,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/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/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;
@@ -48,6 +49,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 +72,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,6 +20,9 @@ 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,
@@ -55,18 +58,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([
@@ -106,6 +110,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.15.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",