> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.royalti.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Advanced Metadata (MEAD)

> Guide to using MEAD enhancement fields for products and assets for rich metadata delivery to DSPs

## Overview

The Royalti.io API supports advanced metadata fields for both **Products** (albums/releases) and **Assets** (tracks) aligned with the DDEX MEAD (Music Enrichment and Description) standard. These fields enable rich metadata delivery to Digital Service Providers (DSPs), improving discoverability and providing comprehensive release information.

### When to Use MEAD Fields

* **Reissues and Special Editions**: Track original release dates, edition types, and reissue status
* **Chart-Eligible Releases**: Include chart history and sequence information
* **Professional Productions**: Document recording/mastering locations, producers, and engineers
* **Multi-Disc Releases**: Specify disc counts and track totals
* **Catalog Variants**: Link related releases via parent release IDs
* **Track-Level Enrichment**: Add musical attributes like tempo, key, and mood to assets

***

## Product MEAD Fields

### Release Information

| Field                 | Type    | Description                          | Example                                |
| --------------------- | ------- | ------------------------------------ | -------------------------------------- |
| `edition`             | string  | Edition designation                  | "Deluxe", "Remastered", "Anniversary"  |
| `reissue`             | boolean | Whether this is a reissue            | `true`                                 |
| `originalReleaseDate` | date    | Original release date (for reissues) | "1985-06-15"                           |
| `packageType`         | string  | Physical/digital package type        | "Album", "EP", "Compilation"           |
| `totalTracks`         | integer | Total track count                    | 12                                     |
| `totalDiscs`          | integer | Total disc count                     | 2                                      |
| `sequenceNumber`      | integer | Position in series/discography       | 5                                      |
| `parentReleaseId`     | uuid    | Parent release for variants          | "550e8400-e29b-41d4-a716-446655440000" |

### Production Credits

| Field               | Type   | Description               | Example                      |
| ------------------- | ------ | ------------------------- | ---------------------------- |
| `producer`          | array  | Producer name(s)          | \["Rick Rubin", "Dr. Dre"]   |
| `engineer`          | array  | Engineer name(s)          | \["Bob Clearmountain"]       |
| `recordingLocation` | string | Recording studio/location | "Abbey Road Studios, London" |
| `masteringLocation` | string | Mastering facility        | "Sterling Sound, NYC"        |

### Chart and Performance Data

| Field          | Type  | Description                |
| -------------- | ----- | -------------------------- |
| `chartHistory` | array | Historical chart positions |

**Chart History Object:**

```json theme={null}
{
  "chart": "Billboard Hot 100",
  "position": 1,
  "date": "2024-03-15"
}
```

### Copyright Information

| Field         | Type    | Description                  | Example           |
| ------------- | ------- | ---------------------------- | ----------------- |
| `c_line_year` | integer | Copyright line year          | 2024              |
| `p_line_year` | integer | Phonogram line year          | 2024              |
| `copyright`   | string  | Copyright holder             | "XYZ Records Inc" |
| `publisher`   | string  | Publisher name               | "XYZ Publishing"  |
| `language`    | string  | Primary language (ISO 639-1) | "en"              |

***

## Asset MEAD Fields

Assets (tracks) support their own set of MEAD enhancement fields for track-level metadata.

### Musical Attributes

| Field   | Type   | Description      | Example                     |
| ------- | ------ | ---------------- | --------------------------- |
| `tempo` | number | Tempo in BPM     | 120                         |
| `key`   | string | Musical key      | "C major", "A minor"        |
| `mood`  | array  | Mood descriptors | \["Energetic", "Uplifting"] |

### Production Information

| Field               | Type    | Description               | Example                      |
| ------------------- | ------- | ------------------------- | ---------------------------- |
| `recordingLocation` | string  | Recording studio/location | "Electric Lady Studios, NYC" |
| `recordingDate`     | date    | Date of recording         | "2024-03-15"                 |
| `productionYear`    | integer | Year of production        | 2024                         |
| `copyrightOwner`    | string  | Copyright owner           | "XYZ Records Inc"            |

### Classification

| Field             | Type   | Description                | Example                           |
| ----------------- | ------ | -------------------------- | --------------------------------- |
| `genre`           | array  | Genre classifications      | \["Pop", "Electronic"]            |
| `subGenre`        | array  | Sub-genre classifications  | \["Synth-pop", "Dance"]           |
| `rhythmStyle`     | array  | Rhythm style descriptors   | \["Four-on-the-floor"]            |
| `instrumentation` | array  | Instruments used           | \["Synthesizer", "Drums", "Bass"] |
| `language`        | string | Lyric language (ISO 639-1) | "en"                              |

