08. The library on disk¶

Where VeeJay's files live, how they are named and tagged, and how copies are kept in step.

8.1 The library folder¶

VeeJay keeps the whole library in one folder named VeeJay. At setup you choose where it goes. Every audio file, video file and NFO file that VeeJay writes or adopts lives inside it, so the whole library can be found in one place.

VeeJay/
  ARTIST/
    YEAR - ALBUM/
      ARTIST - YEAR - ALBUM - 1-05 - TITLE.m4a      (or .flac)
      ARTIST - YEAR - ALBUM - 1-05 - TITLE.m4v
      ARTIST - YEAR - ALBUM - 1-05 - TITLE.nfo
  MOVIES/
  TELEVISION/
  VIDEO GAMES/

The audio, the video and the NFO file of a song sit side by side, with the same name apart from the extension. They are not kept in separate folders, so one folder can serve a Plex music library and a Plex video library at once, each reading the files it understands. Because everything is under one folder, only one folder has to be chosen at setup or mapped into a container, and free space is one pool.

8.2 Names and folders¶

Every file VeeJay creates is named from one row of the database. The pattern is:

ALBUM ARTIST - YEAR - ALBUM - DISC-TRACK - TITLE [DISAMBIGUATION] - TRACK ARTIST

The disambiguation and the track artist are optional.

The Primary has no label. The file name of a Primary video, and of its audio, never carries a disambiguation, even when one is stored. Only videos that are not the Primary carry the bracket.

Films, shows and games. A song from a film, show or game is filed under its title, which takes the place of the album artist, and the performer is shown at the end:

The Craft - 1996 - Music From The Motion Picture - 1-05 - How Soon Is Now - Love Spit Love

These songs live in their own top-level folders, MOVIES, TELEVISION and VIDEO GAMES. When a soundtrack's album title begins with the name of the film, show or game, that name is removed from the album part, because it already begins the name.

Characters. Some characters cannot appear in a file name, and they are replaced the same way every time: / becomes +, : becomes a comma, quote marks and question marks are removed, and an inch mark becomes in.

Clean names. The same rules apply to every name and name tag:

• Plain ASCII. Accents are removed, curly quotes and dashes become straight ones, and a character with no plain form is left as it is and listed for you.
• Capitals. Every word is capitalized. Stylized names (iHeart, k.d. lang) and acronyms and inner capitals (DJ, MTV, McCartney) are kept.
• Version labels in square brackets, never parentheses. A parenthetical that is part of a song's real title stays.
• Credits (feat., ft., with) are removed from the name and moved into the artists tag.
• Albums and folders are never merged. A rename whose new name already exists is skipped and reported.
• Empty folders are moved to the Trash after any move or rename leaves one behind.

8.3 Tags¶

The database is the single source of every fact. VeeJay writes the file names, the tags and the NFO files from it, so the three can never disagree. A tag is written only when its value changes, and the other tags in the file are left alone.

Standard tags are the ones players and Plex read, named as MusicBrainz Picard names them: artist, album artist, title, album, track number and total, disc number and total, date, original date and year, genre, lyrics, language, cover art, composer and credits, label, catalog number, ISRC and the MusicBrainz identifiers. Media Kind is written in MP4 files only. ReplayGain, BPM and key are estimates that VeeJay works out in a background pass, so they never delay a download.

The tags below are the ones the database defines, generated from the blueprint. A tag with no value is left off the file.

FLAC stores tags as plain NAME=value pairs. ALAC and M4V store the standard tags in fixed MP4 atoms and the others as free-form atoms. VeeJay keeps one list of tags and writes each to the right place in whichever format is in use.

The Wikipedia text. The opening paragraph of a song's Wikipedia article is Wikipedia's own text, published under the Creative Commons Attribution-ShareAlike license. Each file also carries the article's URL, so it credits its source. VeeJay copies the text only into your own files and never publishes or redistributes it.

8.4 NFO files and Plex¶

VeeJay writes an NFO file next to every video, with the same name as the video. It is generated from the same row as the tags and holds what Plex shows about the video: the title, the Wikipedia lead as the plot, the date, the genre and the artist. Plex reads NFO files in video libraries, so the videos belong in a Plex video library that reads them, and not in the music library, which ignores them.

8.5 Adopting existing files¶

Most people already have audio and video files before they install VeeJay. VeeJay can adopt them: it reads them, matches them to songs, and moves them into the VeeJay folder under the right names. It never does this on its own. Setup offers it, and you decide.

1. Scan. At your request, VeeJay scans the folders you point it to and reads each file's tags and name.
2. Match. Each file is matched to a song through MusicBrainz.
3. Preview. VeeJay shows what it found: how many matched, how many did not, and what it would rename and move.
4. Approve. Nothing moves until you approve.
5. Move. Each matched file is renamed and moved, and the song's rows are filled from what VeeJay learned.

A file that cannot be matched is left where it is. Every move is recorded so a migration can be reversed, a snapshot of the database is taken first, and moving between drives is a copy followed by a check and then a move of the original to the Trash. After an adoption, Plex libraries need to point at the VeeJay folder.

8.6 Keeping copies in step¶

Every file row records its size in bytes, the SHA-256 hash of its contents and its last-modified time, measured from the file itself when it is filed or replaced and measured again whenever the file changes. Two copies are treated as the same file only when the size and the hash match, and the modified time only tells which copy is newer.

A change is never replaced or removed without your approval, and every change is logged. Which device holds which file is not recorded yet. It is added when the synchronization feature is built.