​
Introduction

This documentation provides technical guidance for integrating Musixmatch’s music metadata into your product. The feed delivers various music-related metadata, including lyrics, writing credits, translations, mood information, and the structural breakdown of tracks. Additionally, it describes the data delivery process, which includes weekly full feeds and daily incremental updates. This document outlines how to interpret and use each section of the data to enrich your product experience. Note that, depending on the contractual agreement between Musixmatch and the client accessing the feed, some of the information described here might not be available to the client.

​
Feed Structure Overview

The metadata feed contains multiple elements such as lyrics, song credits, translations, mood data, and song structure. The feed is delivered in two main ways:

  • Full feed: A complete data feed delivered once a week.
  • Incremental updates: Daily updates containing changes that have occurred since the last full feed.

These deliveries allow your system to stay up-to-date with minimal overhead by consuming only the necessary updates daily, while having access to the full dataset on a weekly basis.

Each item in the feed is delivered in a JSON format and has the following structure:

{
  "commontrack_id": 123456, //internal Musixmatch track id
  "lyrics_id": 456789, //internal Musixmatch lyrics id
  "isrcs": ["USUV12345678"], //ISRC ids associated to the track,
  "language_iso_code_1": "en",
  "explicit": true, //boolean flag for if the track contains explicit lyrics
  "instrumental": false, //boolean flag for if the track is instruemental or not
  "title": "Track Title",
  "artist": "Artist Name",
  "lyrics": "First lyrics line\nSecond lyrics line\nEtc.",
  "snippet": "Most relevant lyrics line of the song",
  "syncs": [], //array of line by line time synced lyrics
  "richsyncs": [], //array of word by word time synced lyrics
  "writers": [], //array of songwriters information
  "translations": [], //array of lyrics translations in multiple languages
  "metadata": {
    "mood_list": [], //array of song moods
    "structure": {}, //song structure information
  },
  "performers": [], //array of song's performers
  "genre": [], //array of the song's genres
  "restrictions": {}, //regional restrictions rules for displaying lyrics
}

​
Detailed Feed Sections

​
Lyrics

The lyrics section provides full-text lyrics of a song, including information about explicit content, language, and the structure of time-synchronized lyrics.

  • Full Lyrics: The complete text of the lyrics in the song. This is typically provided as a single string and may include markers for explicit language. Example:
“lyrics”: “First lyrics line\nSecond lyrics line\nEtc.”
  • Line by line Time-Synchronized Lyrics (Syncs): Time-coded lyrics aligned with specific moments in the song. Each entry in the synchronization list will provide the start time in milliseconds and the corresponding lyric. Example:
"syncs": [
  {
    "id": 123456,
    “body”: [
      {
        “start_milliseconds”: 230,
        “lyric”: “First lyrics line”
      },
      {
        “start_milliseconds”: 3670,
        “lyric”: “Second lyrics line”
      }
    ]
  }
]
  • Word by word Time-Synchronized Lyrics (Rich Syncs): In addition to the line by line synchronisation, with this format we provide also specific timing for each word in a lyrics line. Example:
"richsyncs": [
  {
    "id": 7852411,
    "body": [
      {
        "ts": 3.2, //start time of the line in seconds
        "te": 3.73, //end time of the line in seconds
        "l": [
          {
            "c": "First", // word
            "o": 0 // offset time from the line's start time in seconds
          },
          {
            "c": " ",
            "o": 0.105
          },
          {
            "c": "lyrics",
            "o": 0.158
          },
          {
            "c": " ",
            "o": 0.211
          },
          {
            "c": "line",
            "o": 0.264
          },
        ],
        "x": "First lyrics line" // lyrics line
      },
      {
        "ts": 3.73,
        "te": 5.567,
        "l": [
          {
            "c": "Second",
            "o": 0
          },
          {
            "c": " ",
            "o": 0.01
          },
          {
            "c": "lyrics",
            "o": 0.08
          },
          {
            "c": " ",
            "o": 0.33
          },
          {
            "c": "line",
            "o": 0.38
          }        
        ],
      "x": "Second lyrics line"
     }
    ]
  }
]

