gerdur 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 2.5.0 - 2026-08-31
+
+### Changed
+
+- **`gerdur-core@^2.5.0`.** Track decryption in the download pipeline is now
+  **streamed** to a temp file (`decryptFileToFile`) instead of read fully into
+  memory twice — peak memory during decrypt drops to ~one 2048-byte stripe.
+- Gateway failures now surface as `DeezerError` (re-exported) with `code` /
+  `keys` / `retryable`, and gateway retries are bounded (no more infinite spin
+  on a persistently failing endpoint).
+
+### Added
+
+- Re-exports: `streamTrackDownload`, `createDecryptStream`, `getStream`,
+  `DeezerError` + the `StreamTrackOptions` / `TrackStream` / `StreamResponse` types.
+- **`Session.streamTrack(track, quality?, options?)`** — download a track as a
+  constant-memory stream of decrypted audio (`{stream, size, startedAt}`),
+  with `onProgress` and `resumeFrom`.
+
 ## 2.4.0 - 2026-08-31
 
 ### Added

package/README.md

@@ -258,13 +258,17 @@ Session methods:
 - **browse** — `genres`, `chart`, `chartTracks`, `editorialSections`,
   `artistTopTracks`, `relatedArtists`, `artistAlbums`, `artistRadio`,
   `trackByISRC`, `albumByUPC`
-- **user / download** — `getUser`, `getTrackBuffer`, `downloadTrack`,
-  `downloadTracks`, `downloadUrl`, `trackPreview`, `downloadPreview`
+- **user / download** — `getUser`, `getTrackBuffer`, `streamTrack`,
+  `downloadTrack`, `downloadTracks`, `downloadUrl`, `trackPreview`, `downloadPreview`
 
 Every download call is silent; `downloadTracks` / `downloadUrl` accept
 `concurrency` and an `onProgress` callback and return one `{path, written} | null`
 per track.
 
+`streamTrack(track, quality?, options?)` returns `{stream, size, startedAt,
+isEncrypted}` — decrypted audio at constant memory, with `onProgress(got, total)`
+and `resumeFrom` (bytes). Pipe `stream` to a file or your own tag muxer.
+
 `searchAdvanced(filters, options?)` builds a Deezer advanced-search query from
 `{query?, artist?, album?, track?, label?, durMin?, durMax?, bpmMin?, bpmMax?}`
 and takes `{order?, strict?, limit?, index?, fallback?}`. Deezer's operators are
@@ -315,8 +319,10 @@ or `createSession`):
   `getEditorialCharts`, `getArtistTopTracks`, `getRelatedArtists`,
   `getArtistAlbums`, `getArtistPlaylists`, `getArtistRadioTracks`,
   `getTrackByISRC`, `getAlbumByUPC`
-- **Download** — `getTrackDownloadUrl`, `resolveDownloadUrls`, `getTrackPreview`,
-  `downloadPreview`, `formatName`, `toFormat`, `DEEZER_FORMATS`, `GeoBlocked`
+- **Download** — `getTrackDownloadUrl`, `resolveDownloadUrls`,
+  `streamTrackDownload`, `createDecryptStream`, `getStream`, `getTrackPreview`,
+  `downloadPreview`, `formatName`, `toFormat`, `DEEZER_FORMATS`
+- **Errors** — `DeezerError` (`code` / `keys` / `retryable`), `GeoBlocked`
 
 ### Auth & config helpers
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "gerdur",
-    "version": "2.4.0",
+    "version": "2.5.0",
     "description": "The crucial streaming module for dabox systems.",
     "author": "Christian",
     "license": "SEE LICENSE IN LICENSE",
@@ -48,7 +48,7 @@
         "adm-zip": "^0.5.16",
         "chalk": "^4.1.2",
         "commander": "^9.5.0",
-        "gerdur-core": "^2.3.0",
+        "gerdur-core": "^2.5.0",
         "dot-prop": "^6.0.1",
         "got": "^11.8.6",
         "gradient-string": "^2.0.2",

