[!IMPORTANT] Artwork inspired by ElysiaJS.

Installation

npm

npm install @andreafspeziale/mxm-client

yarn

yarn add @andreafspeziale/mxm-client

pnpm

pnpm add @andreafspeziale/mxm-client

How to use?

[!NOTE] To effectively interact with the Musixmatch API you need a valid API key.

The SDK implements most of the Musixmatch API endpoints, providing a strongly typed and easy-to-use interface for developers. It handles authentication, request construction and response parsing allowing you to focus on building your application.

Zero-config

import { MxmClient } from '@andreafspeziale/mxm-client';

const mxmClient = new MxmClient();

const track = await mxmClient.trackGet({
  query: { track_isrc: 'USUM72005901' },
  apiKey: 'your-api-key',
});

With API key configuration

import { MxmClient } from '@andreafspeziale/mxm-client';

const mxmClient = new MxmClient({
  config: {
    apiKey: 'your-api-key',
  },
});

const track = await mxmClient.trackGet({
  query: { track_isrc: 'USUM72005901' },
});

With API key & Logging configuration

A Pino basic logger instance is created internally when enableLog is set to true.

import { MxmClient } from '@andreafspeziale/mxm-client';

const mxmClient = new MxmClient({
  config: {
    apiKey: 'your-api-key',
    enableLog: true,
    defaultLoggerConfig: {
      formatters: {
        level: (label) => {
          return { level: label };
        },
      },
    },
  },
});

const track = await mxmClient.trackGet({
  query: { track_isrc: 'USUM72005901' },
});

With API key & Pino instance plus Logging configuration

A Pino logger instance is provided and logging can be enabled/disabled via configuration.

import { pino } from 'pino';
import { MxmClient } from '@andreafspeziale/mxm-client';

const logger = pino({
  formatters: {
    level: (label) => {
      return { level: label };
    },
  },
});

const mxmClient = new MxmClient({
  logger,
  config: {
    apiKey: 'your-api-key',
    enableLog: true,
  },
});

const track = await mxmClient.trackGet({
  query: { track_isrc: 'USUM72005901' },
});

Generic enrichment

The SDK supports extending input types via generics for advanced use cases where the API accepts fields beyond the documented ones.

Enriching query parameters

import { MxmClient, type TrackGetQuery } from '@andreafspeziale/mxm-client';

interface MyTrackGetQuery extends TrackGetQuery {
  custom_param: string;
}

const mxmClient = new MxmClient({
  config: { apiKey: 'your-api-key' },
});

const track = await mxmClient.trackGet<MyTrackGetQuery>({
  query: {
    track_isrc: 'USUM72005901',
    custom_param: 'value',
  },
});

Enriching request body (POST endpoints)

import {
  MxmClient,
  type TrackLyricsFingerprintPostQuery,
  type TrackLyricsFingerprintPostBody,
} from '@andreafspeziale/mxm-client';

interface MyBody extends TrackLyricsFingerprintPostBody {
  settings: { algorithm: string };
}

const mxmClient = new MxmClient({
  config: { apiKey: 'your-api-key' },
});

const result = await mxmClient.trackLyricsFingerprintPost<
  TrackLyricsFingerprintPostQuery,
  MyBody
>({
  body: {
    text: "Fratelli d'Italia...",
    settings: { algorithm: 'raw' },
  },
});

Available methods

• matcherLyricsGet (matcher.lyrics.get)
• matcherSubtitleGet (matcher.subtitle.get)
• matcherTrackGet (matcher.track.get)

• trackGet (track.get)
• trackLyricsGet (track.lyrics.get)
• trackSubtitleGet (track.subtitle.get)
• trackRichSyncGet (track.richsync.get)
• trackSearch (track.search)

• trackLyricsFingerprintPost (track.lyrics.fingerprint)

Test

[!NOTE] To keep consistency over time and to be sure each endpoint returns the expected result, e2e tests are run against the actual Musixmatch APIs when a valid API key is provided (environment variable MXM_API_KEY). Instead e2e will be skipped.

• pnpm test

Stay in touch

• Author - Andrea Francesco Speziale

License

mxm-client MIT licensed.