gerdur-core 1.0.4 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # Changelog
 
+## 2.1.0 - 2026-08-31
+
+Phase 2.5 — search, properly. All additive.
+
+### Added
+
+- **`searchPublicApi(query, options?)`** — search the public REST API
+  (`api.deezer.com/search`) rather than the internal `pageSearch` gateway.
+  Returns clean public-API objects (`isrc`, `preview`, `rank`, numeric ids) and
+  takes `type` (`track` | `album` | `artist` | `playlist` | `user` | `radio` |
+  `podcast`), `order`, `strict`, and `limit` / `index` paging. No auth required.
+- **`searchTracks` / `searchAlbums` / `searchArtists` / `searchPlaylists`** —
+  thin typed wrappers over `searchPublicApi` with the entity fixed.
+- **`buildAdvancedQuery(filters)`** — pure helper that composes Deezer's advanced
+  operators into one query string: `{artist, album, track, label}` →
+  `artist:"…"`, `{durMin, durMax, bpmMin, bpmMax}` → `dur_min:NNN` / `bpm_min:NNN`,
+  free-text `query` first. Reliable on the track index only (Deezer's
+  `/search/album` and `/search/artist` ignore the operators).
+- **`suggest(query, nb?)`** — the `deezer.suggest` autocomplete endpoint, for
+  "as you type" UIs; cheaper than a full `searchMusic`.
+- New exported types: `advancedSearchFilters`, `searchOrder`, `searchEntity`,
+  `publicApiSearchOptions`, `publicApiSearchResponse<T>`, `searchResultTrack`,
+  `searchResultAlbum`, `searchResultArtist`, `searchResultPlaylist`,
+  `suggestResult`.
+
+### Fixed
+
+- **`getPlaylistChannel`** returned `MISSING_PARAMETER_PAGE` — the nested
+  `gateway_input` was serialised as `[object Object]`. It is now JSON-stringified
+  before the request, so channel pages resolve again.
+
+## 2.0.0 - 2026-08-31
+
+Metadata overhaul — extract everything Deezer actually exposes for a track.
+
+### Breaking
+
+- **`addTrackTags(buffer, track, options)`** — the third argument is now an
+  options object, not a cover-size number, and it resolves to
+  **`{buffer, model}`** instead of a bare `Buffer`. Migrate:
+  `await addTrackTags(buf, track, 500)` → `(await addTrackTags(buf, track, {coverSize: 500})).buffer`.
+  `model` is the full `TrackTagModel` (all resolved fields + `model.lyricsSynced`,
+  an LRC document).
+- `writeMetadataMp3` / `writeMetadataFlac` now take the `TrackTagModel`, not a
+  raw track + public-album payload.
+- `downloadAlbumCover` clamps its size to Deezer's real ceiling of **1800**
+  (was unbounded); `coverSize` is re-exported from here.
+
+### Added
+
+- **ReplayGain** — `GAIN` (present on every `song.getData`) is written as
+  `REPLAYGAIN_TRACK_GAIN` (`TXXX` on MP3, Vorbis comment on FLAC).
+- **Rich credits** via `normalizeContributors()` — `SNG_CONTRIBUTORS` has
+  inconsistent keys across the catalogue (`main_artist` / `mainartist` / `artist`,
+  `music publisher` with a space, …); this normalises them and surfaces
+  `featuring`, mastering / mixing / recording engineers, producers, mixers,
+  performers.
+- **Featured artists** from `SNG_CONTRIBUTORS.featuring` → `TXXX:FEATURING` /
+  `FEATURING`, plus a combined `ARTISTS` tag.
+- **Original release date** — `getRichAlbum()` merges gw `album.getData`
+  (`ORIGINAL_RELEASE_DATE`, `COPYRIGHT`/`PRODUCER_LINE`, `NUMBER_DISK`,
+  `SUBTYPES`) with the public `/album/` (label, genres, record type). Writes
+  `ORIGINALDATE`/`ORIGINALYEAR` distinct from the reissue `DATE`.
+- **BPM** from the public `/track/` endpoint (`TBPM` + precise `TXXX:BPM`).
+- **Synced lyrics** — `toLrc()` renders `LYRICS_SYNC_JSON` (already fetched with
+  the plain lyrics) as an LRC document, exposed on `model.lyricsSynced` and
+  embedded in FLAC `LYRICS`.
+- Real `©` / `℗` lines, disc totals, compilation/live flags from `SUBTYPES`,
+  proper `EXPLICIT_LYRICS_STATUS` enum handling (`1`/`4` = explicit; `2`/`6` =
+  unknown, not "explicit"), `iTunesAdvisory`, Deezer track/album/artist/label/
+  provider ids, `URL_REWRITING` slug, popularity rank, and the artist photo as a
+  second embedded picture.
+- New exports: `getRichAlbum`, `RichAlbum`, `normalizeContributors`,
+  `NormalizedContributors`, `toLrc`, `buildTagModel`, `TrackTagModel`, `Person`,
+  `AddTrackTagsOptions`, `TaggedTrack`, `downloadArtistImage`, `MAX_COVER_SIZE`.
+
+### Changed
+
+- Album/playlist tracks (which come without `SNG_CONTRIBUTORS` / `VERSION` /
+  `GAIN`) are transparently hydrated with one coalesced `song.getData` before
+  tagging. Disable via `addTrackTags(…, {richCredits: false})`.
+
 ## 1.0.4 - 2026-08-31
 
 ### Added

