Adding music

There are four ways to get music into Tunetorch. You can combine them however you like, for example by importing an existing collection first and then carrying on with uploads.

WayWhat forWhere are the files afterwards?
UploadFor everyday use: single albums or folders from your computer.Managed by Tunetorch (/app/data/audio).
Collection importFor moving an existing collection over once.As a copy managed by Tunetorch. The original stays unchanged.
Rip CDsFor CDs from the shelf, with a drive attached to the server.As FLAC, managed by Tunetorch.
Library scanFor a music folder that should stay where it is.In their original place. Tunetorch only reads.

Uploading

Accounts with the Upload audio permission can upload, and of course admins. You'll find it under Upload in the profile menu. On the same page, below it, is the Import database button, which reads in a Tunetorch database you've brought along (see “Export & import”). That's why the entry is called “Upload” and not “Upload audio”.

  1. Drag files or whole folders into the upload area.
  2. Tunetorch sorts them into an album table and reads the existing tags.
  3. Correct the metadata in the table: artist, album artist, album, title, year, genre, track and disc number, composer. You set the album cover art for the whole group at once.
  4. Add to the library: Tunetorch writes the tracks to the database.

An upload is a session. You can close it and continue editing later. Adding the tracks to the library runs in the background with a progress display, so you're free to close the app in the meantime.

If adding the tracks does get interrupted (by a server restart, for example), the session shows Interrupted. Tracks that were already added stay in the library. The server carries on by itself, at the next start and after that at regular intervals while it's running. Resume sets it going straight away. No duplicate tracks are created.

Tags from file names

When uploading, Tunetorch reads tags from two sources: from the file's metadata (TT_TAGS, written by a Tunetorch export) and from square brackets in file and folder names.

Philip Sayce/2016 - Scorched Earth, Vol.1 [Live]/01 - Powerful Thing [Live].flac

What's on the album folder applies to the album. What's on the file name applies to the track. If all tracks of an album have the same tag, it becomes an album tag instead of twelve identical track tags. That way an export comes back in exactly the way it went out (see Export & import).

Only what's at the end of a name is read. “Live at Wembley [1985] Remaster” keeps its brackets. Otherwise the upload would take apart every name that happens to contain a bracket somewhere.

Unknown names aren't simply created. If the brackets contain something that doesn't exist as a tag in your library yet, the upload editor asks. You get a list of what it found, each with a checkbox. Whatever you tick is created as a new tag and assigned. Whatever you don't tick stays in square brackets as part of the track or album name. Nothing is preselected, so that “[Deluxe Edition]” doesn't turn into a tag without you being asked. If the name already carries the bracket because the folder is named just like the album, it isn't added a second time.

Setting tags while uploading

You can assign tags right in the upload editor. You don't have to add the tracks first and then switch to the metadata editor:

You choose from the existing tags in your library. Only the admin can create new tags (in the server settings), or you confirm something found in square brackets (see above). Album tags appear only once, in the album header, and not in each of the twelve rows. They're left out of the selection menu of the individual rows, so the same tag doesn't end up on the same track twice.

What you set yourself, Tunetorch leaves alone. The rule “a tag on every track becomes an album tag” only applies to tags that were detected automatically. As soon as you've set tags yourself in an album, they stay exactly where you put them.

A Tunetorch database in the folder

If the uploaded folder contains a .ttdbl or .ttdb (an export normally puts it next to the music), Tunetorch does not upload it as audio. That would only produce an error message. Instead it offers it to you: “The uploaded folder contains a Tunetorch database … Import now”. The button opens the import assistant with this file, so you don't have to look for it again.

The import is a separate step with its own confirmation. It writes biographies, images and line-ups, and that shouldn't happen on the side during an audio upload.

Before the upload, the server checks that there is enough free storage space for the file. After a successful import it deletes the uploaded file again; the report stays. If a track failed, the file stays for another attempt until you close the session.

Metadata normalisation

