gerdur-core 1.0.4 → 2.1.0

package/dist/metadata-writer/lrc.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toLrc = void 0;
+const stamp = (ms) => {
+    const cs = Math.round(ms / 10);
+    const m = Math.floor(cs / 6000);
+    const s = Math.floor((cs % 6000) / 100);
+    const c = cs % 100;
+    return `${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}.${String(c).padStart(2, '0')}`;
+};
+/**
+ * Render Deezer's `LYRICS_SYNC_JSON` as a standard LRC document.
+ *
+ * Deezer already gives each line an `lrc_timestamp` like `[00:52.64]`; we trust
+ * `milliseconds` and re-stamp so the output is well-formed even when a line has
+ * an empty timestamp (section breaks come through as `{line: ""}`).
+ */
+const toLrc = (sync, meta = {}) => {
+    if (!sync || !sync.length) {
+        return null;
+    }
+    const head = [];
+    if (meta.artist)
+        head.push(`[ar:${meta.artist}]`);
+    if (meta.title)
+        head.push(`[ti:${meta.title}]`);
+    if (meta.album)
+        head.push(`[al:${meta.album}]`);
+    if (meta.writers)
+        head.push(`[au:${meta.writers}]`);
+    if (meta.length)
+        head.push(`[length:${stamp(meta.length * 1000)}]`);
+    head.push('[re:gerdur]');
+    const lines = sync
+        .filter((l) => l.line && l.line.trim().length)
+        .map((l) => {
+        const ms = Number(l.milliseconds);
+        const ts = l.milliseconds && Number.isFinite(ms) ? `[${stamp(ms)}]` : l.lrc_timestamp || '';
+        return `${ts}${l.line}`;
+    });
+    return [...head, ...lines].join('\n') + '\n';
+};
+exports.toLrc = toLrc;

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

@@ -0,0 +1,75 @@
+/// <reference types="node" />
+import type { RichAlbum } from './rich-album';
+import type { lyricsType, trackType, trackTypePublicApi } from '../types';
+export interface TagModelInput {
+    track: trackType;
+    album?: RichAlbum;
+    /** public `/track/` payload — the only source of BPM */
+    publicTrack?: trackTypePublicApi | null;
+    lyrics?: lyricsType | null;
+    cover?: Buffer | null;
+    artistImage?: Buffer | null;
+    coverSize: number;
+    /** write `DEEZER_*_ID`, `URL_REWRITING` slug, provider/label ids */
+    deezerIds: boolean;
+    /** write popularity rank */
+    includeRank: boolean;
+}
+export interface Person {
+    role: string;
+    name: string;
+}
+export interface TrackTagModel {
+    title: string;
+    subtitle?: string;
+    album: string;
+    artists: string[];
+    mainArtists: string[];
+    featuredArtists: string[];
+    albumArtist: string;
+    composers: string[];
+    lyricists: string[];
+    producers: string[];
+    engineers: Person[];
+    mixers: string[];
+    performers: Person[];
+    publishers: string[];
+    trackNumber: number;
+    trackTotal?: number;
+    discNumber: number;
+    discTotal?: number;
+    isrc?: string;
+    barcode?: string;
+    durationMs: number;
+    bpm?: number;
+    genres: string[];
+    label?: string;
+    releaseType?: string;
+    isCompilation: boolean;
+    date?: string;
+    year?: string;
+    originalDate?: string;
+    originalYear?: string;
+    copyright?: string;
+    producerLine?: string;
+    replayGainTrackGain?: string;
+    explicit: 'explicit' | 'clean' | 'unknown';
+    itunesAdvisory: number;
+    lyrics?: string;
+    lyricsSynced?: string;
+    lyricsWriters?: string;
+    lyricsCopyright?: string;
+    ids: {
+        deezerTrack?: string;
+        deezerAlbum?: string;
+        deezerArtist?: string;
+        slug?: string;
+        labelId?: string;
+        providerId?: string;
+    };
+    rank?: number;
+    cover?: Buffer | null;
+    coverSize: number;
+    artistImage?: Buffer | null;
+}
+export declare const buildTagModel: (input: TagModelInput) => TrackTagModel;

