gerdur 2.11.2 → 2.13.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 2.13.0 - 2026-08-31
+
+### Added
+
+- **`--fast`** — skip the expensive per-track metadata: full studio credits, BPM,
+  and the Musixmatch fallback for tracks Deezer has no lyrics for. Tagging is
+  what actually burns Deezer's rate limit (a 14-track album costs ~54 requests to
+  tag against 2 to fetch), and this takes that album to **7 requests — 81% fewer
+  against the quota**. Audio, cover, Deezer lyrics and `.lrc` sidecars are
+  unchanged; you lose credits, BPM and non-Deezer lyrics.
+- **`gerdur-core@^2.16.0`** for the underlying `lyricsFallback` option.
+
+## 2.12.0 - 2026-08-31
+
+### Changed
+
+- **Downloads no longer hold the track in memory.** The final stage was
+  temp file -> `readFileSync` -> `addTrackTags` (which allocates the file again,
+  plus another copy to strip Deezer's existing tag) -> `writeFileSync`. It is now
+  a single streamed pass — **temp file -> decrypt -> tag -> destination** — using
+  `gerdur-core@2.15.0`'s `resolveTagModel` + `createTagStream`. Peak memory per
+  concurrent download drops from ~2-3x the track size to roughly a couple of
+  2048-byte stripes plus the cover art, which matters most with `-c 8` on FLAC.
+  Output is byte-identical.
+- The intermediate `.dec` temp file is gone — decryption is now a stage in that
+  same pipeline rather than a separate pass over the whole file.
+- Tracks are written to `<name>.part` and renamed on success, so an interrupted
+  or failed run can no longer leave a half-written file where a real track
+  should be.
+
+Verified end to end against live downloads: MP3 (ID3v2.3, all frames, 324 kbps)
+and FLAC (STREAMINFO / SEEKTABLE / VORBIS_COMMENT / 2x PICTURE / PADDING, 16-bit
+44.1 kHz) both decode with zero errors under ffmpeg.
+
 ## 2.11.2 - 2026-08-31
 
 ### Changed

package/README.md

@@ -166,6 +166,7 @@ All options are optional; the interactive prompt fills in the rest. Provide
 | `--search-limit` | | number | How many results to fetch (default 50) |
 | `--preview` | | — | Download 30-second `.preview.mp3` clips — no `--quality`, no `arl` |
 | `--enrich` | | — | Embed a higher-res cover from the Cover Art Archive (by ISRC) |
+| `--fast` | | — | Skip per-track credits, BPM and the Musixmatch lyrics fallback — **~81% fewer Deezer requests** |
 | `--update` | `-U` | — | Self-update (prebuilt binary only) |
 | `--help` | `-h` | — | Full help |
 
@@ -245,6 +246,30 @@ at 1800 px). No match or the services are down? It silently keeps Deezer's cover
 gerdur --enrich -q flac -u https://deezer.com/album/302127
 ```
 
+### Downloading a lot at once (`--fast`)
+
+Tagging, not downloading, is what burns through Deezer's rate limit: a 14-track
+album costs about **54 requests to tag** and 2 to fetch. Most of that is per-track
+— full credits and BPM (`song.getData` + a public lookup each), plus a Musixmatch
+scrape for every track Deezer has no lyrics for, which fails outright on many
+networks.
+
+`--fast` skips exactly those. Same audio, same cover, same Deezer lyrics, same
+`.lrc` sidecars:
+
+```bash
+gerdur --fast -q flac -u https://deezer.com/album/302127
+```
+
+| 14-track album | requests | against Deezer's quota |
+| :--- | ---: | ---: |
+| default | 54 | 36 |
+| `--fast` | **7** | **7** |
+
+You lose full studio credits, BPM, and lyrics for tracks Deezer doesn't carry.
+Worth it when you're pulling a large library and getting rate-limited; leave it
+off for a handful of tracks you care about.
+
 ### Output templates
 
 `--output` (or `saveLayout` in the config) is a path template. `{TOKEN}`s are

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "gerdur",
-    "version": "2.11.2",
+    "version": "2.13.0",
     "description": "Command-line music downloader for Deezer (Spotify/Tidal links resolved via ISRC matching) with automatic MP3/FLAC tagging, synced lyrics and a side-effect-free programmatic API.",
     "keywords": [
         "deezer",
@@ -63,7 +63,7 @@
         "adm-zip": "^0.5.16",
         "chalk": "^4.1.2",
         "commander": "^9.5.0",
-        "gerdur-core": "^2.13.0",
+        "gerdur-core": "^2.16.0",
         "dot-prop": "^6.0.1",
         "got": "^11.8.6",
         "gradient-string": "^2.0.2",

package/dist/src/gerdur.js

@@ -60,7 +60,8 @@ const cmd = new commander_1.Command()
     .option('--dur-max <seconds>', 'Search filter: maximum duration')
     .option('--search-limit <n>', 'Max search results to fetch', '50')
     .option('--preview', 'Download the 30-second preview clips instead of full tracks', false)
-    .option('--enrich', 'Embed a higher-res cover from the Cover Art Archive (looked up by ISRC)', false);
+    .option('--enrich', 'Embed a higher-res cover from the Cover Art Archive (looked up by ISRC)', false)
+    .option('--fast', 'Skip per-track credits, BPM and the Musixmatch lyrics fallback (~81% fewer Deezer requests)', false);
 if (process.pkg) {
     cmd.option('-U, --update', 'Update this program to latest version');
 }
@@ -486,6 +487,7 @@ const startDownload = async (saveLayout, url, skipPrompt) => {
                             message: `(${index}/${data.tracks.length})`,
                             lrc,
                             enrich: Boolean(options.enrich),
+                            fast: Boolean(options.fast),
                             prefetched: prefetchedUrls.get(track.SNG_ID) ?? null,
                         });
                         // Add to saved list

package/dist/src/lib/download-track.d.ts

@@ -27,6 +27,13 @@ interface downloadTrackProps {
      * to Deezer's cover if there's no match. Off by default.
      */
     enrich?: boolean;
+    /**
+     * Skip the expensive per-track metadata: full credits, BPM, and the Musixmatch
+     * fallback for tracks Deezer has no lyrics for. Measured on a 14-track album
+     * that is 54 requests down to 7 — 81% fewer against Deezer's rate limit — at
+     * the cost of those fields. Off by default.
+     */
+    fast?: boolean;
     /**
      * A download URL already resolved for this track by a batch `resolveDownloadUrls`
      * pass. When set, the per-track `get_url` request and quality-fallback round-trips
@@ -40,5 +47,5 @@ interface downloadTrackProps {
         format: string;
     } | null;
 }
-declare const downloadTrack: ({ track, quality, info, coverSizes, path, totalTracks, trackNumber, fallbackTrack, fallbackQuality, isFallback, isQualityFallback, overwrite, message, lrc, enrich, prefetched, }: downloadTrackProps) => Promise<string | undefined>;
+declare const downloadTrack: ({ track, quality, info, coverSizes, path, totalTracks, trackNumber, fallbackTrack, fallbackQuality, isFallback, isQualityFallback, overwrite, message, lrc, enrich, fast, prefetched, }: downloadTrackProps) => Promise<string | undefined>;
 export default downloadTrack;

package/dist/src/lib/download-track.js

@@ -13,12 +13,11 @@ const log_update_1 = __importDefault(require("log-update"));
 const chalk_1 = __importDefault(require("chalk"));
 const signale_1 = __importDefault(require("../lib/signale"));
 const util_2 = require("./util");
-const decrypt_1 = require("./decrypt");
 const pipeline = (0, util_1.promisify)(stream_1.default.pipeline);
 const simulate = process.env.SIMULATE;
 /** media-API format string -> gerdur's numeric quality */
 const FORMAT_TO_QUALITY = { FLAC: 9, MP3_320: 3, MP3_256: 3, MP3_128: 1, MP3_64: 1 };
-const downloadTrack = async ({ track, quality, info, coverSizes, path, totalTracks, trackNumber = true, fallbackTrack = true, fallbackQuality = true, isFallback = false, isQualityFallback = false, overwrite = false, message = '', lrc = true, enrich = false, prefetched = null, }) => {
+const downloadTrack = async ({ track, quality, info, coverSizes, path, totalTracks, trackNumber = true, fallbackTrack = true, fallbackQuality = true, isFallback = false, isQualityFallback = false, overwrite = false, message = '', lrc = true, enrich = false, fast = false, prefetched = null, }) => {
     (0, log_update_1.default)(signale_1.default.pending(track.SNG_TITLE + ' by ' + track.ART_NAME + ' from ' + track.ALB_TITLE));
     try {
         let ext = '.mp3', fileSize = 0, downloaded = 0, coverSize = 500;
@@ -142,17 +141,6 @@ const downloadTrack = async ({ track, quality, info, coverSizes, path, totalTrac
                 (0, log_update_1.default)(signale_1.default.info(`Downloading ${track.SNG_TITLE} ${message}\n  ${bar(transferred)} | ${humanSizeTotal}MiB`));
             }
         }), (0, fs_1.createWriteStream)(tmpfile, { flags: 'a', autoClose: true }));
-        let outFile;
-        if (trackData.isEncrypted) {
-            (0, log_update_1.default)(signale_1.default.pending('Decrypting ' + track.SNG_TITLE + ' by ' + track.ART_NAME));
-            const decfile = tmpfile + '.dec';
-            await (0, decrypt_1.decryptFileToFile)(tmpfile, decfile, track.SNG_ID); // streamed — ~one stripe in memory
-            outFile = (0, fs_1.readFileSync)(decfile);
-            (0, fs_1.unlinkSync)(decfile);
-        }
-        else {
-            outFile = (0, fs_1.readFileSync)(tmpfile);
-        }
         let enrichedCover;
         if (enrich && track.ISRC && !simulate) {
             try {
@@ -167,12 +155,13 @@ const downloadTrack = async ({ track, quality, info, coverSizes, path, totalTrac
             }
         }
         (0, log_update_1.default)(signale_1.default.pending('Tagging ' + track.SNG_TITLE + ' by ' + track.ART_NAME));
-        const { buffer: trackWithMetadata, model } = await (0, gerdur_core_1.addTrackTags)(outFile, track, {
+        // Resolve the metadata first, without touching the audio — the tags are then
+        // written by a stream, so the track is never held in memory.
+        const model = await (0, gerdur_core_1.resolveTagModel)(track, {
             coverSize,
+            ...(fast ? { richCredits: false, lyricsFallback: false } : {}),
             ...(enrichedCover ? { cover: enrichedCover } : {}),
         });
-        // Delete temporary file now
-        (0, fs_1.unlinkSync)(tmpfile);
         (0, log_update_1.default)(signale_1.default.pending('Saving ' + track.SNG_TITLE + ' by ' + track.ART_NAME));
         if (!simulate) {
             // Create directory if not exists
@@ -180,12 +169,32 @@ const downloadTrack = async ({ track, quality, info, coverSizes, path, totalTrac
             if (!(0, fs_1.existsSync)(dir)) {
                 (0, fs_1.mkdirSync)(dir, { recursive: true });
             }
-            // Save file to disk
-            (0, fs_1.writeFileSync)(savePath, trackWithMetadata);
+            // One pass: temp file -> decrypt -> tag -> destination. Peak memory is a
+            // couple of stripes plus the cover, instead of the whole track two or
+            // three times over. `.part` then rename so an interrupted run never
+            // leaves a half-written track behind.
+            const partPath = savePath + '.part';
+            const stages = [(0, fs_1.createReadStream)(tmpfile)];
+            if (trackData.isEncrypted) {
+                stages.push((0, gerdur_core_1.createDecryptStream)(track.SNG_ID));
+            }
+            stages.push((0, gerdur_core_1.createTagStream)(model), (0, fs_1.createWriteStream)(partPath));
+            try {
+                await pipeline(...stages);
+            }
+            catch (err) {
+                if ((0, fs_1.existsSync)(partPath)) {
+                    (0, fs_1.unlinkSync)(partPath);
+                }
+                throw err;
+            }
+            (0, fs_1.renameSync)(partPath, savePath);
             if (lrc !== false && model.lyricsSynced) {
                 (0, fs_1.writeFileSync)(savePath.replace(/\.(mp3|flac)$/i, '.lrc'), model.lyricsSynced);
             }
         }
+        // Delete temporary file now
+        (0, fs_1.unlinkSync)(tmpfile);
         // Print sucess info
         (0, log_update_1.default)(signale_1.default.success(`${isFallback ? chalk_1.default.yellow('[Fallback] ') : ''}${track.SNG_TITLE} by ${track.ART_NAME}`));
         log_update_1.default.done();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gerdur",
-  "version": "2.11.2",
+  "version": "2.13.0",
   "description": "Command-line music downloader for Deezer (Spotify/Tidal links resolved via ISRC matching) with automatic MP3/FLAC tagging, synced lyrics and a side-effect-free programmatic API.",
   "keywords": [
     "deezer",
@@ -63,7 +63,7 @@
     "adm-zip": "^0.5.16",
     "chalk": "^4.1.2",
     "commander": "^9.5.0",
-    "gerdur-core": "^2.13.0",
+    "gerdur-core": "^2.16.0",
     "dot-prop": "^6.0.1",
     "got": "^11.8.6",
     "gradient-string": "^2.0.2",