### Additional Metadata

| Field               | Type  | Description                | Example                     |
| ------------------- | ----- | -------------------------- | --------------------------- |
| `alternativeTitles` | array | Alternative track titles   | \["Radio Edit", "Club Mix"] |
| `chartPositions`    | array | Historical chart positions | See chart object below      |

***

## Quick Start

### Creating a Product with MEAD Fields

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.royalti.io/product \
      -H "Authorization: Bearer YOUR_API_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "title": "Greatest Hits (Remastered)",
        "upc": "123456789012",
        "displayArtist": "Example Artist",
        "releaseDate": "2024-06-01",
        "edition": "Remastered",
        "reissue": true,
        "originalReleaseDate": "1995-03-15",
        "c_line_year": 2024,
        "p_line_year": 1995,
        "copyright": "Legacy Records LLC",
        "publisher": "Legacy Records LLC",
        "totalTracks": 16,
        "totalDiscs": 1,
        "recordingLocation": "Sunset Sound, Los Angeles",
        "masteringLocation": "Bernie Grundman Mastering",
        "producer": ["Original Producer Name"],
        "engineer": ["Remaster Engineer Name"]
      }'
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const response = await fetch('https://api.royalti.io/product', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        title: 'Greatest Hits (Remastered)',
        upc: '123456789012',
        displayArtist: 'Example Artist',
        releaseDate: '2024-06-01',
        edition: 'Remastered',
        reissue: true,
        originalReleaseDate: '1995-03-15',
        c_line_year: 2024,
        p_line_year: 1995,
        copyright: 'Legacy Records LLC',
        publisher: 'Legacy Records LLC',
        totalTracks: 16,
        totalDiscs: 1,
        recordingLocation: 'Sunset Sound, Los Angeles',
        masteringLocation: 'Bernie Grundman Mastering',
        producer: ['Original Producer Name'],
        engineer: ['Remaster Engineer Name']
      })
    });

    const { data } = await response.json();
    console.log('Product created:', data.id);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.post(
        'https://api.royalti.io/product',
        headers={
            'Authorization': f'Bearer {API_TOKEN}',
            'Content-Type': 'application/json'
        },
        json={
            'title': 'Greatest Hits (Remastered)',
            'upc': '123456789012',
            'displayArtist': 'Example Artist',
            'releaseDate': '2024-06-01',
            'edition': 'Remastered',
            'reissue': True,
            'originalReleaseDate': '1995-03-15',
            'c_line_year': 2024,
            'p_line_year': 1995,
            'copyright': 'Legacy Records LLC',
            'publisher': 'Legacy Records LLC',
            'totalTracks': 16,
            'totalDiscs': 1,
            'recordingLocation': 'Sunset Sound, Los Angeles',
            'masteringLocation': 'Bernie Grundman Mastering',
            'producer': ['Original Producer Name'],
            'engineer': ['Remaster Engineer Name']
        }
    )

    data = response.json()['data']
    print(f"Product created: {data['id']}")
    ```
  </Tab>
</Tabs>

### Creating an Asset with MEAD Fields

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.royalti.io/asset \
      -H "Authorization: Bearer YOUR_API_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "title": "Summer Nights",
        "isrc": "USRC12345678",
        "displayArtist": "Example Artist",
        "tempo": 128,
        "key": "G major",
        "mood": ["Energetic", "Happy", "Summer"],
        "genre": ["Pop", "Dance"],
        "subGenre": ["Synth-pop"],
        "recordingLocation": "Electric Lady Studios, NYC",
        "recordingDate": "2024-02-15",
        "productionYear": 2024,
        "copyrightOwner": "XYZ Records Inc",
        "instrumentation": ["Synthesizer", "Drums", "Bass", "Vocals"],
        "language": "en"
      }'
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const response = await fetch('https://api.royalti.io/asset', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        title: 'Summer Nights',
        isrc: 'USRC12345678',
        displayArtist: 'Example Artist',
        tempo: 128,
        key: 'G major',
        mood: ['Energetic', 'Happy', 'Summer'],
        genre: ['Pop', 'Dance'],
        subGenre: ['Synth-pop'],
        recordingLocation: 'Electric Lady Studios, NYC',
        recordingDate: '2024-02-15',
        productionYear: 2024,
        copyrightOwner: 'XYZ Records Inc',
        instrumentation: ['Synthesizer', 'Drums', 'Bass', 'Vocals'],
        language: 'en'
      })
    });

    const { data } = await response.json();
    console.log('Asset created:', data.id);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    response = requests.post(
        'https://api.royalti.io/asset',
        headers={
            'Authorization': f'Bearer {API_TOKEN}',
            'Content-Type': 'application/json'
        },
        json={
            'title': 'Summer Nights',
            'isrc': 'USRC12345678',
            'displayArtist': 'Example Artist',
            'tempo': 128,
            'key': 'G major',
            'mood': ['Energetic', 'Happy', 'Summer'],
            'genre': ['Pop', 'Dance'],
            'subGenre': ['Synth-pop'],
            'recordingLocation': 'Electric Lady Studios, NYC',
            'recordingDate': '2024-02-15',
            'productionYear': 2024,
            'copyrightOwner': 'XYZ Records Inc',
            'instrumentation': ['Synthesizer', 'Drums', 'Bass', 'Vocals'],
            'language': 'en'
        }
    )

    data = response.json()['data']
    print(f"Asset created: {data['id']}")
    ```
  </Tab>
