# Tracks
Source: https://docs.aden.space/docs/developers/concepts/tracks

The core unit of work in Aden. Versions, covers, collaborators, comments, todos, and release status.
A **track** is the central object in Aden. Everything else: albums, sessions,
chat, calendar, todos: eventually points back at a track. If you're building
on top of Aden, you'll spend most of your time here.

## What a track represents [#what-a-track-represents]

A track is one piece of music as it moves through the studio: from first idea,
through revisions and feedback, to a released master. It carries every artifact
needed to get there. Audio versions, artwork, collaborator splits, comments,
todos, and metadata.

Tracks belong to a **team** and can optionally be grouped into an
[**album**](/docs/developers/concepts/albums). A track without an album is a single.

## Data model [#data-model]

| Field                | Type             | Notes                                                              |
| -------------------- | ---------------- | ------------------------------------------------------------------ |
| `id`                 | `number`         | Stable numeric ID.                                                 |
| `title`              | `string`         | Display title.                                                     |
| `status`             | `TrackStatus`    | `idea`, `in_progress`, `mixing`, `mastering`, `ready`, `released`. |
| `team_id`            | `number`         | Owning team.                                                       |
| `album_id`           | `number \| null` | Album, if grouped.                                                 |
| `position`           | `string`         | Fractional index for ordering within team or album.                |
| `cover_url`          | `string \| null` | Original cover.                                                    |
| `cover_url_medium`   | `string \| null` | Resized variant for lists.                                         |
| `current_version_id` | `number \| null` | The version surfaced as "the track right now."                     |
| `created_at`         | `string`         | ISO 8601.                                                          |
| `updated_at`         | `string`         | ISO 8601.                                                          |

A track owns these sub-resources:

* **Versions**: every iteration of the audio. One is marked current.
* **Covers**: every uploaded artwork. One is marked current.
* **Collaborators**: contacts attached to the track with a role and split.
* **Comments**: feedback threads anchored to a version (and optionally a
  timestamp inside that version).
* **Todos**: actionable items scoped to a version.
* **Metadata**, ISRC, BPM, key, genre, writers, publishers, anything the
  release pipeline needs.

## Lifecycle [#lifecycle]

Status is the spine of the lifecycle. The product surfaces it as a kanban,
the API exposes it as a string:

```
idea → in_progress → mixing → mastering → ready → released
```

Status transitions are explicit. Call `PATCH /tracks/{id}/status`. Any
transition is allowed (no enforced graph), but the product UI and analytics
assume the order above.

A track is **released** when its status flips to `released`. That's the moment
to fire downstream automations (DSP delivery, social posts, archival).

## Versions [#versions]

Versions are the heart of the track. Each version is a discrete audio file
with its own waveform, plays, comments, and todos. Workflows revolve around
producing a new version, getting feedback, and promoting one to current.

Key endpoints:

* `GET /tracks/{id}/versions`: list versions.
* `POST /tracks/{id}/versions`: upload a new version.
* `GET /tracks/{id}/versions/{versionId}/detail`: version with comments,
  todos, and metadata in one round trip.
* `PATCH /tracks/{id}/versions/{versionId}/final`: mark this version as the
  current one for the track.
* `POST /tracks/{id}/versions/{versionId}/plays`: record a play (used by the
  player and analytics).
* `POST /tracks/{id}/versions/reorder`: fractional reorder; never rewrites
  rows in bulk.

### Comments [#comments]

Comments live on a version and may carry a timestamp (in seconds) plus
attachments.

* `GET /tracks/{id}/versions/{versionId}/comments`: list.
* `POST /tracks/{id}/versions/{versionId}/comments`: text-only.
* `POST /tracks/{id}/versions/{versionId}/comments/with-attachments`
  multi-file upload in a single request.
* `POST /tracks/{id}/versions/{versionId}/comments/upload`: request a signed
  upload URL when you want to upload directly to storage.
* Reactions: `POST` / `DELETE
  /tracks/{id}/versions/{versionId}/comments/{commentId}/reactions/{emoji}`.

### Todos [#todos]

Todos are version-scoped: "fix the kick at 1:24 in v3" rather than a
free-floating task. Use `GET /tracks/{id}/versions/{versionId}/todos` and the
matching write endpoints.

## Covers [#covers]

Tracks can hold many covers (drafts, A/B variants); one is current.

* `POST /tracks/{id}/covers`: upload a new cover.
* `PATCH /tracks/{id}/covers/{coverId}/current`: promote.

The promoted cover populates `cover_url` and `cover_url_medium` on the track.

## Collaborators [#collaborators]

Collaborators are [contacts](/docs/developers/api) attached to a track with a role
(producer, writer, mixer…) and an optional split percentage. They drive
credits, splits, and access.

* `GET /tracks/{id}/collaborators`
* `POST /tracks/{id}/collaborators`
* `DELETE /tracks/{id}/collaborators` (by contact)

## Search [#search]

Two read endpoints:

* `GET /tracks`: paginated list, filtered by team, album, status, etc.
* `GET /tracks/search/deep`: searches titles, metadata, and version
  filenames. Use this when a producer types into the global command bar.

## Recipes [#recipes]

### List a team's in-progress tracks [#list-a-teams-in-progress-tracks]

```ts
const { data } = await aden.api.v1.tracks.get({
    query: { teamId: 123, status: 'in_progress', limit: 50 },
})
```

### Promote a new version to current [#promote-a-new-version-to-current]

```ts
await aden.api.v1
    .tracks({ id: trackId })
    .versions({ versionId })
    .final.patch({})
```

### Mark a track released after a CI run [#mark-a-track-released-after-a-ci-run]

```ts
await aden.api.v1.tracks({ id: trackId }).status.patch({ status: 'released' })
```

### Drop a timestamped comment from an external tool [#drop-a-timestamped-comment-from-an-external-tool]

```ts
await aden.api.v1
    .tracks({ id: trackId })
    .versions({ versionId })
    .comments.post({
        content: 'Sub bass clipping here',
        timestamp_seconds: 84.3,
    })
```

## Related [#related]

* [Albums](/docs/developers/concepts/albums): group tracks into a release.
* [Team](/docs/developers/concepts/team): who owns the track and who can edit it.
* [API reference](/docs/developers/api): full schemas and parameters.