//SCHEMADocs
Console

Resources

A resource is one file-backed asset in a release: a sound recording, a cover image, a video. DDEX calls them resources, and so does this API.

A resource can exist before its bytes do — a delivered message can arrive before its audio — so every resource has a state: incoming until its file lands, then stored. See Out-of-order delivery.

To put bytes behind a resource, see Uploads.

Operations

The Resource object#

A track, image or video on a release.

Attributes

  • resourcePkInt!
    Unique identifier.
  • isrcStringnullable
    International Standard Recording Code, for sound recordings.
  • resourceTypeStringnullable
    The DDEX resource type, e.g. MusicalWorkSoundRecording or FrontCoverImage.
  • titleStringnullable
    The default title. For every variant, use titles.
  • durationSecondsIntnullable
    Duration in whole seconds.
  • stateString!
    incoming (bytes not yet arrived), stored, analyzing or failed. See Wire values.
  • byteSizeIntnullable
    File size in bytes, once the file has arrived.
  • contentVersionStringnullable
    An opaque value that changes whenever this resource's file is replaced. Use it as a cache version for anything made from the file, such as a resized cover. It is not a content address and cannot be used to fetch anything. null until the file has arrived.
  • sequenceInt!
    Position within its group, from 1.
  • technicalTechnicalnullable
    What //SCHEMA measured from the file. null until it has been analyzed — usually seconds after it lands; resource.analyzed says when.
  • mediaKindMediaKind!
    AUDIO, IMAGE, VIDEO or OTHER. Measured once the file is analyzed; read from resourceType until then.
  • contributors[Credit!]!
    Parties credited on this recording — performers, producers, engineers, writers.
    Arguments
    • roleString
      Only credits in this DDEX role, e.g. MainArtist or Producer. Case-insensitive.
    • territoryString
      Only credits that apply in this territory, e.g. US: credits scoped to it, plus unqualified credits where nothing more specific exists. An explicit Worldwide credit matches only territory: "Worldwide".
  • titles[LocalizedText!]!
    Every title of this resource, in every language, script and territory.
    Arguments
    • typeString
      Only variants of this text type, e.g. DisplayTitle or FormalTitle. Case-insensitive.
    • languageString
      Only variants whose language tag is exactly this, e.g. ja-Jpan or ja-Latn. The whole tag, not a prefix: ja does not match ja-Jpan. Use script to select by script alone.
    • scriptString
      Only variants in this ISO 15924 script, e.g. Jpan or Latn.
    • territoryString
      Only variants that apply in this territory, e.g. US: variants scoped to it, plus unqualified variants where nothing more specific exists. See Territories and languages.
    • isDefaultBoolean
      Only variants whose default flag matches. Many senders flag none as default, so true can legitimately return an empty list.
  • plines[Pline!]!
    ℗ notices for this recording. On a compilation these can differ from the release's.
    Arguments
    • languageString
      Only notices whose language tag is exactly this, e.g. en or ja-Jpan.
    • scriptString
      Only notices in this ISO 15924 script, e.g. Latn.
    • territoryString
      Only notices that apply in this territory: those scoped to it, plus unqualified notices where nothing more specific exists.
    • isDefaultBoolean
      Only notices whose default flag matches.
  • clines[Cline!]!
    © notices for this resource — in DDEX, those of artwork, text and video. A sound recording's © is on the release.
    Arguments
    • languageString
      Only notices whose language tag is exactly this, e.g. en or ja-Jpan.
    • scriptString
      Only notices in this ISO 15924 script, e.g. Latn.
    • territoryString
      Only notices that apply in this territory: those scoped to it, plus unqualified notices where nothing more specific exists.
    • isDefaultBoolean
      Only notices whose default flag matches.
  • encodings[Encoding!]!
    Every file of this resource: the original you delivered, and each encoding //SCHEMA has made of it, with what it measured about each. Lists, never mints — pick one and pass its encoding (and clip) to url. See Encodings and media URLs.
    Arguments
    • losslessBoolean
      true for only lossless files, false for only lossy ones.
    • includePendingBoolean!Default: false
      Also list encodings being made (PENDING) or that could not be made (FAILED). Encodings made only on request appear once requested.
  • urlStringnullablemedia_read

    A short-lived signed URL for one file of this resource — the only way to get one. You always name the file: original (the bytes you delivered), an encoding family such as aac-256 (its newest version), or a pinned encoding such as aac-256-v1.

    Which scope it needs depends on what the file is: media_preview (or media_read) for clips and AAC 128; media_read for other lossy encodings and for artwork; media_lossless and an organization with lossless media for anything lossless — FLAC, WAV, ALAC, or a lossless original. A file not yet analyzed counts as lossless.

    null while the resource is incoming. Any other null comes with an error whose extensions.code says why — see Encodings and media URLs. Every URL minted is logged. The release does not have to be live.

    Arguments
    • encodingString!required
      original, a family such as aac-256, or a pinned encoding such as aac-256-v1. See encodingProfiles.
    • clipBoolean!Default: false
      The 30-second preview clip of that encoding instead of full length. Lossy encodings only.
    • ttlSecondsInt
      How long the URL stays valid, in seconds. Default 300; values above 3600 are capped at 3600; 0 is an error.
    • downloadBoolean!Default: false
      Have a browser save the file as Artist - Title.ext instead of playing it. The name is signed into the URL.
  • artworkArtworknullablemedia_read

    This cover at one of your organization's artwork sizes, by label: artwork(size: "tile-600") { url width height }. media_read, as for the original.

    PENDING with no URL until the rendition is made. null while the resource is incoming. An unknown label is an UNKNOWN_ARTWORK_SIZE error listing your labels; a resource that is not an image is ENCODING_NOT_AVAILABLE, and an image that is not the FrontCoverImage is ARTWORK_NOT_FRONT_COVER — sizes are made of front covers only. Release.coverArt finds the cover for you.

    Arguments