package/dist/src/index.d.ts

@@ -59,7 +59,7 @@ export type { SessionOptions, DownloadTracksOptions, SearchType } from './lib/se
 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, searchPublicApi, searchTracks, searchAlbums, searchArtists, searchPlaylists, buildAdvancedQuery, suggest, getGenres, getChart, getChartTracks, getGenreArtists, getEditorialList, getEditorialReleases, getEditorialSelection, getEditorialCharts, getArtistTopTracks, getRelatedArtists, getArtistAlbums, getArtistPlaylists, getArtistRadioTracks, getTrackByISRC, getAlbumByUPC, getTrackPreview, downloadPreview, formatName, toFormat, DEEZER_FORMATS, getUser, getTrackInfo, getAlbumInfo, getAlbumTracks, getPlaylistInfo, getPlaylistTracks, getArtistInfo, getDiscography, getLyrics, getTrackDownloadUrl, resolveDownloadUrls, addTrackTags, getRichAlbum, normalizeContributors, toLrc, GeoBlocked, } from 'gerdur-core';
+export { initDeezerApi, parseInfo, searchMusic, searchPublicApi, searchTracks, searchAlbums, searchArtists, searchPlaylists, buildAdvancedQuery, suggest, getGenres, getChart, getChartTracks, getGenreArtists, getEditorialList, getEditorialReleases, getEditorialSelection, getEditorialCharts, getArtistTopTracks, getRelatedArtists, getArtistAlbums, getArtistPlaylists, getArtistRadioTracks, getTrackByISRC, getAlbumByUPC, getTrackPreview, downloadPreview, formatName, toFormat, DEEZER_FORMATS, getUser, getTrackInfo, getAlbumInfo, getAlbumTracks, getPlaylistInfo, getPlaylistTracks, getArtistInfo, getDiscography, getLyrics, getTrackDownloadUrl, resolveDownloadUrls, streamTrackDownload, 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, } from 'gerdur-core/types';
-export type { Quality as MediaFormat, DeezerFormat, TrackPreview } from 'gerdur-core';
+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.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.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.searchMusic = exports.parseInfo = exports.initDeezerApi = exports.resolveConfigFile = exports.globalConfigPath = exports.Config = exports.downloadTrackToFile = exports.getTaggedTrack = exports.getTrackBuffer = exports.Session = exports.createSession = exports.getArl = exports.LoginError = exports.loginWithEmail = void 0;
-exports.GeoBlocked = exports.toLrc = exports.normalizeContributors = exports.getRichAlbum = exports.addTrackTags = exports.resolveDownloadUrls = exports.getTrackDownloadUrl = void 0;
+exports.DeezerError = exports.GeoBlocked = exports.toLrc = exports.normalizeContributors = exports.getRichAlbum = exports.addTrackTags = exports.getStream = exports.createDecryptStream = exports.streamTrackDownload = exports.resolveDownloadUrls = exports.getTrackDownloadUrl = void 0;
 // ─── Authentication ────────────────────────────────────────────────────────
 const email_login_1 = require("./lib/email-login");
 Object.defineProperty(exports, "loginWithEmail", { enumerable: true, get: function () { return email_login_1.loginWithEmail; } });
