developermetadatamusic

Embed Metadata, Get Paid: A Developer Guide to Royalty-Friendly Video Descriptions

UUnknown

2026-03-10

9 min read

Practical developer docs and templates to embed publishing/royalty metadata in media so publishers like Kobalt can collect royalties accurately.

Embed Metadata, Get Paid: A Developer Guide to Royalty-Friendly Video Descriptions

Hook: You spent hours recording, mixing, and rendering a music-backed video — but without accurate publishing and royalty metadata embedded in the file or delivered to publishers, the people who should get paid (and you) may never see a cent. This guide gives developers and integrators the concrete templates, commands, and automation patterns to embed royalty metadata into audio and video assets so platforms and publishers (think Kobalt and similar administrators) can accurately identify, register, and collect royalties.

Why this matters in 2026: Rights transparency and automated payouts are non‑negotiable

In late 2025 and early 2026 the industry continued to accelerate toward automated royalty collection and more global administration partnerships — for example, Kobalt's January 2026 partnership with Madverse to widen publishing administration in South Asia. As publishers expand global footprints and rely more on automated ingest pipelines, the quality and presence of embedded metadata are a primary determinant of whether income is tracked and paid correctly.

Platform fingerprinting and AI audio/video recognition are improving, but they don't replace explicit rights metadata. Fingerprints help find matches; metadata tells administrators who owns what, who administers the composition, and how to route payments.

What publishers and admin teams need (and why developers must deliver it)

Publishers and collection societies rely on structured metadata to:

Identify recordings and works (ISRC, ISWC, GRid)
Map contributors to payouts (IPI/CAE numbers, percent shares)
Understand admin relationships (publisher names and admin agencies like Kobalt)
Accept delivery through standard channels (DDEX ERN, sidecar files, or embedded XMP)

For developers building ingestion pipelines, CMS integrations, transcode workflows, or export tools in DAWs/NLEs, the job is to reliably insert this metadata into the format(s) publishers prefer and also produce the supplemental files (DDEX ERN or equivalent) required by admin partners.

Core royalty metadata fields (developer checklist)

Always collect and deliver the following fields. These are the ones publishers use to match and register works.

Identifiers: ISRC (recording), ISWC (composition), GRid (release), UPC / EAN
Work & Recording Title
Contributors: Artist, Composer, Lyricist, Producer — with roles and split percentages
Interested Party IDs: IPI/CAE numbers, Publisher IDs, PRO affiliations (ASCAP, BMI, PRS, etc.)
Publisher / Admin: Publisher name, administering organization (e.g., Kobalt), admin account or client ID
Rights & Territories: Mechanical rights, performance rights, sync rights, territorial scope, start/end dates
Contact & Ingest Info: ingest email/SFTP/API endpoint, delivery manifest identifier
Fingerprint / Hash: audio fingerprint, SHA256 of the file for deduplication
Versioning: master version, release date, ISRC assignment date

Standards & containers — where to put that metadata

There are multiple places to put royalty metadata — embed it, accompany with a sidecar, and always register with the publisher via their preferred protocol. Use a combination for redundancy.

1) Embedded metadata in file containers

MP4 / MOV: use native atoms (©nam, ©ART, ---- freeform atoms) or XMP in the udta. Tools: AtomicParsley, exiftool.
MP3 / AAC: ID3v2 frames (TIT2, TPE1) and TXXX frames for custom structured JSON payloads.
WAV / BWF: Broadcast WAV (BWF) supports iXML and iXML-like chunks for production metadata; also consider BWF axml for structured XML.
MKV / WebM: use Matroska tags (XML) or attachments.
XMP: universal container — embed JSON-LD or structured fields in XMP namespaces (xmpDM, xmpRights).

2) Sidecar files and DDEX

DDEX ERN (Electronic Release Notification) is the industry standard XML for dispatching release and rights metadata to publishers and distributors. Many publishers require ERN files as part of release packaging. Even if you're embedding metadata in the file, produce a DDEX ERN or equivalent JSON manifest for the admin team.

3) Web & page metadata

On the publishing page, include schema.org JSON-LD for MusicRecording / MusicComposition with isrcCode, composer, publisher and identifier fields. This helps discovery and indexing engines.

Developer recipes: concrete commands and templates

The following are proven, minimal examples you can copy into automation scripts.

Embed basic metadata into an MP4 with exiftool