package/dist/metadata-writer/model.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTagModel = void 0;
+const contributors_1 = require("./contributors");
+const lrc_1 = require("./lrc");
+const yearOf = (d) => (d && /^\d{4}/.test(d) ? d.slice(0, 4) : undefined);
+const explicitFrom = (status) => {
+    // Deezer EXPLICIT_LYRICS_STATUS: 0 none · 1 explicit · 2 unknown · 3 edited/clean
+    //   · 4 partially-explicit · 6 no-advice · 7 partially-no-advice
+    if (status === 1 || status === 4)
+        return { explicit: 'explicit', itunesAdvisory: 1 };
+    if (status === 3)
+        return { explicit: 'clean', itunesAdvisory: 2 };
+    return { explicit: 'unknown', itunesAdvisory: 0 };
+};
+const buildTagModel = (input) => {
+    var _a, _b, _c, _d, _e;
+    const { track, album, publicTrack, lyrics, coverSize } = input;
+    const c = (0, contributors_1.normalizeContributors)(track.SNG_CONTRIBUTORS);
+    // main artists: contributors first, else the ARTISTS[] list, else ART_NAME
+    const artistsAll = (track.ARTISTS || []).map((a) => a.ART_NAME).filter(Boolean);
+    const mainArtists = c.mainArtists.length ? c.mainArtists : artistsAll.length ? artistsAll : [track.ART_NAME];
+    const featuredArtists = c.featuring.length ? c.featuring : artistsAll.filter((n) => !mainArtists.includes(n));
+    const artists = [...new Set([...mainArtists, ...featuredArtists])];
+    const albMeta = album || { genres: [], isCompilation: false, isLive: false };
+    const isCompilation = albMeta.isCompilation || /^various/i.test(track.ART_NAME);
+    const date = albMeta.releaseDate ||
+        ((publicTrack === null || publicTrack === void 0 ? void 0 : publicTrack.release_date) && /^\d{4}-\d{2}-\d{2}$/.test(publicTrack.release_date)
+            ? publicTrack.release_date
+            : undefined);
+    const originalDate = albMeta.originalDate && albMeta.originalDate !== date ? albMeta.originalDate : undefined;
+    const gain = parseFloat((_c = (_a = track.GAIN) !== null && _a !== void 0 ? _a : (_b = publicTrack === null || publicTrack === void 0 ? void 0 : publicTrack.gain) === null || _b === void 0 ? void 0 : _b.toString()) !== null && _c !== void 0 ? _c : '');
+    const bpmRaw = (_d = publicTrack === null || publicTrack === void 0 ? void 0 : publicTrack.bpm) !== null && _d !== void 0 ? _d : 0;
+    const explicit = explicitFrom((_e = track.EXPLICIT_TRACK_CONTENT) === null || _e === void 0 ? void 0 : _e.EXPLICIT_LYRICS_STATUS);
+    let releaseType = albMeta.recordType;
+    if (albMeta.isLive)
+        releaseType = 'live';
+    else if (isCompilation)
+        releaseType = 'compilation';
+    const version = (track.VERSION || (publicTrack === null || publicTrack === void 0 ? void 0 : publicTrack.title_version) || '').trim();
+    return {
+        title: track.SNG_TITLE,
+        subtitle: version || undefined,
+        album: track.ALB_TITLE || albMeta.title,
+        artists,
+        mainArtists,
+        featuredArtists,
+        albumArtist: albMeta.albumArtist || track.ART_NAME,
+        composers: c.composers,
+        lyricists: c.lyricists,
+        producers: c.producers,
+        engineers: c.engineers,
+        mixers: c.mixers,
+        performers: c.performers,
+        publishers: c.publishers,
+        trackNumber: Number(track.TRACK_NUMBER) || 0,
+        trackTotal: albMeta.trackTotal,
+        discNumber: Number(track.DISK_NUMBER) || 1,
+        discTotal: albMeta.discTotal,
+        isrc: track.ISRC || (publicTrack === null || publicTrack === void 0 ? void 0 : publicTrack.isrc) || undefined,
+        barcode: albMeta.upc,
+        durationMs: (Number(track.DURATION) || 0) * 1000,
+        bpm: bpmRaw > 0 ? bpmRaw : undefined,
+        genres: albMeta.genres || [],
+        label: albMeta.label,
+        releaseType,
+        isCompilation,
+        date,
+        year: yearOf(date),
+        originalDate,
+        originalYear: yearOf(originalDate),
+        copyright: albMeta.copyright,
+        producerLine: albMeta.producerLine,
+        replayGainTrackGain: Number.isFinite(gain) ? `${gain.toFixed(2)} dB` : undefined,
+        explicit: explicit.explicit,
+        itunesAdvisory: explicit.itunesAdvisory,
+        lyrics: (lyrics === null || lyrics === void 0 ? void 0 : lyrics.LYRICS_TEXT) || undefined,
+        lyricsSynced: (0, lrc_1.toLrc)(lyrics === null || lyrics === void 0 ? void 0 : lyrics.LYRICS_SYNC_JSON, {
+            title: track.SNG_TITLE,
+            artist: mainArtists.join(', '),
+            album: track.ALB_TITLE,
+            writers: lyrics === null || lyrics === void 0 ? void 0 : lyrics.LYRICS_WRITERS,
+            length: Number(track.DURATION) || undefined,
+        }) || undefined,
+        lyricsWriters: (lyrics === null || lyrics === void 0 ? void 0 : lyrics.LYRICS_WRITERS) || undefined,
+        lyricsCopyright: (lyrics === null || lyrics === void 0 ? void 0 : lyrics.LYRICS_COPYRIGHTS) || undefined,
+        ids: input.deezerIds
+            ? {
+                deezerTrack: track.SNG_ID,
+                deezerAlbum: track.ALB_ID,
+                deezerArtist: track.ART_ID,
+                slug: track.URL_REWRITING || undefined,
+                labelId: albMeta.labelId,
+                providerId: track.PROVIDER_ID || undefined,
+            }
+            : {},
+        rank: input.includeRank && track.RANK ? Number(track.RANK) || undefined : undefined,
+        cover: input.cover,
+        coverSize,
+        artistImage: input.artistImage,
+    };
+};
+exports.buildTagModel = buildTagModel;