​
Writers

When available, Musixmatch provides song writing information for each track in the following format.

"writers": [
  {
    "id": 123456, //internal Musixmatch writer id
    "name": "John Smith"
  },
  {
    "id": 345678, //internal Musixmatch writer id
    "name": "Jane Doe"
  }
]

​
Translations

When available, the translated lyrics, are delivered in the format bellow.

"translations": [
  {
    "language_iso_code_1": "fr",
    "lyrics": "Première ligne de paroles\nDeuxième ligne de paroles\nEtc."
  },
  {
    "language_iso_code_1": "de",
    "lyrics": "Erste Liedtextzeile\nZweite Liedtextzeile\nusw."
  }
]

​
Mood

The mood section describes the emotional tone or atmosphere of a track. The feed outputs a selection of 5 most relevant moods for a track from a pool of 25 possible mood labels. Each of the 5 moods is given a value between 0 and 1 defining the amount of the respective mood present in the song.

List of all possible labels:

  • peaceful
  • tender
  • sentimental
  • melancholy
  • somber
  • easygoin
  • romantic
  • sophisticated
  • cool
  • gritty
  • upbeat
  • empowering
  • sensual
  • yearning
  • serious
  • lively
  • stirring
  • fiery
  • urgent
  • brooding
  • excited
  • rowdy
  • energizing
  • defiant
  • aggressive
"mood_list": [
  {
    "label": "sensual",
    "value": 0.22
  },
  {
    "label": "empowering",
    "value": 0.116
  },
  {
    "label": "fiery",
    "value": 0.115
  },
  {
    "label": "stirring",
    "value": 0.078
  },
  {
    "label": "sophisticated",
    "value": 0.059
  }
]

​
Structure

Musixmatch provides a breakdown of the structural elements of a track, such as verses, choruses, bridges, and more. This detailed information allows for deeper insights into the composition of the song.

Sections: A breakdown of each structural element of the track (e.g., verse, chorus, bridge).

  • Intro: The Intro comes at the beginning and introduces the song. It may also introduce the performers by name, especially in rap songs‍. This tag is used for labelling the lyrical introduction to a track and not to be confused with the instrumental part at the begging of a track.
  • Hook: The Hook is the catchiest part of a song - the bit that usually sticks with the listener. Not to be confused with the Chorus as it’s often more repetitive and a little less melodic.
  • Verse: The Verse is the bit of a song that is the most narrative. It tells the story and is usually a little less memorable and catchy than the Chorus or Hook. When two or more sections of the song have almost identical melodies but different lyrics, you can consider each section one verse.
  • Pre-chorus: This is the linking section between the Verse and the Chorus. Not every song has a distinct Pre-chorus, but if it’s there it’s usually distinguished from the verses by a change in the melody or the instrumentation.
  • Chorus: This is most likely the bit the song is famous for. It is repeated throughout the song, usually without changes to the melody or lyrics. It often contains the song title.
  • Bridge: The Bridge commonly comes about 60% of the way through the song and often introduces new melodic and lyrical ideas before a final repetition of the Chorus. It does sometimes, however, ‘re-imagine’ a Verse or the Chorus - maybe presenting the same lyrics with different instrumentation to spice it up a bit.
  • Outro: The Outro takes a song to its conclusion - always coming at the very end of the track‍. As the Intro is used just at the beginning of the track, the Outro is used only at the end.

Example:

"structure": {
  "intro": {
    "lines": [0] //array of indexes of the lyric lines that make part of the specifc song section
  },
  "verse": {
    "lines": [1, 2, 3, 4, 5, 6, 7, 8, 20, 21, 22, 23, 24, 25, 26, 27]
  },
  "chorus": {
    "lines": [9, 10, 11, 12, 32, 33, 34, 35]
  },
  "hook": {
    "lines": [13, 14, 15, 16, 17, 18, 19]
  },
  "pre-chorus": {
    "lines": [28, 29, 30, 31]
  },
  "outro": {
    "lines": [36, 37, 38]
  }
}

