gerdur 1.0.2 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 2.1.0 - 2026-08-31
+
+### Added
+
+- **`gerdur-core@^2.1.0`** — the new search surface is re-exported from the
+  library: `searchPublicApi`, `searchTracks` / `searchAlbums` / `searchArtists` /
+  `searchPlaylists`, `buildAdvancedQuery`, `suggest`, plus the matching types.
+- **`Session.searchAdvanced(filters, options?)`** — structured search against the
+  public REST API — a free-text query plus `{artist, album, track, label, durMin,
+  durMax, bpmMin, bpmMax}`, with `order` / `limit` / `index`. Returns public-API
+  track objects with `isrc` / `preview`; fetch a hit's gw track with
+  `getTrackInfo(id)` to download.
+- **`Session.suggest(query, nb?)`** — `deezer.suggest` autocomplete.
+
+_No CLI changes in this release — the interactive `gerdur` flow is unchanged._
+
+## 2.0.0 - 2026-08-31
+
+### Changed
+
+- **Metadata is now much richer** (`gerdur-core@^2.0.0`). Every downloaded file
+  gets ReplayGain (`REPLAYGAIN_TRACK_GAIN`), BPM, real `©`/`℗` lines, the true
+  original release date (distinct from a reissue date), full studio credits
+  (featured artists, mastering / mixing / recording engineers, producers),
+  compilation/live flags, iTunes advisory, Deezer ids, and the artist photo as a
+  second embedded image. Album/playlist tracks are hydrated with one coalesced
+  `song.getData` so the credits are complete.
+- **`.lrc` sidecar files** are written next to the audio for tracks with
+  time-synced lyrics. Toggle with `"lyrics": {"lrcFile": false}` in
+  `gerdur.config.json`.
+- Cover-art requests are capped at Deezer's real ceiling of 1800 px.
+
+### Breaking (programmatic API)
+
+- `gerdur-core.addTrackTags` changed signature/return — see its 2.0.0 changelog.
+  `getTrackBuffer` is unaffected (still resolves to `Buffer | null`); new
+  `getTaggedTrack(track, quality, options)` returns `{buffer, model}` with the
+  structured metadata and LRC. `downloadTrackToFile` now also returns `lrcPath`
+  when a sidecar was written.
+
 ## 1.0.1 - 2026-08-30
 
 ### Changed

package/README.md

@@ -175,12 +175,22 @@ await session.downloadUrl('https://deezer.com/album/302127', 'flac', {
 const {tracks} = await session.parseUrl('https://deezer.com/track/3135556');
 const found = await session.search('daft punk', ['TRACK'], 10);
 const results = await session.downloadTracks(tracks, '320', {output: '{ART_NAME} - {SNG_TITLE}'});
+
+// Structured search against the public REST API (isrc / preview / bpm-aware):
+const hits = await session.searchAdvanced(
+  {query: 'one more time', artist: 'daft punk', durMin: 200},
+  {limit: 25, order: 'RANKING'},
+);
+const suggestions = await session.suggest('daft'); // autocomplete
 ```
 
-Session methods: `parseUrl`, `search`, `getUser`, `getTrackBuffer`, `downloadTrack`,
-`downloadTracks`, `downloadUrl`. Every download call is silent; `downloadTracks` /
-`downloadUrl` accept `concurrency` and an `onProgress` callback and return one
-`{path, written} | null` per track.
+Session methods: `parseUrl`, `search`, `searchAdvanced`, `suggest`, `getUser`,
+`getTrackBuffer`, `downloadTrack`, `downloadTracks`, `downloadUrl`. Every download
+call is silent; `downloadTracks` / `downloadUrl` accept `concurrency` and an
+`onProgress` callback and return one `{path, written} | null` per track.
+
+`searchAdvanced` returns public-API track objects; fetch a hit's gw track with
+`getTrackInfo(id)` before downloading it.
 
 ### Low-level: primitives
 
@@ -204,9 +214,11 @@ const {path, written} = (await downloadTrackToFile(track, 'flac', {output: '{ART
 So you don't need `gerdur-core` as a second dependency (call after `initDeezerApi`
 or `createSession`):
 
-`parseInfo`, `searchMusic`, `getUser`, `getTrackInfo`, `getAlbumInfo`, `getAlbumTracks`,
-`getPlaylistInfo`, `getPlaylistTracks`, `getArtistInfo`, `getDiscography`, `getLyrics`,
-`getTrackDownloadUrl`, `GeoBlocked`.
+`parseInfo`, `searchMusic`, `searchPublicApi`, `searchTracks`, `searchAlbums`,
+`searchArtists`, `searchPlaylists`, `buildAdvancedQuery`, `suggest`, `getUser`,
+`getTrackInfo`, `getAlbumInfo`, `getAlbumTracks`, `getPlaylistInfo`,
+`getPlaylistTracks`, `getArtistInfo`, `getDiscography`, `getLyrics`,
+`getTrackDownloadUrl`, `resolveDownloadUrls`, `GeoBlocked`.
 
 ### Auth & config helpers
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "gerdur",
-    "version": "1.0.2",
+    "version": "2.1.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": "^1.0.4",
+        "gerdur-core": "^2.1.0",
         "dot-prop": "^6.0.1",
         "got": "^11.8.6",
         "gradient-string": "^2.0.2",

package/dist/src/gerdur.js

@@ -215,6 +215,7 @@ const startDownload = async (saveLayout, url, skipPrompt) => {
             const trackNumber = conf.get('trackNumber', true);
             const fallbackTrack = conf.get('fallbackTrack', true);
             const fallbackQuality = conf.get('fallbackQuality', true);
+            const lrc = conf.get('lyrics.lrcFile', true);
             const overwrite = options.overwrite ?? conf.get('overwrite', false);
             const resolveFullPath = options.resolveFullPath ?? conf.get('playlist.resolveFullPath');
             const savedFiles = [];
@@ -259,6 +260,7 @@ const startDownload = async (saveLayout, url, skipPrompt) => {
                         fallbackQuality,
                         overwrite,
                         message: `(${index}/${data.tracks.length})`,
+                        lrc,
                         prefetched: prefetchedUrls.get(track.SNG_ID) ?? null,
                     });
                     // Add to saved list

package/dist/src/index.d.ts

@@ -56,7 +56,9 @@ export declare class LoginError extends Error {
 export declare const getArl: (email: string, password: string) => Promise<string>;
 export { createSession, Session } from './lib/session';
 export type { SessionOptions, DownloadTracksOptions, SearchType } from './lib/session';
-export { getTrackBuffer, downloadTrackToFile } from './lib/api-download';
+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, getUser, getTrackInfo, getAlbumInfo, getAlbumTracks, getPlaylistInfo, getPlaylistTracks, getArtistInfo, getDiscography, getLyrics, getTrackDownloadUrl, GeoBlocked, } from 'gerdur-core';
+export { initDeezerApi, parseInfo, searchMusic, searchPublicApi, searchTracks, searchAlbums, searchArtists, searchPlaylists, buildAdvancedQuery, suggest, getUser, getTrackInfo, getAlbumInfo, getAlbumTracks, getPlaylistInfo, getPlaylistTracks, getArtistInfo, getDiscography, getLyrics, getTrackDownloadUrl, resolveDownloadUrls, addTrackTags, getRichAlbum, normalizeContributors, toLrc, GeoBlocked, } 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, } from 'gerdur-core/types';

package/dist/src/index.js

@@ -33,7 +33,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GeoBlocked = exports.getTrackDownloadUrl = exports.getLyrics = exports.getDiscography = exports.getArtistInfo = exports.getPlaylistTracks = exports.getPlaylistInfo = exports.getAlbumTracks = exports.getAlbumInfo = exports.getTrackInfo = exports.getUser = exports.searchMusic = exports.parseInfo = exports.initDeezerApi = exports.resolveConfigFile = exports.globalConfigPath = exports.Config = exports.downloadTrackToFile = 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 = exports.getLyrics = exports.getDiscography = exports.getArtistInfo = exports.getPlaylistTracks = exports.getPlaylistInfo = exports.getAlbumTracks = exports.getAlbumInfo = exports.getTrackInfo = exports.getUser = 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;
 // ─── Authentication ────────────────────────────────────────────────────────
 const email_login_1 = require("./lib/email-login");
 Object.defineProperty(exports, "loginWithEmail", { enumerable: true, get: function () { return email_login_1.loginWithEmail; } });
@@ -74,6 +74,7 @@ Object.defineProperty(exports, "Session", { enumerable: true, get: function () {
 // ─── Download primitives ─────────────────────────────────────────────────────
 var api_download_1 = require("./lib/api-download");
 Object.defineProperty(exports, "getTrackBuffer", { enumerable: true, get: function () { return api_download_1.getTrackBuffer; } });
+Object.defineProperty(exports, "getTaggedTrack", { enumerable: true, get: function () { return api_download_1.getTaggedTrack; } });
 Object.defineProperty(exports, "downloadTrackToFile", { enumerable: true, get: function () { return api_download_1.downloadTrackToFile; } });
 // ─── Config ──────────────────────────────────────────────────────────────────
 // The same config the CLI uses (env var, global path resolution, arl storage).
@@ -88,6 +89,13 @@ var gerdur_core_1 = require("gerdur-core");
 Object.defineProperty(exports, "initDeezerApi", { enumerable: true, get: function () { return gerdur_core_1.initDeezerApi; } });
 Object.defineProperty(exports, "parseInfo", { enumerable: true, get: function () { return gerdur_core_1.parseInfo; } });
 Object.defineProperty(exports, "searchMusic", { enumerable: true, get: function () { return gerdur_core_1.searchMusic; } });
+Object.defineProperty(exports, "searchPublicApi", { enumerable: true, get: function () { return gerdur_core_1.searchPublicApi; } });
+Object.defineProperty(exports, "searchTracks", { enumerable: true, get: function () { return gerdur_core_1.searchTracks; } });
+Object.defineProperty(exports, "searchAlbums", { enumerable: true, get: function () { return gerdur_core_1.searchAlbums; } });
+Object.defineProperty(exports, "searchArtists", { enumerable: true, get: function () { return gerdur_core_1.searchArtists; } });
+Object.defineProperty(exports, "searchPlaylists", { enumerable: true, get: function () { return gerdur_core_1.searchPlaylists; } });
+Object.defineProperty(exports, "buildAdvancedQuery", { enumerable: true, get: function () { return gerdur_core_1.buildAdvancedQuery; } });
+Object.defineProperty(exports, "suggest", { enumerable: true, get: function () { return gerdur_core_1.suggest; } });
 Object.defineProperty(exports, "getUser", { enumerable: true, get: function () { return gerdur_core_1.getUser; } });
 Object.defineProperty(exports, "getTrackInfo", { enumerable: true, get: function () { return gerdur_core_1.getTrackInfo; } });
 Object.defineProperty(exports, "getAlbumInfo", { enumerable: true, get: function () { return gerdur_core_1.getAlbumInfo; } });
@@ -98,4 +106,9 @@ Object.defineProperty(exports, "getArtistInfo", { enumerable: true, get: functio
 Object.defineProperty(exports, "getDiscography", { enumerable: true, get: function () { return gerdur_core_1.getDiscography; } });
 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, "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; } });

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

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+import type { AddTrackTagsOptions } from 'gerdur-core';
 import type { trackType } from 'gerdur-core/types';
 /** Music quality accepted by the API. */
 export type Quality = '128' | '320' | 'flac' | 1 | 3 | 9;
@@ -10,18 +11,30 @@ export interface GetTrackBufferOptions {
      * before giving up. Default true.
      */
     fallbackQuality?: boolean;
+    /**
+     * Extra metadata-writer options passed straight to `gerdur-core.addTrackTags`
+     * (e.g. `{embedArtistImage: false, richCredits: false}`). `coverSize` above
+     * wins over `metadata.coverSize`.
+     */
+    metadata?: AddTrackTagsOptions;
 }
 /**
  * Download, decrypt, and tag a single track entirely in memory.
  *
  * Returns the ready-to-write audio Buffer (MP3 or FLAC), or `null` if the track
  * is not available for download. Nothing is written to disk and nothing is
- * logged.
+ * logged. Use `getTaggedTrack` if you also want the structured metadata / LRC.
  *
  * @param track Track info (e.g. from `getTrackInfo` or `parseUrl`).
  * @param quality '128' | '320' | 'flac' (or numeric 1 | 3 | 9).
  */
-export declare const getTrackBuffer: (track: trackType, quality?: Quality, { coverSize, fallbackQuality }?: GetTrackBufferOptions) => Promise<Buffer | null>;
+export declare const getTrackBuffer: (track: trackType, quality?: Quality, options?: GetTrackBufferOptions) => Promise<Buffer | null>;
+/**
+ * Like `getTrackBuffer`, but returns `{buffer, model}` — `model` carries every
+ * field gerdur pulled from Deezer, including `model.lyricsSynced` (an LRC
+ * document) when the track has time-synced lyrics.
+ */
+export declare const getTaggedTrack: (track: trackType, quality?: Quality, options?: GetTrackBufferOptions) => Promise<import("gerdur-core").TaggedTrack | null>;
 export interface DownloadTrackOptions extends GetTrackBufferOptions {
     /**
      * Output file path or a `saveLayout` template (e.g. `{ART_NAME} - {SNG_TITLE}`).
@@ -37,12 +50,16 @@ export interface DownloadTrackOptions extends GetTrackBufferOptions {
     trackNumber?: boolean;
     /** Re-download even if the destination file already exists. Default false. */
     overwrite?: boolean;
+    /** Write a `.lrc` sidecar next to the audio when the track has synced lyrics. Default true. */
+    lrc?: boolean;
 }
 export interface DownloadResult {
     /** The path the file was written to (or would have been, if skipped). */
     path: string;
     /** True if the file was written; false if skipped because it already existed. */
     written: boolean;
+    /** Path of the `.lrc` sidecar, if one was written. */
+    lrcPath?: string;
 }
 /**
  * Download a single track to disk (silent). Resolves the destination path from

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

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.downloadTrackToFile = exports.getTrackBuffer = void 0;
+exports.downloadTrackToFile = exports.getTaggedTrack = exports.getTrackBuffer = void 0;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const got_1 = __importDefault(require("got"));
@@ -22,18 +22,12 @@ const resolveQuality = (quality) => {
     const key = String(quality).toLowerCase();
     return QUALITY_MAP[key] ?? QUALITY_MAP['320'];
 };
-/**
- * Download, decrypt, and tag a single track entirely in memory.
- *
- * Returns the ready-to-write audio Buffer (MP3 or FLAC), or `null` if the track
- * is not available for download. Nothing is written to disk and nothing is
- * logged.
- *
- * @param track Track info (e.g. from `getTrackInfo` or `parseUrl`).
- * @param quality '128' | '320' | 'flac' (or numeric 1 | 3 | 9).
- */
-const getTrackBuffer = async (track, quality = '320', { coverSize = 500, fallbackQuality = true } = {}) => {
-    const order = fallbackQuality ? [quality, '320', '128'] : [quality];
+const tagOptions = (o) => ({
+    ...o.metadata,
+    coverSize: o.coverSize ?? o.metadata?.coverSize ?? 500,
+});
+const fetchDecryptTag = async (track, quality, options) => {
+    const order = options.fallbackQuality === false ? [quality] : [quality, '320', '128'];
     const tried = new Set();
     for (const q of order) {
         const { q: qNum } = resolveQuality(q);
@@ -54,13 +48,34 @@ const getTrackBuffer = async (track, quality = '320', { coverSize = 500, fallbac
         if (!trackData) {
             continue;
         }
-        const { body } = await (0, got_1.default)(trackData.trackUrl, { responseType: 'buffer' });
+        const { body } = await (0, got_1.default)(trackData.trackUrl, { responseType: 'buffer', agent: { http: gerdur_core_1.httpAgent, https: gerdur_core_1.httpsAgent } });
         const decrypted = trackData.isEncrypted ? (0, decrypt_1.decryptDownload)(body, track.SNG_ID) : body;
-        return (0, gerdur_core_1.addTrackTags)(decrypted, track, coverSize);
+        return (0, gerdur_core_1.addTrackTags)(decrypted, track, tagOptions(options));
     }
     return null;
 };
+/**
+ * Download, decrypt, and tag a single track entirely in memory.
+ *
+ * Returns the ready-to-write audio Buffer (MP3 or FLAC), or `null` if the track
+ * is not available for download. Nothing is written to disk and nothing is
+ * logged. Use `getTaggedTrack` if you also want the structured metadata / LRC.
+ *
+ * @param track Track info (e.g. from `getTrackInfo` or `parseUrl`).
+ * @param quality '128' | '320' | 'flac' (or numeric 1 | 3 | 9).
+ */
+const getTrackBuffer = async (track, quality = '320', options = {}) => {
+    const tagged = await fetchDecryptTag(track, quality, options);
+    return tagged ? tagged.buffer : null;
+};
 exports.getTrackBuffer = getTrackBuffer;
+/**
+ * Like `getTrackBuffer`, but returns `{buffer, model}` — `model` carries every
+ * field gerdur pulled from Deezer, including `model.lyricsSynced` (an LRC
+ * document) when the track has time-synced lyrics.
+ */
+const getTaggedTrack = (track, quality = '320', options = {}) => fetchDecryptTag(track, quality, options);
+exports.getTaggedTrack = getTaggedTrack;
 /**
  * Download a single track to disk (silent). Resolves the destination path from
  * the `output` template, skips existing files unless `overwrite` is set, and
@@ -75,15 +90,20 @@ const downloadTrackToFile = async (track, quality = '320', options = {}) => {
     if ((0, fs_1.existsSync)(savePath) && !overwrite) {
         return { path: savePath, written: false };
     }
-    const buffer = await (0, exports.getTrackBuffer)(track, quality, options);
-    if (!buffer) {
+    const tagged = await (0, exports.getTaggedTrack)(track, quality, options);
+    if (!tagged) {
         return null;
     }
     const dir = (0, path_1.dirname)(savePath);
     if (dir && !(0, fs_1.existsSync)(dir)) {
         (0, fs_1.mkdirSync)(dir, { recursive: true });
     }
-    (0, fs_1.writeFileSync)(savePath, buffer);
-    return { path: savePath, written: true };
+    (0, fs_1.writeFileSync)(savePath, tagged.buffer);
+    let lrcPath;
+    if (options.lrc !== false && tagged.model.lyricsSynced) {
+        lrcPath = savePath.replace(/\.(mp3|flac)$/i, '.lrc');
+        (0, fs_1.writeFileSync)(lrcPath, tagged.model.lyricsSynced);
+    }
+    return { path: savePath, written: true, lrcPath };
 };
 exports.downloadTrackToFile = downloadTrackToFile;

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

@@ -12,7 +12,7 @@ export declare const globalConfigPath: () => string;
  *   3. the global config path (created on first write)
  */
 export declare const resolveConfigFile: (configFile: string) => string;
-type keysType = 'concurrency' | 'saveLayout' | 'saveLayout.track' | 'saveLayout.album' | 'saveLayout.artist' | 'saveLayout.playlist' | 'playlist.resolveFullPath' | 'trackNumber' | 'fallbackTrack' | 'fallbackQuality' | 'overwrite' | 'coverSize' | 'coverSize.128' | 'coverSize.320' | 'coverSize.flac' | 'cookies.arl' | 'cookies.email' | 'cookies.password';
+type keysType = 'concurrency' | 'saveLayout' | 'saveLayout.track' | 'saveLayout.album' | 'saveLayout.artist' | 'saveLayout.playlist' | 'playlist.resolveFullPath' | 'trackNumber' | 'fallbackTrack' | 'fallbackQuality' | 'overwrite' | 'coverSize' | 'coverSize.128' | 'coverSize.320' | 'coverSize.flac' | 'lyrics.lrcFile' | 'cookies.arl' | 'cookies.email' | 'cookies.password';
 declare class Config {
     userConfigLocation: string | null;
     private configFile;

package/dist/src/lib/config.js

@@ -62,6 +62,9 @@ const defaultConfig = {
         '320': 500,
         flac: 1000,
     },
+    lyrics: {
+        lrcFile: true,
+    },
     cookies: {
         arl: 'c973964816688562722418b5200c1515dffaad15a42643ebf87cc72824a54612ec51c2ad42d566743f9e424c774e98ccae7737770acff59251328e6cd598c7bcac38ca269adf78bfb88ec5bbad6cd800db3c0b88b2af645bb22b99e71de26416',
     },
@@ -94,6 +97,9 @@ class Config {
             if (userConfig.coverSize) {
                 userConfig.coverSize = { ...defaultConfig.coverSize, ...userConfig.coverSize };
             }
+            if (userConfig.lyrics) {
+                userConfig.lyrics = { ...defaultConfig.lyrics, ...userConfig.lyrics };
+            }
             if (userConfig.cookies) {
                 userConfig.cookies = { ...defaultConfig.cookies, ...userConfig.cookies };
             }

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

@@ -19,6 +19,8 @@ interface downloadTrackProps {
     isQualityFallback?: boolean;
     overwrite?: boolean;
     message?: string;
+    /** Write a `.lrc` sidecar for tracks with time-synced lyrics. Default true. */
+    lrc?: 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
@@ -32,5 +34,5 @@ interface downloadTrackProps {
         format: string;
     } | null;
 }
-declare const downloadTrack: ({ track, quality, info, coverSizes, path, totalTracks, trackNumber, fallbackTrack, fallbackQuality, isFallback, isQualityFallback, overwrite, message, prefetched, }: downloadTrackProps) => Promise<string | undefined>;
+declare const downloadTrack: ({ track, quality, info, coverSizes, path, totalTracks, trackNumber, fallbackTrack, fallbackQuality, isFallback, isQualityFallback, overwrite, message, lrc, prefetched, }: downloadTrackProps) => Promise<string | undefined>;
 export default downloadTrack;

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

@@ -18,7 +18,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 = '', 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, 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;
@@ -89,6 +89,7 @@ const downloadTrack = async ({ track, quality, info, coverSizes, path, totalTrac
                     isFallback: true,
                     overwrite,
                     message,
+                    lrc,
                 });
             }
             else if (fallbackQuality && quality !== 1) {
@@ -105,6 +106,7 @@ const downloadTrack = async ({ track, quality, info, coverSizes, path, totalTrac
                     isQualityFallback: true,
                     overwrite,
                     message,
+                    lrc,
                 });
             }
             (0, log_update_1.default)(signale_1.default.warn(`Skipped "${track.SNG_TITLE}", track not available.`));
@@ -149,7 +151,7 @@ const downloadTrack = async ({ track, quality, info, coverSizes, path, totalTrac
             outFile = (0, fs_1.readFileSync)(tmpfile);
         }
         (0, log_update_1.default)(signale_1.default.pending('Tagging ' + track.SNG_TITLE + ' by ' + track.ART_NAME));
-        const trackWithMetadata = await (0, gerdur_core_1.addTrackTags)(outFile, track, coverSize);
+        const { buffer: trackWithMetadata, model } = await (0, gerdur_core_1.addTrackTags)(outFile, track, { coverSize });
         // 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));
@@ -161,6 +163,9 @@ const downloadTrack = async ({ track, quality, info, coverSizes, path, totalTrac
             }
             // Save file to disk
             (0, fs_1.writeFileSync)(savePath, trackWithMetadata);
+            if (lrc !== false && model.lyricsSynced) {
+                (0, fs_1.writeFileSync)(savePath.replace(/\.(mp3|flac)$/i, '.lrc'), model.lyricsSynced);
+            }
         }
         // 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}`));

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

