Exporting music

Exporting gets music and its metadata back out of Tunetorch: for a backup, for the MP3 player in the car or for another Tunetorch instance.

You need the Export permission for it. Only admins may start the export of the whole database.

The normal export is free. ZIP and a folder on the server, original or converted, with cover art and companion files: you don't need a subscription for that, and you can get your music back out at any time. Two variants belong to Tunetorch Pro: the .ttdb and the export of the whole database. Both are convenient ways to move an entire collection including the music in one file. The slim .ttdbl (information without music) explicitly stays free. With it you pass on carefully kept information, and that shouldn't depend on a subscription.

Starting an export

You start an export where the music is: via the Export audio entry in the options menu (⋮) of an album or artist. The source and the name of the export (the artist or “Artist - Album”) are then already filled in.

You export a playlist from the playlist manager: in its detail view, Export audio sits in the options menu (⋮) next to “Replace queue”. That works for your own playlists and for public ones. The tracks end up in the chosen folder structure like in any other export, each one only once. On top of that there's a <name>.m3u8 in the top folder: it plays the tracks in the playlist's order in any common player (VLC, foobar2000, Kodi, many car stereos), as long as the folder stays together.

You get an overview of running and finished exports via the Audio export entry in the user menu. That's also where you set how the export is done.

The options

Audio

Hi-res sources above 48 kHz are cleanly downsampled first for MP3 and AAC. Lossy formats gain nothing from hi-res at a limited bitrate.

Scope (artist export only)

Cover art

• Size: Original, L, M, S or none
• Format: JPEG (default, plays in every player) or the source format

Folders and file names

There are two templates:

Artist/Year - Album/No - Artist - Title        (with an artist folder)
Artist - Year - Album/No - Artist - Title      (without an artist folder)

For albums with several CDs the CD number comes before the track number, for example 1-01 - Artist - Intro and 2-01 - Artist - Intro. If a box set has ten CDs or more, the CD number gets a leading zero too (01-01 … 12-01) so the order in the file manager is right. If two tracks would still end up with the same name, say two albums with the same title from the same year, the later one gets a “(2)” after the track title. If the track title is so long that the file name hits the length limit, the title is shortened to make room, and the number stays. No track overwrites another. If even a fully shortened title leaves no room, because the artist alone fills the file name, the export stops with a note naming the track.

On top of that you choose the target system for the file and folder names. There are three levels, and each higher one also does everything the lower one does:

• None: the names stay as they are.
• Linux / macOS: additionally, the backslash \ is replaced.
• Windows / NAS / USB: additionally, < > : " | ? *, reserved device names (CON, NUL, COM1, …) and trailing dots and spaces are replaced, and the path length is limited.

Choose “Windows / NAS / USB” if the files are going onto a NAS, a Windows computer, a USB stick or a car stereo. A NAS share is almost always a Windows share (SMB). An album with a colon or question mark in its name can't be stored there otherwise, even though the export itself ran without errors.

“None” doesn't mean “nothing at all”. Four things happen at every level, because the file couldn't be created otherwise: the slash / is replaced, since it separates folders (“AC/DC” would otherwise become a folder “AC” with a file “DC”). Control characters are dropped, . and .. as a whole name become _, and very long names are shortened. So the difference between “None” and “Linux / macOS” is exactly the backslash. On Linux it's a perfectly normal character, but when copied to Windows the name falls apart into folders at that point.

Exporting tags along

Tunetorch appends the tags to the names in square brackets: album tags to the album folder, a track's tags (its own and those inherited from the album) to the file name:

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

If a very long track name hits the length limit for file names, the name in front is shortened and the brackets stay at the end. That's the only place where an upload finds them again.

They're also stored invisibly in the music file's metadata. There they survive any renaming.

Each of the two ways has its own switch, and both are preselected:

• “Write tags into the audio file's metadata” – invisible, file names stay unchanged. This only works with MP3, FLAC, Ogg and Opus; other formats such as M4A have no custom tag fields.
• “Append tags to folder and file names” – the square brackets shown above.