<pre>exiftool -Title="Song Title" \
  -Artist="Artist Name" \
  -ISRC="US-ABC-21-00001" \
  -XMP-dc:creator="[\"Composer Name\"]" \
  -XMP-xmpRights:WebStatement="https://yourdomain.example/rights" \
  output.mp4</pre>

Notes: exiftool writes XMP into MOV/MP4 udta. Use -overwrite_original in scripts for CI pipelines.

Write a structured JSON royalty payload into an MP3 ID3 TXXX frame (eyeD3)

<pre>eyed3 --remove-all myfile.mp3
python - <<'PY'
from mutagen.id3 import ID3, TXXX
import json
meta = {
  "isrc": "US-ABC-21-00001",
  "iswc": "T-123.456.789-0",
  "contributors": [
    {"name": "Composer Name","role": "composer","ipi": "000000000"}
  ],
  "publisher": {"name": "Acme Publishing","admin": "Kobalt", "publisher_id":"KBT-12345"}
}
ID3('myfile.mp3').add(TXXX(encoding=3, desc='royalty_metadata', text=json.dumps(meta)))
ID3('myfile.mp3').save()
PY</pre>

Set MP4 freeform atom with AtomicParsley

<pre>AtomicParsley input.mp4 --title "Song Title" --artist "Artist Name" \
  --comment "{\"isrc\":\"US-ABC-21-00001\",\"publisher\":{\"name\":\"Acme\"}}" -o output.mp4</pre>

Embed schema.org JSON-LD into a web page

<pre><script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "MusicRecording",
  "name": "Song Title",
  "isrcCode": "US-ABC-21-00001",
  "byArtist": {"@type": "MusicGroup","name": "Artist Name"},
  "composer": {"@type": "Person","name": "Composer Name"},
  "isPartOf": {"@type": "MusicAlbum","name": "Release Title","barcode": "0123456789012"}
}
</script></pre>

DDEX ERN minimal XML template (sidecar)

Below is a stripped-down ERN-style XML template. Publishers will have specific required fields; treat this as a starting point:

<pre><ReleaseDelivery xmlns="http://ddex.net/xml/ern/3" ReleaseId="RELEASE-12345" DeliveryId="DEL-20260117-001">
  <Release>
    <ReleaseReference>
      <ReleaseId>GRID-0000001</ReleaseId>
    </ReleaseReference>
    <ReleaseDetails>
      <Title>Release Title</Title>
      <ReleaseType>Single</ReleaseType>
      <ReleaseDate>2026-01-17</ReleaseDate>
    </ReleaseDetails>
    <SoundRecordingList>
      <SoundRecording ReleaseSoundRecordingId="SR-0001">
        <Title>Song Title</Title>
        <SoundRecordingId>
          <ISRC>US-ABC-21-00001</ISRC>
        </SoundRecordingId>
        <RightsController>Kobalt Music</RightsController>
        <ContributorList>
          <Contributor><PartyName>Composer Name</PartyName><Role>Composer</Role><IPI>000000000</IPI></Contributor>
        </ContributorList>
      </SoundRecording>
    </SoundRecordingList>
  </Release>
</ReleaseDelivery></pre>

Automation pipeline: end-to-end pattern

A reliable ingestion pipeline should perform these steps automatically after export:

Generate canonical metadata JSON from your CMS/DAW export metadata (including contributor IDs and splits).
Embed core fields into the media file (ISRC, title, composer, publisher) using exiftool / AtomicParsley / mutagen.
Generate a DDEX ERN (or publisher-specific JSON manifest) from the canonical metadata.
Upload the asset to the CDN/hosting provider and transfer the ERN to the publisher via their ingestion mechanism (SFTP, API, or E-Mail).
Send a verification webhook to your internal dashboard and to the publisher with checksums and file manifests.

Example: a GitHub Actions job (simplified) could run the embed script, produce ERN XML, call a publisher API, and tag the release in your CMS.

Validation & QA: how to test that publishers can read your metadata

Never assume — always test. Publishers and collection houses have different parsers. Run these checks as part of CI:

Use exiftool -a -u -g1 file.mp4 and ffprobe -show_format -show_streams to inspect native atoms.
Use mutagen / id3v2 / eyeD3 to validate MP3 frames.
Validate ERN XML against DDEX schemas or use publisher-provided validators. Log and fix schema errors automatically.
Confirm checksums (SHA256) and upload receipt from the publisher or aggregator.
Send a test message with a small sample file when integrating with a new publisher like Kobalt — ask for sample ingestion logs.

