Table of contents¶

VeeJay does three things:

It synchronizes music video and music audio playlists across as many platforms as possible.
It downloads the matching music videos with yt-dlp and the matching music audio from SoulSeek with slskd.
It gives you a rich, graphical artist portal, with links to each artist's own website and all of their social media.

The documentation follows those three purposes. It first explains how VeeJay sees music, then takes each purpose in turn, then covers what they all rest on: the research that identifies artists and songs, the library on disk, the database, and the application itself.

The documentation is arranged in categories. Each category is a group of chapters, and each chapter is one page. A chapter is listed here as soon as it is planned and becomes a link when it is written.

Status: planning. Every chapter below is planned and none is written.

1. Introduction¶

Chapter	What it covers
1.1 What VeeJay is	VeeJay in one page: what it does for a person who loves music videos.
1.2 The three purposes	Playlist synchronization, downloading, and the artist portal, and how they depend on each other.
1.3 Who it is for	The person VeeJay is built for and what they already use (YouTube, Plex, a music library).
1.4 Key words	The words the documentation uses on purpose: artist, song, video, audio, Primary, platform, library, verified.

2. How VeeJay sees music¶

The concepts every other category relies on, explained without any technology.

Chapter	What it covers
2.1 Artists, groups and their relations	A person, a group, its members, a backing band, a side project, an alias.
2.2 Songs, albums and collections	A song as one recording, filed under its original album, or under a film, show or game.
2.3 Videos and their roles	The Primary and the Alternates, covers, live versions, remixes, lyric videos and other kinds.
2.4 Audio and files	The audio that matches a video, and a file as a physical copy of either.
2.5 Identity and trust	What it means for VeeJay to be sure who an artist or a song is.

3. Playlists and platforms¶

Purpose 1: keeping playlists the same everywhere.

Chapter	What it covers
3.1 What a synchronized playlist is	One playlist, its copies on each platform, and what "the same" means.
3.2 Supported platforms	Each platform VeeJay can synchronize with, what each one can and cannot do, and how more are added.
3.3 Matching a song across platforms	How one song is recognized as the same song on every platform.
3.4 Directions, changes and conflicts	Which way changes flow, what happens when two copies change, and how removals are handled.
3.5 Video playlists and audio playlists	How a music video playlist and a music audio playlist relate to each other.
3.6 Likes	How a thumbs-up or a thumbs-down becomes a change to the playlists.
3.7 Sign-in, limits and quotas	How VeeJay signs in to each platform and keeps within each platform's limits.

4. Getting the videos¶

Purpose 2, first half: downloading the music videos with yt-dlp.

Chapter	What it covers
4.1 Finding the right video	Choosing the Primary among the videos of one song, and keeping the Alternates apart.
4.2 Downloading with yt-dlp	Quality, formats, captions and what is saved with the video.
4.3 Videos that are gone	Deleted, private and blocked videos, and how they are reported.
4.4 Idents and other pieces that are not songs	MTV idents, bumpers and promos, which are kept apart from songs.

5. Getting the audio¶

Purpose 2, second half: finding the matching music audio on SoulSeek with slskd.

Chapter	What it covers
5.1 Finding audio on SoulSeek	Searching through slskd, choosing among results and what is refused.
5.2 Checking it is the right recording	Comparing the audio with the recording it should be, so a wrong file never enters the library.
5.3 Quality and the better copy	How two copies of the same song are compared, and which one is kept.
5.4 Converting, tagging and lyrics	The final format, the tags written and the synchronized lyrics.
5.5 Pairing audio with video	Why a song's audio and video share one name, and what pairs them.

6. The artist portal¶

Purpose 3: a rich, graphical page for every artist.

Chapter	What it covers
6.1 The artist page	What an artist's page shows and how it is laid out.
6.2 Websites and social media	The official website and every social account, each shown only once it is verified.
6.3 Discography and videos	The artist's albums, songs and videos, with artwork.
6.4 Members, bands and relations	Who was in which group, and which bands are side projects of which.
6.5 Browsing and discovery	Searching, filtering and moving between artists, songs and albums.
6.6 Correcting what is shown	How you fix a wrong link or a wrong fact, and what VeeJay does with the correction.

7. Research and verification¶

How VeeJay finds out who an artist and a song really are.

Chapter	What it covers
7.1 Search first	Why every artist and song starts with a web search, and what a search result is trusted for.
7.2 The chain of trust	Anchors, links from verified pages, and what makes a fact verified.
7.3 The identity score	The score out of 100, what counts toward it, and what the levels mean.
7.4 Sources and authority	Which source wins when two disagree.
7.5 Needs attention	What VeeJay asks you, and how each question is answered.

8. The library on disk¶

Chapter	What it covers
8.1 The library folder	The VeeJay folder and what is inside it.
8.2 Names and folders	File and folder names, and what happens to characters a file name cannot hold.
8.3 Tags	Every tag written to the audio and video files.
8.4 NFO files and Plex	The NFO files and how Plex reads the library.
8.5 Adopting existing files	How VeeJay takes in the files you already have.
8.6 Keeping copies in step	The facts kept about every file so that copies on different devices can be compared exactly.

9. The database¶

The design of the database, from the meaning of the data down to the tests that prove it.

Chapter	What it covers
9.1 The data model	The things VeeJay knows about and how they relate.
9.2 The data dictionary	Every field: its name, definition, purpose, type, tags and rules.
9.3 Reference data	The fixed lists: countries, choices and the outside identifier formats.
9.4 The physical schema	How the design is stored in SQLite, and how each rule becomes a constraint.
9.5 Migrations	How the structure changes over time without losing control of it.
9.6 Rules and tests	The catalog of rules and the tests that try to break each one.
9.7 The database and the files	Why the database is the source of truth, and what happens when a file disagrees.

10. The application¶

Chapter	What it covers
10.1 The big picture	The parts and how they fit together.
10.2 The back end	The server program, its modules and how it talks to outside services.
10.3 The front end	The screens and the technology behind them.
10.4 Background work and recovery	The job queue, resuming after an interruption and safe repeats.
10.5 Settings, secrets and backups	Where private information lives, how backups work and what is cached.
10.6 Signing in and the API	Who may use VeeJay, and the interface other programs use.
10.7 Testing and quality	The layers of testing and how a change is accepted.

11. Services VeeJay talks to¶

One chapter for each outside service or group of services.

Chapter	What it covers
11.1 YouTube and YouTube Music	Likes, playlists, video details and the daily quota.
11.2 Apple Music, Spotify, TIDAL and other platforms	What each platform's interface allows.
11.3 MusicBrainz, Wikipedia and Wikidata	The sources of identity and release facts.
11.4 Search engines	How the web searches are made and kept within each engine's limits.
11.5 yt-dlp and ffmpeg	The tools that download and convert video and audio.
11.6 slskd and SoulSeek	The tool that searches and downloads audio.
11.7 Lidarr	Reading the existing catalog and adding artists.
11.8 Lyrics and cover art	The lyrics providers and the cover art archive.
11.9 Plex and Discord	The media server and the optional notifications.

12. Delivery and business¶

Chapter	What it covers
12.1 Installing VeeJay	The supported ways to run it.
12.2 Updating and rolling back	How a new version reaches you and how to go back.
12.3 The name and the look	The name, the logo and the visual style.
12.4 Licensing and cost	How VeeJay is licensed and what it costs to run.

13. Decisions¶

Chapter	What it covers
13.1 The decision log	Each decision, its reason, the alternatives rejected and what it affects.