Switch the brackets off if you're syncing into a folder that already contains an earlier export. Otherwise all the file names change and you have every piece twice. If you leave the metadata switch on, the files still keep their tags. With both switches off, the tags are only in the companion text file and in the Tunetorch database.

That an album tag is on every file is intentional. That way even a single file copied out on its own keeps its “Live” label. When uploading, Tunetorch recognises the brackets again, and a tag that all tracks of an album have becomes an album tag there again instead of twelve separate track tags (see Adding music).

Companion files per artist

Collaboration albums

If you export an artist, their collaboration albums come along too, even if they're filed under the partner.

What counts here is the artist line, not the section on the profile. Every album on which the artist appears in the artist line is included, even if that only applies to a single track. On their profile, on the other hand, a record like that is listed under Guest appearances, because it isn't a collaboration throughout.

Out of the box, such albums go into a folder of their own with both names (“Beth Hart & Joe Bonamassa”). There's a reason for that: this way the record exists only once, even if you export both artists one after the other into the same target folder. Alternatively, you file them under the exported artist.

In the music file, the combined name is in the ARTIST tag, and the individual names are also in ARTISTS. With a later import, the people involved can be told apart again.

Guest appearances only come along with the “Every track by the artist” scope and don't change the folder.

A guest isn't in the ARTIST tag. It would appear twice there, because record labels almost always include it in the track title already. That's why there's a separate tag next to it, TT_GAESTE, which says which names from ARTISTS were guests. Only that way does the role come back correctly when the files are read in again. M4A can't store this tag (there the cover art takes precedence; see below). M4A files therefore only contain the names from the artist line, and the guests are only in the Tunetorch database.

Which tags are written

title, artist, album, album_artist, track, date, genre, composer, disc and comment (with the shared note). Plus your private note in a tag of its own. That's only ever your own, never those of other accounts, and only in formats that can store tags of their own (with M4A the cover art takes precedence instead).

The track's Tunetorch tags are also stored in a tag of their own (TT_TAGS, own and inherited together), provided “Write tags into the audio file's metadata” is on. These are missing from M4A too.

Tracks with several people involved also get ARTISTS (all names) and TT_GAESTE (which of them are guests). The details are under Collaboration albums.

album_artist is always set, even if you haven't entered a separate album artist in Tunetorch. It then holds the artist the album is filed under. For a collaboration album it's the shared credit, for example Beth Hart & Joe Bonamassa. Many players and media servers group albums by this field. Without it, an album with one differing track easily splits in two there.

The output

The Tunetorch database (.ttdb)

It contains all of the artist's tracks as originals plus all the information: artist, artist image, biography, line-up, cover art and tags. Everything is in one file, together with a note of who created it and when.

It's meant for passing on and for importing into another Tunetorch instance later. If you choose it, the settings for audio quality, cover art, folders and names don't apply, because everything is stored in the database as the original.

You need an active Pro subscription for it. Without Pro the option is marked and can't be selected. ZIP and a folder on the server work as usual.

What doesn't come along: anything tied to a user account, that is private notes, favourites, playlists, audiobook progress and playback history. This data belongs to your account on this server and couldn't be assigned to any account on another server. If you pass the file on to someone else, it doesn't belong there anyway. The play counts stay here too, because they describe how often something was listened to on this server.

Of the tags, only the name travels, not the colour. If the same tag already exists on the other server, it keeps its colour there.

The .ttdbl from the companion files is the slim variant: the same information, but without the music. It can be imported too and then adds biography, images and line-up to an artist. It can't create new tracks, because the music is missing.

Exporting the entire music database

Only the admin starts the export of the whole library: Server settings → Export sessions → Export the entire music database. There's a small form for it:

If an export runs twice under the same name, the server appends a number (… (2), … (3)). An existing copy is never overwritten.

The output is always a folder on the server. A ZIP file of the whole library would be too big to download sensibly, and whoever is allowed to start this export has access to the server anyway.

Interrupted exports

An export can take hours and doesn't survive every disruption. Tunetorch is prepared for that:

