DDEX Builder

v0.4.4 - Enhanced compatibility with ddex-parser v0.4.4's strict validation. Improved round-trip workflows with better error handling.

v0.4.3 - Performance optimizations and enhanced stability.

v0.4.2 - Linux x64 Node.js binaries added for cloud deployment compatibility!

Generate deterministic, industry-compliant DDEX XML files with smart normalization. Transform messy DDEX data from any source into clean, compliant DDEX 4.3 with comprehensive validation, partner-specific presets, and data integrity preservation.

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:

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')

WebAssembly (Browser)

// Load from CDN or local build
import init, { DdexBuilder } from './pkg/ddex_builder_wasm.js';

async function generateDDEX() {
  // Initialize WASM module
  await init();
  const builder = new DdexBuilder();
  
  const releaseData = {
    release_id: 'RELEASE_2024_001',
    title: 'Amazing Album',
    artist: 'Incredible Artist',
    release_date: '2024-01-01',
    tracks: [{
      title: 'Hit Song',
      duration: 195,
      isrc: 'US1234567890'
    }]
  };
  
  const xml = builder.build_release_simple(JSON.stringify(releaseData));
  console.log('Generated deterministic DDEX XML:', xml.length, 'bytes');
  return xml;
}

Rust

use ddex_builder::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
• Smart normalization for consistent, compliant output
• 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 (114KB gzipped)
• 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

🧹 Smart Normalization

DDEX Builder transforms inconsistent, messy DDEX data from various sources into clean, compliant output:

Input Sources Supported

• Vendor DDEX files with mixed namespace conventions
• Legacy DDEX versions (3.8.2, 4.2) normalized to 4.3
• Inconsistent element ordering from different systems
• Mixed formatting with redundant whitespace
• Non-standard extensions properly preserved and namespaced

Normalization Benefits

• Consistent namespaces: Standardizes ern:Title vs Title vs ns2:Title variations
• Specification-compliant ordering: Elements arranged per DDEX standard
• Clean formatting: Removes redundant whitespace and formatting issues
• Version standardization: Upgrades legacy DDEX to modern 4.3 structure
• Extension preservation: Maintains partner extensions (Spotify, YouTube, Apple) with proper namespacing

// Transform messy vendor DDEX into clean output
const builder = new DDEXBuilder({
  normalize: true,        // Enable smart normalization
  target_version: '4.3',  // Standardize to DDEX 4.3
  optimize_size: true     // Remove redundant formatting
});

const messyVendorData = /* mixed formatting, legacy version */;
const cleanDdex = await builder.build(messyVendorData);
// Result: Clean, compliant DDEX 4.3 with preserved semantics

Performance Benchmarks

Performance comparison across environments and languages:

Build Performance

Memory Usage

*With streaming mode enabled

Security

v0.4.0 includes comprehensive security enhancements:

• Zero vulnerabilities, forbids unsafe code
• Supply chain security with cargo-deny and SBOM
• Memory-bounded processing with configurable limits
• Built-in validation prevents malformed output
• Deterministic generation prevents injection attacks

Getting Started

Installation Guides

• JavaScript/TypeScript → - npm package with Node.js and browser support
• Python → - PyPI package with pandas integration
• WebAssembly → - Browser-ready WASM bundle with examples
• Rust → - Crates.io package documentation

Round-Trip Compatibility

Seamless integration with ddex-parser for complete workflows with smart normalization:

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);

// Round-trip with beneficial normalization
const reparsed = await parser.parseString(newXml);
console.assert(reparsed.releases[0].title === 'Remastered Edition');

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.