The upload editor has a switch for normalisation. It capitalises every word and removes characters that cause trouble in file names (\ / : * ? " < > |). Which rules apply to which field is set by the admin under Server settings → Normalise metadata, separately for artist, album artist, title, album and genre.

Two corrections belong to no rule and therefore always apply: double spaces and spaces at the start or end are removed, and an accent used instead of an apostrophe (´ or `, typical of compilation rips) becomes '. A typographic ’ stays as it is. When music is added to the library, Tunetorch removes surplus spaces even with the switch off — otherwise “Tabaluga ” would sit next to “Tabaluga” as a second artist.

For the same reason Tunetorch doesn't create a second artist if the name already exists in exactly one other spelling: “Lmfao” ends up with “LMFAO”, “Celine Dion” with “Céline Dion”, “Simon and Garfunkel” with “Simon & Garfunkel”. The comparison ignores upper and lower case, accents, apostrophes and punctuation. If several entries match, nothing is guessed and a new one is created. The same applies to the collection import, CD ripping and scanning.

The same rules are used later by the metadata assistant to find mismatches in the existing library (it belongs to Pro). The rules themselves always apply, so during upload they work without a subscription too.

Conversion on upload

For lossless raw formats (wav, aiff), the upload asks in a drop-down: keep them as they are, convert to FLAC (lossless, much smaller) or convert to Opus. FLAC files are always kept as they are; there's nothing to gain.

When adding the tracks, Tunetorch strips the tags from the file and keeps the metadata in its database. In addition, it stores a metadata backup as a text file next to each original file, as a safety net for emergencies.

Collection import

This is the most convenient way if you already have a large, well-kept collection.

Mount it read-only during setup:

    volumes:
      - ./tunetorch-daten:/app/data
      - /path/to/your/collection:/app/import:ro

As long as this folder is mounted, an import box appears at the very top of the server settings. One click takes all the audio files it finds into Tunetorch's management: the files are copied into the data directory, the tags are cleaned up, artist, album, track and cover art are created from the tags, and the loudness is measured.

This is how the import behaves:

After the import you can unmount the folder again.

Ripping CDs

If a CD drive is attached to the server (built in or via USB), Tunetorch reads audio CDs straight into the library. The tracks are checked as carefully along the way as good ripping programs do on a computer, and end up in the library either losslessly as FLAC or, to save space, as Opus, MP3 or AAC.

Setting up (once, as an admin)

  1. Pass the drive through to the container: for that you add a few lines to the docker-compose.yml; see Passing through a CD drive.
  2. Enable it under Server settings → Audio & playback → Rip CDs. It's off out of the box. When you enable it, Tunetorch asks first, because the check against AccurateRip opens a connection to the internet (see below). The check can also be switched off separately there.
  3. Grant the permission: whoever should rip needs the Rip audio CDs permission (Users & permissions).
  4. Enable the drive. A detected drive is only available for ripping once you enable it for ripping in the same section under Detected drives. Only enabled drives show up when ripping. If several are attached to the server, you enable exactly the ones that should be used; you can disable a drive again at any time.
  5. Set the read offset. Every drive model reads a few samples off. Without the right offset, AccurateRip can't confirm a rip. If a common commercial CD is in the drive when you enable it, Tunetorch detects the offset right away. Otherwise you let it be detected later with a known CD or enter it by hand (you'll find the value in the AccurateRip drive list). Only an admin may do this, because a wrong offset spoils every further rip without anyone noticing. If the inserted CD exists in several pressings, it matches several offsets. Then Tunetorch saves nothing and reports “several pressings”. With a second, different CD, the value that fits both is the one that remains.

Ripping

Insert an audio CD into an enabled drive, and Rip CDs appears in the user menu. After a few seconds the form appears there:

Start ripping reads the CD in two passes: in the test pass Tunetorch reads every track once, in the copy pass a second time, and compares both reads bit for bit. Because the whole CD is read and then the whole CD again, the drive's cache can't fake a second read. If AccurateRip knows the CD, Tunetorch also checks the copy against other people's rips. While ripping, the report shows where it is, for example Pass 1 of 2 — Test pass: Track 3 of 12.

A rip therefore takes about twice as long as a plain copy. That is intentional and can't be switched off: both passes run for every CD, so that every track reaches the library as accurately as possible. Tunetorch doesn't trade accuracy and audio quality for speed.

Once the CD has been read, the drive ejects it (checkbox Eject the CD after ripping, on out of the box), and it's free for the next one. If a track has remained uncertain, the CD stays in despite the checkbox, so you can re-read it right away.

The report

StatusMeaning
verifiedAccurateRip confirms it: others have read exactly the same data from the same CD.
consistentTest and copy are identical, but AccurateRip doesn't know the CD (or the check is off). Very probably error-free.
uncertainTest and copy differ, or the drive had to skip passages. Re-read tries again. Cleaning the CD first often helps.
ErrorThe track couldn't be read. Adding the tracks is then only possible after a confirmation and without this track.

Ripped CDs

A CD that has been read in full lands in the Ripped CDs list below the drive. It waits there with no time limit until you add it or discard it, just like an export. So you can insert and read several CDs one after another and go through the reports later at your leisure. A click on a CD opens its report.

Before adding the tracks, you choose under Save as how they go into the library:

The device remembers the format you chose last. Add to the library and delete the rip stores the tracks in the chosen format, measures the loudness and then deletes the raw rip data from the server. You no longer need the CD for that; it can long be back on the shelf. The rip log with all checksums is available for download once the CD has been read in full (next to the add button) and after adding.

When something gets in the way

AccurateRip and your privacy

The check is included without Pro too, because it safeguards quality and isn't a convenience extra. For it, the server asks accuraterip.com once per CD. All that's sent is the CD's ID, which is calculated from its table of contents. No titles, accounts or usage data go along. As long as nobody switches CD ripping on, this connection doesn't exist.

AccurateRip only offers unencrypted HTTP. Anyone who can read your traffic therefore sees the CD's ID and could fake the answer. That applies to every ripping program that uses AccurateRip. All it can achieve is wrong check results (the rating of the rip, the offset detection): Tunetorch follows no redirect and reads at most 1 MB of the answer.

Library scan

If your collection should stay where it is, perhaps because another program already manages it, mount it under /app/musik (always with :ro) and let Tunetorch scan it.

The scan detects new, changed and vanished tracks. You start it via Server settings → Maintenance & cron tasks → Scan the music library. It runs in the background, and new tracks appear without you having to reload the page.

The scan task is off out of the box. You only need it if you really have mounted an external folder. Switch it on in the same place when needed and choose an interval or a fixed time.

Good to know:

Taking scanned tracks into Tunetorch's management

A scanned track remains an external file. In the metadata editor, an admin can take it into Tunetorch's management with one click, converted to FLAC or Opus straight away if you like. The file is copied into the data directory, and the original path is left out of the next scan so that nothing shows up twice.

Supported formats

Tunetorch reads the common formats: MP3, FLAC, AAC/M4A, OGG, Opus, WAV, AIFF and WMA.

For playback, Tunetorch converts to Opus on the server when needed. Which version you hear depends on the quality level you've chosen (see Playback & audio quality). The original stays unchanged.

Afterwards

Freshly imported tracks often have inconsistent spellings, missing cover art or wrongly assigned compilations. That's what the metadata assistant and the metadata editor are for. The assistant finds the typical problems by itself and belongs to Pro. You can correct everything in the editor without it too.

Where to go next

Back to the documentation overview