Real-world considerations & 2026 trends

Here are four trends affecting metadata engineers in 2026 and how to adapt:

Growing admin partnerships: As Kobalt and others expand regionally (e.g., partnerships like Kobalt/Madverse), plan for multi-jurisdictional fields (territories, additional publisher IDs).
AI detection plus metadata: Platforms combine fingerprinting with metadata to reduce false positives. Provide both fingerprint (acoustic ID) and explicit metadata.
ISO & DDEX updates: Keep ERN generators up to date; subscribe to DDEX announcements and bump schema versions automatically in your generator.
Privacy & consent: Avoid embedding personal PII in public atoms; store contact PII in secure publisher manifests rather than public file fields where feasible.

Security, privacy, and governance

Embedded metadata is visible to anyone who downloads the file. Consider these rules:

Do not embed personal contact details in publicly-distributed assets. Use publisher/client IDs and store contact info in secure manifests delivered directly to the publisher.
Sign your delivery manifests with a delivery signature (SHA256 + private key) so receivers can validate authenticity.
Log every metadata injection and delivery as part of an immutable audit trail for disputes.

Edge cases and gotchas

Some streaming platforms strip or remap certain atoms — always supply a sidecar DDEX ERN to cover embedding losses.
Complex split arrangements (many contributors, micro-percentages) must be exact — round-tripping through JSON/XML converters can alter decimals. Use fixed decimal places and validate totals equal 100%.
Not every publisher accepts every field. When onboarding to a publisher (e.g., Kobalt), request their ingest schema and sample ERNs early.

Quick reference developer templates

Copy these templates into your repo and adapt the fields to match your CMS and publisher requirements.

Canonical JSON model (the single source of truth used to render XMP, ERN, ID3 payloads):

<pre>{
  "releaseId": "GRID-0000001",
  "recordings": [
    {
      "recordingId": "SR-0001",
      "title": "Song Title",
      "isrc": "US-ABC-21-00001",
      "iswc": "T-123.456.789-0",
      "contributors": [
        {"name": "Composer Name","role":"composer","ipi":"000000000","share":50},
        {"name": "Artist","role":"performer","ipi":"111111111","share":50}
      ],
      "publisher": {"name":"Acme Publishing","admin":"Kobalt","publisherId":"KBT-12345"},
      "rights": [{"type":"mechanical","territory":"WORLD","start":"2026-01-17"}]
    }
  ]
}</pre>

Checklist before distribution

Is ISRC assigned and embedded?
Are composer/writer names and IPI numbers present and accurate?
Is publisher/admin info present (name + admin ID)?
Is an ERN or publisher manifest generated and validated?
Did you compute and include a SHA256 fingerprint?
Did you notify publisher ingestion endpoint and confirm receipt?

Embed the metadata, register the release, and send the ERN — fingerprints alone are not enough to guarantee royalty attribution.

Example: Minimal end-to-end flow (practical)

1) Export final master video (MP4) from your NLE. 2) Run the metadata embedding script which reads your canonical JSON and writes XMP and TXXX frames. 3) Generate ERN XML and checksum. 4) Upload file to CDN and deliver ERN to publisher SFTP/API. 5) Confirm ingestion log from the publisher and archive the signed manifest.

Final best practices

Automate everywhere: Manual metadata entry is error-prone; use automated pipelines.
Keep a canonical source of truth: Your CMS or metadata DB should feed every output format (XMP, ID3, ERN).
Test with publishers early: Do a small test delivery and get parser logs from the publisher.
Version your schema: Track schema changes and migrations so older releases remain verifiable.

Takeaway

Embedding robust, standardized publishing and royalty metadata into your media files — and delivering a validated DDEX (or publisher‑specific) manifest — is the practical difference between discovered work and paid work. In 2026, with publishers expanding regionally and automation taking over routine administration, accurate metadata is not optional; it's the pathway to correct royalty collection.

Call to action

Ready to implement? Download the sample repository of scripts, ERN templates, and CI job examples from our integration hub (or fork our starter repo) and start embedding royalty‑ready metadata into your export pipeline today. If you’re integrating with a publisher like Kobalt, request their ingest schema and run a test delivery — then iterate until the ingestion logs show green. Need help? Contact our integrations team to review your pipeline and provide custom templates for your workflow.

Unknown

Contributor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.