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 email@example.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.
|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
batchIdrepresents the date and time of its creation using the format
batchIdis unique and used to name the batch directory.
- “Every release within the batch must have a separate folder using the
ReleaseIdof 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_
20201010310922000/ // BatchId (YYYYMMDDhhmmssnnn)
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.
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 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.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||‘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||The full name of the first specified MainArtist. Used as the track’s artist.|
|composerName||[v].Composer||The full name of the first specified composer. Used as the track’s composer.|
|publisherName||[v].OriginalPublisher||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.|