The Resource object
{
  "resourcePk": 771201,
  "isrc": "JPTO09404900",
  "resourceType": "MusicalWorkSoundRecording",
  "title": "Signal Fire",
  "durationSeconds": 214,
  "state": "stored",
  "byteSize": 48213377,
  "contentVersion": "3b9e1f0c7a42d851",
  "sequence": 1,
  "mediaKind": "AUDIO",
  "technical": {
    "mediaKind": "audio",
    "container": "flac",
    "codec": "flac",
    "bitrateKbps": 1802,
    "sampleRateHz": 44100,
    "bitDepth": 16,
    "channels": 2,
    "durationMs": 214306,
    "lossless": true,
    "integratedLufs": -9.8,
    "truePeakDbtp": -0.3,
    "widthPx": null,
    "heightPx": null
  }
}

The Technical object#

What //SCHEMA measured from the file itself, never what the sender asserted. Compare durationMs with the delivered durationSeconds to catch a truncated or wrong file.

Attributes

  • mediaKindStringnullable
    audio, image, video, or other for a file that is none of them.
  • containerStringnullable
    The file format, e.g. wav, flac, aiff, mp4, jpeg.
  • codecStringnullable
    The codec, e.g. pcm_s24le, flac, mp3, jpeg.
  • bitrateKbpsIntnullable
    Bitrate in kilobits per second.
  • sampleRateHzIntnullable
    Sample rate in hertz, e.g. 44100.
  • bitDepthIntnullable
    Bits per sample, e.g. 16 or 24. Lossless audio only.
  • channelsIntnullable
    Number of audio channels.
  • durationMsIntnullable
    Measured duration, in milliseconds.
  • losslessBooleannullable
    Whether the audio is lossless. null for anything that is not audio.
  • integratedLufsFloatnullable
    EBU R128 integrated loudness, in LUFS — what DSPs normalize on.
  • truePeakDbtpFloatnullable
    EBU R128 true peak, in dBTP.
  • widthPxIntnullable
    Image or video width in pixels.
  • heightPxIntnullable
    Image or video height in pixels.

The DraftResource object#

A resource as returned by the authoring mutations.

Attributes

  • resourcePkInt!
    Unique identifier. Upload against it.
  • isrcStringnullable
    The ISRC, when known.
  • stateString!
    incoming until bytes are attached, then stored.
The DraftResource object
{ "resourcePk": 771340, "isrc": "JPTO09404920", "state": "incoming" }

The AddResourceInput input object#

A resource to add to a release.

Fields

  • releasePkInt!required
    The release to add it to. Must be in your catalog.
  • isrcString
    International Standard Recording Code.
  • resourceTypeString!required
    The DDEX resource type — MusicalWorkSoundRecording for a track, FrontCoverImage for cover art.
  • resourceTypeKindString!Default: "SoundRecordingType"
    The vocabulary resourceType belongs to. SoundRecordingType for audio; use ImageType for artwork.
  • titleString
    The title.
  • durationSecondsInt
    Duration in whole seconds.
  • sequenceInt
    Track number. Omit to append after the last track.

Add a resource#

mutationaddResource→DraftResource!catalog_write

Add a track or an image to a draft release. The resource starts as incoming; upload its bytes with requestUpload and completeUpload.

Cover art is a resource like any other: add it with resourceType: "FrontCoverImage" and resourceTypeKind: "ImageType".

Arguments

  • inputAddResourceInput!required
    The resource to add.
    Show child parameters
    • releasePkInt!required
      The release to add it to. Must be in your catalog.
    • isrcString
      International Standard Recording Code.
    • resourceTypeString!required
      The DDEX resource type — MusicalWorkSoundRecording for a track, FrontCoverImage for cover art.
    • resourceTypeKindString!Default: "SoundRecordingType"
      The vocabulary resourceType belongs to. SoundRecordingType for audio; use ImageType for artwork.
    • titleString
      The title.
    • durationSecondsInt
      Duration in whole seconds.
    • sequenceInt
      Track number. Omit to append after the last track.

Returns

A DraftResource. Keep its resourcePk — you upload against it.

Request
mutation AddTrack($input: AddResourceInput!) {
  addResource(input: $input) {
    resourcePk
    state
  }
}
Variables
{
  "input": {
    "releasePk": 48290,
    "resourceType": "MusicalWorkSoundRecording",
    "title": "Harbour Lights",
    "isrc": "JPTO09404920"
  }
}
Response
{
  "data": {
    "addResource": {
      "resourcePk": 771340,
      "state": "incoming"
    }
  }
}

Update a resource#

mutationupdateResource→Boolean!catalog_write

Rename a track, correct its ISRC or duration, or set its own ℗ and © notices. Only the arguments you pass are changed. This is what lets a client upload files first and name them afterwards.

Arguments

  • releasePkInt!required
    The release the resource belongs to.
  • resourcePkInt!required
    The resource to change.
  • titleString
    New title.
  • isrcString
    New ISRC.
  • durationSecondsInt
    New duration, in whole seconds.
  • plines[CopyrightLineInput!]
    This track's ℗ notices, when they differ from the release's — a licensed-in track on a compilation, say. A list replaces them all; [] clears.
    Show child parameters
    • textString!required
      The notice as displayed, e.g. (P) 2026 Lanternfish Records. Stored exactly as given.
    • yearString
      The year, as a string.
    • companyString
      The rights holder, when not only inside text.
    • languageAndScriptCodeString
      A BCP-47 tag such as en or ja-Jpan, when the notice is in one language. The script is extracted as it is from a delivery.
    • territoryString
      Leave unset unless the notice applies to one territory only. Unset is not the same as Worldwide.
    • isDefaultBoolean!Default: false
      The default among several. At most one per list; when none is marked, the first is.
  • clines[CopyrightLineInput!]
    This resource's © notices — usually for artwork, text or video. Same rule as plines.
    Show child parameters
    • textString!required
      The notice as displayed, e.g. (P) 2026 Lanternfish Records. Stored exactly as given.
    • yearString
      The year, as a string.
    • companyString
      The rights holder, when not only inside text.
    • languageAndScriptCodeString
      A BCP-47 tag such as en or ja-Jpan, when the notice is in one language. The script is extracted as it is from a delivery.
    • territoryString
      Leave unset unless the notice applies to one territory only. Unset is not the same as Worldwide.
    • isDefaultBoolean!Default: false
      The default among several. At most one per list; when none is marked, the first is.

Returns

true if the resource was updated, false if it is not in that release.

Request
mutation {
  updateResource(releasePk: 48290, resourcePk: 771340, title: "Harbour Lights (Reprise)")
}
Response
{
  "data": {
    "updateResource": true
  }
}

Reorder tracks#

mutationreorderTracks→Boolean!catalog_write

Set the track order. resourcePks is the new order, first to last. Resources you leave out keep their relative order after the ones you list, so a partial list reorders rather than truncates.

Track numbers (sequence) are recomputed as 1…n.

If any id is not in this release, nothing changes and the result is false.

Arguments

  • releasePkInt!required
    The release to reorder.
  • resourcePks[Int!]!required
    Resource ids in their new order.

Returns

true when the new order was applied.

Request
mutation {
  reorderTracks(releasePk: 48290, resourcePks: [771341, 771340])
}
Response
{
  "data": {
    "reorderTracks": true
  }
}

Remove a resource#

mutationremoveResource→Boolean!catalog_write

Take a track or image off a release and delete it. Idempotent: removing one that is already gone returns false rather than an error.

Uploaded bytes are not deleted from storage — media is stored by content address, and may back other resources.

Arguments

  • releasePkInt!required
    The release to remove it from.
  • resourcePkInt!required
    The resource to remove.

Returns

true if a resource was removed.

Request
mutation {
  removeResource(releasePk: 48290, resourcePk: 771341)
}
Response
{
  "data": {
    "removeResource": true
  }
}