• The server notices by itself when an export has broken off, and resumes it, at start-up and after that every few minutes while it's running. Tracks already exported are skipped, so it doesn't start again from zero.
• You can also set interrupted or failed exports going again by hand with Resume.

It can take a few minutes before the server picks an export up again. It first waits to see whether the export still reports in before treating it as broken off. Otherwise two exports would run into the same files at the same time.

Export sessions are not cleaned up automatically. They stay until you delete them in the export view (or an admin does so in the server settings). A scheduled clean-up would be too risky with runs lasting hours.

Storage space and limits

Before starting, Tunetorch estimates how much space the export needs and only begins if it's free. A ZIP counts double, because the folder and the archive briefly sit side by side while packing. Right before packing it checks again with the real size; if that isn't enough, the export stops at Error and can be resumed once you've freed space. That way the memory card, which also holds the database, doesn't run full.

If you're not an admin, you can run one export at a time and keep at most ten exports on the server. For a new one, delete an old one first.

Importing a Tunetorch database

You can also read a .ttdb or .ttdbl back in, for instance on another server, after a move, or when someone sends you their carefully kept data.

Two ways in. On an artist's page, you import a file directly to that artist, via Import database in the options menu (⋮) next to their name. If the artist doesn't exist on your server yet, go via Upload in the profile menu. No artist is needed there. The Import database button is below Start a new upload session.

Who may import what. Both formats write information into your library and therefore need the Music metadata permission. A .ttdb also creates new tracks including the music and needs Upload audio for that as well. Anyone who may only curate metadata can therefore only import .ttdbl files (and under Upload also only sees the import, not the audio upload).

Limits for files from elsewhere. A file that can't be read is rejected with a message. That applies to damaged files and to files containing more text than a Tunetorch database can have. Tags from the file arrive with at most 50 per track or album; names longer than 100 characters are skipped. Once your library already has 1,000 tags, the import doesn't create any new ones and only assigns existing ones.

The assistant decides nothing on its own

After uploading, you see what's in the file and what of it you already have. Everything is preselected, but nothing is overwritten without you:

• If something is missing on your side that's in the file, for example a comment on a track you already have, it's added.
• If you both have something different, your version stays. You see both side by side and decide.
• For an entry you can also take everything from the file, replacing your own state.
• If an artist, album or person is only “probably present” because the name is merely similar (“Greatest Hits Vol. 2” next to your “Vol. 1”), the choice is set to Create new. Only when you pick Same as “…” does the content go to the existing entry. If you turn down an artist, its albums don't go to the artist the assistant had guessed either.

The number at the top only shows the points where you really have to decide. The rest simply goes through.

How it recognises what you already have

Artist, album and track are compared by their names. Upper and lower case, accents and punctuation don't matter, and an addition such as “(Remaster 2014)” is skipped. Additions such as “(Live)” or “(Acoustic)”, on the other hand, are not, because those are separate recordings.

The playing time counts as well. Two tracks with the same name but clearly different lengths aren't automatically treated as the same. That way a live version is never mistakenly classed as “already there”. In such cases the assistant asks.

If you run the same import twice, nothing happens the second time, because everything is already there.

Large files

The file is uploaded in pieces, and the upload can be resumed. If the connection drops at 6 GB, it carries on at the same point instead of from the start. An import that's interrupted halfway through can be resumed too, without tracks being created twice.

During the import, the uploaded file sits next to the tracks created from it. So before every audio file Tunetorch checks whether there's still space. If there isn't, the import pauses with a notice instead of filling the memory card; once you've cleaned up, you resume it.

Closing deletes nothing. An unfinished import stays on the server, even when you close the dialog. The next time you open Import database, it's listed at the top under Unfinished imports: you resume an interrupted upload by choosing the same file again; the parts already transferred aren't sent again. A fully uploaded import takes you back to the selection, an interrupted one can be resumed. If you need the space, Discard removes the import and its file, after asking you first.

Restricted accounts

Accounts with restricted access automatically only export the tracks that have been shared with them.

Where to go next

• Managing metadata
• Security & backup