package/README.md

@@ -68,11 +68,14 @@ const data = await downloadBuffer(trackData.trackUrl);
 // Decrypt track if needed
 const outFile = trackData.isEncrypted ? api.decryptDownload(data, track.SNG_ID) : data;
 
-// Add id3 metadata
-const trackWithMetadata = await api.addTrackTags(outFile, track, 500);
+// Add metadata — resolves album info, credits, lyrics and cover from Deezer
+const {buffer, model} = await api.addTrackTags(outFile, track, {coverSize: 500});
 
 // Save file to disk
-fs.writeFileSync(track.SNG_TITLE + '.mp3', trackWithMetadata);
+fs.writeFileSync(track.SNG_TITLE + '.mp3', buffer);
+
+// Time-synced lyrics, when Deezer has them, come back as an LRC document
+if (model.lyricsSynced) fs.writeFileSync(track.SNG_TITLE + '.lrc', model.lyricsSynced);
 ```
 
 ### [Read FAQ](docs/faq.md)
@@ -159,6 +162,40 @@ All method returns `Object` or throws `Error`. Make sure to catch error on your
 | `types`    |    No    |  `array` | ['TRACK'] |           array of search types |
 | `limit`    |    No    | `number` |        15 | maximum item to fetch per types |
 
+### `.searchPublicApi(query, options?)` — and `.searchTracks` / `.searchAlbums` / `.searchArtists` / `.searchPlaylists`
+
+Hits the **public** REST API (`api.deezer.com/search`) instead of the internal
+`pageSearch` gateway. Returns clean public-API objects (`isrc`, `preview`,
+`rank`, numeric ids), accepts the advanced query operators, an `order`, and
+`limit` / `index` paging. No auth required.
+
+| Parameters       | Required | Type      | Description                                                                   |
+| ---------------- | :------: | --------- | --------------------------------------------------------------------------- |
+| `query`          | Yes      | `string`  | plain text, or the output of `buildAdvancedQuery`                            |
+| `options.type`   | No       | `string`  | `'track'` (default), `'album'`, `'artist'`, `'playlist'`, `'user'`, `'radio'` |
+| `options.order`  | No       | `string`  | `RANKING`, `TRACK_ASC`, `RATING_DESC`, `DURATION_DESC`, …                    |
+| `options.strict` | No       | `boolean` | send Deezer's `strict=on` (disables the fuzzy fallback)                     |
+| `options.limit`  | No       | `number`  | page size (Deezer caps near 100)                                            |
+| `options.index`  | No       | `number`  | offset into the result set                                                  |
+
+```js
+const {data} = await searchTracks(buildAdvancedQuery({artist: 'daft punk', durMin: 200}), {limit: 25});
+```
+
+### `.buildAdvancedQuery(filters)`
+
+Pure helper — composes Deezer's advanced operators into one query string.
+`{artist, album, track, label}` become `artist:"…"`; `{durMin, durMax, bpmMin, bpmMax}`
+become `dur_min:NNN` / `bpm_min:NNN`; a free-text `query` is emitted first.
+Reliable only on the **track** index — `/search/album` and `/search/artist`
+ignore the operators, so pass a plain string there.
+
+### `.suggest(query, nb?)`
+
+`deezer.suggest` autocomplete — cheaper and faster than `searchMusic`, for
+"as you type" UIs. `nb` (default 5) caps items per type. Needs an initialised
+session (`initDeezerApi`).
+
 ### `.getTrackDownloadUrl(track, quality);`
 
 | Parameters | Required |        Type |                        Description |
@@ -173,13 +210,18 @@ All method returns `Object` or throws `Error`. Make sure to catch error on your
 | `data`     |   Yes    | `buffer` | downloaded song buffer |
 | `song_id`  |   Yes    | `string` |               track id |
 
-### `.addTrackTags(data, track,coverSize)`
+### `.addTrackTags(data, track, options?)`
+
+Resolves album info, credits, lyrics and artwork from Deezer and writes them into
+the audio (ID3v2.3 for MP3, Vorbis comments for FLAC). Returns
+`{buffer, model}` — `model` is the full `TrackTagModel`, including
+`model.lyricsSynced` (an LRC document) when the track has time-synced lyrics.
 
-| Parameters  | Required |      Type |            Description |
-| ----------- | :------: | --------: | ---------------------: |
-| `data`      |   Yes    |  `buffer` | downloaded song buffer |
-| `track`     |   Yes    |  `string` |           track object |
-| `coverSize` |    No    | `56-1800` |         cover art size |
+| Parameters | Required |     Type | Description                                    |
+| ---------- | :------: | -------: | --------------------------------------------- |
+| `data`     |   Yes    | `buffer` | downloaded, decrypted song buffer             |
+| `track`    |   Yes    | `object` | track object from `getTrackInfo` / `parseInfo` |
+| `options`  |    No    | `object` | `AddTrackTagsOptions` — `coverSize` (56–1800), pre-fetched `album`/`lyrics`/`cover`, and toggles (`richCredits`, `embedArtistImage`, `deezerIds`, …) |
 
 ###
 

package/dist/api/api.js

@@ -177,6 +177,9 @@ const getPlaylistChannel = async (page) => {
         lang: 'en',
         timezone_offset: '6',
     };
-    return await (0, request_1.requestGet)('app_page_get', { gateway_input }, page);
+    // `gateway_input` is a nested object; it must reach the gateway as a JSON
+    // string, otherwise it serialises to `[object Object]` and Deezer reports the
+    // inner `page` as missing (`MISSING_PARAMETER_PAGE`).
+    return await (0, request_1.requestGet)('app_page_get', { gateway_input: JSON.stringify(gateway_input) }, page);
 };
 exports.getPlaylistChannel = getPlaylistChannel;

package/dist/api/index.d.ts

@@ -1,2 +1,3 @@
 export * from './api';
 export * from './request';
+export * from './search';

package/dist/api/index.js

@@ -16,3 +16,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./api"), exports);
 __exportStar(require("./request"), exports);
+__exportStar(require("./search"), exports);

package/dist/api/search.d.ts

@@ -0,0 +1,49 @@
+import type { advancedSearchFilters, publicApiSearchOptions, publicApiSearchResponse, searchResultAlbum, searchResultArtist, searchResultPlaylist, searchResultTrack, suggestResult } from '../types';
+/**
+ * Compose Deezer's advanced search operators into one query string.
+ *
+ * ```ts
+ * buildAdvancedQuery({artist: 'daft punk', durMin: 200, durMax: 400});
+ * // => 'artist:"daft punk" dur_min:200 dur_max:400'
+ * ```
+ *
+ * Free-text `query` is emitted first and bare. Deezer treats the operators as
+ * ranking hints rather than hard filters (and honours `track:` only now and
+ * then) — this only builds the string their docs describe. Pair it with
+ * `searchPublicApi(query, {strict: true})` to tighten what Deezer allows.
+ *
+ * The operators are reliable only on the **track** index (`searchPublicApi` /
+ * `searchTracks`). `/search/album` and `/search/artist` ignore or mishandle
+ * `artist:` / `album:` — use a plain string there.
+ */
+export declare const buildAdvancedQuery: (filters: advancedSearchFilters) => string;
+/**
+ * Search the **public** Deezer REST API (`api.deezer.com/search`).
+ *
+ * Unlike `searchMusic` (which drives the internal `deezer.pageSearch` gateway),
+ * this returns clean public-API objects — with `isrc`, `preview`, `rank`, real
+ * numeric ids — and accepts the advanced query operators (see
+ * `buildAdvancedQuery`), an `order`, and `limit` / `index` paging. No auth
+ * required; results are memoised by the api layer.
+ *
+ * @param query a plain string, or the output of `buildAdvancedQuery`
+ * @param options `type` (`'track'` default), `order`, `strict`, `limit`, `index`
+ */
+export declare const searchPublicApi: <T = searchResultTrack>(query: string, options?: publicApiSearchOptions) => Promise<publicApiSearchResponse<T>>;
+/** `searchPublicApi` fixed to tracks. */
+export declare const searchTracks: (query: string, options?: Omit<publicApiSearchOptions, 'type'>) => Promise<publicApiSearchResponse<searchResultTrack>>;
+/** `searchPublicApi` fixed to albums. */
+export declare const searchAlbums: (query: string, options?: Omit<publicApiSearchOptions, 'type'>) => Promise<publicApiSearchResponse<searchResultAlbum>>;
+/** `searchPublicApi` fixed to artists. */
+export declare const searchArtists: (query: string, options?: Omit<publicApiSearchOptions, 'type'>) => Promise<publicApiSearchResponse<searchResultArtist>>;
+/** `searchPublicApi` fixed to playlists. */
+export declare const searchPlaylists: (query: string, options?: Omit<publicApiSearchOptions, 'type'>) => Promise<publicApiSearchResponse<searchResultPlaylist>>;
+/**
+ * `deezer.suggest` — the internal autocomplete endpoint. Cheaper and faster than
+ * a full `searchMusic`, and it powers "as you type" suggestion UIs. Needs an
+ * initialised session (`initDeezerApi`), like every gateway call.
+ *
+ * @param query partial query text
+ * @param nb    max items per type (default 5)
+ */
+export declare const suggest: (query: string, nb?: number) => Promise<suggestResult>;

package/dist/api/search.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.suggest = exports.searchPlaylists = exports.searchArtists = exports.searchAlbums = exports.searchTracks = exports.searchPublicApi = exports.buildAdvancedQuery = void 0;
+const request_1 = require("./request");
+/**
+ * Compose Deezer's advanced search operators into one query string.
+ *
+ * ```ts
+ * buildAdvancedQuery({artist: 'daft punk', durMin: 200, durMax: 400});
+ * // => 'artist:"daft punk" dur_min:200 dur_max:400'
+ * ```
+ *
+ * Free-text `query` is emitted first and bare. Deezer treats the operators as
+ * ranking hints rather than hard filters (and honours `track:` only now and
+ * then) — this only builds the string their docs describe. Pair it with
+ * `searchPublicApi(query, {strict: true})` to tighten what Deezer allows.
+ *
+ * The operators are reliable only on the **track** index (`searchPublicApi` /
+ * `searchTracks`). `/search/album` and `/search/artist` ignore or mishandle
+ * `artist:` / `album:` — use a plain string there.
+ */
+const buildAdvancedQuery = (filters) => {
+    const { query, artist, album, track, label, durMin, durMax, bpmMin, bpmMax } = filters;
+    const parts = [];
+    if (query && query.trim()) {
+        parts.push(query.trim());
+    }
+    const textOps = [
+        ['artist', artist],
+        ['album', album],
+        ['track', track],
+        ['label', label],
+    ];
+    for (const [op, value] of textOps) {
+        if (value && value.trim()) {
+            parts.push(`${op}:"${value.trim().replace(/"/g, '')}"`);
+        }
+    }
+    const rangeOps = [
+        ['dur_min', durMin],
+        ['dur_max', durMax],
+        ['bpm_min', bpmMin],
+        ['bpm_max', bpmMax],
+    ];
+    for (const [op, value] of rangeOps) {
+        if (typeof value === 'number' && Number.isFinite(value) && value >= 0) {
+            parts.push(`${op}:${Math.round(value)}`);
+        }
+    }
+    return parts.join(' ');
+};
+exports.buildAdvancedQuery = buildAdvancedQuery;
+const SEARCH_ENTITIES = ['track', 'album', 'artist', 'playlist', 'user', 'radio', 'podcast'];
+/**
+ * Search the **public** Deezer REST API (`api.deezer.com/search`).
+ *
+ * Unlike `searchMusic` (which drives the internal `deezer.pageSearch` gateway),
+ * this returns clean public-API objects — with `isrc`, `preview`, `rank`, real
+ * numeric ids — and accepts the advanced query operators (see
+ * `buildAdvancedQuery`), an `order`, and `limit` / `index` paging. No auth
+ * required; results are memoised by the api layer.
+ *
+ * @param query a plain string, or the output of `buildAdvancedQuery`
+ * @param options `type` (`'track'` default), `order`, `strict`, `limit`, `index`
+ */
+const searchPublicApi = (query, options = {}) => {
+    const { type, order, strict, limit, index } = options;
+    const segment = type && type !== 'track' && SEARCH_ENTITIES.includes(type) ? `/${type}` : '';
+    const search = new URLSearchParams({ q: query });
+    if (strict) {
+        search.set('strict', 'on');
+    }
+    if (order) {
+        search.set('order', order);
+    }
+    if (typeof limit === 'number') {
+        search.set('limit', String(limit));
+    }
+    if (typeof index === 'number') {
+        search.set('index', String(index));
+    }
+    return (0, request_1.requestPublicApi)(`/search${segment}?${search.toString()}`);
+};
+exports.searchPublicApi = searchPublicApi;
+/** `searchPublicApi` fixed to tracks. */
+const searchTracks = (query, options = {}) => (0, exports.searchPublicApi)(query, { ...options, type: 'track' });
+exports.searchTracks = searchTracks;
+/** `searchPublicApi` fixed to albums. */
+const searchAlbums = (query, options = {}) => (0, exports.searchPublicApi)(query, { ...options, type: 'album' });
+exports.searchAlbums = searchAlbums;
+/** `searchPublicApi` fixed to artists. */
+const searchArtists = (query, options = {}) => (0, exports.searchPublicApi)(query, { ...options, type: 'artist' });
+exports.searchArtists = searchArtists;
+/** `searchPublicApi` fixed to playlists. */
+const searchPlaylists = (query, options = {}) => (0, exports.searchPublicApi)(query, { ...options, type: 'playlist' });
+exports.searchPlaylists = searchPlaylists;
+/**
+ * `deezer.suggest` — the internal autocomplete endpoint. Cheaper and faster than
+ * a full `searchMusic`, and it powers "as you type" suggestion UIs. Needs an
+ * initialised session (`initDeezerApi`), like every gateway call.
+ *
+ * @param query partial query text
+ * @param nb    max items per type (default 5)
+ */
+const suggest = (query, nb = 5) => (0, request_1.requestLight)({
+    QUERY: query,
+    NB: nb,
+    TYPES: { ALBUM: true, ARTIST: true, TRACK: true, PLAYLIST: true, RADIO: true, SHOW: true },
+}, 'deezer.suggest');
+exports.suggest = suggest;