</Tabs>

***

## Common Use Cases

### Product: Reissued Album

When re-releasing a classic album with new mastering:

```json theme={null}
{
  "title": "Thriller (40th Anniversary Edition)",
  "releaseDate": "2022-11-18",
  "edition": "40th Anniversary",
  "reissue": true,
  "originalReleaseDate": "1982-11-30",
  "c_line_year": 2022,
  "p_line_year": 1982,
  "masteringLocation": "Capitol Studios, Hollywood",
  "producer": ["Quincy Jones"],
  "engineer": ["Matt Hennessy"]
}
```

<Note>
  For reissues, `p_line_year` typically reflects the original recording year, while `c_line_year` reflects the new release year.
</Note>

### Product: Deluxe Edition with Bonus Tracks

When releasing an expanded version of an album:

```json theme={null}
{
  "title": "Album Name (Deluxe Edition)",
  "edition": "Deluxe",
  "totalTracks": 18,
  "totalDiscs": 2,
  "parentReleaseId": "original-album-uuid",
  "sequenceNumber": 2
}
```

### Product: Multi-Disc Box Set

For comprehensive anthology releases:

```json theme={null}
{
  "title": "Complete Studio Albums Box Set",
  "packageType": "Box Set",
  "totalDiscs": 8,
  "totalTracks": 96,
  "edition": "Collector's Edition",
  "recordingLocation": "Various Studios",
  "producer": ["Producer A", "Producer B", "Producer C"]
}
```

### Product: Chart-Eligible Release with History

Including historical chart performance:

```json theme={null}
{
  "title": "Hit Single",
  "chartHistory": [
    {
      "chart": "Billboard Hot 100",
      "position": 1,
      "date": "2023-08-15"
    },
    {
      "chart": "UK Singles Chart",
      "position": 3,
      "date": "2023-08-18"
    }
  ]
}
```

### Asset: Electronic Dance Track

Rich metadata for DJ and playlist curation:

```json theme={null}
{
  "title": "Midnight Drive",
  "isrc": "USRC98765432",
  "displayArtist": "DJ Example",
  "tempo": 126,
  "key": "A minor",
  "mood": ["Dark", "Driving", "Atmospheric"],
  "genre": ["Electronic", "House"],
  "subGenre": ["Tech House", "Progressive"],
  "rhythmStyle": ["Four-on-the-floor"],
  "instrumentation": ["Synthesizer", "Drum Machine", "Bass Synthesizer"],
  "language": "en"
}
```

### Asset: Acoustic Recording

Capturing performance details:

```json theme={null}
{
  "title": "Unplugged Session",
  "isrc": "USRC11223344",
  "displayArtist": "Singer Songwriter",
  "recordingLocation": "Village Studios, Los Angeles",
  "recordingDate": "2024-01-20",
  "productionYear": 2024,
  "copyrightOwner": "Indie Label LLC",
  "mood": ["Intimate", "Melancholic", "Reflective"],
  "instrumentation": ["Acoustic Guitar", "Vocals", "Piano"],
  "key": "E minor",
  "tempo": 72
}
```

***

## Updating Existing Products

