Track versions

What track versions are for

Often you'll want to keep multiple takes of the same track on one page:

• The master + an instrumental version.
• The album mix + a radio edit.
• The pre-master + the final.
• Demo v1, demo v2, demo v3 as you iterate.

Track versions let one track row hold all of those takes, each with its own audio file and an optional note about what changed. We number them in the order you post them: v1, v2, v3, and so on. Nothing is overwritten, and the listener picks which one to play, right on the track page.

There's no limit on how many versions a track can hold. Each version's audio counts towards your storage space, so that's the only ceiling.

How to add a version

A version is posted on the track itself, on the same page as the waveform and the feedback. Open your track and choose Add the next version. On a wide screen it's in the ACTIONS menu at the top of the page; on a narrower one it's behind the ⋯ under the title. Your file picker opens straight away and there's nothing to fill in: the version takes the file's name, which you can change later. You can also drop the file anywhere on the page.

You see that option on your own track, and so does anyone you made a Collaborator in the track's circle. Once you put the track in your archive, new versions close until you Reopen it.

When the upload is done, the new version joins the list and plays the moment it's ready.

Two other doors take you to a two-step upload page instead, so you don't have to open the track first:

• The fixed address: app.soundassist.online/tracks/new-version. Two steps: pick the track you're iterating on, and the upload opens right there as step 2. It lists the tracks in Your sound and the ones your circles are running on.
• From your track list: in Your sound, click the ⋯ on the track row and choose Add a version. That opens step 2 straight away.

Choose your version or drop it onto the picker. On a slow connection an MP3 uploads much faster and works fine for a listening round.

That page asks a few optional things. What do you call this one? defaults to the file name. What stage is this? (Rough demo, Composition, Production, Mix, Stem mastering, Premaster, Master, or Custom for a word of your own) says where the track is in its life. What changed?, up to 200 characters, is the line people read when they open that version on the track page, so keep it short: "Removed sub-bass", "Vocal level adjusted", "Final master". Leave them empty and the version still has its file's name and its number, so you don't have to invent a label for every revision.

When that upload finishes we take you to the track, on the new version. Wherever you post it from, the version is added to the existing track; it doesn't create a new track row, and the share link you already sent out stays the same.

Everyone in the track's circle, plus anyone who asked to be kept posted on this track, gets an email that a new version landed.

Which version is the default?

The link plays the main version, and the list marks it main. That's the newest one until you pick another: open a version with Edit and choose Make this the main version. The link then keeps playing your pick until you post a new version yourself. The first time you add a version to a track, we file the original upload as v1 (with the note "First upload") so it stays in the list.

Version numbers follow the order you posted them, and we don't renumber or reorder them. What you can change afterwards is under each version's Edit on the track page: its name, its note (in your words), Mark as the one to show everyone which take you're going on with (the link still plays the main version), or Delete this version. The only version can't be deleted, and neither can the main one until another version is main. The audio itself and what we measured from it stay fixed, so the history stays honest: to change how the track sounds, post a new version rather than editing an old one.

Listener experience

On /listen/<token> the visitor lands on the main version, ready to play. Everyone with the private link sees the versions. How they look depends on the width of the screen:

• On a wide screen (1024 pixels and up), an A/B strip sits above the waveform, in the same card. Slots A and B each hold a version, and the one you're hearing is white. Click a slot to hear it; the ⌄ on a slot picks which version it holds. Click for A/B (or press X) flips between the two, and Same loudness sits beside it. The count at the end of the strip (12 ⌄ on a track with twelve versions) folds the list of versions open underneath.
• On a medium screen (640 to 1023 pixels), the versions are a list of rows above the waveform. Click a row to hear it. The list's header carries a small A/B pill and Same loudness.
• On a phone (below 640 pixels), the rows sit behind one chip that names the version you're hearing, like Version 3 · latest. Tap it and the versions slide up in a sheet, with the A/B pill in its header.

Each row shows the version's name and its number, and main marks the one the link plays. The newest three are open; older ones are one click away. Open a version (Edit on your own track, the ⌄ on anyone else's) to read its note.

A/B needs two versions. With only one, you and your collaborators still see the strip on a wide screen, where slot B reads Add the next version: the place the second one will stand. Everyone else sees no A/B until there are two.

A/B flips between the two at the same point in the track. When two versions can't be lined up, the page says so, and the switch keeps the timestamp rather than the moment in the music. Same loudness turns the louder versions down to the level of the quietest one, so you compare the work and not the level; when it can't match them, it says why.

Each version has its own address: add ?v=2 to the share link to send someone straight to that one.

The versions are part of the track, not a separate share.

API access (programmatic)

The version list is available via the API at:

GET /api/tracks/<id>/versions

Owner-only, authenticated with the same session token the app uses (as a Bearer header). There's no separate API key. It returns { versions: [...] }, newest first. Each row carries version_number, name, note, tags, phase, created_at, duration_sec, file_size, what we measured (bpm, musical_key, key_camelot, waveform_peaks) and the storage keys for the audio.

POST to the same path registers a version whose audio is already in our storage, so it takes the storage key rather than the file itself. PATCH and DELETE on /api/tracks/<id>/versions/<n> change a version's name or note, or remove it.