plx-converter 0.1.8 → 0.1.9

package/dist/conversion.js

@@ -1,4 +1,4 @@
-import { matchCandidates } from './matcher.js';
+import { matchByDuration, matchByTitle, matchCandidates } from './matcher.js';
 import { writeCsv } from './csv.js';
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 // One conversion path for every direction: read the playlist from `source`, match each track into
@@ -21,7 +21,7 @@ export class Conversion {
     }
     // Every row carries the direction that produced it, so the file still makes sense a month later
     // and a report from one of six directions is not mistaken for another.
-    record(row) { this.rows.push({ ...row, source: this.source.name, target: this.target.name }); }
+    record(row) { const full = { ...row, source: this.source.name, target: this.target.name }; this.rows.push(full); return full; }
     async matchPlaylist(playlist, dryRun = false) {
         let result;
         try {
@@ -44,12 +44,11 @@ export class Conversion {
         // Entries the source refused to convert are recorded before the matched ones, as their own kind
         // of row: they were never searched for, so calling them "no match" would misreport them.
         for (const entry of result.skipped ?? []) {
-            this.record({ playlist: playlist.name, title: entry.name, artist: entry.artist, isrc: null, matched: false, note: 'skipped: music video (channel name is not a reliable artist)' });
+            this.record({ playlist: playlist.name, title: entry.name, artist: entry.artist, isrc: null, matched: false, note: `skipped: ${entry.reason}` });
         }
         if (result.skipped?.length)
-            console.log(`[${playlist.name}] ${result.skipped.length} music video${result.skipped.length === 1 ? '' : 's'} skipped.`);
-        const matchedIds = [];
-        let verified = 0;
+            console.log(`[${playlist.name}] ${result.skipped.length} entr${result.skipped.length === 1 ? 'y' : 'ies'} skipped (see the report).`);
+        const matched = [];
         for (let i = 0; i < result.tracks.length; i += 1) {
             const track = result.tracks[i];
             let match = null;
@@ -65,24 +64,35 @@ export class Conversion {
                         await sleep(2 ** attempt * 1000);
                 }
             }
+            // A track the source resolved from a music video says so: the row is the song, not the video.
+            const via = track.video ? `from music video "${track.video}"` : null;
             if (match) {
                 const flag = await this.verify(track, match);
-                if (this.target.resolveTrack && flag === null)
-                    verified += 1;
-                matchedIds.push(match.id);
-                this.record({ playlist: playlist.name, title: track.name, artist: track.artist, isrc: null, matched: true, target_id: match.id, method: match.method, note: [flag, dryRun ? 'dry-run' : null].filter(Boolean).join('; ') || null });
+                const row = this.record({ playlist: playlist.name, title: track.name, artist: track.artist, isrc: null, matched: true, target_id: match.id, method: match.method, note: [via, flag, dryRun ? 'dry-run' : null].filter(Boolean).join('; ') || null });
+                matched.push({ id: match.id, fromVideo: Boolean(track.video), verified: Boolean(this.target.resolveTrack) && flag === null, row });
                 console.log(`  [${i + 1}/${result.tracks.length}] ✓ ${match.method} — ${track.name} — ${track.artist}${flag ? ` — ${flag}` : ''}`);
             }
             else {
-                this.record({ playlist: playlist.name, title: track.name, artist: track.artist, isrc: null, matched: false, note: dryRun ? 'dry-run: no match' : 'no match' });
+                this.record({ playlist: playlist.name, title: track.name, artist: track.artist, isrc: null, matched: false, note: [dryRun ? 'dry-run: no match' : 'no match', via].filter(Boolean).join('; ') });
                 console.log(`  [${i + 1}/${result.tracks.length}] ✗ not found — ${track.name} — ${track.artist}`);
             }
             await sleep(300);
         }
-        const missed = result.tracks.length - matchedIds.length;
-        console.log(this.target.resolveTrack
-            ? `[${playlist.name}] ${matchedIds.length}/${result.tracks.length} matched (${verified} verified${missed ? `, ${missed} match failed` : ''}).`
-            : `[${playlist.name}] ${matchedIds.length}/${result.tracks.length} tracks matched.`);
+        // A music video whose song the playlist also holds as a song gives way to that song, which keeps
+        // its own place. Compared on the target id: the source may carry the two under different ids. A
+        // video with no song twin still converts. `video` is provenance on the Track, not a provider's.
+        const songIds = new Set(matched.filter((m) => !m.fromVideo).map((m) => m.id));
+        const songTwin = (m) => m.fromVideo && songIds.has(m.id);
+        const kept = matched.filter((m) => !songTwin(m));
+        const dropped = matched.length - kept.length;
+        for (const m of matched)
+            if (songTwin(m))
+                Object.assign(m.row, { matched: false, method: null, note: `skipped: music video, its song is already in the playlist (${m.row.target_id})` });
+        const missed = result.tracks.length - matched.length;
+        const verified = kept.filter((m) => m.verified).length;
+        const parts = [this.target.resolveTrack ? `${verified} verified` : null, dropped ? `${dropped} music video${dropped === 1 ? '' : 's'} left out, song already in playlist` : null, missed ? `${missed} match failed` : null].filter(Boolean);
+        console.log(`[${playlist.name}] ${kept.length}/${result.tracks.length} tracks converted${parts.length ? ` (${parts.join(', ')})` : ''}.`);
+        const matchedIds = kept.map((m) => m.id);
         return { matchedIds, total: result.tracks.length, truncated: result.truncated };
     }
     // Resolve the match back from the target and re-check it against the source track (precision).
@@ -92,7 +102,12 @@ export class Conversion {
             return null;
         try {
             const meta = await this.target.resolveTrack(match.id);
-            const same = matchCandidates(track.name, track.artist, track.durationMs, [{ id: match.id, title: meta.name, artist: meta.artist, duration: meta.durationMs != null ? Math.round(meta.durationMs / 1000) : null }]);
+            const resolved = [{ id: match.id, title: meta.name, artist: meta.artist, duration: meta.durationMs != null ? Math.round(meta.durationMs / 1000) : null }];
+            // A last-resort match re-checks under the rule that accepted it: a title-only match differs in
+            // its artist by definition, so holding it to matchCandidates would flag every one of them.
+            const same = matchCandidates(track.name, track.artist, track.durationMs, resolved)
+                ?? (match.method === 'title-only' ? matchByTitle(track.name, track.artist, track.durationMs, resolved) : null)
+                ?? (match.method === 'duration-only' ? matchByDuration(track.name, track.artist, track.durationMs, resolved) : null);
             return same ? null : '⚠️ recheck (possibly wrong track)';
         }
         catch {

package/dist/deezer.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { fetchJson, retry } from './http.js';
-import { firstArtist, matchByDuration, matchCandidates, searchQuery, stripFeat } from './matcher.js';
+import { fieldQuery, firstArtist, matchByDuration, matchByTitle, matchCandidates, searchQuery } from './matcher.js';
 const gqlSchema = z.object({ errors: z.array(z.object({ message: z.string() })).optional(), data: z.unknown() });
 const API = 'https://api.deezer.com';
 const GQL = 'https://pipe.deezer.com/api';
@@ -72,7 +72,7 @@ export class DeezerClient {
         if (match)
             return match;
         // Free-text relevance ranks covers/remixes above the real K-pop track; fall back to field syntax.
-        const field = `${API}/search?${new URLSearchParams({ q: `track:"${stripFeat(track.name)}" artist:"${firstArtist(track.artist)}"`, limit: '5' })}`;
+        const field = `${API}/search?${new URLSearchParams({ q: fieldQuery(track.name, track.artist), limit: '5' })}`;
         const data2 = await retry(async () => fetchJson(field));
         const candidates2 = toCandidates(data2);
         const match2 = matchCandidates(track.name, track.artist, track.durationMs, candidates2);
@@ -82,7 +82,8 @@ export class DeezerClient {
         const byAlbum = await this.searchByAlbum(track);
         if (byAlbum)
             return byAlbum;
-        return matchByDuration(track.name, track.artist, track.durationMs, [...candidates, ...candidates2]);
+        const all = [...candidates, ...candidates2];
+        return matchByDuration(track.name, track.artist, track.durationMs, all) ?? matchByTitle(track.name, track.artist, track.durationMs, all);
     }
     // Artist → albums → album tracks, for tracks the search index never surfaces (e.g. "Salty & Sweet").
     async searchByAlbum(track) {

package/dist/matcher.js

@@ -2,22 +2,44 @@ export function normalize(value) {
     return value.normalize('NFKD').replace(/\p{M}/gu, '').toLowerCase().replace(/\(.*?\)/g, '').replace(/[\[(]\s*(feat\.?|ft\.?)\s*/gi, '').replace(/\]/g, '').replace(/[^\p{L}\p{N}_\s]/gu, '').replace(/\s+/g, ' ').trim();
 }
 export function firstArtist(artist) { return artist.split(',')[0].trim(); }
+// The artist a comparison keys on. YouTube Music credits co-artists as one string — "ROSÉ & Bruno
+// Mars" — where Spotify names ROSÉ alone, so this splits on " & " as well as ",". Both sides of a
+// comparison split alike, which keeps a duo's own name ("Chase & Status") equal to itself. Search
+// terms keep the whole credit (firstArtist): free text finds a duo by its full name.
+function leadArtist(artist) { return artist.split(/,|\s&\s/)[0].trim(); }
 function artistKey(artist) { return normalize(artist).replace(/\s+/g, ''); }
 export function stripFeat(title) { return title.replace(/\s*[([]\s*(feat|ft)\.?[^)\]]*[)\]]/gi, '').trim(); }
+// A title with its bracketed tags kept as words. normalize() drops "(Eng Ver.)" outright, while a
+// catalog writing the same tag as a suffix — "Algorithm - Eng Ver." — keeps it, so on normalize()
+// alone it is the untagged original that compares equal.
+function taggedTitle(title) { return normalize(stripFeat(title).replace(/[()[\]]/g, ' ')); }
 export function matchDurationMs(spotifyMs, deezerSec, toleranceMs = 3000) { return spotifyMs == null || deezerSec == null || Math.abs(spotifyMs - deezerSec * 1000) <= toleranceMs; }
 export function searchQuery(title, artist) { return `${firstArtist(artist)} ${stripFeat(title)}`.trim(); }
+// The field-syntax retry Deezer and Spotify send after free text misses. Double quotes would end the
+// quoted field early, so they are dropped; with no artist there is nothing to pin, so no artist field.
+export function fieldQuery(title, artist) {
+    const clean = (v) => v.replace(/"/g, '').trim();
+    const a = clean(firstArtist(artist));
+    return `track:"${clean(stripFeat(title))}"${a ? ` artist:"${a}"` : ''}`;
+}
 export function matchCandidates(title, artist, durationMs, candidates) {
     const nt = normalize(stripFeat(title));
-    const na = artistKey(firstArtist(artist));
+    const tt = taggedTitle(title);
+    const na = artistKey(leadArtist(artist));
+    const sameArtist = (c) => na === artistKey(leadArtist(c.artist));
+    // The same title with its version tag intact beats one that only agrees once tags are dropped.
+    for (const c of candidates)
+        if (tt === taggedTitle(c.title) && sameArtist(c) && matchDurationMs(durationMs, c.duration))
+            return { id: c.id, title: c.title, artist: c.artist, method: 'exact' };
     for (const c of candidates)
-        if (nt === normalize(c.title) && na === artistKey(c.artist) && matchDurationMs(durationMs, c.duration))
+        if (nt === normalize(c.title) && sameArtist(c) && matchDurationMs(durationMs, c.duration))
             return { id: c.id, title: c.title, artist: c.artist, method: 'exact' };
     for (const c of candidates)
-        if (nt === normalize(c.title) && na === artistKey(c.artist))
+        if (nt === normalize(c.title) && sameArtist(c))
             return { id: c.id, title: c.title, artist: c.artist, method: 'fuzzy-duration' };
     for (const c of candidates) {
         const ct = normalize(c.title);
-        if (na === artistKey(c.artist) && nt && ct && (nt.includes(ct) || ct.includes(nt)))
+        if (sameArtist(c) && nt && ct && (nt.includes(ct) || ct.includes(nt)))
             return { id: c.id, title: c.title, artist: c.artist, method: 'fuzzy-title' };
     }
     return null;
@@ -65,6 +87,62 @@ export function matchByDuration(title, artist, durationMs, candidates) {
     const [c] = hits;
     return { id: c.id, title: c.title, artist: c.artist, method: 'duration-only' };
 }
+// Last-resort tier, the mirror of matchByDuration: the artist is not compared. It exists for one case
+// — a catalog crediting the artist in another script, YouTube Music's 지효 for Spotify's JIHYO — so it
+// applies only when the two artist names are in different scripts; two Latin names that differ are
+// two artists, and "Intro" by A is not "Intro" by B.
+//
+// The title must be equal with its tags intact (never merely contained), the duration tightens to 2s
+// and is mandatory, and the survivors must all be one artist: a single and its album release are two
+// ids for one recording, but a title two artists share at the same length is refused.
+const latinOnly = (s) => !/[^\p{Script=Latin}\p{N}\p{P}\p{S}\s]/u.test(s);
+export function matchByTitle(title, artist, durationMs, candidates) {
+    if (durationMs == null)
+        return null;
+    const tt = taggedTitle(title);
+    const lead = leadArtist(artist);
+    if (!tt || !lead)
+        return null;
+    const hits = candidates.filter((c) => c.duration != null && matchDurationMs(durationMs, c.duration, 2000)
+        && taggedTitle(c.title) === tt && latinOnly(lead) !== latinOnly(leadArtist(c.artist)));
+    if (!hits.length || new Set(hits.map((c) => artistKey(leadArtist(c.artist)))).size !== 1)
+        return null;
+    const [c] = hits;
+    return { id: c.id, title: c.title, artist: c.artist, method: 'title-only' };
+}
+// The catalog song a music video carries. A video's own metadata is the uploader's: a channel where
+// the artist belongs, a title dressed as "XG - MILLION PLACES (Official Music Video)" or "APT. - ROSÉ
+// & Bruno Mars | Cover by TsunamiCat and Dangle". So it converts as the song it spells out: one whose
+// title — or the other-language name it carries in brackets, 라비앙로즈 (La Vie en Rose) — appears in
+// the video title as whole words, by a lead artist the video title or channel names. Tags count as
+// words, so "NOT CUTE ANYMORE (Sped up)" is not what a video titled "NOT CUTE ANYMORE" carries.
+// Duration is no guard here: an official video runs long (an intro, a dance break) and a re-upload
+// is often trimmed. First such song, in search order.
+// A bracket that names a version or a guest rather than the song itself: never an alternate name.
+const TAG = /\bw\/|\b(feat|ft|prod|sped|slowed|speed|remix|mix|live|ver|version|inst|instrumental|acoustic|karaoke|cover|edit|remaster(ed)?|demo|english|korean|japanese|chinese)\b/i;
+// Whether `name` is named in `text` as whole words, spaces aside: "Bruno Mars" in "ROSÉ & Bruno Mars",
+// "BLACKPINK" in "BLACK PINK" — but not "V" inside "Love" or "IVE" inside "Live".
+function namesArtist(text, name) {
+    const key = artistKey(name);
+    const words = normalize(text.replace(/[()[\]]/g, ' ')).split(' ').filter(Boolean);
+    for (let i = 0; i < words.length; i += 1) {
+        let joined = '';
+        for (let j = i; j < words.length && joined.length < key.length; j += 1)
+            joined += words[j];
+        if (joined === key)
+            return true;
+    }
+    return false;
+}
+export function songForVideo(videoTitle, channel, songs) {
+    const words = ` ${taggedTitle(videoTitle)} `;
+    const spelled = (title) => { const t = taggedTitle(title); return t !== '' && words.includes(` ${t} `); };
+    return songs.find((s) => {
+        const aliases = [...s.title.matchAll(/\(([^)]*)\)/g)].map((m) => m[1]).filter((a) => !TAG.test(a));
+        const lead = leadArtist(s.artist);
+        return [s.title, ...aliases].some(spelled) && lead !== '' && namesArtist(`${videoTitle} ${channel}`, lead);
+    }) ?? null;
+}
 // Match rules for a music video, used only after the catalog has produced nothing.
 //
 // A music video's stated artist is usually the uploading channel, so the artist rule relaxes from

package/dist/spotify.js

@@ -1,7 +1,7 @@
 import { createHmac } from 'node:crypto';
 import { z } from 'zod';
 import { browserHeaders, fetchJson, fetchText } from './http.js';
-import { matchByDuration, matchCandidates, searchQuery } from './matcher.js';
+import { fieldQuery, matchByDuration, matchByTitle, matchCandidates, searchQuery } from './matcher.js';
 const PATHFINDER_URL = 'https://api-partner.spotify.com/pathfinder/v1/query';
 const FETCH_PLAYLIST_SHA = 'a65e12194ed5fc443a1cdebed5fabe33ca5b07b987185d63c72483867ad13cb4';
 export const EMBED_TRACK_LIMIT = 100;
@@ -220,9 +220,17 @@ export class SpotifyProvider {
     }
     readPlaylist(ref) { return readPlaylist(parsePlaylistId(ref), this.token); }
     async search(track) {
-        const candidates = await searchTrack(searchQuery(track.name, track.artist), this.token);
-        return matchCandidates(track.name, track.artist, track.durationMs, candidates)
-            ?? matchByDuration(track.name, track.artist, track.durationMs, candidates);
+        const free = await searchTrack(searchQuery(track.name, track.artist), this.token);
+        const match = matchCandidates(track.name, track.artist, track.durationMs, free);
+        if (match)
+            return match;
+        // Free text can rank an artist's hits above a short title — "ILLIT Pop" never surfaces "Pop" —
+        // so a miss retries in field syntax, which pins both. The same fallback Deezer runs.
+        const fielded = await searchTrack(fieldQuery(track.name, track.artist), this.token);
+        const all = [...free, ...fielded];
+        return matchCandidates(track.name, track.artist, track.durationMs, fielded)
+            ?? matchByDuration(track.name, track.artist, track.durationMs, all)
+            ?? matchByTitle(track.name, track.artist, track.durationMs, all);
     }
     createPlaylist(title) { return createPlaylist(title, this.token); }
     // Returns the count submitted, not one the service confirmed: addToPlaylist reports transport

package/dist/ytmusic-parse.js

@@ -2,6 +2,7 @@
 // official-source upload, a user upload, a podcast — is a video whose stated artist is the channel.
 // An entry with no type at all is an unavailable/removed track and is treated the same way.
 const SONG_TYPE = 'MUSIC_VIDEO_TYPE_ATV';
+const PODCAST_TYPE = 'MUSIC_VIDEO_TYPE_PODCAST_EPISODE';
 const runsText = (t) => t?.runs?.map((r) => r.text ?? '').join('') ?? '';
 // "3:49" → 229, "1:02:03" → 3723. Anything that is not a clock reading is null, *not* zero — a
 // playlist read has a duration column and a search result does not, and callers tell the two apart
@@ -60,13 +61,15 @@ function parseItem(renderer) {
     const subtitleParts = (columns[1] ?? '').split('•').map((s) => s.trim()).filter(Boolean);
     const trailing = subtitleParts.length > 1 ? subtitleParts[subtitleParts.length - 1] : '';
     const durationSec = parseDuration(fixed) ?? parseDuration(trailing);
+    const type = watch?.watchEndpointMusicSupportedConfigs?.watchEndpointMusicConfig?.musicVideoType;
     return {
         videoId,
         setVideoId: renderer.playlistItemData?.playlistSetVideoId,
         title,
         artist: subtitleParts[0] ?? '',
         durationSec,
-        isSong: watch?.watchEndpointMusicSupportedConfigs?.watchEndpointMusicConfig?.musicVideoType === SONG_TYPE,
+        isSong: type === SONG_TYPE,
+        isVideo: Boolean(type) && type !== SONG_TYPE && type !== PODCAST_TYPE,
     };
 }
 export function parseItems(response) {

package/dist/ytmusic-provider.js

@@ -1,4 +1,5 @@
-import { matchByDuration, matchCandidates, matchVideoCandidates, searchQuery } from './matcher.js';
+import { retry } from './http.js';
+import { matchByDuration, matchByTitle, matchCandidates, matchVideoCandidates, searchQuery, songForVideo } from './matcher.js';
 import { innertube, isMix, parsePlaylistRef } from './ytmusic.js';
 import { continuationToken, parseItems, playlistTitle, toCandidate } from './ytmusic-parse.js';
 // Search filter params, as the web client sends them: catalog songs, and music videos.
@@ -28,19 +29,58 @@ export class YtMusicProvider {
                 return { pages, items };
         }
     }
-    // Music videos are read but not converted: their stated artist is the uploading channel, so
-    // matching on it produces confident wrong answers. They come back as `skipped` so the report can
-    // show them as their own kind of row rather than silently dropping them.
+    // A music video's stated artist is the uploading channel and its title is dressed for the upload,
+    // so matching on either produces confident wrong answers. It converts instead as the catalog song
+    // it carries, found by this catalog's own song search (songForVideo), in its place in the playlist.
+    // Anything else that is not a song — a video that resolves to nothing, an entry with no type (an
+    // unavailable track), a podcast episode — comes back as `skipped` with its reason, so the report
+    // shows it as its own kind of row rather than silently dropping it.
     async readPlaylist(playlistId) {
         if (isMix(playlistId)) {
             throw new Error('That is a mix, not a playlist. A mix is generated fresh every time it is opened, so it has no fixed contents to convert — open the playlist you want and use its link.');
         }
         const { items } = await this.browseAll(playlistId);
-        return {
-            tracks: items.filter((i) => i.isSong).map((i) => ({ name: i.title, artist: i.artist, durationMs: secToMs(i.durationSec) })),
-            truncated: false,
-            skipped: items.filter((i) => !i.isSong).map((i) => ({ name: i.title, artist: i.artist })),
-        };
+        const videos = items.filter((i) => i.isVideo).length;
+        if (videos)
+            console.log(`Resolving ${videos} music video${videos === 1 ? '' : 's'} to the song${videos === 1 ? '' : 's'} they carry…`);
+        const tracks = [];
+        const skipped = [];
+        for (const item of items) {
+            if (item.isSong) {
+                tracks.push({ name: item.title, artist: item.artist, durationMs: secToMs(item.durationSec) });
+                continue;
+            }
+            if (!item.isVideo) {
+                skipped.push({ name: item.title, artist: item.artist, reason: 'unavailable on YouTube Music, or not music' });
+                continue;
+            }
+            const song = await this.resolveVideo(item);
+            if (song)
+                tracks.push({ name: song.title, artist: song.artist, durationMs: secToMs(song.duration), video: item.title });
+            else
+                skipped.push({ name: item.title, artist: item.artist, reason: song === null ? 'music video with no matching song' : 'music video, song lookup failed' });
+        }
+        return { tracks, truncated: false, skipped };
+    }
+    // The channel leads the query, as the artist does for a song. A re-upload channel ("splash.mp3")
+    // only muddies it, so a video that resolves to nothing tries its title alone. Resolves null when
+    // nothing matched and undefined when the search itself kept failing: one bad lookup costs that
+    // video, never the whole playlist read.
+    async resolveVideo(video) {
+        const queries = [{ name: video.title, artist: video.artist }, { name: video.title, artist: '' }];
+        try {
+            for (const query of queries) {
+                const songs = await retry(() => this.searchItems(query, SONGS));
+                await new Promise((resolve) => setTimeout(resolve, 300)); // the same pacing the conversion keeps
+                const song = songForVideo(video.title, video.artist, songs.filter((i) => i.isSong).map(toCandidate));
+                if (song)
+                    return song;
+            }
+            return null;
+        }
+        catch {
+            return undefined;
+        }
     }
     async playlistName(playlistId) {
         if (isMix(playlistId))
@@ -61,8 +101,10 @@ export class YtMusicProvider {
         const song = matchCandidates(track.name, track.artist, track.durationMs, songCandidates);
         if (song)
             return song;
-        // A catalog song under a translated title still beats a video — see matchByDuration.
-        const translated = matchByDuration(track.name, track.artist, track.durationMs, songCandidates);
+        // A catalog song under a translated title or artist still beats a video — see matchByDuration
+        // and matchByTitle.
+        const translated = matchByDuration(track.name, track.artist, track.durationMs, songCandidates)
+            ?? matchByTitle(track.name, track.artist, track.durationMs, songCandidates);
         if (translated)
             return translated;
         const videos = await this.searchItems(track, VIDEOS);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plx-converter",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Convert playlists between Spotify, Deezer, and YouTube Music using your own browser session",
   "license": "MIT",
   "repository": {