Bulk Lyrics Submission

​

Documentation for Partners

This document outlines the standardized formats and methods for submitting lyrics in bulk to contribute lyrical content at scale.

Last updated May 7, 2025

​

Overview of Accepted Formats

Musixmatch accepts lyrics submissions in several standardized formats to accommodate different partner workflows:

1. CSV Musixmatch Standard Format - Method for bulk lyrics delivery primarily suitable for labels
2. JSONL Format - Method for bulk lyrics delivery primarily suitable for labels
3. DDEX MEAD - For partners using industry standard DDEX protocols
4. Lyrics-Specific API: miss.process.post - Method for bulk lyrics delivery primarily suitable for labels
5. Publisher-Specific API: work.post - For publishers to submit copyright information and lyrics associated with musical works

​

Submission Process

1. Initial Setup: Contact Musixmatch filling this form to establish credentials and delivery method
2. Test Submission: Send a small (100 tracks) batch for validation
3. Feedback Integration: Address any formatting issues identified
4. Production Submission: Begin regular delivery of properly formatted lyrics

​

Best Practices

1. Data Validation: Ensure all ISRCs are valid and correctly formatted
2. Lyrics Transcription: Ensure that the lyrics are transcribed as sung in the recording, following Musixmatch transcription guidelines
3. Lyrics Formatting: Maintain original line breaks and paragraph structure
4. Character Encoding: Verify UTF-8 encoding to preserve special characters
5. Regular Updates: Establish a consistent schedule for delivering new content
6. Communication: Inform Musixmatch of significant changes to your delivery format

Note that internal staff may periodically review lyrics to maintain the quality standards required by DSPs, with no impact on content integrity.

​

1. CSV Standard Format for Lyrics Submission

​

File Specifications

• File naming convention: partnername_lyrics_YYYYMMDD.csv
• Format: CSV file (not Excel)
• Encoding: UTF-8, with or without BOM
• Delimiter: Comma (,)
• Quote character: Double quote (”)
  • Used to escape values containing delimiters
  • Example: "Laser , Game", nice, 829
• Escape character: Double quote (”)
  • For escaping quoted values containing quotes
  • Example: "We Will Rock You (From ""We Will Rock You"")"

​

Headers and Fields

Headers must appear in this exact order:

​

Example

isrc,title,artist,duration,language,partner_id,lyrics
GBAAA9100070,Stars,John Doe,247000,en,A23,"Lyrics body in brackets 
command return to line break,
lorem ipsum"
GBAAA9100071,Luna,Jane Something,247001,es,A24,"Lyrics body in brackets 
command return to line break,
lorem ipsum"

​

2. JSONL Format

The JSONL format, with each JSON object on a single line, is efficient for streaming and processing large datasets. Its line-by-line structure supports independent processing, simple appending, and efficient handling of bulk lyric submissions.

Below is a JSONL model that reflects the CSV standard format for lyrics submission.

​

JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["isrc", "artist", "title", "lyrics"],
  "properties": {
    "isrc": {
      "type": "string",
      "description": "International Standard Recording Code",
      "pattern": "^[A-Z]{2}-?[A-Z\\d]{3}-?\\d{2}-?\\d{5}$"
    },
    "artist": {
      "type": "string",
      "description": "Name of the artist associated with the track"
    },
    "title": {
      "type": "string",
      "description": "Title of the track"
    },
    "lyrics": {
      "type": "string",
      "description": "The lyrics as sung in the recording, following Musixmatch transcription guidelines"
    },
    "duration": {
      "type": "integer",
      "description": "Integer representing track duration in milliseconds (e.g., 240000 for 4 minutes); fill in '0' if not available"
    },
    "language": {
      "type": "string",
      "description": "The expected language (ISO 3166-1 alpha-2 code)",
      "pattern": "^[a-zA-Z]{2}$"
    },
    "partner_id": {
      "type": "string",
      "description": "Partner internal identification number"
    }
  },
  "additionalProperties": false
}

​

JSONL Example with Single Lyrics

{"isrc":"ABCDE1234567","artist":"Artist Name","title":"Track Title","lyrics":"Lyrics line 1\nLyrics line 2\nLyrics line 3","duration":240000,"language":"en","partner_id":"PARTNER123"}

​

JSONL Example with Multiple Lyrics

{"isrc":"ABCDE1234567","artist":"Artist Name","title":"Track Title","lyrics":"Lyrics line 1\nLyrics line 2\nLyrics line 3","duration":240000,"language":"en","partner_id":"PARTNER123"}
{"isrc":"FGHIJ8901234","artist":"Another Artist","title":"Another Track","lyrics":"More lyrics line 1\nMore lyrics line 2","duration":180000,"language":"fr","partner_id":"PARTNER124"}
{"isrc":"KLMNO5678901","artist":"Third Artist","title":"Third Track","lyrics":"Third song lyrics\nWith multiple lines\nAnd verses too","duration":320000,"language":"es","partner_id":"PARTNER125"}

​

3. DDEX MEAD Standard

For partners already using DDEX standards, Musixmatch accepts lyrics submissions using DDEX MEAD (Media Enrichment and Description) version 1.1.

Different DDEX formats should be agreed upon separately.

​

MEAD Integration

• Standard Version: MEAD 1.1
• Official Reference: DDEX MEAD Documentation

The ISRC field is mandatory.

​

4. Lyrics-Specific API

​

API Endpoint

​

4.1 miss.process.post

To submit data, use the following endpoint:

POST https://api.musixmatch.com/ws/1.1/miss.process.post?batch_type=lyrics_post

Payload parameters:

{
  "isrc": "string",
  "ext_id": "string",
  "lyrics_body": "string"
}

Example response:

{
  "message": "",
  "data": {
    "created_batch_list": [
      1671539
    ]
  }
}

​

4.2 miss.process.get

To find more information about the aforementioned ID:

GET https://api.musixmatch.com/ws/1.1/miss.process.get?batch_id=1671539

Example response:

{
  "message": "",
  "data": {
    "batch_id": 1671539,
    "status": "success",
    "created_by": "...",
    "batch_step_list": [
      {
        "id": 3800222,
        "name": "...",
        "status": "success",
        "created_at": {
          ...
        },
        "ended_at": {
          ...
        },
        "details": "",
        "metadata": {
          ...
        }
      }
    ]
  }
}

To retrieve the data the developer has to set a polling to the API above.

​

5. Publisher-Specific API: work.post

Note: The work.post API is exclusively for publishers to submit copyright information and lyrics associated with musical works. If you are a label looking to send lyrics in bulk, please use one of the other methods listed in the documentation.

​

API Endpoint

POST https://api.musixmatch.com/ws/1.1/work.post

For detailed information on using this API refer to our official documentation. For activation, please contact your Musixmatch representative.

This documentation is subject to updates as formats evolve. Partners will be notified of any significant changes to submission requirements.