gerdur 2.12.0 → 2.14.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 2.14.0 - 2026-08-31
+
+### Added
+
+- **`mix:<trackId>`** — download a "more like this" mix seeded from a track.
+  Backed by `gerdur-core@2.17.0`'s `getTrackMix`, which returns tracks with
+  their `TRACK_TOKEN`s already attached, so unlike the public radio sources
+  there is no per-track lookup before downloading.
+- **`library`** (also `favorites` / `favourites`) — pick from the logged-in
+  account's own loved tracks, **private library included**. The public profile
+  endpoints can't see these.
+- **`gerdur-core@^2.17.0`** — re-exports the whole private-library surface:
+  `getMyPlaylists`, `getMyFavorite{Tracks,TrackIds,Albums,Artists,Playlists,Radios,Shows}`,
+  `getTrackMix`.
+
+## 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

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 |
 
@@ -191,6 +192,8 @@ Anywhere a URL is accepted (`-u`, the interactive prompt, or a line in
 | `radio:<id>` | a radio's current playlist |
 | `chart` · `chart:<genreId>` | this week's chart (optionally a genre) |
 | `artist-top:<artistId>` | an artist's most popular tracks |
+| `mix:<trackId>` | a "more like this" mix seeded from a track |
+| `library` · `favorites` | your own loved tracks (private library) |
 | `episode:<episodeId>` | a single podcast episode (plain MP3, saved to `Podcasts/`) |
 
 All of these work in `--headless` mode too (`gerdur -d -q 320 -u flow`).
@@ -245,6 +248,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.12.0",
+    "version": "2.14.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.15.0",
+        "gerdur-core": "^2.17.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');
 }
@@ -147,6 +148,36 @@ const pickAndHydrate = async (results, id) => {
     }
     return { info: { type: 'track', id }, linktype: 'track', linkinfo: {}, tracks };
 };
+/**
+ * Like `pickAndHydrate`, but for gateway tracks — the library and mix endpoints
+ * already return full tracks with `TRACK_TOKEN`s, so there is nothing to fetch.
+ */
+const pickGwTracks = async (results, id) => {
+    if (!results.length) {
+        console.log(signale_1.default.warn('Nothing to download.'));
+        return null;
+    }
+    let picks = results;
+    if (!options.headless) {
+        const choice = await (0, prompts_1.default)([
+            {
+                type: 'multiselect',
+                name: 'items',
+                message: `Select tracks to download. ${results.length} available.`,
+                choices: results.map((r) => ({
+                    title: `${r.SNG_TITLE} — ${r.ART_NAME}`,
+                    value: r,
+                    description: `Album: ${r.ALB_TITLE ?? 'Unknown'} · ${(0, util_1.formatSecondsReadable)(Number(r.DURATION) || 0)}`,
+                })),
+            },
+        ], { onCancel });
+        picks = choice.items ?? [];
+    }
+    if (!picks.length) {
+        return null;
+    }
+    return { info: { type: 'track', id }, linktype: 'track', linkinfo: {}, tracks: picks.map(stampVersion) };
+};
 const resolveAdvancedSearch = async (filters) => {
     const limit = toFiniteNumber(options.searchLimit) ?? 50;
     const { data: results, query, usedFallback } = await (0, search_1.searchAdvancedTracks)(filters, { limit });
@@ -234,7 +265,7 @@ const startDownload = async (saveLayout, url, skipPrompt) => {
                 {
                     type: 'text',
                     name: 'query',
-                    message: 'Enter a URL, a search term, or a prefix (search: isrc: upc: flow radio: chart artist-top: episode:):',
+                    message: 'Enter a URL, a search term, or a prefix (search: isrc: upc: flow radio: chart artist-top: mix: library episode:):',
                     validate: (value) => (value ? true : false),
                 },
             ], { onCancel });
@@ -306,6 +337,26 @@ const startDownload = async (saveLayout, url, skipPrompt) => {
                 throw new Error(`Artist ${aid} returned no top tracks.`);
             }
         }
