Skip to content

ADR-0007: Exact YouTube Video ID Resolution

Status

Accepted

Date

2026-08-12

Context

Every download runs through YouTube: Spotify tracks must be matched to a YouTube video, and YouTube Music playlist tracks are YouTube videos already.

The pre-rewrite code asked yt-dlp to search, downloading ytsearch1:{query} with a query built as "artists - title". Letting the downloader search had three problems:

  1. Wrong-result risk. A search can return a cover, a live recording, a remix or a re-upload instead of the intended track.
  2. Non-determinism. Search ranking changes over time; the same input can produce a different track later, and results are not reproducible or testable.
  3. Search traffic. Every new track costs a search round-trip, even when the correct video is already identifiable from track metadata.

Spotify tracks carry enough metadata (title, artists, album, and crucially the ISRC) to be matched to a specific YouTube video by spotdl's matcher. YouTube Music tracks need no resolution at all — their playlist entries already contain the video ID.

Decision

  • Download by exact video ID. yt-dlp is always given a concrete video_id, never a search query.
  • Spotify tracks are resolved via spotdl's matcher (Song.from_missing_data + YouTubeMusic().search()), using the track's metadata and ISRC.
  • YouTube Music tracks are downloaded directly with their own video ID.
  • A Spotify track that cannot be resolved is skipped, not downloaded.

Using spotdl's matcher rather than hand-rolling matching was chosen because it is the proven reference implementation for exactly this problem (cited in ADR-0001) and requires far less code to integrate.

Consequences

Positive

  • Correctness: the exact video is always downloaded; a wrong version cannot silently replace the intended recording.
  • Determinism: resolution is reproducible, and the download step is a simple, testable function of a video ID.
  • Zero resolution cost for YouTube Music tracks.
  • Simpler yt-dlp invocation: no search-query construction or parsing.

Negative

  • A Spotify track the matcher fails to resolve is dropped, even when the recording does exist on YouTube. A search fallback could recover these cases but would reintroduce the wrong-result risk and search traffic; it is not implemented.

Neutral

  • Correctness now depends on spotdl's matcher internals, which does its own YouTube search per unmatched track.

Alternatives Considered

Let yt-dlp search (the old approach)

Rejected: non-deterministic, wrong-version risk, extra search traffic per track.

Fall back to ytsearch1: when the matcher finds nothing

Considered: would rescue obscure or mis-tagged tracks ("everything is on YouTube"), but reintroduces the wrong-result risk the exact-ID approach eliminates. Currently skipped; a possible future enhancement.

Hand-rolled matching

Rejected: more code to write and maintain for a problem spotdl already solves.