Skip to content

Prerequisites

  • Docker
  • An S3-compatible bucket containing your DDEX deliveries
  • AWS credentials (key + secret) with read access to the bucket
  • An Audius SDK API key and secret (obtain from the Audius Developer Portal)
  • A PostgreSQL database

Quick Start

The ddex-processor is published as a Docker image at audius/ddex:latest. You can run it directly:

docker run -d \
  -e DDEX_DATABASE_URL=postgres://postgres:postgres@host.docker.internal:5432/ddex \
  -e DDEX_PORT=8989 \
  -e COOKIE_SECRET=your-random-secret \
  -e ADMIN_HANDLES=your-audius-handle \
  -p 8989:8989 \
  -v $(pwd)/sources.json:/app/sources.json \
  audius/ddex:latest

Configure your sources.json before starting (see Source Configuration below).

The web UI will be available at http://localhost:8989.

Source Configuration

Sources define where DDEX deliveries come from and how they should be published. Create a sources.json file in the project root:

{
  "sources": [
    {
      "env": "production",
      "name": "my-label",
      "ddexKey": "your-audius-app-api-key",
      "ddexSecret": "your-audius-app-api-secret",
      "autoPublish": false,
      "awsKey": "your-aws-access-key",
      "awsSecret": "your-aws-secret-key",
      "awsRegion": "us-east-1",
      "awsBucket": "my-ddex-deliveries"
    }
  ]
}

Source Fields

FieldRequiredDescription
envYesAudius environment: production, staging, or development
nameYesUnique identifier for this source
ddexKeyYesYour Audius app API key (used for OAuth and SDK publishing)
ddexSecretYesYour Audius app API secret
autoPublishNoWhen true, automatically publishes to claimable accounts without artist authorization. Default: false
awsKeyYesAWS access key for S3 bucket
awsSecretYesAWS secret key for S3 bucket
awsRegionYesAWS region of the S3 bucket
awsBucketYesS3 bucket name containing DDEX deliveries
payoutUserIdNoEncoded Audius user ID to receive payouts for paid releases
labelUserIdsNoObject mapping label names to encoded Audius user IDs for payout splits

Publishing Modes

Artist-Authorized (autoPublish: false)

Artists authorize your app via OAuth at distro.audius.co. The processor polls for authorized users and matches them to artist names in DDEX deliveries. Releases are only published once an artist has granted permission.

Auto-Publish (autoPublish: true)

Releases are published immediately to claimable accounts. A magic link is generated that the distributor can pass to the artist, allowing them to claim their Audius account.

Architecture

The ddex-processor runs as two main processes — a worker and a server — backed by PostgreSQL.

Worker

The worker runs on a 5-minute loop and handles:

  1. S3 Polling — scans configured S3 buckets for new DDEX XML files and assets using incremental marker-based pagination
  2. XML Parsing — parses NewReleaseMessage (deliveries/updates) and PurgeReleaseMessage (takedowns) in ERN 3.8 or ERN 4.0 format
  3. User Polling — checks for newly authorized artists via the Audius API
  4. Publishing — publishes pending releases via the Audius SDK when all preconditions are met (artist authorized or auto-publish enabled, release date reached, assets available)
  5. Reporting — generates CLM reports and processes LSR files

Server

The Hono-based web server provides:

  • A management UI for viewing and administering releases
  • OAuth login for artists to authorize publishing
  • Manual publish/retry controls
  • Sales and delivery reporting
  • Admin access controlled by the ADMIN_HANDLES environment variable

CLI Commands

The processor includes a CLI for debugging and manual operations:

# Parse a DDEX XML file and print the result
npx ts-node cli.ts parse <source-name> <path-to-xml>
 
# Publish a specific release to a user
npx ts-node cli.ts publish-to-user <release-id> <user-id>
 
# Publish to a claimable account (auto-publish)
npx ts-node cli.ts publish-to-claimable-account <release-id>
 
# Poll S3 for new deliveries
npx ts-node cli.ts poll-s3
 
# Delete a published release
npx ts-node cli.ts delete <release-id>
 
# Start the server only (no background worker)
npx ts-node cli.ts server
 
# Start the worker only (no web UI)
npx ts-node cli.ts worker
 
# Start both server and worker
npx ts-node cli.ts start

Delivery Format

The processor expects DDEX deliveries in your S3 bucket as either:

  • ZIP files containing a DDEX XML file and associated assets (audio files, artwork)
  • Directories with XML files and assets organized per the DDEX standard

Supported message types:

  • NewReleaseMessage — deliver new releases or update existing ones
  • PurgeReleaseMessage — take down (delete) previously published releases

See the Specification section for details on supported metadata fields, deal types, and best practices.

Machine Recommendations

For production deployments, we recommend:

  • OS: Ubuntu or any Linux distribution with Docker support
  • CPU: 4+ cores
  • Memory: 8-16 GB
  • Storage: Depends on delivery volume — assets are cached locally during processing

More Information