MatcherAPI

class minim.api.musixmatch.MatcherAPI(client: APIClient, /)

Bases: MusixmatchResourceAPI

Matcher API endpoints for the Musixmatch Lyrics API.

Important

This class is managed by MusixmatchLyricsAPIClient and should not be instantiated directly.

Parameters:

clientminim.api._shared.APIClient

API client instance used to make HTTP requests.

Methods

match_track	Matcher > matcher.track.get: Match a track by artist and track name (fuzzy search) or by ISRC to get Musixmatch catalog information for it.
match_track_lyrics	Matcher > matcher.lyrics.get: Match a track by artist and track name (fuzzy search) or by ISRC to get Musixmatch catalog information for its lyrics.
match_track_subtitles	Matcher > matcher.subtitle.get: Match a track by artist and track name (fuzzy search) or by ISRC to get Musixmatch catalog information for its subtitles.

match_track(*, artist: str | None = None, track: str | None = None, isrc: str | None = None) → dict[str, Any]

Matcher > matcher.track.get: Match a track by artist and track name (fuzzy search) or by ISRC to get Musixmatch catalog information for it.

Subscription

Required

Musixmatch Basic plan

Access music metadata and static lyrics. Learn more.

Parameters:

artiststr; keyword-only; optional

Artist name to match.

trackstr; keyword-only; optional

Track name to match.

isrcstr; keyword-only; optional

ISRC of the track.

Example: "USUM70905526".

Returns:

trackdict[str, Any]

Musixmatch metadata for the matched track.

Sample response

{
  "message": {
    "body": {
      "track": {
        "album_id": <int>,
        "album_name": <str>,
        "artist_id": <int>,
        "artist_name": <str>,
        "commontrack_id": <int>,
        "commontrack_isrcs": <list[list[str]]>,
        "explicit": <int>,
        "has_lyrics": <int>,
        "has_richsync": <int>,
        "has_subtitles": <int>,
        "instrumental": <int>,
        "num_favourite": <int>,
        "primary_genres": {
          "music_genre_list": [
            {
              "music_genre": {
                "music_genre_id": <int>,
                "music_genre_name": <str>,
                "music_genre_name_extended": <str>,
                "music_genre_parent_id": <int>,
                "music_genre_vanity": <str>
              }
            }
          ]
        },
        "restricted": <int>,
        "track_edit_url": <str>,
        "track_id": <int>,
        "track_isrc": <str>,
        "track_length": <int>,
        "track_lyrics_translation_status": [
          {
            "from": <str>,
            "perc": <int>,
            "to": <str>
          }
        ],
        "track_name": <str>,
        "track_rating": <int>,
        "track_share_url": <str>,
        "track_spotify_id": <str>,
        "updated_time": <str>
      }
    },
    "header": {
      "cached": <int>,
      "confidence": <int>,
      "execute_time": <float>,
      "mode": <str>,
      "status_code": <int>
    }
  }
}

match_track_lyrics(*, artist: str | None = None, track: str | None = None, isrc: str | None = None) → dict[str, Any]

Matcher > matcher.lyrics.get: Match a track by artist and track name (fuzzy search) or by ISRC to get Musixmatch catalog information for its lyrics.

Subscription

Required

Musixmatch Basic plan

Access music metadata and static lyrics. Learn more.

Parameters:

artiststr; keyword-only; optional

Artist name to match.

trackstr; keyword-only; optional

Track name to match.

isrcstr; keyword-only; optional

ISRC of the track.

Example: "USUM70905526".

Returns:

lyricsdict[str, Any]

Musixmatch metadata for the matched track’s lyrics.

Sample response

{
  "message": {
    "body": {
      "lyrics": {
        "explicit": <int>,
        "lyrics_body": <str>,
        "lyrics_copyright": <str>,
        "lyrics_id": <int>,
        "lyrics_language": <str>,
        "pixel_tracking_url": <str>,
        "region_restriction": {
          "allowed": <list[str]>,
          "blocked": <list[str]>
        },
        "script_tracking_url": <str>,
        "updated_time": <str>
      }
    },
    "header": {
      "execute_time": <float>,
      "status_code": <int>
    }
  }
}

match_track_subtitles(*, artist: str | None = None, track: str | None = None, isrc: str | None = None, duration: int | str | None = None, max_duration_deviation: int | str | None = None) → dict[str, Any]

Matcher > matcher.subtitle.get: Match a track by artist and track name (fuzzy search) or by ISRC to get Musixmatch catalog information for its subtitles.

Subscription

Required

Musixmatch Scale plan

Access time-synced lyrics. Learn more.

Parameters:

artiststr; keyword-only; optional

Artist name to match.

trackstr; keyword-only; optional

Track name to match.

isrcstr; keyword-only; optional

ISRC of the track.

Example: "USUM70905526".

durationint or str; keyword-only; optional

Target subtitle duration, in seconds.

max_duration_deviationint or str; keyword-only; optional

Maximum deviation allowed from the requested duration. Only applicable when duration is specified.

Returns:

subtitlesdict[str, Any]

Musixmatch metadata for the matched track’s subtitles.

Sample response

{
  "message": {
    "body": {
      "subtitle": {
        "html_tracking_url": <str>,
        "lyrics_copyright": <str>,
        "pixel_tracking_url": <str>,
        "published_status": <int>,
        "publisher_list": [],
        "restricted": <int>,
        "script_tracking_url": <str>,
        "subtitle_avg_count": <int>,
        "subtitle_body": <str>,
        "subtitle_id": <int>,
        "subtitle_language": <str>,
        "subtitle_language_description": <str>,
        "subtitle_length": <int>,
        "updated_time": <str>,
        "writer_list": []
      }
    },
    "header": {
      "execute_time": <float>,
      "status_code": <int>
    }
  }
}