Uploading DDEX Batches


You can add music to your site by sending us DDEX deliveries of your new releases. Your site will have its own DDEX drive set up where you can send batches of new content. When we receive a new batch, we’ll start ingesting all the releases into our system. We’ll create new albums and tracks using the resources and metadata obtained from each release. When all releases are ingested and done processing, we send an acknowledgement message to let you know we’re done. After we acknowledge your releases, head on over to your site to see your new content.

To get started with our DDEX feed please read the specs below and contact support@sourceaudio.com to have DDEX deliveries added to your site.

Using the DDEX Feed

Our DDEX feed uses the ECHO 1.5 FTP Batch profile standard for coordinating deliveries and the DDEX ERN 3.8.2 release notification standard for metadata ingestion.

You can get the full delivery specs from the DDEX standards documentation on ECHO 1.5 FTP Batch deliveries here.

DDEX Standard Version Profiles Messages
ECHO Choreography 1.5 Batch FTP/SFTP Profile ManifestMessage, ftpAcknowledgementMessage
Electronic Release Notification (ERN) 3.8.2 All audio profiles NewReleaseMessage

Delivering New Content

  1. Upload a new batch to your site’s DDEX feed.
  2. Upload a batch_complete file to the batch directory once you’ve uploaded all batch contents to let us know you’re ready for us to process the batch.

Typically, a batch is acknowledged within 48 hours of delivery. If you haven’t received an acknowledgement within 48 hrs. check the structure, file names, and directory names of the batch to ensure conformance to the echo 1.5 ftp batch delivery profile specification.

Note: We remove track and image resources from the feed after they’re ingested. As a best practice, we recommend removing completed batches within 48 hours of acknowledgement. Batches that are 30 days old or older are subject to automated removals by our system.

ECHO 1.5 Delivery Summary

  • A batchId represents the date and time of its creation using the formatYYYYMMDDhhmmssnnn. The batchId is unique and used to name the batch directory.
  • “Every release within the batch must have a separate folder using the ReleaseId of the release as its name.” Conventionally, this is the album UPC or GRid.
  • The root release directory contains two items: The release notification XML file and a “resources” directory.
  • The release “resources“ directory contains all the track MP3, WAV, or AIFF files specified within the release and an image resource file for the release’s album art.
  • The last file uploaded to the root batch directory is a “BatchComplete“ file. This file is uploaded at the batch level after all other batch files are delivered. It signals to our system to begin the ingestion process. Per DDEX specification the name of the file must be “BatchComplete_batchId.xml”.

Delivery Example:

20201010310922000/                        // BatchId (YYYYMMDDhhmmssnnn)
A10301A0001887532A/ // ReleaseId (UPC|GRid)
A10301A0001887532A.xml // ReleaseId.xml (NewReleaseMessage)
A10301A0001887532A_T1_001.mp3 // ReleaseId_TechnicalResourceDetailsReference_SequenceNumber.{mp3,aif,wav}
A10301A0001887532A_T2.jpg // ReleaseId_TechnicalResourceDetailsReference.{jpg,png}
BatchComplete_20201010310922000.xml // BatchComplete_BatchId.xml
acknowledgements/ // Ack directory
ACK_20201010310922000_A10301A0001887532A.xml // ACK_BatchId_ReleaseId.xml


After the batch is ingested and processed, we upload an acknowledgement directory within the batch directory. The presence of this folder shows that we have ingested the contents into our system and added them to your site. This directory contains an acknowledgement message for each batched release. The name of the acknowledgement message will be “ACK_batchId_releaseId.xml,” per ddex standard.

Acknowledgement Example
<?xml version="1.0" encoding="UTF-8"?>
xsi:schemaLocation="http://ddex.net/xml/ern-c/15 http://ddex.net/xml/ern-c/15/ern-choreography.xsd">
<FullName>SourceAudio Holdings LLC.</FullName>
<FullName><!--Your Company Name--></FullName>
<!-- //// if file status is anything other than FileOk -->
<!-- problems with the release message or content will be included here -->
<!-- //// -->

Automated Metadata Mapping

SourceAudio looks for metadata in your release files during the import process and matches the fields it’s able to interpret to fields on your site. It looks for album metadata in the main release and track metadata in the sound recording resource. The exact ddex element hierarchy will vary depending on the release profile used, and the included release and resource list composites. We recommend that you include the value you want mapped only once, or include it before the subsequent ddex variations used for the same value. The standard SourceAudio field set doesn’t map metadata per territory so it will use the global set of territorial metadata when provided, otherwise it uses the first included set of territorial metadata. Fields that aren’t included in the release data will be left empty or filled by metadata embedded in the audio files.

Bold Fields are required for using the ddex feed.

Standard Field DDEX ERN Element
———– Album Metadata ————
ReleaseList.Release The main release. Conventionally noted as R0 with a release type of Album, SingleResourceRelease etc.
labelName LabelName The label the album was released under. A new label is created if it doesn’t already exist on your site.
albumCode ReleaseId[0] ICPN/UPC/GRID The code to use as the SouceAudio album code.
albumName ReferenceTitle.TitleText The display name to be used for the album.
albumFullName ReferenceTitle.TitleText Same as above.
albumGenre Genre[0-n].GenreText The genre names that apply to the album.
albumReleaseDate OriginalReleaseDate The original release date for the album.
trackNumber ResourceGroupContentItem.n.SequenceNumber The order in which the track appears on the EP/LP
image Image[0].File.FileName The image to use as the displayed album image.
———– Track Metadata ————
isrc SoundRecordingId.Id.ISRC The track’s ISRC number.
iswc IndirectSoundRecordingId.ISWC The track’s ISWC number.
length Duration The length of the track.
ReleaseDetailsByTerritory[0] ‘Worlwide’ or first set of provided territorial track metadata.
title Title.TitleText The title to be used as the tracks displayed title.
artistName [v].MainArtist[0] The full name of the first specified MainArtist. Used as the track’s artist.
composerName [v].Composer[0] The full name of the first specified composer. Used as the track’s composer.
publisherName [v].OriginalPublisher[0] The full name of the first specified OriginalPublisher. Used as the track’s publisher.
genres Genre[0-n].GenreText The genre names that apply to the track.
releaseDate OriginalResourceReleaseDate, CreationDate The track’s original release date.
keywords Keywords The keywords or tags to use for the track.
description Synopsis A descripton of the track.
explicit ParentalWarningType If “Explicit” then set to true otherwise false.