Add MEAD fields to existing products using the PUT endpoint:

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X PUT https://api.royalti.io/product/prod-123 \
      -H "Authorization: Bearer YOUR_API_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "edition": "Deluxe",
        "totalTracks": 15,
        "producer": ["New Producer"],
        "recordingLocation": "Studio Name"
      }'
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const response = await fetch('https://api.royalti.io/product/prod-123', {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        edition: 'Deluxe',
        totalTracks: 15,
        producer: ['New Producer'],
        recordingLocation: 'Studio Name'
      })
    });

    const { data } = await response.json();
    console.log('Product updated:', data);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = requests.put(
        'https://api.royalti.io/product/prod-123',
        headers={
            'Authorization': f'Bearer {API_TOKEN}',
            'Content-Type': 'application/json'
        },
        json={
            'edition': 'Deluxe',
            'totalTracks': 15,
            'producer': ['New Producer'],
            'recordingLocation': 'Studio Name'
        }
    )

    data = response.json()['data']
    print(f"Product updated: {data}")
    ```
  </Tab>
</Tabs>

## Updating Existing Assets

Add MEAD fields to existing assets using the PUT endpoint:

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X PUT https://api.royalti.io/asset/asset-123 \
      -H "Authorization: Bearer YOUR_API_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "tempo": 128,
        "key": "C major",
        "mood": ["Uplifting", "Energetic"],
        "copyrightOwner": "New Rights Holder LLC"
      }'
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const response = await fetch('https://api.royalti.io/asset/asset-123', {
      method: 'PUT',
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        tempo: 128,
        key: 'C major',
        mood: ['Uplifting', 'Energetic'],
        copyrightOwner: 'New Rights Holder LLC'
      })
    });

    const { data } = await response.json();
    console.log('Asset updated:', data);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = requests.put(
        'https://api.royalti.io/asset/asset-123',
        headers={
            'Authorization': f'Bearer {API_TOKEN}',
            'Content-Type': 'application/json'
        },
        json={
            'tempo': 128,
            'key': 'C major',
            'mood': ['Uplifting', 'Energetic'],
            'copyrightOwner': 'New Rights Holder LLC'
        }
    )

    data = response.json()['data']
    print(f"Asset updated: {data}")
    ```
  </Tab>
</Tabs>

***

## Bulk Operations

Update multiple products with MEAD fields efficiently:

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.royalti.io/product/bulk \
      -H "Authorization: Bearer YOUR_API_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "products": [
          {
            "title": "Album One",
            "upc": "111111111111",
            "displayArtist": "Artist",
            "releaseDate": "2024-01-01",
            "edition": "Standard",
            "c_line_year": 2024,
            "p_line_year": 2024
          },
          {
            "title": "Album One (Deluxe)",
            "upc": "222222222222",
            "displayArtist": "Artist",
            "releaseDate": "2024-03-01",
            "edition": "Deluxe",
            "c_line_year": 2024,
            "p_line_year": 2024,
            "totalTracks": 18
          }
        ]
      }'
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const response = await fetch('https://api.royalti.io/product/bulk', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${API_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        products: [
          {
            title: 'Album One',
            upc: '111111111111',
            displayArtist: 'Artist',
            releaseDate: '2024-01-01',
            edition: 'Standard',
            c_line_year: 2024,
            p_line_year: 2024
          },
          {
            title: 'Album One (Deluxe)',
            upc: '222222222222',
            displayArtist: 'Artist',
            releaseDate: '2024-03-01',
            edition: 'Deluxe',
            c_line_year: 2024,
            p_line_year: 2024,
            totalTracks: 18
          }
        ]
      })
    });

    const { data } = await response.json();
    console.log(`Created ${data.created} products`);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    response = requests.post(
        'https://api.royalti.io/product/bulk',
        headers={
            'Authorization': f'Bearer {API_TOKEN}',
            'Content-Type': 'application/json'
        },
        json={
            'products': [
                {
                    'title': 'Album One',
                    'upc': '111111111111',
                    'displayArtist': 'Artist',
                    'releaseDate': '2024-01-01',
                    'edition': 'Standard',
                    'c_line_year': 2024,
                    'p_line_year': 2024
                },
                {
                    'title': 'Album One (Deluxe)',
                    'upc': '222222222222',
                    'displayArtist': 'Artist',
                    'releaseDate': '2024-03-01',
                    'edition': 'Deluxe',
                    'c_line_year': 2024,
                    'p_line_year': 2024,
                    'totalTracks': 18
                }
            ]
        }
    )

    data = response.json()['data']
    print(f"Created {data['created']} products")
    ```
  </Tab>
</Tabs>

## DSP Delivery Integration

MEAD fields are automatically included when delivering products to DSPs that support rich metadata.

### Supported Providers

DSPs that accept MEAD enhancement fields:

| Provider      | Edition | Reissue Info | Production Credits | Chart Data |
| ------------- | ------- | ------------ | ------------------ | ---------- |
| Spotify       | Yes     | Yes          | Yes                | No         |
| Apple Music   | Yes     | Yes          | Yes                | No         |
| YouTube Music | Yes     | Yes          | Partial            | No         |
| Tidal         | Yes     | Yes          | Yes                | Yes        |
| Deezer        | Yes     | Yes          | Partial            | No         |
| Amazon Music  | Yes     | Yes          | Yes                | No         |

### Validation Before Delivery

When delivering products, MEAD fields are validated against provider requirements:

```bash theme={null}
curl -X POST https://api.royalti.io/product/prod-123/deliveries/validate \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "providers": ["spotify-ddex-sftp", "apple-ddex-api"]
  }'