package/dist/metadata-writer/rich-album.d.ts

@@ -0,0 +1,39 @@
+import type { albumType, albumTypePublicApi } from '../types';
+export interface RichAlbum {
+    id: string;
+    title: string;
+    albumArtist: string;
+    /** © line — from gw `COPYRIGHT`, falls back to `PRODUCER_LINE` */
+    copyright?: string;
+    /** ℗ line — only set when it differs from `copyright` */
+    producerLine?: string;
+    /** best available release date, YYYY-MM-DD */
+    releaseDate?: string;
+    /** ORIGINAL_RELEASE_DATE — the true first release; only when it differs from releaseDate */
+    originalDate?: string;
+    upc?: string;
+    label?: string;
+    labelId?: string;
+    genres: string[];
+    /** album | single | ep | compile | live … */
+    recordType?: string;
+    isCompilation: boolean;
+    isLive: boolean;
+    trackTotal?: number;
+    discTotal?: number;
+    fans?: number;
+    /** the two raw payloads, for callers that want more */
+    gw?: albumType;
+    publicApi?: albumTypePublicApi;
+}
+/**
+ * One merged album view from the two endpoints that actually carry the good
+ * fields: `album.getData` (gw — ©/℗, original release date, disc total,
+ * subtypes) and the public `/album/` (label, genres, record type). Both calls
+ * are memoised and in-flight-coalesced by the api layer, so calling this once
+ * per track of an album costs a single network round-trip for the whole album.
+ *
+ * The public endpoint 404s for some small-label albums; that path is optional
+ * and the gw data still comes through.
+ */
+export declare const getRichAlbum: (albId: string) => Promise<RichAlbum>;