​
Performers

The performers section provides information on the artists performing the song, when available. The data is a breakdown of the lyrics with each part(snippet) having associated one or more performers and in some cases the performer can also be unknown. The performer object contains the type and an id to an external artist entity (such as a Spotify artist id).

Example:

"performers": [
  {
    "snippet": "Lorem ipsum\n",
    "performers": [
      {
        "type": "unknown"
      }
    ]
  },
  {
    "snippet": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.\nPellentesque vestibulum elit id ultricies consequat.\n",
    "performers": [
      {
        "type": "artist",
        "fqid": "spotify:artist:2YZyLoL8N0Wb9xBt1NhZWg"
      }
    ]
  },
  {
    "snippet": "Maecenas eget augue vel est egestas commodo vitae eu tortor./nDonec mollis mi eget lorem aliquet, et bibendum elit rhoncus./n",
    "performers": [
      {
        "type": "artist",
        "fqid": "spotify:artist:7tYKF4w9nC0nq9CsPZTHyP"
      }
    ]
  },
  {
    "snippet": "Donec gravida nibh lacinia odio tincidunt, in mattis mauris aliquet./nProin in lacus mollis, vulputate nunc vitae, ornare lorem./n",
    "performers": [
      {
        "type": "artist",
        "fqid": "spotify:artist:7tYKF4w9nC0nq9CsPZTHyP"
      },
      {
        "type": "artist",
        "fqid": "spotify:artist:2YZyLoL8N0Wb9xBt1NhZWg"
      }
    ]
  }
]

​
Genre

The genres associated to a track are listed as an array like described here:

"genre": [
  {
    "id": 1076, //internal Musixmatch genre id
    "name": "Rap"
  },
  {
    "id": 18,
    "name": "Hip Hop/Rap"
  }
]

​
Restrictions

Restrictions on content are applied for a number of reasons; however, it all comes down to preserving copyright owners and preventing legal queries.

Within every API response that includes lyrics or subtitles we’re going to provide a territory based restriction data which will allows you to identify the countries you are allowed to display that content in.

It is imperative that the client applies the updates of the country-restriction data as soon as possible. We expect these updates to happen ideally on the day the update is made available to you as they may, for example, include a restriction included as a result of a takedown notice.

This restriction block contains two sets, the allowed and the blocked countries:

  • Countries are identified with the ISO 3166-1 alpha-2 standard
  • XW Identifies every country

There are two different types of possible configurations:

  1. All the world allowed with the exception of a specific set of countries (that is usually empty)
restrictions: { allowed: [XW], blocked: [] }

This means you can display the lyrics in every country.

restrictions: { allowed: [XW], blocked: [US,CA] }

This means you can not display the lyrics in the USA and in Canada. 2. 1. All the world is NOT allowed, with the exclusion of zero or few countries

restrictions: { allowed: [], blocked: [XW] }

This means you can not display the lyrics in any country.

restrictions: { allowed: [IT], blocked: [XW] }

This means you can only display the lyrics in Italy.

​
Data Delivery and Updates

​
Full Data Feed

Musixmatch provides a full feed of its entire music metadata catalog once a week, typically on Tuesdays. This feed includes all available data fields for each track and serves as the base dataset for your integration.

  • Delivery Time: Once a week
  • Use Case: Use this feed to initialize your database or refresh the entire catalog in bulk.

​
Daily Incremental Updates

In addition to the weekly full feed, Musixmatch offers daily incremental updates. These updates contain only the changes (additions, modifications, or deletions) made to the data since the last full feed. This is particularly useful for keeping your metadata synchronized without having to process the entire catalog daily.

  • Delivery Time: Daily
  • Use Case: Use this to keep your database updated with the latest changes in the metadata, reducing processing time and overhead.
Country restrictionsLyric Lens