```

The validation response includes warnings for MEAD fields that may not transfer to specific providers.

## Best Practices

<CardGroup cols={2}>
  <Card title="Copyright Year Accuracy" icon="calendar">
    Use `p_line_year` for original recording year and `c_line_year` for the current release compilation/mastering year.
  </Card>

  <Card title="Link Related Releases" icon="link">
    Use `parentReleaseId` and `sequenceNumber` to maintain catalog relationships between standard and deluxe editions.
  </Card>

  <Card title="Production Credits" icon="users">
    Include all relevant producers and engineers for proper attribution and improved DSP discoverability.
  </Card>

  <Card title="Reissue Documentation" icon="rotate">
    Always set `originalReleaseDate` when `reissue` is true for accurate release history.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="MEAD fields not appearing in DSP delivery">
    **Cause:** The delivery provider may not support specific MEAD fields.

    **Solution:**

    1. Check the provider's supported fields in the [Product Delivery guide](/guides/product-delivery)
    2. Verify the fields are set before delivery
    3. Some fields are DDEX MEAD-specific and may not transfer via CSV delivery methods
  </Accordion>

  <Accordion title="Invalid c_line_year or p_line_year">
    **Error:** `Year must be between 1900 and 2100`

    **Solution:** Ensure year values are 4-digit integers within the valid range:

    ```json theme={null}
    {
      "c_line_year": 2024,
      "p_line_year": 1985
    }
    ```
  </Accordion>

  <Accordion title="chartHistory validation error">
    **Error:** `Invalid chart history format`

    **Solution:** Each chart history entry must include `chart`, `position`, and `date`:

    ```json theme={null}
    {
      "chartHistory": [
        {
          "chart": "Billboard Hot 100",
          "position": 1,
          "date": "2024-01-15"
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="Invalid tempo value">
    **Error:** `Tempo must be a positive number`

    **Solution:** Tempo should be a positive integer representing BPM (beats per minute), typically between 60-200:

    ```json theme={null}
    {
      "tempo": 128
    }
    ```
  </Accordion>

  <Accordion title="Asset mood or genre not appearing in DSP">
    **Cause:** Some DSPs have their own genre/mood taxonomies and may not accept custom values.

    **Solution:**

    1. Use standardized mood and genre terms where possible
    2. Check DSP-specific documentation for accepted values
    3. Asset classification fields like `mood`, `genre`, and `subGenre` are best-effort mappings
  </Accordion>
</AccordionGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="Product API Reference" icon="book" href="/api-reference/product/post-product">
    Complete product endpoint documentation
  </Card>

  <Card title="Asset API Reference" icon="music" href="/api-reference/asset/post-asset">
    Complete asset endpoint documentation
  </Card>

  <Card title="Product Delivery" icon="rocket" href="/guides/product-delivery">
    Deliver products to DSPs
  </Card>

  <Card title="Asset DDEX Management" icon="file-audio" href="/guides/asset-ddex-management">
    Prepare assets for DDEX delivery
  </Card>

  <Card title="DDEX Integration" icon="file-code" href="/guides/ddex-integration">
    DDEX message generation
  </Card>

  <Card title="FUGA Integration" icon="upload" href="/guides/fuga-integration">
    CSV-based distribution via FUGA
  </Card>
</CardGroup>