package/dist/metadata-writer/rich-album.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRichAlbum = void 0;
+const api_1 = require("../api");
+const pickDate = (s) => s && /^\d{4}-\d{2}-\d{2}$/.test(s) && !/^0000/.test(s) ? s : undefined;
+/**
+ * One merged album view from the two endpoints that actually carry the good
+ * fields: `album.getData` (gw — ©/℗, original release date, disc total,
+ * subtypes) and the public `/album/` (label, genres, record type). Both calls
+ * are memoised and in-flight-coalesced by the api layer, so calling this once
+ * per track of an album costs a single network round-trip for the whole album.
+ *
+ * The public endpoint 404s for some small-label albums; that path is optional
+ * and the gw data still comes through.
+ */
+const getRichAlbum = async (albId) => {
+    var _a, _b, _c, _d, _e;
+    const [gwResult, publicResult] = await Promise.allSettled([(0, api_1.getAlbumInfo)(albId), (0, api_1.getAlbumInfoPublicApi)(albId)]);
+    const gw = gwResult.status === 'fulfilled' ? gwResult.value : undefined;
+    const pub = publicResult.status === 'fulfilled' ? publicResult.value : undefined;
+    const copyright = ((gw === null || gw === void 0 ? void 0 : gw.COPYRIGHT) || (gw === null || gw === void 0 ? void 0 : gw.PRODUCER_LINE) || '').trim() || undefined;
+    const producerLineRaw = ((gw === null || gw === void 0 ? void 0 : gw.PRODUCER_LINE) || '').trim() || undefined;
+    const producerLine = producerLineRaw && producerLineRaw !== copyright ? producerLineRaw : undefined;
+    const releaseDate = pickDate(gw === null || gw === void 0 ? void 0 : gw.DIGITAL_RELEASE_DATE) ||
+        pickDate(pub === null || pub === void 0 ? void 0 : pub.release_date) ||
+        pickDate(gw === null || gw === void 0 ? void 0 : gw.PHYSICAL_RELEASE_DATE) ||
+        pickDate(gw === null || gw === void 0 ? void 0 : gw.ORIGINAL_RELEASE_DATE);
+    const originalRaw = pickDate(gw === null || gw === void 0 ? void 0 : gw.ORIGINAL_RELEASE_DATE);
+    const originalDate = originalRaw && originalRaw !== releaseDate ? originalRaw : undefined;
+    const recordType = (pub === null || pub === void 0 ? void 0 : pub.record_type) || undefined;
+    return {
+        id: albId,
+        title: (gw === null || gw === void 0 ? void 0 : gw.ALB_TITLE) || (pub === null || pub === void 0 ? void 0 : pub.title) || '',
+        albumArtist: (gw === null || gw === void 0 ? void 0 : gw.ART_NAME) || ((_a = pub === null || pub === void 0 ? void 0 : pub.artist) === null || _a === void 0 ? void 0 : _a.name) || '',
+        copyright,
+        producerLine,
+        releaseDate,
+        originalDate,
+        upc: (gw === null || gw === void 0 ? void 0 : gw.UPC) || (pub === null || pub === void 0 ? void 0 : pub.upc) || undefined,
+        label: (pub === null || pub === void 0 ? void 0 : pub.label) || undefined,
+        labelId: (gw === null || gw === void 0 ? void 0 : gw.LABEL_ID) || undefined,
+        genres: (((_b = pub === null || pub === void 0 ? void 0 : pub.genres) === null || _b === void 0 ? void 0 : _b.data) || []).map((g) => g.name).filter(Boolean),
+        recordType,
+        isCompilation: Boolean((_c = gw === null || gw === void 0 ? void 0 : gw.SUBTYPES) === null || _c === void 0 ? void 0 : _c.isCompilation) || recordType === 'compile',
+        isLive: Boolean((_d = gw === null || gw === void 0 ? void 0 : gw.SUBTYPES) === null || _d === void 0 ? void 0 : _d.isLive),
+        trackTotal: (gw === null || gw === void 0 ? void 0 : gw.NUMBER_TRACK) ? Number(gw.NUMBER_TRACK) : pub === null || pub === void 0 ? void 0 : pub.nb_tracks,
+        discTotal: (gw === null || gw === void 0 ? void 0 : gw.NUMBER_DISK) ? Number(gw.NUMBER_DISK) : undefined,
+        fans: (_e = pub === null || pub === void 0 ? void 0 : pub.fans) !== null && _e !== void 0 ? _e : gw === null || gw === void 0 ? void 0 : gw.NB_FAN,
+        gw,
+        publicApi: pub,
+    };
+};
+exports.getRichAlbum = getRichAlbum;

