DDEX (Digital Data Exchange) is the industry standard for exchanging music metadata between parties in the music industry. Proper DDEX metadata is essential for delivering your products to Digital Service Providers (DSPs).This guide covers how to:
def check_ddex_readiness(asset_id): """Check if asset is ready for DDEX delivery""" url = f"https://api.royalti.io/asset/{asset_id}/ddex-readiness" headers = { "Authorization": f"Bearer {os.getenv('ROYALTI_ACCESS_TOKEN')}" } response = requests.get(url, headers=headers) response.raise_for_status() data = response.json()["data"] if data["isReady"]: print(f"✓ Asset is DDEX ready (score: {data['readinessScore']}%)") else: print(f"✗ Asset is NOT ready (score: {data['readinessScore']}%)") if data["missingFields"]: print(f"Missing fields: {data['missingFields']}") if data["invalidFields"]: print(f"Invalid fields: {data['invalidFields']}") if data["warnings"]: print(f"Warnings: {data['warnings']}") return datacheck_ddex_readiness('asset_123')
A readiness score of 100% is required for delivery. Scores below 100% indicate missing or invalid fields.
3
Review and Fix Issues
Address any missing or invalid fields identified in the readiness check.
Copy
{ "status": "success", "data": { "isReady": false, "readinessScore": 75, "missingFields": [ "soundRecordingDetails.isrc", "ddexMetadata.duration" ], "invalidFields": [ { "field": "technicalResourceDetails.sampleRate", "issue": "Must be 44100 or 48000", "currentValue": 22050 } ], "warnings": [ "Genre 'Unknown' may not be recognized by all DSPs" ], "suggestions": [ "Add ISRC code for proper identification", "Update sample rate to 44100 Hz or 48000 Hz", "Specify a standard genre from the approved list" ] }}
Update your asset metadata to address each issue, then re-check readiness.
4
Integrate with Product Delivery
Once your asset is DDEX ready, you can include it in product deliveries.See the Product Delivery Guide for complete delivery workflows.
ISRC: International Standard Recording Code (12 characters: 2-letter country + 3-char registrant + 2-digit year + 5-digit designation)Genre Standards: Use recognized genre names from the DDEX genre list for best DSP compatibility.
Error: soundRecordingDetails.isrc is requiredCause: ISRC (International Standard Recording Code) is mandatory for DSP delivery.Solution: Generate or obtain an ISRC code for your recording:
Node.js
Python
Copy
// If you have an ISRCconst ddexData = { soundRecordingDetails: { isrc: 'USRC17607839' }};// If you need to generate one (contact your national ISRC agency)// Format: CC-XXX-YY-NNNNN// CC = Country code (e.g., US)// XXX = Registrant code// YY = Year// NNNNN = Designation code
Copy
# If you have an ISRCddex_data = { 'soundRecordingDetails': { 'isrc': 'USRC17607839' }}# Format validationimport redef validate_isrc(isrc): pattern = r'^[A-Z]{2}[A-Z0-9]{3}\d{7}$' return bool(re.match(pattern, isrc))
Invalid Duration Format
Error: ddexMetadata.duration must be in ISO 8601 formatCause: Duration must be specified in ISO 8601 format (e.g., PT3M45S).Solution: Convert your duration to ISO 8601 format:
from datetime import timedeltadef seconds_to_iso8601(seconds): """Convert seconds to ISO 8601 duration format""" td = timedelta(seconds=seconds) hours = td.seconds // 3600 minutes = (td.seconds % 3600) // 60 secs = td.seconds % 60 parts = ['PT'] if hours > 0: parts.append(f'{hours}H') if minutes > 0: parts.append(f'{minutes}M') if secs > 0: parts.append(f'{secs}S') return ''.join(parts)# Example: 225 seconds = 3 minutes 45 secondsduration = seconds_to_iso8601(225) # "PT3M45S"
Invalid Sample Rate
Error: technicalResourceDetails.sampleRate must be 44100, 48000, or 96000Cause: DSPs require specific sample rates for audio delivery.Solution: Re-encode your audio file at an accepted sample rate (44.1 kHz recommended):
Copy
# Using ffmpeg to convert sample rateffmpeg -i input.wav -ar 44100 -sample_fmt s16 output.wav
Error: soundRecordingDetails.pLine is recommendedCause: P-Line (phonographic copyright) is recommended for proper rights attribution.Solution: Add P-Line information:
Copy
{ "soundRecordingDetails": { "pLine": { "year": 2024, "pLineText": "2024 Your Record Label Name" } }}
P-Line year should be the year of first publication, not the current year.
Unrecognized Genre
Warning: Genre 'Unknown' may not be recognized by all DSPsCause: Using non-standard or generic genre names.Solution: Use standard DDEX genre classifications:Primary Genres:
Warning: musicalWorkReference is recommended for publishing metadataCause: No link between the sound recording and the underlying musical work.Solution: Add musical work reference if you have publishing information: