@postfetch/core 0.13.0 → 0.13.1

package/dist/hls.d.ts

@@ -1,4 +1,4 @@
-import type { Net } from "./internal";
+import { type Net } from "./internal";
 export type HlsVariant = {
     width: number;
     height: number;

package/dist/index.js

@@ -37,6 +37,21 @@ function createNet(baseFetch = globalThis.fetch) {
     throw lastError instanceof Error ? lastError : new Error("request failed");
   };
 }
+async function readBody(net, url, init, read) {
+  for (let attempt = 1;; attempt += 1) {
+    const response = await net(url, init);
+    if (!response.ok || !response.body)
+      return read(response);
+    try {
+      return await read(response);
+    } catch (error) {
+      if (attempt === 3)
+        throw error;
+      await response.body?.cancel().catch(() => {});
+      await sleep(500 * 2 ** (attempt - 1));
+    }
+  }
+}
 function object(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -1256,11 +1271,13 @@ function parseMaster(text, baseUrl, options = {}) {
   return { variants, audio };
 }
 async function assembleHls(net, playlistUrl, headers) {
-  const response = await net(playlistUrl, { headers });
-  if (!response.ok) {
-    throw new Error(`HLS playlist failed: ${response.status}`);
-  }
-  const segments = mediaSegments(await response.text(), playlistUrl);
+  const text = await readBody(net, playlistUrl, { headers }, async (response) => {
+    if (!response.ok) {
+      throw new Error(`HLS playlist failed: ${response.status}`);
+    }
+    return response.text();
+  });
+  const segments = mediaSegments(text, playlistUrl);
   if (segments.length === 0) {
     throw new Error("HLS playlist has no segments");
   }
@@ -1317,11 +1334,12 @@ async function fetchSegment(net, segment, headers) {
   if (segment.range) {
     requestHeaders.set("range", `bytes=${segment.range.offset}-${segment.range.offset + segment.range.length - 1}`);
   }
-  const response = await net(segment.url, { headers: requestHeaders });
-  if (!response.ok) {
-    throw new Error(`HLS segment failed: ${response.status}`);
-  }
-  return new Uint8Array(await response.arrayBuffer());
+  return readBody(net, segment.url, { headers: requestHeaders }, async (response) => {
+    if (!response.ok) {
+      throw new Error(`HLS segment failed: ${response.status}`);
+    }
+    return new Uint8Array(await response.arrayBuffer());
+  });
 }
 
 // src/pinterest.ts
@@ -2327,8 +2345,7 @@ async function resolveSpotify(input) {
     throw new PostfetchError(400, "Spotify requires an open.spotify.com track URL");
   }
   const track = await spotifyTrack(input, id);
-  const youtubeUrl = await matchYoutube(input, track);
-  const youtube = await resolveYoutube({ ...input, url: youtubeUrl });
+  const { youtube, youtubeUrl, liveFallback } = await matchingYoutube(input, track);
   return {
     archiveFilename: filename(`spotify_${id}.zip`),
     comments: [],
@@ -2338,7 +2355,12 @@ async function resolveSpotify(input) {
     metadata: {
       title: track.title,
       author: { name: track.artists.join(", ") },
-      extra: { artists: track.artists, durationSeconds: track.durationSeconds, youtubeUrl }
+      extra: {
+        artists: track.artists,
+        durationSeconds: track.durationSeconds,
+        youtubeUrl,
+        ...liveFallback ? { youtubeLiveFallback: true } : {}
+      }
     }
   };
 }
@@ -2365,9 +2387,73 @@ async function spotifyTrack(input, id) {
   const duration = number(entity.duration);
   return { title, artists, durationSeconds: duration !== null && duration > 0 ? duration / 1000 : undefined };
 }
-async function matchYoutube(input, track) {
+async function matchingYoutube(input, track) {
+  const quotedTitle = `"${track.title.replace(/"/g, "")}"`;
+  const primaryQuery = `${track.artists.join(" ")} ${track.title} audio`;
+  const queries = new Set([
+    primaryQuery,
+    `${track.artists[0]} ${quotedTitle}`,
+    track.title,
+    `${track.artists[0]} ${track.title.replace(/\s+/g, "")}`
+  ]);
+  const attempted = new Set;
+  const live = new Map;
+  let resolutionError;
+  let searchError;
+  for (const query of queries) {
+    let candidates;
+    try {
+      candidates = await searchYoutube(input, query);
+    } catch (error) {
+      if (query === primaryQuery)
+        throw error;
+      searchError = error;
+      continue;
+    }
+    const originals = candidates.map((candidate, index) => ({
+      candidate,
+      score: matchScore(track, candidate) - index / 1000
+    })).filter(({ score }) => Number.isFinite(score)).sort((left, right) => right.score - left.score);
+    for (const candidate of candidates) {
+      if (Number.isFinite(matchScore(track, candidate)))
+        continue;
+      const score = matchScore(track, candidate, true);
+      if (Number.isFinite(score)) {
+        const url = `https://www.youtube.com/watch?v=${candidate.videoId}`;
+        live.set(url, Math.max(live.get(url) ?? -Infinity, score));
+      }
+    }
+    for (const { candidate } of originals) {
+      const youtubeUrl = `https://www.youtube.com/watch?v=${candidate.videoId}`;
+      if (attempted.has(youtubeUrl) || attempted.size >= 3)
+        continue;
+      attempted.add(youtubeUrl);
+      try {
+        const youtube = await resolveYoutube({ ...input, url: youtubeUrl });
+        return { youtube, youtubeUrl, liveFallback: false };
+      } catch (error) {
+        resolutionError = error;
+      }
+    }
+  }
+  const performances = [...live].sort((left, right) => right[1] - left[1]).slice(0, 2);
+  for (const [youtubeUrl] of performances) {
+    try {
+      const youtube = await resolveYoutube({ ...input, url: youtubeUrl });
+      return { youtube, youtubeUrl, liveFallback: true };
+    } catch (error) {
+      resolutionError = error;
+    }
+  }
+  if (resolutionError)
+    throw resolutionError;
+  if (searchError)
+    throw searchError;
+  throw new PostfetchError(404, "No matching YouTube video found for this Spotify track", "noMatch");
+}
+async function searchYoutube(input, query) {
   const url = new URL("https://www.youtube.com/results");
-  url.searchParams.set("search_query", `${track.artists.join(" ")} ${track.title} audio`);
+  url.searchParams.set("search_query", query);
   url.searchParams.set("hl", "en");
   const response = await input.net(url.href, {
     headers: { "accept-language": "en-US,en;q=0.9", cookie: "SOCS=CAI", "user-agent": browserUserAgent() }
@@ -2377,17 +2463,12 @@ async function matchYoutube(input, track) {
   }
   const html = await response.text();
   const raw = html.match(/(?:\bytInitialData|window\[["']ytInitialData["']\])\s*=\s*(\{[\s\S]*?)<\/script>/)?.[1];
-  const payload = parseAssignment(raw);
+  const jsonScript = html.match(/<script\b[^>]*\bid=["']yt-initial-data["'][^>]*>([\s\S]*?)<\/script>/i)?.[1];
+  const payload = parseJson2(jsonScript) ?? parseAssignment(raw);
   if (!payload || !object(payload.contents)) {
     throw new PostfetchError(502, "YouTube search results not found");
   }
-  const candidates = videoRenderers(payload.contents);
-  const ranked = candidates.map((candidate, index) => ({ candidate, score: matchScore(track, candidate) - index / 1000 })).filter(({ score }) => Number.isFinite(score)).sort((left, right) => right.score - left.score);
-  const id = ranked[0]?.candidate.videoId;
-  if (typeof id !== "string") {
-    throw new PostfetchError(404, "No matching YouTube video found for this Spotify track", "notFound");
-  }
-  return `https://www.youtube.com/watch?v=${id}`;
+  return videoRenderers(payload.contents);
 }
 function videoRenderers(value) {
   if (Array.isArray(value))
@@ -2409,28 +2490,65 @@ function normalize(value) {
 function contains(haystack, needle) {
   return needle.length > 0 && ` ${haystack} `.includes(` ${needle} `);
 }
+function artistMatches(value, artist) {
+  if (contains(value, artist))
+    return true;
+  return /^[bcdfghjklmnpqrstvwxyz]{6,}$/.test(artist) && value.split(" ").some((word) => /^[a-z]+$/.test(word) && word.replace(/[aeiou]/g, "") === artist);
+}
 function durationSeconds(value) {
   if (!/^\d+(?::\d{2}){1,2}$/.test(value))
     return null;
   return value.split(":").reduce((seconds, part) => seconds * 60 + Number(part), 0);
 }
-function matchScore(track, candidate) {
+function topicArtistMatch(author, artist) {
+  if (!author.endsWith(" topic"))
+    return false;
+  const actual = author.slice(0, -6).trim().split(" ");
+  const expected = artist.split(" ");
+  if (actual.length !== expected.length)
+    return false;
+  let typos = 0;
+  return expected.every((word, index) => {
+    const candidate = actual[index];
+    if (candidate === word)
+      return true;
+    if (word.length < 6 || candidate.length !== word.length || ++typos > 1)
+      return false;
+    for (let offset = 0;offset < word.length - 1; offset += 1) {
+      const swapped = word.slice(0, offset) + word[offset + 1] + word[offset] + word.slice(offset + 2);
+      if (candidate === swapped)
+        return true;
+    }
+    return false;
+  });
+}
+function matchScore(track, candidate, allowLive = false) {
   if (typeof candidate.videoId !== "string" || !/^[A-Za-z0-9_-]{11}$/.test(candidate.videoId))
     return -Infinity;
   const title = normalize(text(candidate.title));
   const author = normalize(text(candidate.ownerText) || text(candidate.longBylineText) || text(candidate.shortBylineText));
-  const expected = normalize(track.title.replace(/\s*[([](?:feat\.?|ft\.?).*?[)\]]/gi, ""));
+  const trackTitle = track.title.replace(/\s*[([](?:feat\.?|ft\.?).*?[)\]]/gi, "");
+  const expected = normalize(trackTitle);
+  const artists = track.artists.map(normalize);
+  const artistUpload = artistMatches(author, artists[0]) || topicArtistMatch(author, artists[0]);
+  const credited = artists.map((artist, index) => artistMatches(`${title} ${author}`, artist) || index === 0 && artistUpload);
+  if (!credited[0])
+    return -Infinity;
   const tokens = expected.split(" ").filter(Boolean);
   if (tokens.length === 0)
     return -Infinity;
-  const coverage = tokens.filter((token) => contains(title, token)).length / tokens.length;
-  if (coverage < (tokens.length <= 3 ? 1 : 0.8))
-    return -Infinity;
-  if (tokens.length <= 3 && !contains(title, expected))
-    return -Infinity;
-  const artists = track.artists.map(normalize);
-  if (!contains(`${title} ${author}`, artists[0]))
-    return -Infinity;
+  let coverage = tokens.filter((token) => contains(title, token)).length / tokens.length;
+  const joinedTitle = expected.replace(/ /g, "");
+  const joinedMatch = tokens.length > 1 && joinedTitle.length >= 6 && contains(title, joinedTitle);
+  if (joinedMatch)
+    coverage = 1;
+  if (coverage < (tokens.length <= 3 ? 1 : 0.8) || tokens.length <= 3 && !contains(title, expected) && !joinedMatch) {
+    const parts = trackTitle.split(/\s+[-–—|]\s+/);
+    if (parts.length < 3 || !parts[0].includes(":") || artists.length < 2 || !credited.every(Boolean) || !contains(title, normalize(parts.slice(1).join(" ")))) {
+      return -Infinity;
+    }
+    coverage = 1;
+  }
   const duration = durationSeconds(text(candidate.lengthText));
   if (duration === null || duration <= 0)
     return -Infinity;
@@ -2441,13 +2559,16 @@ function matchScore(track, candidate) {
   let recordingTitle = title;
   for (const artist of artists)
     recordingTitle = recordingTitle.replace(artist, "");
-  for (const version of [/\bremix\b/, /\bcover\b/, /\bkaraoke\b/, /\binstrumental\b/, /\bslowed\b/, /\b(?:sped|speed) up\b/, /\bnightcore\b/, /\blive\b/, /\bacoustic\b/]) {
+  const isLive = /\blive\b/.test(recordingTitle);
+  const requestedLive = /\blive\b/.test(expected);
+  if (isLive !== requestedLive && !(allowLive && isLive && !requestedLive))
+    return -Infinity;
+  for (const version of [/\bremix\b/, /\bcover\b/, /\bkaraoke\b/, /\binstrumental\b/, /\bslowed\b/, /\b(?:sped|speed) up\b/, /\bnightcore\b/, /\bacoustic\b/]) {
     if (version.test(recordingTitle) !== version.test(expected))
       return -Infinity;
   }
-  const artistUpload = contains(author, artists[0]);
-  const credited = artists.filter((artist) => contains(`${title} ${author}`, artist)).length / artists.length;
-  return coverage * 10 + (artistUpload ? 8 : 0) + credited * 2 + (contains(title, "official") ? 2 : 0) + 3 * (1 - delta / tolerance);
+  const creditCoverage = credited.filter(Boolean).length / artists.length;
+  return coverage * 10 + (artistUpload ? 8 : 0) + creditCoverage * 2 + (contains(title, "official") ? 2 : 0) + 3 * (1 - delta / tolerance);
 }
 function parseJson2(value) {
   try {
@@ -3640,11 +3761,13 @@ async function downloadBlob(input, optionsOrHeaders = {}, legacyOptions = {}) {
   const options = modern ? optionsOrHeaders : legacyOptions;
   const headers = modern ? optionsOrHeaders.headers ?? {} : optionsOrHeaders;
   const net = createNet(options.fetch ?? globalThis.fetch);
-  const response = typeof input === "string" ? await net(input, { headers }) : await download({ ...input, headers: modern ? optionsOrHeaders.headers ?? input.headers : input.headers }, options);
-  if (!response.ok || !response.body) {
-    throw new PostfetchError(502, `download failed: ${response.status}`);
-  }
-  const blob = await response.blob();
+  const item = typeof input === "string" ? null : { ...input, headers: modern ? optionsOrHeaders.headers ?? input.headers : input.headers };
+  const blob = item && buffered(item) ? new Blob([toArrayBuffer(await itemBytes2(net, item))], { type: item.mime }) : await readBody(net, typeof input === "string" ? input : input.url, { headers: item?.headers ?? headers }, async (response) => {
+    if (!response.ok || !response.body) {
+      throw new PostfetchError(502, `download failed: ${response.status}`);
+    }
+    return response.blob();
+  });
   if (!modern || optionsOrHeaders.remux !== true) {
     return blob;
   }
@@ -3748,11 +3871,12 @@ async function mergedBytes(net, item, audio) {
   return mergeAudioVideo(video, audioBytes);
 }
 async function fetchBytes(net, url, headers) {
-  const response = await net(url, { headers });
-  if (!response.ok) {
-    throw new PostfetchError(502, `download failed: ${response.status}`);
-  }
-  return new Uint8Array(await response.arrayBuffer());
+  return readBody(net, url, { headers }, async (response) => {
+    if (!response.ok) {
+      throw new PostfetchError(502, `download failed: ${response.status}`);
+    }
+    return new Uint8Array(await response.arrayBuffer());
+  });
 }
 function toArrayBuffer(bytes) {
   return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);

package/dist/internal.d.ts

@@ -152,6 +152,8 @@ export type SpotifyExtra = {
     durationSeconds?: number;
     /** Public watch URL passed to the existing YouTube resolver. */
     youtubeUrl: string;
+    /** A live performance was selected after original-recording searches failed. */
+    youtubeLiveFallback?: boolean;
 };
 /** Pinterest-specific metadata. */
 export type PinterestExtra = {
@@ -207,7 +209,7 @@ export type ResolveContext = {
  * Lets callers tell a user-facing limitation (age-gated, private, removed) apart
  * from a transient/technical failure.
  */
-export type PostfetchReason = "ageRestricted" | "private" | "loginRequired" | "deleted" | "notFound" | "rateLimited" | "unavailable";
+export type PostfetchReason = "ageRestricted" | "private" | "loginRequired" | "deleted" | "notFound" | "noMatch" | "rateLimited" | "unavailable";
 /** An error carrying an HTTP status, so adapters can map failures onto responses. */
 export declare class PostfetchError extends Error {
     /** HTTP status that best describes the failure. */
@@ -229,6 +231,8 @@ export declare class PostfetchError extends Error {
 }
 export type Json = Record<string, unknown>;
 export declare function createNet(baseFetch?: typeof fetch): Net;
+/** Retry interrupted body reads; request/status retries remain owned by net. */
+export declare function readBody<T>(net: Net, url: string, init: RequestInit, read: (response: Response) => Promise<T>): Promise<T>;
 export declare function object(value: unknown): value is Json;
 export declare function string(value: unknown): string | null;
 export declare function number(value: unknown): number | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postfetch/core",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Zero-dependency typed core that turns Facebook, Instagram, LinkedIn, Pinterest, Reddit, SoundCloud, Spotify, TikTok, X and YouTube post URLs into media files.",
   "license": "MIT",
   "type": "module",

package/src/download.ts

@@ -1,5 +1,5 @@
 import { assembleHls } from "./hls";
-import { createNet, PostfetchError, type MediaItem, type Net, type PostfetchResult } from "./internal";
+import { createNet, PostfetchError, readBody, type MediaItem, type Net, type PostfetchResult } from "./internal";
 import { prepareMp4 } from "./mp4-remux";
 import { mergeAudioVideo } from "./remux";
 import { zip } from "./zip";
@@ -118,13 +118,16 @@ export async function downloadBlob(
   const options = modern ? optionsOrHeaders : legacyOptions;
   const headers = modern ? optionsOrHeaders.headers ?? {} : optionsOrHeaders;
   const net = createNet(options.fetch ?? globalThis.fetch);
-  const response = typeof input === "string"
-    ? await net(input, { headers })
-    : await download({ ...input, headers: modern ? optionsOrHeaders.headers ?? input.headers : input.headers }, options);
-  if (!response.ok || !response.body) {
-    throw new PostfetchError(502, `download failed: ${response.status}`);
-  }
-  const blob = await response.blob();
+  const item = typeof input === "string" ? null
+    : { ...input, headers: modern ? optionsOrHeaders.headers ?? input.headers : input.headers };
+  const blob = item && buffered(item)
+    ? new Blob([toArrayBuffer(await itemBytes(net, item))], { type: item.mime })
+    : await readBody(net, typeof input === "string" ? input : input.url, { headers: item?.headers ?? headers }, async (response) => {
+      if (!response.ok || !response.body) {
+        throw new PostfetchError(502, `download failed: ${response.status}`);
+      }
+      return response.blob();
+    });
   if (!modern || optionsOrHeaders.remux !== true) {
     return blob;
   }
@@ -267,11 +270,12 @@ async function mergedBytes(net: Net, item: MediaItem, audio: NonNullable<MediaIt
 }
 
 async function fetchBytes(net: Net, url: string, headers: HeadersInit): Promise<Uint8Array> {
-  const response = await net(url, { headers });
-  if (!response.ok) {
-    throw new PostfetchError(502, `download failed: ${response.status}`);
-  }
-  return new Uint8Array(await response.arrayBuffer());
+  return readBody(net, url, { headers }, async (response) => {
+    if (!response.ok) {
+      throw new PostfetchError(502, `download failed: ${response.status}`);
+    }
+    return new Uint8Array(await response.arrayBuffer());
+  });
 }
 
 function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {

package/src/hls.ts

@@ -1,5 +1,5 @@
 import { concat } from "./isobmff";
-import type { Net } from "./internal";
+import { readBody, type Net } from "./internal";
 import { packedAacToMp4 } from "./packed-aac";
 
 // HLS support for the fMP4/CMAF playlists reddit-style muxing already covers:
@@ -54,11 +54,13 @@ export function parseMaster(text: string, baseUrl: string, options: { preferOrig
 }
 
 export async function assembleHls(net: Net, playlistUrl: string, headers: HeadersInit): Promise<Uint8Array> {
-  const response = await net(playlistUrl, { headers });
-  if (!response.ok) {
-    throw new Error(`HLS playlist failed: ${response.status}`);
-  }
-  const segments = mediaSegments(await response.text(), playlistUrl);
+  const text = await readBody(net, playlistUrl, { headers }, async (response) => {
+    if (!response.ok) {
+      throw new Error(`HLS playlist failed: ${response.status}`);
+    }
+    return response.text();
+  });
+  const segments = mediaSegments(text, playlistUrl);
   if (segments.length === 0) {
     throw new Error("HLS playlist has no segments");
   }
@@ -122,9 +124,10 @@ async function fetchSegment(net: Net, segment: Segment, headers: HeadersInit): P
   if (segment.range) {
     requestHeaders.set("range", `bytes=${segment.range.offset}-${segment.range.offset + segment.range.length - 1}`);
   }
-  const response = await net(segment.url, { headers: requestHeaders });
-  if (!response.ok) {
-    throw new Error(`HLS segment failed: ${response.status}`);
-  }
-  return new Uint8Array(await response.arrayBuffer());
+  return readBody(net, segment.url, { headers: requestHeaders }, async (response) => {
+    if (!response.ok) {
+      throw new Error(`HLS segment failed: ${response.status}`);
+    }
+    return new Uint8Array(await response.arrayBuffer());
+  });
 }

package/src/internal.ts

@@ -159,6 +159,8 @@ export type SpotifyExtra = {
   durationSeconds?: number;
   /** Public watch URL passed to the existing YouTube resolver. */
   youtubeUrl: string;
+  /** A live performance was selected after original-recording searches failed. */
+  youtubeLiveFallback?: boolean;
 };
 
 /** Pinterest-specific metadata. */
@@ -237,6 +239,7 @@ export type PostfetchReason =
   | "loginRequired"
   | "deleted"
   | "notFound"
+  | "noMatch"
   | "rateLimited"
   | "unavailable";
 
@@ -289,6 +292,27 @@ export function createNet(baseFetch: typeof fetch = globalThis.fetch): Net {
   };
 }
 
+/** Retry interrupted body reads; request/status retries remain owned by net. */
+export async function readBody<T>(
+  net: Net,
+  url: string,
+  init: RequestInit,
+  read: (response: Response) => Promise<T>,
+): Promise<T> {
+  for (let attempt = 1; ; attempt += 1) {
+    const response = await net(url, init);
+    // Let callers report HTTP/empty-body failures without restarting request retries.
+    if (!response.ok || !response.body) return read(response);
+    try {
+      return await read(response);
+    } catch (error) {
+      if (attempt === 3) throw error;
+      await response.body?.cancel().catch(() => {});
+      await sleep(500 * 2 ** (attempt - 1));
+    }
+  }
+}
+
 export function object(value: unknown): value is Json {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/src/spotify.ts

@@ -1,5 +1,5 @@
 import { browserUserAgent } from "./fingerprint";
-import { asUrl, filename, number, object, PostfetchError, string, type Json, type PlatformResult, type ResolveContext, type SpotifyExtra } from "./internal";
+import { asUrl, filename, number, object, PostfetchError, string, type Json, type PlatformResult, type PostfetchResult, type ResolveContext, type SpotifyExtra } from "./internal";
 import { resolveYoutube } from "./youtube";
 
 type Track = { title: string; artists: string[]; durationSeconds?: number };
@@ -12,9 +12,7 @@ export async function resolveSpotify(input: ResolveContext): Promise<PlatformRes
     throw new PostfetchError(400, "Spotify requires an open.spotify.com track URL");
   }
   const track = await spotifyTrack(input, id);
-  const youtubeUrl = await matchYoutube(input, track);
-  // Keep YouTube's media, filenames, separate audio and client fallback intact.
-  const youtube = await resolveYoutube({ ...input, url: youtubeUrl });
+  const { youtube, youtubeUrl, liveFallback } = await matchingYoutube(input, track);
   return {
     archiveFilename: filename(`spotify_${id}.zip`),
     comments: [],
@@ -24,7 +22,10 @@ export async function resolveSpotify(input: ResolveContext): Promise<PlatformRes
     metadata: {
       title: track.title,
       author: { name: track.artists.join(", ") },
-      extra: { artists: track.artists, durationSeconds: track.durationSeconds, youtubeUrl },
+      extra: {
+        artists: track.artists, durationSeconds: track.durationSeconds, youtubeUrl,
+        ...(liveFallback ? { youtubeLiveFallback: true } : {}),
+      },
     },
   };
 }
@@ -55,9 +56,71 @@ async function spotifyTrack(input: ResolveContext, id: string): Promise<Track> {
   return { title, artists, durationSeconds: duration !== null && duration > 0 ? duration / 1000 : undefined };
 }
 
-async function matchYoutube(input: ResolveContext, track: Track): Promise<string> {
+async function matchingYoutube(input: ResolveContext, track: Track): Promise<{ youtube: PostfetchResult; youtubeUrl: string; liveFallback: boolean }> {
+  const quotedTitle = `"${track.title.replace(/"/g, "")}"`;
+  const primaryQuery = `${track.artists.join(" ")} ${track.title} audio`;
+  const queries = new Set([
+    primaryQuery,
+    `${track.artists[0]} ${quotedTitle}`,
+    track.title,
+    `${track.artists[0]} ${track.title.replace(/\s+/g, "")}`,
+  ]);
+  const attempted = new Set<string>();
+  const live = new Map<string, number>();
+  let resolutionError: unknown;
+  let searchError: unknown;
+  for (const query of queries) {
+    let candidates: Json[];
+    try {
+      candidates = await searchYoutube(input, query);
+    } catch (error) {
+      // A failed primary search is a technical failure, not a missing match.
+      if (query === primaryQuery) throw error;
+      searchError = error;
+      continue;
+    }
+    const originals = candidates.map((candidate, index) => ({
+      candidate, score: matchScore(track, candidate) - index / 1000,
+    })).filter(({ score }) => Number.isFinite(score)).sort((left, right) => right.score - left.score);
+    for (const candidate of candidates) {
+      if (Number.isFinite(matchScore(track, candidate))) continue;
+      const score = matchScore(track, candidate, true);
+      if (Number.isFinite(score)) {
+        const url = `https://www.youtube.com/watch?v=${candidate.videoId}`;
+        live.set(url, Math.max(live.get(url) ?? -Infinity, score));
+      }
+    }
+    for (const { candidate } of originals) {
+      const youtubeUrl = `https://www.youtube.com/watch?v=${candidate.videoId}`;
+      if (attempted.has(youtubeUrl) || attempted.size >= 3) continue;
+      attempted.add(youtubeUrl);
+      try {
+        // Keep YouTube's separate streams and client fallback intact for each upload.
+        const youtube = await resolveYoutube({ ...input, url: youtubeUrl });
+        return { youtube, youtubeUrl, liveFallback: false };
+      } catch (error) {
+        resolutionError = error;
+      }
+    }
+  }
+  // Try at most two live performances, after all searches for the original.
+  const performances = [...live].sort((left, right) => right[1] - left[1]).slice(0, 2);
+  for (const [youtubeUrl] of performances) {
+    try {
+      const youtube = await resolveYoutube({ ...input, url: youtubeUrl });
+      return { youtube, youtubeUrl, liveFallback: true };
+    } catch (error) {
+      resolutionError = error;
+    }
+  }
+  if (resolutionError) throw resolutionError;
+  if (searchError) throw searchError;
+  throw new PostfetchError(404, "No matching YouTube video found for this Spotify track", "noMatch");
+}
+
+async function searchYoutube(input: ResolveContext, query: string): Promise<Json[]> {
   const url = new URL("https://www.youtube.com/results");
-  url.searchParams.set("search_query", `${track.artists.join(" ")} ${track.title} audio`);
+  url.searchParams.set("search_query", query);
   url.searchParams.set("hl", "en");
   const response = await input.net(url.href, {
     headers: { "accept-language": "en-US,en;q=0.9", cookie: "SOCS=CAI", "user-agent": browserUserAgent() },
@@ -66,22 +129,15 @@ async function matchYoutube(input: ResolveContext, track: Track): Promise<string
     throw new PostfetchError(502, `YouTube search failed: ${response.status}`);
   }
   const html = await response.text();
-  // Read the JSON assignment up to the end of its script, without evaluating JS.
-  // The balanced JSON object is extracted before parsing; trailing JS is ignored.
+  // Read the JSON script or legacy assignment without evaluating JavaScript.
+  // Assignment parsing balances the object and ignores trailing statements.
   const raw = html.match(/(?:\bytInitialData|window\[["']ytInitialData["']\])\s*=\s*(\{[\s\S]*?)<\/script>/)?.[1];
-  const payload = parseAssignment(raw);
+  const jsonScript = html.match(/<script\b[^>]*\bid=["']yt-initial-data["'][^>]*>([\s\S]*?)<\/script>/i)?.[1];
+  const payload = parseJson(jsonScript) ?? parseAssignment(raw);
   if (!payload || !object(payload.contents)) {
     throw new PostfetchError(502, "YouTube search results not found");
   }
-  const candidates = videoRenderers(payload.contents);
-  const ranked = candidates.map((candidate, index) => ({ candidate, score: matchScore(track, candidate) - index / 1000 }))
-    .filter(({ score }) => Number.isFinite(score))
-    .sort((left, right) => right.score - left.score);
-  const id = ranked[0]?.candidate.videoId;
-  if (typeof id !== "string") {
-    throw new PostfetchError(404, "No matching YouTube video found for this Spotify track", "notFound");
-  }
-  return `https://www.youtube.com/watch?v=${id}`;
+  return videoRenderers(payload.contents);
 }
 
 function videoRenderers(value: unknown): Json[] {
@@ -106,23 +162,66 @@ function contains(haystack: string, needle: string): boolean {
   return needle.length > 0 && ` ${haystack} `.includes(` ${needle} `);
 }
 
+function artistMatches(value: string, artist: string): boolean {
+  if (contains(value, artist)) return true;
+  // Recognize long, vowel-free abbreviations such as Chkbns / Cheekbones.
+  // Match whole words, never a short/common acronym or arbitrary edit distance.
+  return /^[bcdfghjklmnpqrstvwxyz]{6,}$/.test(artist) && value.split(" ").some((word) =>
+    /^[a-z]+$/.test(word) && word.replace(/[aeiou]/g, "") === artist
+  );
+}
+
 function durationSeconds(value: string): number | null {
   if (!/^\d+(?::\d{2}){1,2}$/.test(value)) return null;
   return value.split(":").reduce((seconds, part) => seconds * 60 + Number(part), 0);
 }
 
-function matchScore(track: Track, candidate: Json): number {
+// Some auto-generated Topic channels transpose adjacent letters in an artist's
+// name. Allow one such typo in a long word only, with every other word exact.
+function topicArtistMatch(author: string, artist: string): boolean {
+  if (!author.endsWith(" topic")) return false;
+  const actual = author.slice(0, -6).trim().split(" ");
+  const expected = artist.split(" ");
+  if (actual.length !== expected.length) return false;
+  let typos = 0;
+  return expected.every((word, index) => {
+    const candidate = actual[index];
+    if (candidate === word) return true;
+    if (word.length < 6 || candidate.length !== word.length || ++typos > 1) return false;
+    for (let offset = 0; offset < word.length - 1; offset += 1) {
+      const swapped = word.slice(0, offset) + word[offset + 1] + word[offset] + word.slice(offset + 2);
+      if (candidate === swapped) return true;
+    }
+    return false;
+  });
+}
+
+function matchScore(track: Track, candidate: Json, allowLive = false): number {
   if (typeof candidate.videoId !== "string" || !/^[A-Za-z0-9_-]{11}$/.test(candidate.videoId)) return -Infinity;
   const title = normalize(text(candidate.title));
   const author = normalize(text(candidate.ownerText) || text(candidate.longBylineText) || text(candidate.shortBylineText));
-  const expected = normalize(track.title.replace(/\s*[([](?:feat\.?|ft\.?).*?[)\]]/gi, ""));
+  const trackTitle = track.title.replace(/\s*[([](?:feat\.?|ft\.?).*?[)\]]/gi, "");
+  const expected = normalize(trackTitle);
+  const artists = track.artists.map(normalize);
+  const artistUpload = artistMatches(author, artists[0]) || topicArtistMatch(author, artists[0]);
+  const credited = artists.map((artist, index) => artistMatches(`${title} ${author}`, artist) || (index === 0 && artistUpload));
+  if (!credited[0]) return -Infinity;
   const tokens = expected.split(" ").filter(Boolean);
   if (tokens.length === 0) return -Infinity;
-  const coverage = tokens.filter((token) => contains(title, token)).length / tokens.length;
-  if (coverage < (tokens.length <= 3 ? 1 : 0.8)) return -Infinity;
-  if (tokens.length <= 3 && !contains(title, expected)) return -Infinity;
-  const artists = track.artists.map(normalize);
-  if (!contains(`${title} ${author}`, artists[0])) return -Infinity;
+  let coverage = tokens.filter((token) => contains(title, token)).length / tokens.length;
+  const joinedTitle = expected.replace(/ /g, "");
+  const joinedMatch = tokens.length > 1 && joinedTitle.length >= 6 && contains(title, joinedTitle);
+  if (joinedMatch) coverage = 1;
+  if (coverage < (tokens.length <= 3 ? 1 : 0.8) || (tokens.length <= 3 && !contains(title, expected) && !joinedMatch)) {
+    // A soundtrack title may prefix the song and its show/version with project
+    // context, e.g. "Project: Subtitle - Song - Show". Require the complete
+    // remaining phrase and every credited artist before accepting its omission.
+    const parts = trackTitle.split(/\s+[-–—|]\s+/);
+    if (parts.length < 3 || !parts[0].includes(":") || artists.length < 2 || !credited.every(Boolean) || !contains(title, normalize(parts.slice(1).join(" ")))) {
+      return -Infinity;
+    }
+    coverage = 1;
+  }
   const duration = durationSeconds(text(candidate.lengthText));
   if (duration === null || duration <= 0) return -Infinity; // Excludes live streams and upcoming videos.
   const tolerance = Math.min(30, Math.max(12, (track.durationSeconds ?? duration) * 0.08));
@@ -132,12 +231,14 @@ function matchScore(track: Track, candidate: Json): number {
   // are removed first so e.g. a band called "Live" is not treated as a live edit.
   let recordingTitle = title;
   for (const artist of artists) recordingTitle = recordingTitle.replace(artist, "");
-  for (const version of [/\bremix\b/, /\bcover\b/, /\bkaraoke\b/, /\binstrumental\b/, /\bslowed\b/, /\b(?:sped|speed) up\b/, /\bnightcore\b/, /\blive\b/, /\bacoustic\b/]) {
+  const isLive = /\blive\b/.test(recordingTitle);
+  const requestedLive = /\blive\b/.test(expected);
+  if (isLive !== requestedLive && !(allowLive && isLive && !requestedLive)) return -Infinity;
+  for (const version of [/\bremix\b/, /\bcover\b/, /\bkaraoke\b/, /\binstrumental\b/, /\bslowed\b/, /\b(?:sped|speed) up\b/, /\bnightcore\b/, /\bacoustic\b/]) {
     if (version.test(recordingTitle) !== version.test(expected)) return -Infinity;
   }
-  const artistUpload = contains(author, artists[0]);
-  const credited = artists.filter((artist) => contains(`${title} ${author}`, artist)).length / artists.length;
-  return coverage * 10 + (artistUpload ? 8 : 0) + credited * 2 + (contains(title, "official") ? 2 : 0) + 3 * (1 - delta / tolerance);
+  const creditCoverage = credited.filter(Boolean).length / artists.length;
+  return coverage * 10 + (artistUpload ? 8 : 0) + creditCoverage * 2 + (contains(title, "official") ? 2 : 0) + 3 * (1 - delta / tolerance);
 }
 
 function parseJson(value: string | undefined): Json | null {