@@ -128,8 +128,12 @@ Object.defineProperty(exports, "getDiscography", { enumerable: true, get: functi
 Object.defineProperty(exports, "getLyrics", { enumerable: true, get: function () { return gerdur_core_1.getLyrics; } });
 Object.defineProperty(exports, "getTrackDownloadUrl", { enumerable: true, get: function () { return gerdur_core_1.getTrackDownloadUrl; } });
 Object.defineProperty(exports, "resolveDownloadUrls", { enumerable: true, get: function () { return gerdur_core_1.resolveDownloadUrls; } });
+Object.defineProperty(exports, "streamTrackDownload", { enumerable: true, get: function () { return gerdur_core_1.streamTrackDownload; } });
+Object.defineProperty(exports, "createDecryptStream", { enumerable: true, get: function () { return gerdur_core_1.createDecryptStream; } });
+Object.defineProperty(exports, "getStream", { enumerable: true, get: function () { return gerdur_core_1.getStream; } });
 Object.defineProperty(exports, "addTrackTags", { enumerable: true, get: function () { return gerdur_core_1.addTrackTags; } });
 Object.defineProperty(exports, "getRichAlbum", { enumerable: true, get: function () { return gerdur_core_1.getRichAlbum; } });
 Object.defineProperty(exports, "normalizeContributors", { enumerable: true, get: function () { return gerdur_core_1.normalizeContributors; } });
 Object.defineProperty(exports, "toLrc", { enumerable: true, get: function () { return gerdur_core_1.toLrc; } });
 Object.defineProperty(exports, "GeoBlocked", { enumerable: true, get: function () { return gerdur_core_1.GeoBlocked; } });
+Object.defineProperty(exports, "DeezerError", { enumerable: true, get: function () { return gerdur_core_1.DeezerError; } });

package/dist/src/lib/decrypt.d.ts

@@ -1,4 +1,9 @@
 /// <reference types="node" />
-export { decryptDownload, TrackDecryptStream } from 'gerdur-core';
-/** Decrypt a track that was streamed to a temp file. */
+export { decryptDownload, createDecryptStream, TrackDecryptStream } from 'gerdur-core';
+/** Decrypt a track that was streamed to a temp file (buffered — reads the file into memory). */
 export declare const decryptDownloadFile: (tmpfile: string, trackId: string) => Buffer;
+/**
+ * Decrypt `src` → `dest` as a stream — peak memory is ~one 2048-byte stripe,
+ * not the whole file twice. Use this over `decryptDownloadFile` for large FLACs.
+ */
+export declare const decryptFileToFile: (src: string, dest: string, trackId: string) => Promise<void>;

package/dist/src/lib/decrypt.js

@@ -1,17 +1,30 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.decryptDownloadFile = exports.TrackDecryptStream = exports.decryptDownload = void 0;
+exports.decryptFileToFile = exports.decryptDownloadFile = exports.TrackDecryptStream = exports.createDecryptStream = exports.decryptDownload = void 0;
 /**
  * Track decryption. As of gerdur-core@1.0.2 the core `decryptDownload` is a
  * correct, dependency-free Blowfish that works on every Node (it no longer
  * touches OpenSSL's removed `bf-cbc`), at ~290 MiB/s — so there is nothing left
  * to wrap or fall back to here.
  */
+const stream_1 = __importDefault(require("stream"));
+const util_1 = require("util");
 const fs_1 = require("fs");
 const gerdur_core_1 = require("gerdur-core");
 var gerdur_core_2 = require("gerdur-core");
 Object.defineProperty(exports, "decryptDownload", { enumerable: true, get: function () { return gerdur_core_2.decryptDownload; } });
+Object.defineProperty(exports, "createDecryptStream", { enumerable: true, get: function () { return gerdur_core_2.createDecryptStream; } });
 Object.defineProperty(exports, "TrackDecryptStream", { enumerable: true, get: function () { return gerdur_core_2.TrackDecryptStream; } });
-/** Decrypt a track that was streamed to a temp file. */
+const pipeline = (0, util_1.promisify)(stream_1.default.pipeline);
+/** Decrypt a track that was streamed to a temp file (buffered — reads the file into memory). */
 const decryptDownloadFile = (tmpfile, trackId) => (0, gerdur_core_1.decryptDownload)((0, fs_1.readFileSync)(tmpfile), trackId);
 exports.decryptDownloadFile = decryptDownloadFile;
+/**
+ * Decrypt `src` → `dest` as a stream — peak memory is ~one 2048-byte stripe,
+ * not the whole file twice. Use this over `decryptDownloadFile` for large FLACs.
+ */
+const decryptFileToFile = (src, dest, trackId) => pipeline((0, fs_1.createReadStream)(src), (0, gerdur_core_1.createDecryptStream)(trackId), (0, fs_1.createWriteStream)(dest));
+exports.decryptFileToFile = decryptFileToFile;

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

@@ -145,7 +145,10 @@ const downloadTrack = async ({ track, quality, info, coverSizes, path, totalTrac
         let outFile;
         if (trackData.isEncrypted) {
             (0, log_update_1.default)(signale_1.default.pending('Decrypting ' + track.SNG_TITLE + ' by ' + track.ART_NAME));
-            outFile = await (0, decrypt_1.decryptDownloadFile)(tmpfile, track.SNG_ID);
+            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);

package/dist/src/lib/session.d.ts

@@ -3,7 +3,7 @@ import { parseInfo, searchMusic } from 'gerdur-core';
 import type { AdvancedSearchOptions } from './search';
 import type { Quality, DownloadTrackOptions, DownloadResult } from './api-download';
 import type { trackType, userType, advancedSearchFilters, publicApiSearchResponse, searchResultTrack, suggestResult, chartType, genreType, editorialType, artistAlbumResult, searchResultArtist, publicApiList, trackTypePublicApi, albumTypePublicApi } from 'gerdur-core/types';
-import type { TrackPreview } from 'gerdur-core';
+import type { TrackPreview, StreamTrackOptions, TrackStream } from 'gerdur-core';
 /** Search result categories accepted by {@link Session.search}. */
 export type SearchType = 'ALBUM' | 'ARTIST' | 'TRACK' | 'PLAYLIST' | 'RADIO' | 'SHOW' | 'USER' | 'LIVESTREAM' | 'CHANNEL';
 export interface SessionOptions {
@@ -92,6 +92,13 @@ export declare class Session {
     downloadPreview(track: trackType | string | number): Promise<Buffer | null>;
     /** Return a fully tagged audio Buffer for a track (nothing written to disk). */
     getTrackBuffer(track: trackType, quality?: Quality, options?: {}): Promise<Buffer | null>;
+    /**
+     * Download a track as a **stream** of decrypted audio — constant memory,
+     * regardless of file size or concurrency. `{stream, size, startedAt,
+     * isEncrypted}`; pipe `stream` to a file or your own tag muxer.
+     * `options.onProgress(received, total)`, `options.resumeFrom` (bytes).
+     */
+    streamTrack(track: trackType, quality?: 1 | 3 | 9, options?: StreamTrackOptions): Promise<TrackStream>;
     /** Download a single track to disk. */
     downloadTrack(track: trackType, quality?: Quality, options?: DownloadTrackOptions): Promise<DownloadResult | null>;
     /**

package/dist/src/lib/session.js

@@ -128,6 +128,15 @@ class Session {
     getTrackBuffer(track, quality = '320', options = {}) {
         return (0, api_download_1.getTrackBuffer)(track, quality, options);
     }
+    /**
+     * Download a track as a **stream** of decrypted audio — constant memory,
+     * regardless of file size or concurrency. `{stream, size, startedAt,
+     * isEncrypted}`; pipe `stream` to a file or your own tag muxer.
+     * `options.onProgress(received, total)`, `options.resumeFrom` (bytes).
+     */
+    streamTrack(track, quality = 3, options = {}) {
+        return (0, gerdur_core_1.streamTrackDownload)(track, quality, options);
+    }
     /** Download a single track to disk. */
     downloadTrack(track, quality = '320', options = {}) {
         return (0, api_download_1.downloadTrackToFile)(track, quality, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gerdur",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "The crucial streaming module for dabox systems.",
   "author": "Christian",
   "license": "SEE LICENSE IN LICENSE",
@@ -48,7 +48,7 @@
     "adm-zip": "^0.5.16",
     "chalk": "^4.1.2",
     "commander": "^9.5.0",
-    "gerdur-core": "^2.3.0",
+    "gerdur-core": "^2.5.0",
     "dot-prop": "^6.0.1",
     "got": "^11.8.6",
     "gradient-string": "^2.0.2",