+        // `mix:<trackId>` — a "more like this" mix. Tokens come attached, so unlike
+        // the public radio sources there is no per-track lookup before downloading.
+        if (!searchData && url && url.startsWith('mix:')) {
+            const sid = url.slice('mix:'.length).trim();
+            console.log(signale_1.default.info(`Building a mix from track ${sid}…`));
+            const { data } = await (0, gerdur_core_1.getTrackMix)(sid, toFiniteNumber(options.searchLimit) ?? 40);
+            searchData = await pickGwTracks(data, `mix:${sid}`);
+            if (!searchData) {
+                throw new Error(`Track ${sid} returned no mix.`);
+            }
+        }
+        // `library` — the logged-in account's loved tracks, private ones included.
+        if (!searchData && url && (url === 'library' || url === 'favorites' || url === 'favourites')) {
+            console.log(signale_1.default.info('Fetching your loved tracks…'));
+            const { data, total } = await (0, gerdur_core_1.getMyFavoriteTracks)(undefined, toFiniteNumber(options.searchLimit) ?? 100);
+            if (!data.length) {
+                throw new Error(`Your library has no loved tracks (total ${total}).`);
+            }
+            searchData = await pickGwTracks(data, 'library');
+        }
         // `episode:<id>` — a podcast episode (a plain MP3: no licence, decryption or tagging).
         if (!searchData && url && url.startsWith('episode:')) {
             const eid = url.slice('episode:'.length).trim();
@@ -486,6 +537,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/index.d.ts

@@ -63,7 +63,7 @@ export type { MBRecording, MBRelease, MBArtistCredit, CoverArt, CoverArtImage }
 export { getTrackBuffer, getTaggedTrack, downloadTrackToFile } from './lib/api-download';
 export type { Quality, GetTrackBufferOptions, DownloadTrackOptions, DownloadResult } from './lib/api-download';
 export { default as Config, globalConfigPath, resolveConfigFile } from './lib/config';
-export { initDeezerApi, parseInfo, searchMusic, searchFacets, searchPublicApi, searchTracks, searchAlbums, searchArtists, searchPlaylists, buildAdvancedQuery, suggest, getGenres, getChart, getChartTracks, getGenreArtists, getEditorialList, getEditorialReleases, getEditorialSelection, getEditorialCharts, getArtistTopTracks, getRelatedArtists, getArtistAlbums, getArtistPlaylists, getArtistRadioTracks, getUserFlow, getUserFavoriteTracks, getUserFavoriteAlbums, getUserFavoriteArtists, getUserPlaylists, getUserRadios, getUserChartTracks, getRadios, getRadioTracks, getRadioGenres, getEpisode, getShowEpisodes, refreshTrackTokens, getTrackByISRC, getAlbumByUPC, getTrackPreview, downloadPreview, formatName, toFormat, DEEZER_FORMATS, getUser, getTrackInfo, getAlbumInfo, getAlbumTracks, getPlaylistInfo, getPlaylistTracks, getArtistInfo, getDiscography, getLyrics, getTrackDownloadUrl, resolveDownloadUrls, streamTrackDownload, downloadTrackBuffer, createDecryptStream, getStream, addTrackTags, getRichAlbum, normalizeContributors, toLrc, GeoBlocked, DeezerError, } from 'gerdur-core';
+export { initDeezerApi, parseInfo, searchMusic, searchFacets, searchPublicApi, searchTracks, searchAlbums, searchArtists, searchPlaylists, buildAdvancedQuery, suggest, getGenres, getChart, getChartTracks, getGenreArtists, getEditorialList, getEditorialReleases, getEditorialSelection, getEditorialCharts, getArtistTopTracks, getRelatedArtists, getArtistAlbums, getArtistPlaylists, getArtistRadioTracks, getUserFlow, getUserFavoriteTracks, getUserFavoriteAlbums, getUserFavoriteArtists, getUserPlaylists, getUserRadios, getUserChartTracks, getRadios, getRadioTracks, getRadioGenres, getEpisode, getShowEpisodes, getMyPlaylists, getMyFavoriteTracks, getMyFavoriteTrackIds, getMyFavoriteAlbums, getMyFavoriteArtists, getMyFavoritePlaylists, getMyFavoriteRadios, getMyFavoriteShows, getTrackMix, refreshTrackTokens, getTrackByISRC, getAlbumByUPC, getTrackPreview, downloadPreview, formatName, toFormat, DEEZER_FORMATS, getUser, getTrackInfo, getAlbumInfo, getAlbumTracks, getPlaylistInfo, getPlaylistTracks, getArtistInfo, getDiscography, getLyrics, getTrackDownloadUrl, resolveDownloadUrls, streamTrackDownload, downloadTrackBuffer, createDecryptStream, getStream, addTrackTags, getRichAlbum, normalizeContributors, toLrc, GeoBlocked, DeezerError, } from 'gerdur-core';
 export type { AddTrackTagsOptions, TaggedTrack, TrackTagModel, RichAlbum, ResolvedUrl, NormalizedContributors, } from 'gerdur-core';
 export type { advancedSearchFilters, searchOrder, searchEntity, publicApiSearchOptions, publicApiSearchResponse, searchResultTrack, searchResultAlbum, searchResultArtist, searchResultPlaylist, suggestResult, publicApiList, chartType, chartTrack, chartAlbum, chartArtist, chartPlaylist, chartPodcast, genreType, editorialType, artistAlbumResult, userFavoriteTrack, userFavoriteAlbum, userFavoriteArtist, userPlaylistResult, radioResult, radioGenre, } from 'gerdur-core/types';
 export type { Quality as MediaFormat, DeezerFormat, TrackPreview, StreamTrackOptions, TrackStream, StreamResponse, DeezerErrorPayload, } from 'gerdur-core';

package/dist/src/index.js

@@ -34,7 +34,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getUserFavoriteAlbums = exports.getUserFavoriteTracks = exports.getUserFlow = exports.getArtistRadioTracks = exports.getArtistPlaylists = exports.getArtistAlbums = exports.getRelatedArtists = exports.getArtistTopTracks = exports.getEditorialCharts = exports.getEditorialSelection = exports.getEditorialReleases = exports.getEditorialList = exports.getGenreArtists = exports.getChartTracks = exports.getChart = exports.getGenres = exports.suggest = exports.buildAdvancedQuery = exports.searchPlaylists = exports.searchArtists = exports.searchAlbums = exports.searchTracks = exports.searchPublicApi = exports.searchFacets = exports.searchMusic = exports.parseInfo = exports.initDeezerApi = exports.resolveConfigFile = exports.globalConfigPath = exports.Config = exports.downloadTrackToFile = exports.getTaggedTrack = exports.getTrackBuffer = exports.PoliteJsonClient = exports.getCoverArtByISRC = exports.getRecordingCoverArt = exports.getBestCoverArtUrl = exports.getCoverArt = exports.getMusicBrainzRelease = exports.getMusicBrainzRecording = exports.lookupRecordingByISRC = exports.configureMusicBrainz = exports.defaultSession = exports.CoreSession = exports.createCoreSession = exports.Session = exports.createSession = exports.getArl = exports.LoginError = exports.loginWithEmail = void 0;
-exports.DeezerError = exports.GeoBlocked = exports.toLrc = exports.normalizeContributors = exports.getRichAlbum = exports.addTrackTags = exports.getStream = exports.createDecryptStream = exports.downloadTrackBuffer = exports.streamTrackDownload = exports.resolveDownloadUrls = exports.getTrackDownloadUrl = exports.getLyrics = exports.getDiscography = exports.getArtistInfo = exports.getPlaylistTracks = exports.getPlaylistInfo = exports.getAlbumTracks = exports.getAlbumInfo = exports.getTrackInfo = exports.getUser = exports.DEEZER_FORMATS = exports.toFormat = exports.formatName = exports.downloadPreview = exports.getTrackPreview = exports.getAlbumByUPC = exports.getTrackByISRC = exports.refreshTrackTokens = exports.getShowEpisodes = exports.getEpisode = exports.getRadioGenres = exports.getRadioTracks = exports.getRadios = exports.getUserChartTracks = exports.getUserRadios = exports.getUserPlaylists = exports.getUserFavoriteArtists = void 0;
+exports.DeezerError = exports.GeoBlocked = exports.toLrc = exports.normalizeContributors = exports.getRichAlbum = exports.addTrackTags = exports.getStream = exports.createDecryptStream = exports.downloadTrackBuffer = exports.streamTrackDownload = exports.resolveDownloadUrls = exports.getTrackDownloadUrl = exports.getLyrics = exports.getDiscography = exports.getArtistInfo = exports.getPlaylistTracks = exports.getPlaylistInfo = exports.getAlbumTracks = exports.getAlbumInfo = exports.getTrackInfo = exports.getUser = exports.DEEZER_FORMATS = exports.toFormat = exports.formatName = exports.downloadPreview = exports.getTrackPreview = exports.getAlbumByUPC = exports.getTrackByISRC = exports.refreshTrackTokens = exports.getTrackMix = exports.getMyFavoriteShows = exports.getMyFavoriteRadios = exports.getMyFavoritePlaylists = exports.getMyFavoriteArtists = exports.getMyFavoriteAlbums = exports.getMyFavoriteTrackIds = exports.getMyFavoriteTracks = exports.getMyPlaylists = exports.getShowEpisodes = exports.getEpisode = exports.getRadioGenres = exports.getRadioTracks = exports.getRadios = exports.getUserChartTracks = exports.getUserRadios = exports.getUserPlaylists = exports.getUserFavoriteArtists = void 0;
 // ─── Authentication ────────────────────────────────────────────────────────
 const email_login_1 = require("./lib/email-login");
 Object.defineProperty(exports, "loginWithEmail", { enumerable: true, get: function () { return email_login_1.loginWithEmail; } });
@@ -142,6 +142,15 @@ Object.defineProperty(exports, "getRadioTracks", { enumerable: true, get: functi
 Object.defineProperty(exports, "getRadioGenres", { enumerable: true, get: function () { return gerdur_core_3.getRadioGenres; } });
 Object.defineProperty(exports, "getEpisode", { enumerable: true, get: function () { return gerdur_core_3.getEpisode; } });
 Object.defineProperty(exports, "getShowEpisodes", { enumerable: true, get: function () { return gerdur_core_3.getShowEpisodes; } });
+Object.defineProperty(exports, "getMyPlaylists", { enumerable: true, get: function () { return gerdur_core_3.getMyPlaylists; } });
+Object.defineProperty(exports, "getMyFavoriteTracks", { enumerable: true, get: function () { return gerdur_core_3.getMyFavoriteTracks; } });
+Object.defineProperty(exports, "getMyFavoriteTrackIds", { enumerable: true, get: function () { return gerdur_core_3.getMyFavoriteTrackIds; } });
+Object.defineProperty(exports, "getMyFavoriteAlbums", { enumerable: true, get: function () { return gerdur_core_3.getMyFavoriteAlbums; } });
+Object.defineProperty(exports, "getMyFavoriteArtists", { enumerable: true, get: function () { return gerdur_core_3.getMyFavoriteArtists; } });
+Object.defineProperty(exports, "getMyFavoritePlaylists", { enumerable: true, get: function () { return gerdur_core_3.getMyFavoritePlaylists; } });
+Object.defineProperty(exports, "getMyFavoriteRadios", { enumerable: true, get: function () { return gerdur_core_3.getMyFavoriteRadios; } });
+Object.defineProperty(exports, "getMyFavoriteShows", { enumerable: true, get: function () { return gerdur_core_3.getMyFavoriteShows; } });
+Object.defineProperty(exports, "getTrackMix", { enumerable: true, get: function () { return gerdur_core_3.getTrackMix; } });
 Object.defineProperty(exports, "refreshTrackTokens", { enumerable: true, get: function () { return gerdur_core_3.refreshTrackTokens; } });
 Object.defineProperty(exports, "getTrackByISRC", { enumerable: true, get: function () { return gerdur_core_3.getTrackByISRC; } });
 Object.defineProperty(exports, "getAlbumByUPC", { enumerable: true, get: function () { return gerdur_core_3.getAlbumByUPC; } });

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

@@ -17,7 +17,7 @@ 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;
@@ -159,6 +159,7 @@ const downloadTrack = async ({ track, quality, info, coverSizes, path, totalTrac
         // 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 } : {}),
         });
         (0, log_update_1.default)(signale_1.default.pending('Saving ' + track.SNG_TITLE + ' by ' + track.ART_NAME));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gerdur",
-  "version": "2.12.0",
+  "version": "2.14.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.15.0",
+    "gerdur-core": "^2.17.0",
     "dot-prop": "^6.0.1",
     "got": "^11.8.6",
     "gradient-string": "^2.0.2",