DDEX Builder

Generate deterministic, industry-compliant DDEX XML files with byte-perfect reproducibility. Build DDEX messages from structured data with comprehensive validation, partner-specific presets, and perfect round-trip compatibility with ddex-parser.

Part of the DDEX Suite - a comprehensive toolkit for working with DDEX metadata in the music industry.

🚀 Language Support

Choose your preferred language and get started immediately:

Language	Package	Installation
JavaScript/TypeScript	ddex-builder (npm)	`npm install ddex-builder`
Python	ddex-builder (PyPI)	`pip install ddex-builder`
Rust	ddex-builder-core (crates.io)	`cargo add ddex-builder-core`

Quick Start

JavaScript/TypeScript

import { DDEXBuilder } from 'ddex-builder';

const builder = new DDEXBuilder({ validate: true, preset: 'youtube' });

const releaseData = {
  messageHeader: {
    senderName: 'My Record Label',
    messageId: 'RELEASE_2024_001'
  },
  releases: [{
    title: 'Amazing Album',
    mainArtist: 'Incredible Artist',
    tracks: [{
      title: 'Hit Song',
      duration: 195,
      isrc: 'US1234567890'
    }]
  }]
};

const xml = await builder.buildFromObject(releaseData, { version: '4.3' });
console.log('Generated deterministic DDEX XML:', xml.length, 'bytes');

Python

from ddex_builder import DDEXBuilder
import pandas as pd

builder = DDEXBuilder(validate=True, preset='youtube')

release_data = {
    'message_header': {
        'sender_name': 'My Record Label',
        'message_id': 'RELEASE_2024_001'
    },
    'releases': [{
        'title': 'Amazing Album',
        'main_artist': 'Incredible Artist',
        'tracks': [{
            'title': 'Hit Song',
            'duration': 195,
            'isrc': 'US1234567890'
        }]
    }]
}

xml = builder.build_from_dict(release_data, version='4.3')
print(f'Generated deterministic DDEX XML: {len(xml)} bytes')

Rust

use ddex_builder_core::DDEXBuilder;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let builder = DDEXBuilder::new()
        .with_validation(true)
        .with_preset("youtube");
    
    let release_data = serde_json::json!({
        "message_header": {
            "sender_name": "My Record Label",
            "message_id": "RELEASE_2024_001"
        },
        "releases": [{
            "title": "Amazing Album",
            "main_artist": "Incredible Artist",
            "tracks": [{
                "title": "Hit Song",
                "duration": 195,
                "isrc": "US1234567890"
            }]
        }]
    });
    
    let xml = builder.build_from_json(&release_data, "4.3")?;
    println!("Generated deterministic DDEX XML: {} bytes", xml.len());
    
    Ok(())
}

Core Features

🎯 Deterministic Output

100% reproducible XML generation with stable hash IDs
DB-C14N/1.0 canonicalization for byte-perfect consistency
Content-addressable resource IDs for reliable references
Stable ordering ensures identical output across all platforms

🏭 Industry Presets

YouTube Music: Content ID and monetization standards
Generic: Default preset for broad distributor compatibility

🌐 Cross-Platform Compatibility

Node.js 16+ with native addon performance
Python 3.8+ with comprehensive type hints
Browser support via optimized WASM (<400KB)
Rust native for maximum performance and safety

🔒 Comprehensive Validation

Real-time DDEX schema validation with detailed error messages
Business rule enforcement for industry compliance
Reference integrity checking across the entire message
Territory and rights validation with suggestion engine

🚀 High Performance

Native Rust core with optimized language bindings
Streaming generation for large catalogs (>100,000 tracks)
Memory-efficient processing with configurable limits
Parallel resource processing for maximum throughput

API Overview

All language bindings provide consistent APIs with language-specific optimizations:

Common Operations

Operation	JavaScript	Python	Rust
Build from object	`builder.buildFromObject(data)`	`builder.build_from_dict(data)`	`builder.build_from_json(data)`
Build from JSON	`builder.buildFromJSON(json)`	`builder.build_from_json(json)`	`builder.build_from_json_str(json)`
Validate	`builder.validate(data)`	`builder.validate(data)`	`builder.validate(data)`
Apply preset	`builder.applyPreset(name)`	`builder.apply_preset(name)`	`builder.with_preset(name)`