package/dist/lib/metaflac-js.d.ts

@@ -91,7 +91,7 @@ declare class Metaflac {
      *
      * @param {string} filename
      */
-    importPicture(picture: Buffer, dimension: number, mime: 'image/jpeg' | 'image/png'): void;
+    importPicture(picture: Buffer, dimension: number, mime: 'image/jpeg' | 'image/png', type?: number, description?: string): void;
     /**
      * Return all tags.
      */

package/dist/lib/metaflac-js.js

@@ -236,9 +236,11 @@ class Metaflac {
      *
      * @param {string} filename
      */
-    importPicture(picture, dimension, mime) {
+    importPicture(picture, dimension, mime, type = 3, description = '') {
         const spec = this.buildSpecification({
+            type,
             mime,
+            description,
             width: dimension,
             height: dimension,
         });

package/dist/metadata-writer/abumCover.d.ts

@@ -1,10 +1,14 @@
 /// <reference types="node" />
 import type { trackType } from '../types';
-type coverSize = 56 | 250 | 500 | 1000 | 1500 | 1800 | number;
+export type coverSize = 56 | 250 | 500 | 1000 | 1200 | 1500 | 1800 | number;
+export declare const MAX_COVER_SIZE = 1800;
 /**
- *
- * @param {Object} track track info json from deezer api
- * @param {Number} albumCoverSize in pixel, between 56-1800
+ * @param track track info json from deezer api
+ * @param albumCoverSize in pixels, 56–1800 (clamped)
  */
 export declare const downloadAlbumCover: (track: trackType, albumCoverSize: coverSize) => Promise<Buffer | null>;
-export {};
+/**
+ * Artist photo (`ART_PICTURE` md5). Returns null when the track has no artist
+ * image (common for small-catalogue artists).
+ */
+export declare const downloadArtistImage: (track: trackType, size?: coverSize) => Promise<Buffer | null>;

package/dist/metadata-writer/abumCover.js

@@ -3,35 +3,49 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.downloadAlbumCover = void 0;
+exports.downloadArtistImage = exports.downloadAlbumCover = exports.MAX_COVER_SIZE = void 0;
 const fast_lru_1 = __importDefault(require("../lib/fast-lru"));
 const http_1 = require("../lib/http");
+exports.MAX_COVER_SIZE = 1800;
 // expire cache in 30 minutes
 const lru = new fast_lru_1.default({
     maxSize: 50,
     ttl: 30 * 60000,
 });
-/**
- *
- * @param {Object} track track info json from deezer api
- * @param {Number} albumCoverSize in pixel, between 56-1800
- */
-const downloadAlbumCover = async (track, albumCoverSize) => {
-    if (!track.ALB_PICTURE) {
+const clampSize = (n) => Math.max(56, Math.min(exports.MAX_COVER_SIZE, Math.round(n) || 500));
+const imageUrl = (kind, md5, size) => `https://e-cdns-images.dzcdn.net/images/${kind}/${md5}/${size}x${size}-000000-80-0-0.jpg`;
+const fetchImage = async (kind, md5, size) => {
+    if (!md5) {
         return null;
     }
-    const cache = lru.get(track.ALB_PICTURE + albumCoverSize);
-    if (cache) {
-        return cache;
+    const px = clampSize(size);
+    const key = `${kind}:${md5}:${px}`;
+    const cached = lru.get(key);
+    if (cached) {
+        return cached;
     }
     try {
-        const url = `https://e-cdns-images.dzcdn.net/images/cover/${track.ALB_PICTURE}/${albumCoverSize}x${albumCoverSize}-000000-80-0-0.jpg`;
-        const data = await (0, http_1.getBuffer)(url);
-        lru.set(track.ALB_PICTURE + albumCoverSize, data);
+        const data = await (0, http_1.getBuffer)(imageUrl(kind, md5, px));
+        lru.set(key, data);
         return data;
     }
     catch (err) {
         return null;
     }
 };
+/**
+ * @param track track info json from deezer api
+ * @param albumCoverSize in pixels, 56–1800 (clamped)
+ */
+const downloadAlbumCover = (track, albumCoverSize) => fetchImage('cover', track.ALB_PICTURE, albumCoverSize);
 exports.downloadAlbumCover = downloadAlbumCover;
+/**
+ * Artist photo (`ART_PICTURE` md5). Returns null when the track has no artist
+ * image (common for small-catalogue artists).
+ */
+const downloadArtistImage = (track, size = 1000) => {
+    var _a, _b;
+    const md5 = track.ART_PICTURE || ((_b = (_a = track.ARTISTS) === null || _a === void 0 ? void 0 : _a.find((a) => a.ART_PICTURE)) === null || _b === void 0 ? void 0 : _b.ART_PICTURE);
+    return fetchImage('artist', md5, size);
+};
+exports.downloadArtistImage = downloadArtistImage;

package/dist/metadata-writer/contributors.d.ts

@@ -0,0 +1,31 @@
+import type { sngContributors } from '../types';
+export interface NormalizedContributors {
+    /** billed / lead artists */
+    mainArtists: string[];
+    /** "feat." artists */
+    featuring: string[];
+    composers: string[];
+    /** author / writer / lyricist, de-duplicated */
+    lyricists: string[];
+    producers: string[];
+    /** {role, name} for mastering / mixing / recording (+ "second") engineers */
+    engineers: {
+        role: string;
+        name: string;
+    }[];
+    mixers: string[];
+    /** other performers Deezer credits by role, e.g. background vocalist */
+    performers: {
+        role: string;
+        name: string;
+    }[];
+    publishers: string[];
+}
+/**
+ * Turn Deezer's inconsistent `SNG_CONTRIBUTORS` bag into a stable shape.
+ *
+ * The role keys vary across the catalogue (`main_artist` / `mainartist` /
+ * `artist`, `musicpublisher` / `music publisher`, …) and the value is
+ * occasionally an empty array — this hides all of that.
+ */
+export declare const normalizeContributors: (raw: sngContributors | undefined) => NormalizedContributors;

package/dist/metadata-writer/contributors.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeContributors = void 0;
+/** collapse `Music Publisher`, `music_publisher`, `musicpublisher` → `musicpublisher` */
+const canon = (key) => key.toLowerCase().replace(/[\s_-]+/g, '');
+const ENGINEER_LABELS = {
+    masteringengineer: 'mastering engineer',
+    mixingengineer: 'mixing engineer',
+    recordingengineer: 'recording engineer',
+    recordingsecondengineer: 'assistant recording engineer',
+    assistantengineer: 'assistant engineer',
+    engineer: 'engineer',
+    studiopersonnel: 'engineer',
+};
+const uniq = (arr) => [...new Set(arr.filter((x) => x && x.trim()))].map((x) => x.trim());
+/**
+ * Turn Deezer's inconsistent `SNG_CONTRIBUTORS` bag into a stable shape.
+ *
+ * The role keys vary across the catalogue (`main_artist` / `mainartist` /
+ * `artist`, `musicpublisher` / `music publisher`, …) and the value is
+ * occasionally an empty array — this hides all of that.
+ */
+const normalizeContributors = (raw) => {
+    const out = {
+        mainArtists: [],
+        featuring: [],
+        composers: [],
+        lyricists: [],
+        producers: [],
+        engineers: [],
+        mixers: [],
+        performers: [],
+        publishers: [],
+    };
+    if (!raw || Array.isArray(raw)) {
+        return out;
+    }
+    const bucket = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!Array.isArray(value)) {
+            continue;
+        }
+        const k = canon(key);
+        bucket[k] = (bucket[k] || []).concat(value);
+    }
+    out.mainArtists = uniq([...(bucket.mainartist || []), ...(bucket.artist || [])]);
+    out.featuring = uniq([...(bucket.featuring || []), ...(bucket.featuredartist || []), ...(bucket.feat || [])]);
+    out.composers = uniq(bucket.composer || []);
+    out.lyricists = uniq([
+        ...(bucket.author || []),
+        ...(bucket.writer || []),
+        ...(bucket.lyricist || []),
+        ...(bucket.songwriter || []),
+    ]);
+    out.producers = uniq([...(bucket.producer || []), ...(bucket.coproducer || []), ...(bucket.executiveproducer || [])]);
+    out.mixers = uniq([...(bucket.mixer || []), ...(bucket.remixer || [])]);
+    out.publishers = uniq([
+        ...(bucket.publisher || []),
+        ...(bucket.musicpublisher || []),
+        ...(bucket.originalpublisher || []),
+    ]);
+    for (const [canonKey, label] of Object.entries(ENGINEER_LABELS)) {
+        for (const name of uniq(bucket[canonKey] || [])) {
+            out.engineers.push({ role: label, name });
+        }
+    }
+    for (const [canonKey, names] of Object.entries(bucket)) {
+        if (canonKey === 'mainartist' ||
+            canonKey === 'artist' ||
+            canonKey === 'featuring' ||
+            canonKey === 'composer' ||
+            canonKey === 'mixer' ||
+            canonKey === 'producer' ||
+            canonKey in ENGINEER_LABELS ||
+            /publisher|author|writer|lyricist/.test(canonKey)) {
+            continue;
+        }
+        // remaining roles: vocalist, backgroundvocalist, instruments, arranger, …
+        const role = canonKey.replace(/([a-z])([A-Z])/g, '$1 $2');
+        for (const name of uniq(names)) {
+            out.performers.push({ role, name });
+        }
+    }
+    return out;
+};
+exports.normalizeContributors = normalizeContributors;

package/dist/metadata-writer/flacmetata.d.ts

@@ -1,3 +1,12 @@
 /// <reference types="node" />
-import type { albumTypePublicApi, trackType } from '../types';
-export declare const writeMetadataFlac: (buffer: Buffer, track: trackType, album: albumTypePublicApi | null, dimension: number, cover?: Buffer | null) => Buffer;
+import type { TrackTagModel } from './model';
+export interface FlacWriteOptions {
+    /** embed the LRC document as a `SYNCEDLYRICS` Vorbis comment. default true */
+    embedSyncedLyrics?: boolean;
+}
+/**
+ * Write Vorbis comments + PICTURE blocks from the canonical model. Vorbis
+ * comments are free-form, so every field Deezer gives us lands here — including
+ * multi-valued credits (one comment per value) and synced lyrics.
+ */
+export declare const writeMetadataFlac: (buffer: Buffer, m: TrackTagModel, options?: FlacWriteOptions) => Buffer;