Skip to content

04. Getting the videos

Finding the right video for each song, and downloading it.

4.1 Finding the right video

Every song has one Primary video. Among the videos of a song, VeeJay ignores lyric videos, visualizers and audio-only uploads unless one of those is all there is. It then chooses in this order:

  1. An official video wins, and the most-viewed official video is the Primary. A video is official when it is any of these:
    • the music video that the song's Wikipedia article names,
    • the video that IMVDb names as the song's primary video, when the artist has an IMVDb entry,
    • an upload from the artist's or record label's own channel whose title says Official Video or Official Music Video, or whose description is the label's line "Music video by artist performing song".
  2. When none is official, the best picture wins. The highest resolution of the downloaded files decides, then the most views. Until the versions have been downloaded, the song is marked Primary pending.
  3. When the indicators disagree, VeeJay lists the song for you with the evidence, and you decide.

Search never sets a Primary. It only supplies evidence of an official video.

When the Primary changes

The old Primary becomes an Alternate. Its other choices (origin, performance, version and so on) do not change, because a live video and a cover are different content and not rivals for the Primary.

A second video of the same song

When another video of a song that already has a Primary is added, VeeJay compares the two. A true duplicate, such as the same video uploaded again, is not kept twice: the better file stays and the other goes to the Trash. A video that is genuinely different, such as another cut or a version made for another country, is kept as an Alternate.

4.2 Downloading with yt-dlp

  • Resolution. VeeJay downloads the highest resolution that YouTube offers, with the best audio available.
  • Container. Every video is an MP4 file, and its extension is changed to .m4v.
  • Captions. English closed captions are embedded in the video. Manual captions are taken first and automatic captions second. A video with no captions is still downloaded: missing captions never fail a download.
  • One at a time. Videos are downloaded one at a time, with a pause between each, and a record is kept of what is done so a run can resume after an interruption.
  • Named and tagged from the row. Each video is named and tagged only from its database row, then filed, and its path is written back to the row. A video with no verified row is not downloaded.
  • Collisions. When a file with the same name already exists, the better file wins: the better resolution, then the better audio, then the larger file. The loser goes to the Trash and is logged. It is never deleted outright.

Every video that is not a Primary has a role of Alternate and is downloaded in the same way. Only the Primary gets audio.

4.3 Videos that are gone

A video that is deleted, private or blocked gets no row and no field. It is listed in a report instead, so nothing in the library points at something that cannot be played. A video that appears twice in a playlist gets one row.

4.4 Idents and other pieces that are not songs

MTV's own pieces (idents, bumpers, promos, top-of-the-hour broadcasts and excerpts) are kept in a separate table and are never mixed with songs. Each has a title and a year, and a category: Ident, Bumper, Promo, Top Of The Hour, Broadcast Excerpt or Outro.

  • File names are MTV - Year - Category - Title, built from the row.
  • No duplicates. Each ident is held once. Two videos are duplicates only when the evidence shows the same piece: the same name, the same year or an unknown one, and about the same length. A different cut, length or version is not a duplicate. When duplicates are found, the best version is kept: the more complete one first, then the better quality, then the one with more views. A removed video is remembered, so a later run does not add it back.