Deterministic Generation

All language bindings guarantee identical output:

// JavaScript
const xml1 = await builder.buildFromObject(data, { version: '4.3' });
const xml2 = await builder.buildFromObject(data, { version: '4.3' });
console.assert(xml1 === xml2); // ✅ Byte-perfect reproducibility

# Python
xml1 = builder.build_from_dict(data, version='4.3')
xml2 = builder.build_from_dict(data, version='4.3')  
assert xml1 == xml2  # ✅ Byte-perfect reproducibility

// Rust
let xml1 = builder.build_from_json(&data, "4.3")?;
let xml2 = builder.build_from_json(&data, "4.3")?;
assert_eq!(xml1, xml2); // ✅ Byte-perfect reproducibility

Advanced Features

Streaming for Large Catalogs

Process massive datasets with constant memory usage:

// JavaScript/TypeScript - Stream from Node.js readable
import { createReadStream } from 'fs';

const fileStream = createReadStream('huge-catalog.json');
const xml = await builder.buildFromStream(fileStream, {
  version: '4.3',
  batchSize: 1000,
  progressCallback: (progress) => {
    console.log(`Progress: ${progress.percentage}% (${progress.itemsProcessed} items)`);
  }
});

# Python - Stream from CSV with pandas
import pandas as pd

def build_streaming_catalog(csv_file: str) -> str:
    builder = DDEXBuilder(streaming=True)
    
    for chunk in pd.read_csv(csv_file, chunksize=1000):
        builder.process_chunk(chunk)
    
    return builder.finalize()

xml = build_streaming_catalog('massive_catalog.csv')

Industry Preset System

Pre-configured settings for major platforms:

// Apply YouTube preset for content ID optimization
const youtubeBuilder = new DDEXBuilder({ preset: 'youtube' });

// Automatically applies:
// - Content ID requirements
// - Territory-specific usage rights  
// - Video content metadata
// - Monetization compatibility
// - YouTube-specific metadata fields

# Apply YouTube Music preset for Content ID compliance
builder = DDEXBuilder(preset='youtube_music')

# Automatically applies:
# - Content ID requirements
# - Monetization compatibility
# - Territory-specific rights
# - Video content specifications

Round-Trip Compatibility

Perfect integration with ddex-parser for complete workflows:

import { DDEXParser } from 'ddex-parser';
import { DDEXBuilder } from 'ddex-builder';

// Parse existing DDEX file
const parser = new DDEXParser();
const original = await parser.parseFile('input.xml');

// Modify specific fields
const modified = { ...original.flattened };
modified.releases[0].title = 'Remastered Edition';

// Build new deterministic XML
const builder = new DDEXBuilder({ canonical: true });
const newXml = await builder.buildFromFlattened(modified);

// Perfect round-trip fidelity guaranteed
const reparsed = await parser.parseString(newXml);
console.assert(reparsed.releases[0].title === 'Remastered Edition');

Performance Benchmarks

Performance comparison across environments and languages:

Build Performance

Dataset Size	Node.js	Python	Rust	Browser (WASM)
Single release (10 tracks)	3ms	5ms	0.8ms	8ms
Album catalog (100 releases)	25ms	40ms	12ms	85ms
Label catalog (1000 releases)	180ms	280ms	95ms	650ms
Large catalog (10000 releases)	1.8s	2.8s	950ms	6.5s

Memory Usage

Dataset Size	Traditional XML	ddex-builder	Improvement
1000 releases	450MB	120MB	73% less
10000 releases	4.2GB	300MB	93% less
100000 releases	>16GB	500MB*	>97% less

*With streaming mode enabled

Getting Started

Installation Guides

JavaScript/TypeScript → - npm package with Node.js and browser support
Python → - PyPI package with pandas integration
Rust → - Crates.io package documentation

Example Projects

Express.js API - REST API for DDEX generation
Python Analytics - Catalog generation from analytics data
React Generator - Interactive DDEX builder
Rust CLI - Command-line DDEX builder

Industry Presets Reference

Generic Preset

name: "generic"
description: "Default preset for broad distributor compatibility"
requirements:
  - explicit_content_flag: optional
  - territory_restrictions: none
  - artist_id: optional
validation_rules:
  - isrc: required
  - duration: min_30_seconds
  - territories: ["WorldWide"]