@@ -1,7 +1,7 @@
 /// <reference types="node" />
 import { parseInfo, searchMusic } from 'gerdur-core';
 import type { Quality, DownloadTrackOptions, DownloadResult } from './api-download';
-import type { trackType, userType } from 'gerdur-core/types';
+import type { trackType, userType, advancedSearchFilters, publicApiSearchOptions, publicApiSearchResponse, searchResultTrack, suggestResult } from 'gerdur-core/types';
 /** Search result categories accepted by {@link Session.search}. */
 export type SearchType = 'ALBUM' | 'ARTIST' | 'TRACK' | 'PLAYLIST' | 'RADIO' | 'SHOW' | 'USER' | 'LIVESTREAM' | 'CHANNEL';
 export interface SessionOptions {
@@ -52,6 +52,17 @@ export declare class Session {
     parseUrl(url: string): ReturnType<typeof parseInfo>;
     /** Search Deezer. Defaults to track results. */
     search(query: string, types?: SearchType[], limit?: number): ReturnType<typeof searchMusic>;
+    /**
+     * Search the public REST API with structured filters (`{artist, album, track,
+     * label, durMin, durMax, bpmMin, bpmMax}`) plus a free-text `query`. Returns
+     * public-API track objects (with `isrc`, `preview`); to download a result,
+     * fetch its gw track first with the re-exported `getTrackInfo(id)`.
+     *
+     * Deezer applies the operators loosely — see `buildAdvancedQuery`.
+     */
+    searchAdvanced(filters: advancedSearchFilters, options?: Omit<publicApiSearchOptions, 'type'>): Promise<publicApiSearchResponse<searchResultTrack>>;
+    /** `deezer.suggest` autocomplete — for "as you type" UIs. `nb` caps items per type. */
+    suggest(query: string, nb?: number): Promise<suggestResult>;
     /** Return a fully tagged audio Buffer for a track (nothing written to disk). */
     getTrackBuffer(track: trackType, quality?: Quality, options?: {}): Promise<Buffer | null>;
     /** Download a single track to disk. */

package/dist/src/lib/session.js

@@ -57,6 +57,21 @@ class Session {
     search(query, types = ['TRACK'], limit) {
         return (0, gerdur_core_1.searchMusic)(query, types, limit);
     }
+    /**
+     * Search the public REST API with structured filters (`{artist, album, track,
+     * label, durMin, durMax, bpmMin, bpmMax}`) plus a free-text `query`. Returns
+     * public-API track objects (with `isrc`, `preview`); to download a result,
+     * fetch its gw track first with the re-exported `getTrackInfo(id)`.
+     *
+     * Deezer applies the operators loosely — see `buildAdvancedQuery`.
+     */
+    searchAdvanced(filters, options = {}) {
+        return (0, gerdur_core_1.searchTracks)((0, gerdur_core_1.buildAdvancedQuery)(filters), options);
+    }
+    /** `deezer.suggest` autocomplete — for "as you type" UIs. `nb` caps items per type. */
+    suggest(query, nb) {
+        return (0, gerdur_core_1.suggest)(query, nb);
+    }
     /** Return a fully tagged audio Buffer for a track (nothing written to disk). */
     getTrackBuffer(track, quality = '320', options = {}) {
         return (0, api_download_1.getTrackBuffer)(track, quality, options);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gerdur",
-  "version": "1.0.2",
+  "version": "2.1.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": "^1.0.4",
+    "gerdur-core": "^2.1.0",
     "dot-prop": "^6.0.1",
     "got": "^11.8.6",
     "gradient-string": "^2.0.2",