Track Assets

Dolby Atmos and music video masters attached to a track

Resource Overview

A track asset is a master file attached to a track: a Dolby Atmos master (atmos) or a music video master (video). A track carries at most one asset of each type. Masters are attached by URL only: the URL must download the file directly over HTTPS.

Attaching a master validates the file. Follow its validation-status with GET /track-assets/{id}.

Base Endpoint
/track-assets
Resource Type
track-assets
User Scope
Track owner-restricted

Schema

Writable Attributes

Field Type Required Description
asset-type string On create atmos or video. Cannot be changed afterwards
url string On create HTTPS link that downloads the master directly, up to 2048 characters (any other scheme answers 422 with URL_NOT_HTTPS). Cannot be changed afterwards
secondary-isrc string | null No atmos only. A valid 12-character ISRC (e.g., ARC572500001), different from the track's own ISRC; otherwise 422 with isrc_format_invalid or atmos_isrc_must_differ. Leave it empty to have one assigned
crop-top, crop-bottom, crop-left, crop-right integer | null No video only. Inactive pixels (black bars) on each edge, 0 or more. Write 0 when there are none

Read-only Attributes

Field Type Description
validation-status string validating, valid or invalid. A valid master can still become invalid later; validation-errors then says why
validation-errors array | null List of {code, message} when processing failed, otherwise null
needs-isrc boolean true for an atmos asset without a secondary ISRC: one will be assigned
md5 string | null MD5 of the stored master, once computed
byte-size integer | null Size of the stored master in bytes, once known
master-url string | null Permanent link to the stored master, once stored
preview-url string | null video only. Browser-playable preview, when available
created-at, updated-at string (ISO 8601) Timestamps

Relationships

Relationship Related Resource Description
track tracks Track the master belongs to. Required on create, cannot be changed afterwards

A track lists its assets at GET /tracks/{id}/track-assets, or with include=track-assets.

List Track Assets

GET 
GET /track-assets
  • • filter[id] - Asset IDs (comma-separated)
  • • filter[track] - Track ID
  • • filter[asset-type] - atmos or video
  • • filter[validation-status] - validating, valid or invalid
  • • include - track
  • • sort - track, created-at, updated-at (prefix with - for descending)
  • • page[number], page[size] - default 20, max 500

Attach a Master

POST 
POST /track-assets

{
  "data": {
    "type": "track-assets",
    "attributes": {
      "asset-type": "atmos",
      "url": "https://cdn.example.com/masters/song-atmos.wav",
      "secondary-isrc": "ARC572500002"
    },
    "relationships": {
      "track": { "data": { "type": "tracks", "id": "5" } }
    }
  }
}
201 Created
{
  "data": {
    "type": "track-assets",
    "id": "17",
    "attributes": {
      "asset-type": "atmos",
      "url": "https://cdn.example.com/masters/song-atmos.wav",
      "secondary-isrc": "ARC572500002",
      "needs-isrc": false,
      "crop-top": null,
      "crop-bottom": null,
      "crop-left": null,
      "crop-right": null,
      "validation-status": "valid",
      "validation-errors": null,
      "md5": null,
      "byte-size": null,
      "master-url": null,
      "preview-url": null,
      "created-at": "2026-10-15T12:00:00.000000Z",
      "updated-at": "2026-10-15T12:00:00.000000Z"
    },
    "relationships": {
      "track": { "data": { "type": "tracks", "id": "5" } }
    }
  }
}
  • • 404 - the track does not exist or is not yours
  • • 403 - your account is not enabled for this asset type (ATMOS_NOT_ALLOWED, VIDEO_NOT_ALLOWED)
  • • 409 - the track already has an asset of this type (track-asset-exists). To replace a master, delete it and attach the new one
  • • 422 - the file was refused: one error per reason, with its code and a detail that says what to fix. Nothing is attached

A video master must have sound: a file with no audio is refused with AUDIO_STREAM_MISSING. A video master may be accepted with validation-status: validating; it becomes valid or invalid later, as shown by GET /track-assets/{id}.

422 Unprocessable Entity
{
  "errors": [
    {
      "status": "422",
      "title": "Unprocessable Entity",
      "code": "SAMPLE_RATE_INVALID",
      "detail": "The Atmos master must be 48 kHz."
    }
  ]
}

Edit an Asset

PATCH 
PATCH /track-assets/18

{
  "data": {
    "type": "track-assets",
    "id": "18",
    "attributes": { "crop-top": 0, "crop-bottom": 0, "crop-left": 0, "crop-right": 0 }
  }
}
  • • atmos: only secondary-isrc. An empty value sets needs-isrc to true
  • • video: only the crops. A crop cannot be emptied (CROP_CANNOT_BE_BLANK): write 0
  • • The file is never re-validated or changed. url, asset-type and track cannot be changed
  • • Members you do not send are left as they are

Remove an Asset

DELETE 
DELETE /track-assets/18

Answers 204 No Content. The track can then receive a new master of that type.