YouTube Music Preset

name: "youtube_music"
description: "Content ID and monetization requirements"
requirements:
  - content_id: enabled
  - monetization: standard_policies
  - territory_handling: youtube_specific
validation_rules:
  - track_references: required
  - usage_rights: monetization_compatible

Custom Preset Creation

import { DDEXBuilder, type CustomPreset } from 'ddex-builder';

const myLabelPreset: CustomPreset = {
  name: 'my_label',
  defaultTerritories: ['US', 'CA', 'GB'],
  requiredFields: {
    release: ['title', 'mainArtist', 'labelName', 'releaseDate'],
    track: ['title', 'duration', 'isrc', 'position']
  },
  validationRules: {
    maxTrackDuration: 600, // 10 minutes
    requireExplicitFlag: true,
    genreNormalization: ['Pop', 'Rock', 'Electronic', 'Hip-Hop']
  },
  businessRules: {
    enforceISRC: true,
    validateTerritoryRights: true,
    requireUPCForAlbums: true
  }
};

const builder = new DDEXBuilder({ preset: myLabelPreset });

Migration Guides

From v0.1.0 to v0.2.0

The v0.2.0 release introduced significant improvements:

// v0.1.0 (deprecated)
import buildDdex from 'ddex-builder';
const xml = buildDdex(data, { version: '4.3' });

// v0.2.0+ (current)
import { DDEXBuilder } from 'ddex-builder';
const builder = new DDEXBuilder();
const xml = await builder.buildFromObject(data, { version: '4.3' });

New in v0.2.0:

Deterministic output with DB-C14N/1.0
Industry preset system
Enhanced validation engine
Streaming support for large datasets
Round-trip compatibility with ddex-parser
Full TypeScript support across all bindings

From Other DDEX Tools

Migration helpers for common scenarios:

# From manual XML generation
template = """<?xml version="1.0"?>
<ernm:NewReleaseMessage>
  <!-- Manual template approach -->
</ernm:NewReleaseMessage>"""

# To ddex-builder
from ddex_builder import DDEXBuilder
builder = DDEXBuilder(validate=True)
xml = builder.build_from_dict(structured_data, version='4.3')

Error Handling

Comprehensive error types with detailed information:

import { DDEXBuilder, ValidationError, BuilderError } from 'ddex-builder';

try {
  const xml = await builder.buildFromObject(data, { version: '4.3' });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation failed:', error.details);
    error.fieldErrors.forEach(fieldError => {
      console.error(`${fieldError.field}: ${fieldError.message}`);
      if (fieldError.suggestions) {
        console.log('Suggestions:', fieldError.suggestions.join(', '));
      }
    });
  } else if (error instanceof BuilderError) {
    console.error('Build failed:', error.message);
  }
}

Testing

Run comprehensive tests across all language bindings:

# Test all languages
npm test

# Test specific binding
cd bindings/node && npm test
cd bindings/python && python -m pytest
cargo test -p ddex-builder-core

# Run determinism tests
npm run test:determinism

# Run round-trip tests  
npm run test:round-trip

Contributing

We welcome contributions! Please read our Contributing Guide before submitting PRs.

Development Setup

git clone https://github.com/ddex-suite/ddex-suite.git
cd ddex-suite/packages/ddex-builder

# Install dependencies
npm install
pip install -r requirements-dev.txt
cargo build

# Run tests
npm run test:all

# Test deterministic output
npm run test:determinism

Roadmap

Current Status (v0.2.0)

✅ Deterministic XML generation with DB-C14N/1.0
✅ Industry preset system (YouTube, Generic)
✅ Comprehensive validation engine
✅ JavaScript/TypeScript bindings (Node.js + Browser)
✅ Python bindings with pandas integration
✅ Round-trip compatibility with ddex-parser

Upcoming Features

v1.0.0 (Q3 2025)

Production Grade: Enterprise-ready stability and performance
Complete Documentation: Comprehensive guides and tutorials

Support

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

ddex-parser - Parse DDEX XML files to structured data
DDEX Suite - Complete DDEX processing toolkit
DDEX Workbench - Official DDEX validation tools

Built with ❤️ for the music industry. Engineered for deterministic, industry-grade DDEX generation.

ddex-builder 0.3.0