Uploading DDEX Batches

Overview

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

Upload a new batch to your site’s DDEX feed.
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) 
        resources/ 
            A10301A0001887532A_T1_001.mp3 // ReleaseId_TechnicalResourceDetailsReference_SequenceNumber.{mp3,aif,wav}
            A10301A0001887532A_T2.jpg     // ReleaseId_TechnicalResourceDetailsReference.{jpg,png}
    A10301A00017EG98F/
        A10301A00017EG98F.xml
        resources/
            A10301A00017EG98F_T1_001.mp4
            A10301A00017EG98F_T2_002.mp3
    BatchComplete_20201010310922000.xml              // BatchComplete_BatchId.xml
    acknowledgements/                                // Ack directory
        ACK_20201010310922000_A10301A0001887532A.xml // ACK_BatchId_ReleaseId.xml
        ACK_20201010310922000_A10301A00017EG98F.xml

Acknowledgements

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"?>
<echo:FtpAcknowledgementMessage
        xmlns:echo="http://ddex.net/xml/ern-c/15"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        MessageVersionId="1.5"
        xsi:schemaLocation="http://ddex.net/xml/ern-c/15 http://ddex.net/xml/ern-c/15/ern-choreography.xsd">
    <MessageHeader>
        <MessageSender>
            <PartyId><!--SourceAudioDPID--></PartyId>
            <PartyName>
                <FullName>SourceAudio Holdings LLC.</FullName>
            </PartyName>
        </MessageSender>
        <MessageRecipient>
            <PartyId><!--YourDPID--></PartyId>
            <PartyName>
                <FullName><!--Your Company Name--></FullName>
            </PartyName>
        </MessageRecipient>
        <MessageCreatedDateTime>2020-02-13T07:04:10Z</MessageCreatedDateTime>
    </MessageHeader>
    <AcknowledgedFile>
        <ReleaseId>809162100050</ReleaseId>
        <Date>2020-07-31</Date>
    </AcknowledgedFile>
    <FileStatus>FileOk</FileStatus>
    <!-- //// if file status is anything other than FileOk -->
    <ErrorText>
        <!-- problems with the release message or content will be included here -->
    </ErrorText>
      <!-- //// -->
    <AffectedResource>
        <ISRC>CASE00000001</ISRC>
    </AffectedResource>
    <AffectedResource>
        <ISRC>CASE00000002</ISRC>
    </AffectedResource>
    <AffectedResource>
        <ISRC>CASE00000003</ISRC>
    </AffectedResource>
    <AffectedResource>
        <ISRC>CASE00000004</ISRC>
    </AffectedResource>
    <AffectedResource>
        <ISRC>CASE00000005</ISRC>
    </AffectedResource>
    <AffectedResource>
        <ISRC>CASE00000006</ISRC>
    </AffectedResource>
</echo:FtpAcknowledgementMessage>

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.
	ReleaseDetailsByTerritory[0]
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
	ResourceList.Resource
image	Image[0].File.FileName	The image to use as the displayed album image.
	———– Track Metadata ————
	SoundRecording[0-n]
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.