@postfetch/core 0.12.5 → 0.13.1

package/dist/internal.d.ts

@@ -1,5 +1,5 @@
 /** A platform that {@link postfetch} can resolve. */
-export type Platform = "facebook" | "instagram" | "linkedin" | "pinterest" | "reddit" | "soundcloud" | "tiktok" | "twitter" | "youtube";
+export type Platform = "facebook" | "instagram" | "linkedin" | "pinterest" | "reddit" | "soundcloud" | "spotify" | "tiktok" | "twitter" | "youtube";
 /** The kind of a {@link MediaItem}. */
 export type MediaKind = "audio" | "image" | "video";
 /** A single resolved media file: a direct URL plus everything needed to fetch and name it. */
@@ -144,6 +144,17 @@ export type SoundcloudExtra = {
     /** Track duration in seconds. */
     durationSeconds?: number;
 };
+/** Spotify track metadata, with the YouTube source selected for downloading. */
+export type SpotifyExtra = {
+    /** Artists credited on Spotify, in order. */
+    artists: string[];
+    /** Spotify track duration in seconds, when available. */
+    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 = {
     /** Times the pin was saved (repinned). */
@@ -165,7 +176,7 @@ export type PostComment = {
     items: MediaItem[];
 };
 /** The result of resolving a post: its platform, id, media items and metadata. */
-export type PostfetchResult = PlatformResult<"facebook", never> | PlatformResult<"instagram", InstagramExtra> | PlatformResult<"linkedin", never> | PlatformResult<"pinterest", PinterestExtra> | PlatformResult<"reddit", RedditExtra> | PlatformResult<"soundcloud", SoundcloudExtra> | PlatformResult<"tiktok", TiktokExtra> | PlatformResult<"twitter", TwitterExtra> | PlatformResult<"youtube", YoutubeExtra>;
+export type PostfetchResult = PlatformResult<"facebook", never> | PlatformResult<"instagram", InstagramExtra> | PlatformResult<"linkedin", never> | PlatformResult<"pinterest", PinterestExtra> | PlatformResult<"reddit", RedditExtra> | PlatformResult<"soundcloud", SoundcloudExtra> | PlatformResult<"spotify", SpotifyExtra> | PlatformResult<"tiktok", TiktokExtra> | PlatformResult<"twitter", TwitterExtra> | PlatformResult<"youtube", YoutubeExtra>;
 /** One platform's variant of a {@link PostfetchResult}, carrying that platform's `extra` metadata shape. */
 export type PlatformResult<P extends Platform, Extra> = {
     /** Suggested filename when zipping every item. */
@@ -198,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. */
@@ -220,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/dist/spotify.d.ts

@@ -0,0 +1,3 @@
+import { type PlatformResult, type ResolveContext, type SpotifyExtra } from "./internal";
+/** Resolve Spotify track metadata and a matching video through YouTube. */
+export declare function resolveSpotify(input: ResolveContext): Promise<PlatformResult<"spotify", SpotifyExtra>>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@postfetch/core",
-  "version": "0.12.5",
-  "description": "Zero-dependency typed core that turns Facebook, Instagram, LinkedIn, Pinterest, Reddit, SoundCloud, TikTok, X and YouTube post URLs into media files.",
+  "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",
   "exports": {
@@ -35,6 +35,7 @@
     "pinterest",
     "reddit",
     "soundcloud",
+    "spotify",
     "tiktok",
     "twitter",
     "youtube",

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;
   }
@@ -185,10 +188,16 @@ export async function archive(result: PostfetchResult, options: DownloadOptions
  * @returns A `Response` a server or edge function can return directly.
  */
 export async function toResponse(result: PostfetchResult, options: DownloadOptions = {}): Promise<Response> {
-  if (result.items.length === 1) {
-    return singleResponse(result.items[0], options);
+  const response = result.items.length === 1
+    ? await singleResponse(result.items[0], options)
+    : await archiveResponse(result, options);
+  if (result.platform === "spotify") {
+    response.headers.set("x-media-platform", result.platform);
+    response.headers.set("x-media-id", result.id);
+    const youtubeUrl = result.metadata?.extra?.youtubeUrl;
+    if (youtubeUrl) response.headers.set("x-media-youtube-url", youtubeUrl);
   }
-  return archiveResponse(result, options);
+  return response;
 }
 
 async function singleResponse(item: MediaItem, options: DownloadOptions): Promise<Response> {
@@ -261,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/index.ts

@@ -1,8 +1,9 @@
 /**
  * Turn a public social post URL into its media.
  *
- * {@link postfetch} resolves Instagram, LinkedIn, TikTok, YouTube, Facebook and X (Twitter)
- * URLs to typed {@link MediaItem}s. Zero dependencies, only Web-standard APIs
+ * {@link postfetch} resolves public social post and Spotify track URLs to typed
+ * {@link MediaItem}s. Spotify tracks are matched to YouTube videos.
+ * Zero dependencies, only Web-standard APIs
  * (`fetch`, `Response`, `URL`, `crypto`) — so it runs on Deno, Node, Bun,
  * Cloudflare Workers and browsers alike. It only resolves the media; the
  * {@link download}, {@link downloadBlob}, {@link archive} and {@link toResponse}
@@ -46,6 +47,7 @@ export type {
   PostMetadata,
   RedditExtra,
   SoundcloudExtra,
+  SpotifyExtra,
   TiktokExtra,
   TwitterExtra,
   TwitterQuotedTweet,

package/src/internal.ts

@@ -1,5 +1,5 @@
 /** A platform that {@link postfetch} can resolve. */
-export type Platform = "facebook" | "instagram" | "linkedin" | "pinterest" | "reddit" | "soundcloud" | "tiktok" | "twitter" | "youtube";
+export type Platform = "facebook" | "instagram" | "linkedin" | "pinterest" | "reddit" | "soundcloud" | "spotify" | "tiktok" | "twitter" | "youtube";
 
 /** The kind of a {@link MediaItem}. */
 export type MediaKind = "audio" | "image" | "video";
@@ -151,6 +151,18 @@ export type SoundcloudExtra = {
   durationSeconds?: number;
 };
 
+/** Spotify track metadata, with the YouTube source selected for downloading. */
+export type SpotifyExtra = {
+  /** Artists credited on Spotify, in order. */
+  artists: string[];
+  /** Spotify track duration in seconds, when available. */
+  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 = {
   /** Times the pin was saved (repinned). */
@@ -181,6 +193,7 @@ export type PostfetchResult =
   | PlatformResult<"pinterest", PinterestExtra>
   | PlatformResult<"reddit", RedditExtra>
   | PlatformResult<"soundcloud", SoundcloudExtra>
+  | PlatformResult<"spotify", SpotifyExtra>
   | PlatformResult<"tiktok", TiktokExtra>
   | PlatformResult<"twitter", TwitterExtra>
   | PlatformResult<"youtube", YoutubeExtra>;
@@ -226,6 +239,7 @@ export type PostfetchReason =
   | "loginRequired"
   | "deleted"
   | "notFound"
+  | "noMatch"
   | "rateLimited"
   | "unavailable";
 
@@ -278,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/postfetch.ts

@@ -5,6 +5,7 @@ import { resolveLinkedin } from "./linkedin";
 import { resolvePinterest } from "./pinterest";
 import { resolveReddit } from "./reddit";
 import { resolveSoundcloud } from "./soundcloud";
+import { resolveSpotify } from "./spotify";
 import { resolveTiktok } from "./tiktok";
 import { resolveTwitter } from "./twitter";
 import { resolveYoutube } from "./youtube";
@@ -85,6 +86,8 @@ async function resolve(context: ResolveContext): Promise<PostfetchResult> {
       return resolveReddit(context);
     case "soundcloud":
       return resolveSoundcloud(context);
+    case "spotify":
+      return resolveSpotify(context);
     case "tiktok":
       return resolveTiktok(context);
     case "twitter":
@@ -180,6 +183,9 @@ export function detect(url: string): Platform {
   if (host.includes("soundcloud.com") || host === "snd.sc") {
     return "soundcloud";
   }
+  if (host === "open.spotify.com") {
+    return "spotify";
+  }
   if (host.includes("youtube.com") || host === "youtu.be") {
     return "youtube";
   }
@@ -189,5 +195,5 @@ export function detect(url: string): Platform {
   if (host === "x.com" || host.endsWith(".x.com") || host.includes("twitter.com")) {
     return "twitter";
   }
-  throw new PostfetchError(400, "only Facebook, Instagram, LinkedIn, Pinterest, Reddit, SoundCloud, TikTok, X and YouTube URLs are supported");
+  throw new PostfetchError(400, "only Facebook, Instagram, LinkedIn, Pinterest, Reddit, SoundCloud, Spotify, TikTok, X and YouTube URLs are supported");
 }

package/src/spotify.ts

@@ -0,0 +1,271 @@
+import { browserUserAgent } from "./fingerprint";
+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 };
+
+/** Resolve Spotify track metadata and a matching video through YouTube. */
+export async function resolveSpotify(input: ResolveContext): Promise<PlatformResult<"spotify", SpotifyExtra>> {
+  const url = asUrl(input.url);
+  const id = url.pathname.match(/^\/(?:intl-[a-z-]+\/)?(?:embed\/)?track\/([A-Za-z0-9]{22})\/?$/i)?.[1];
+  if (!id) {
+    throw new PostfetchError(400, "Spotify requires an open.spotify.com track URL");
+  }
+  const track = await spotifyTrack(input, id);
+  const { youtube, youtubeUrl, liveFallback } = await matchingYoutube(input, track);
+  return {
+    archiveFilename: filename(`spotify_${id}.zip`),
+    comments: [],
+    id,
+    items: youtube.items,
+    platform: "spotify",
+    metadata: {
+      title: track.title,
+      author: { name: track.artists.join(", ") },
+      extra: {
+        artists: track.artists, durationSeconds: track.durationSeconds, youtubeUrl,
+        ...(liveFallback ? { youtubeLiveFallback: true } : {}),
+      },
+    },
+  };
+}
+
+async function spotifyTrack(input: ResolveContext, id: string): Promise<Track> {
+  const response = await input.net(`https://open.spotify.com/embed/track/${id}`, {
+    headers: { "user-agent": browserUserAgent() },
+  });
+  if (!response.ok) {
+    throw new PostfetchError(response.status === 404 ? 404 : 502, `Spotify track lookup failed: ${response.status}`);
+  }
+  const html = await response.text();
+  const raw = html.match(/<script\b[^>]*\bid=["']__NEXT_DATA__["'][^>]*>([\s\S]*?)<\/script>/i)?.[1];
+  const payload = parseJson(raw);
+  const props = payload && object(payload.props) ? payload.props : null;
+  const page = props && object(props.pageProps) ? props.pageProps : null;
+  const state = page && object(page.state) ? page.state : null;
+  const data = state && object(state.data) ? state.data : null;
+  const entity = data && object(data.entity) ? data.entity : null;
+  const title = entity && (string(entity.title) ?? string(entity.name));
+  const artists = entity && Array.isArray(entity.artists)
+    ? entity.artists.filter(object).map((artist) => string(artist.name)).filter((name): name is string => name !== null)
+    : [];
+  if (!entity || entity.type !== "track" || entity.id !== id || !title || artists.length === 0) {
+    throw new PostfetchError(502, "Spotify track metadata not found");
+  }
+  const duration = number(entity.duration);
+  return { title, artists, durationSeconds: duration !== null && duration > 0 ? duration / 1000 : undefined };
+}
+
+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", 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() },
+  });
+  if (!response.ok) {
+    throw new PostfetchError(502, `YouTube search failed: ${response.status}`);
+  }
+  const html = await response.text();
+  // 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 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");
+  }
+  return videoRenderers(payload.contents);
+}
+
+function videoRenderers(value: unknown): Json[] {
+  if (Array.isArray(value)) return value.flatMap(videoRenderers);
+  if (!object(value)) return [];
+  if (object(value.videoRenderer)) return [value.videoRenderer];
+  return Object.values(value).flatMap(videoRenderers);
+}
+
+function text(value: unknown): string {
+  if (!object(value)) return "";
+  return string(value.simpleText) ?? (Array.isArray(value.runs)
+    ? value.runs.filter(object).map((run) => typeof run.text === "string" ? run.text : "").join("")
+    : "");
+}
+
+function normalize(value: string): string {
+  return value.normalize("NFKD").replace(/\p{M}/gu, "").toLowerCase().replace(/[^\p{L}\p{N}]+/gu, " ").trim();
+}
+
+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);
+}
+
+// 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 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;
+  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));
+  const delta = track.durationSeconds === undefined ? 0 : Math.abs(duration - track.durationSeconds);
+  if (delta > tolerance) return -Infinity;
+  // Do not silently substitute a different recording or speed edit. Artist names
+  // 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, "");
+  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 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 {
+  try {
+    const parsed: unknown = JSON.parse(value ?? "");
+    return object(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseAssignment(value: string | undefined): Json | null {
+  if (!value) return null;
+  // Balance braces outside JSON strings so titles containing `};` cannot truncate
+  // the payload, and trailing statements in the same script are ignored.
+  let depth = 0;
+  let quoted = false;
+  let escaped = false;
+  for (let index = 0; index < value.length; index += 1) {
+    const character = value[index];
+    if (quoted) {
+      if (escaped) escaped = false;
+      else if (character === "\\") escaped = true;
+      else if (character === '"') quoted = false;
+    } else if (character === '"') quoted = true;
+    else if (character === "{") depth += 1;
+    else if (character === "}" && --depth === 0) return parseJson(value.slice(0, index + 1));
+  }
+  return null;
+}