package/dist/types/album.d.ts

@@ -21,8 +21,8 @@ export interface albumTypeMinimal {
 }
 export interface albumType {
     ALB_CONTRIBUTORS: {
-        main_artist: string[];
-    };
+        [role: string]: string[];
+    } | [];
     ALB_ID: string;
     ALB_PICTURE: string;
     EXPLICIT_ALBUM_CONTENT: {
@@ -34,7 +34,9 @@ export interface albumType {
     ART_ID: string;
     ART_NAME: string;
     ARTIST_IS_DUMMY: boolean;
+    COPYRIGHT?: string;
     DIGITAL_RELEASE_DATE: string;
+    ORIGINAL_RELEASE_DATE?: string;
     EXPLICIT_LYRICS?: string;
     NB_FAN: number;
     NUMBER_DISK: string;
@@ -45,6 +47,12 @@ export interface albumType {
     RANK: string;
     RANK_ART: string;
     STATUS: string;
+    SUBTYPES?: {
+        isStudio: boolean;
+        isLive: boolean;
+        isCompilation: boolean;
+        isKaraoke: boolean;
+    };
     TYPE: string;
     UPC: string;
     __TYPE__: 'album';

package/dist/types/search.d.ts

@@ -47,6 +47,163 @@ export interface discographyType {
     start: number;
     nb: number;
 }
+/**
+ * Deezer's advanced search operators. Compose these into one query string with
+ * `buildAdvancedQuery()` — e.g. `{artist: 'daft punk', durMin: 200}` becomes
+ * `artist:"daft punk" dur_min:200`.
+ *
+ * Deezer applies these as ranking hints, not hard filters, and honours `track:`
+ * only intermittently on their side — this type just mirrors the syntax they
+ * document.
+ */
+export interface advancedSearchFilters {
+    /** free-text terms, emitted first and bare */
+    query?: string;
+    artist?: string;
+    album?: string;
+    track?: string;
+    label?: string;
+    /** minimum duration, seconds */
+    durMin?: number;
+    /** maximum duration, seconds */
+    durMax?: number;
+    /** minimum beats-per-minute */
+    bpmMin?: number;
+    /** maximum beats-per-minute */
+    bpmMax?: number;
+}
+export type searchOrder = 'RANKING' | 'TRACK_ASC' | 'TRACK_DESC' | 'ARTIST_ASC' | 'ARTIST_DESC' | 'ALBUM_ASC' | 'ALBUM_DESC' | 'RATING_ASC' | 'RATING_DESC' | 'DURATION_ASC' | 'DURATION_DESC';
+export type searchEntity = 'track' | 'album' | 'artist' | 'playlist' | 'user' | 'radio' | 'podcast';
+export interface publicApiSearchOptions {
+    /** which index to hit — `track` (default), `album`, `artist`, `playlist`, `user`, `radio`, `podcast` */
+    type?: searchEntity;
+    order?: searchOrder;
+    /** send Deezer's `strict=on` — disables the fuzzy fallback */
+    strict?: boolean;
+    /** page size; Deezer caps this near 100 */
+    limit?: number;
+    /** offset into the result set */
+    index?: number;
+}
+export interface publicApiSearchResponse<T> {
+    data: T[];
+    total: number;
+    /** absolute URL of the next page, when there is one */
+    next?: string;
+    prev?: string;
+}
+interface searchArtistRef {
+    id: number;
+    name: string;
+    link?: string;
+    picture?: string;
+    picture_small?: string;
+    picture_medium?: string;
+    picture_big?: string;
+    picture_xl?: string;
+    tracklist?: string;
+    type: 'artist';
+}
+interface searchAlbumRef {
+    id: number;
+    title: string;
+    cover?: string;
+    cover_small?: string;
+    cover_medium?: string;
+    cover_big?: string;
+    cover_xl?: string;
+    md5_image?: string;
+    tracklist?: string;
+    type: 'album';
+}
+export interface searchResultTrack {
+    id: number;
+    readable: boolean;
+    title: string;
+    title_short: string;
+    title_version?: string;
+    link: string;
+    duration: number;
+    rank: number;
+    explicit_lyrics: boolean;
+    explicit_content_lyrics: number;
+    explicit_content_cover: number;
+    preview: string;
+    md5_image: string;
+    isrc?: string;
+    artist: searchArtistRef;
+    album: searchAlbumRef;
+    type: 'track';
+}
+export interface searchResultAlbum {
+    id: number;
+    title: string;
+    link: string;
+    cover: string;
+    cover_small?: string;
+    cover_medium?: string;
+    cover_big?: string;
+    cover_xl?: string;
+    md5_image: string;
+    genre_id: number;
+    nb_tracks: number;
+    record_type: string;
+    explicit_lyrics: boolean;
+    artist: searchArtistRef;
+    type: 'album';
+}
+export interface searchResultArtist {
+    id: number;
+    name: string;
+    link: string;
+    picture: string;
+    picture_small?: string;
+    picture_medium?: string;
+    picture_big?: string;
+    picture_xl?: string;
+    nb_album: number;
+    nb_fan: number;
+    radio: boolean;
+    tracklist: string;
+    type: 'artist';
+}
+export interface searchResultPlaylist {
+    id: number;
+    title: string;
+    public: boolean;
+    nb_tracks: number;
+    link: string;
+    picture: string;
+    picture_small?: string;
+    picture_medium?: string;
+    picture_big?: string;
+    picture_xl?: string;
+    checksum?: string;
+    tracklist: string;
+    creation_date?: string;
+    user?: {
+        id: number;
+        name: string;
+        tracklist?: string;
+        type: 'user';
+    };
+    type: 'playlist';
+}
+/**
+ * `deezer.suggest` — lightweight autocomplete off the internal gateway. Each
+ * per-type array is gw-shaped (uppercase keys), same as `searchMusic`'s.
+ */
+export interface suggestResult {
+    QUERY: string;
+    TOP_RESULT: unknown[];
+    ORDER: string[];
+    ALBUM?: albumTypeMinimal[];
+    ARTIST?: artistInfoTypeMinimal[];
+    TRACK?: trackType[];
+    PLAYLIST?: playlistInfoMinimal[];
+    SHOW?: unknown[];
+    RADIO?: radioType[];
+}
 export interface searchType {
     QUERY: string;
     FUZZINNESS: boolean;

package/dist/types/tracks.d.ts

@@ -3,7 +3,7 @@ interface mediaType {
     TYPE: 'preview';
     HREF: string;
 }
-interface lyricsSync {
+export interface lyricsSync {
     lrc_timestamp: string;
     milliseconds: string;
     duration: string;
@@ -16,6 +16,17 @@ export interface lyricsType {
     LYRICS_COPYRIGHTS?: string;
     LYRICS_WRITERS?: string;
 }
+/**
+ * `SNG_CONTRIBUTORS` as Deezer actually ships it: a bag of role -> names.
+ * The role keys are inconsistent across the catalogue — `main_artist` vs
+ * `mainartist` vs `artist`, `musicpublisher` vs `music publisher` — and the
+ * whole thing is sometimes an empty array. Normalise with
+ * `normalizeContributors()` from `metadata-writer/contributors` rather than
+ * reading keys directly.
+ */
+export type sngContributors = {
+    [role: string]: string[];
+} | [];
 interface songType {
     ALB_ID: string;
     ALB_TITLE: string;
@@ -40,17 +51,7 @@ interface songType {
     SMARTRADIO: string;
     SNG_ID: string;
     SNG_TITLE: string;
-    SNG_CONTRIBUTORS?: {
-        main_artist: string[];
-        author?: string[];
-        composer?: string[];
-        musicpublisher?: string[];
-        producer?: string[];
-        publisher: string[];
-        engineer?: string[];
-        writer?: string[];
-        mixer?: string[];
-    } | [];
+    SNG_CONTRIBUTORS?: sngContributors;
     STATUS: number;
     S_MOD: number;
     S_PREMIUM: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gerdur-core",
-  "version": "1.0.4",
+  "version": "2.1.0",
   "description": "Core module for gerdur.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",