<picture> <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/bbye98/minim/main/assets/logo_dark.svg"> <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/bbye98/minim/main/assets/logo_light.svg"> <img alt="minim logo" src="https://raw.githubusercontent.com/bbye98/minim/main/assets/logo_light.svg"> </picture> <br></br>

Minim

[!IMPORTANT] Minim v1 (current main branch) is now in maintenance mode. It will receive only critical bug fixes and occasional backports from v2.

A full rewrite for Minim v2 is actively underway in the dev branch. If you’d like to try the bleeding-edge version or share feedback, please check out the dev branch and open an Issue!

Minim is a lightweight Python 3 library that can interface with APIs by popular music services—iTunes, Qobuz, Spotify, and TIDAL—and operate on audio files, such as updating metadata and converting between audio formats.

• Documentation: https://bbye98.github.io/minim/ (old) and https://minim.readthedocs.io/en/latest/ (new)

Features

• minim.audio: Audio file handlers for reading and writing metadata and converting between audio formats.
• minim.itunes: A client for the iTunes Search API.
• minim.qobuz: A client for the Qobuz API with support for the password grant type for user authentication and user authentication token caching.
• minim.spotify: Clients for the Spotify Lyrics service and the Spotify Web API with support for the authorization code, authorization code with proof key for code exchange (PKCE), and client credentials grant types, and access token caching.
• minim.tidal: Clients for the old and new TIDAL APIs with support for the authorization code with PKCE and client credentials grant types, and access token caching.

Installation

Minim requires Python 3.9 or later.

Clone the repository and install the package using pip:

git clone https://github.com/bbye98/minim.git
cd minim
python -m pip install -e .

Examples

• Import Minim and create clients for the different APIs. Additional keyword arguments can be passed to the constructors to control user authentication.

  >>> from minim import itunes, qobuz, spotify, tidal
  >>> client_itunes = itunes.SearchAPI()
  >>> client_qobuz = qobuz.PrivateAPI()
  >>> client_spotify = spotify.WebAPI(flow="web_player")
  >>> client_tidal = tidal.PrivateAPI(client_id=<TIDAL_CLIENT_ID>)
  

• Search for and retrieve information about an artist, such as the EDM group Galantis:

  iTunes Search API

  >>> client_itunes.search("Galantis", entity="musicArtist", 
  ...                      limit=1)["results"][0]
  

  <details> <summary>Output</summary>

  {
    "wrapperType": "artist",
    "artistType": "Artist",
    "artistName": "Galantis",
    "artistLinkUrl": "https://music.apple.com/us/artist/galantis/543322169?uo=4",
    "artistId": 543322169,
    "amgArtistId": 2616267,
    "primaryGenreName": "Dance",
    "primaryGenreId": 17
  }
  

  </details>

  Private Qobuz API

  >>> client_qobuz.search("Galantis", limit=1, 
  ...                     strict=True)["artists"]["items"][0]
  

  <details> <summary>Output</summary>

  {
    "picture": "https://static.qobuz.com/images/artists/covers/small/8dcf30e5c8e30281ecbb13b0886426c8.jpg",
    "image": {
      "small": "https://static.qobuz.com/images/artists/covers/small/8dcf30e5c8e30281ecbb13b0886426c8.jpg",
      "medium": "https://static.qobuz.com/images/artists/covers/medium/8dcf30e5c8e30281ecbb13b0886426c8.jpg",
      "large": "https://static.qobuz.com/images/artists/covers/large/8dcf30e5c8e30281ecbb13b0886426c8.jpg",
      "extralarge": "https://static.qobuz.com/images/artists/covers/large/8dcf30e5c8e30281ecbb13b0886426c8.jpg",
      "mega": "https://static.qobuz.com/images/artists/covers/large/8dcf30e5c8e30281ecbb13b0886426c8.jpg"
    },
    "name": "Galantis",
    "slug": "galantis",
    "albums_count": 126,
    "id": 865362
  }
  

  </details>

  Spotify Web API

  >>> client_spotify.search("Galantis", "artist", limit=1)["items"][0]
  

  <details> <summary>Output</summary>

  {
    "external_urls": {
      "spotify": "https://open.spotify.com/artist/4sTQVOfp9vEMCemLw50sbu"
    },
    "followers": {
      "href": null,
      "total": 3373205
    },
    "genres": [
      "dance pop",
      "edm",
      "pop",
      "pop dance"
    ],
    "href": "https://api.spotify.com/v1/artists/4sTQVOfp9vEMCemLw50sbu",
    "id": "4sTQVOfp9vEMCemLw50sbu",
    "images": [
      {
        "height": 640,
        "url": "https://i.scdn.co/image/ab6761610000e5eb7bda087d6fb48d481efd3344",
        "width": 640
      },
      {
        "height": 320,
        "url": "https://i.scdn.co/image/ab676161000051747bda087d6fb48d481efd3344",
        "width": 320
      },
      {
        "height": 160,
        "url": "https://i.scdn.co/image/ab6761610000f1787bda087d6fb48d481efd3344",
        "width": 160
      }
    ],
    "name": "Galantis",
    "popularity": 67,
    "type": "artist",
    "uri": "spotify:artist:4sTQVOfp9vEMCemLw50sbu"
  }
  

  </details>

  Private TIDAL API

  >>> client_tidal.search("Galantis", type="artist", limit=1)["items"][0]
  

  <details> <summary>Output</summary>

  {
    "id": 4676988,
    "name": "Galantis",
    "artistTypes": [
      "ARTIST",
      "CONTRIBUTOR"
    ],
    "url": "http://www.tidal.com/artist/4676988",
    "picture": "a627e21c-60f7-4e90-b2bb-e50b178c4f0b",
    "popularity": 72,
    "artistRoles": [
      {
        "categoryId": -1,
        "category": "Artist"
      },
      {
        "categoryId": 11,
        "category": "Performer"
      },
      {
        "categoryId": 3,
        "category": "Engineer"
      },
      {
        "categoryId": 10,
        "category": "Production team"
      },
      {
        "categoryId": 1,
        "category": "Producer"
      },
      {
        "categoryId": 2,
        "category": "Songwriter"
      }
    ],
    "mixes": {
      "ARTIST_MIX": "000202a7e72fd90d0c0df2ed56ddea"
    }
  }
  

  </details>

• Search for and retrieve information about a track, such as "Everybody Talks" by Neon Trees:

  iTunes Search API

  >>> client_itunes.search("Everybody Talks", media="music", 
  ...                      limit=1)["results"][0]
  

  <details> <summary>Output</summary>

  {
    "wrapperType": "track",
    "kind": "song",
    "artistId": 350172836,
    "collectionId": 1443469527,
    "trackId": 1443469581,
    "artistName": "Neon Trees",
    "collectionName": "Picture Show",
    "trackName": "Everybody Talks",
    "collectionCensoredName": "Picture Show",
    "trackCensoredName": "Everybody Talks",
    "artistViewUrl": "https://music.apple.com/us/artist/neon-trees/350172836?uo=4",
    "collectionViewUrl": "https://music.apple.com/us/album/everybody-talks/1443469527?i=1443469581&uo=4",
    "trackViewUrl": "https://music.apple.com/us/album/everybody-talks/1443469527?i=1443469581&uo=4",
    "previewUrl": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview122/v4/5c/29/bf/5c29bf6b-ca2c-4e8b-2be6-c51a282c7dae/mzaf_1255557534804450018.plus.aac.p.m4a",
    "artworkUrl30": "https://is1-ssl.mzstatic.com/image/thumb/Music115/v4/80/e3/95/80e39565-35f9-2496-c6f8-6572490c4a7b/12UMGIM12509.rgb.jpg/30x30bb.jpg",
    "artworkUrl60": "https://is1-ssl.mzstatic.com/image/thumb/Music115/v4/80/e3/95/80e39565-35f9-2496-c6f8-6572490c4a7b/12UMGIM12509.rgb.jpg/60x60bb.jpg",
    "artworkUrl100": "https://is1-ssl.mzstatic.com/image/thumb/Music115/v4/80/e3/95/80e39565-35f9-2496-c6f8-6572490c4a7b/12UMGIM12509.rgb.jpg/100x100bb.jpg",
    "collectionPrice": 6.99,
    "trackPrice": 1.29,
    "releaseDate": "2011-12-19T12:00:00Z",
    "collectionExplicitness": "explicit",
    "trackExplicitness": "explicit",
    "discCount": 1,
    "discNumber": 1,
    "trackCount": 12,
    "trackNumber": 3,
    "trackTimeMillis": 177280,
    "country": "USA",
    "currency": "USD",
    "primaryGenreName": "Alternative",
    "contentAdvisoryRating": "Explicit",
    "isStreamable": true
  }
  

  </details>

  Private Qobuz API

  >>> client_qobuz.search("Everybody Talks", "ReleaseName", limit=1, 
  ...                     strict=True)["tracks"]["items"][0]
  

  <details> <summary>Output</summary>

  {
    "maximum_bit_depth": 16,
    "copyright": "\u2117 2011 UMG Recordings, Inc.",
    "performers": "Justin Meldal-Johnsen, Producer, Guitar, Additional Keyboards, Percussion, Programmer, AssociatedPerformer - Tim Pagnotta, ComposerLyricist - Greg Collins, Engineer, StudioPersonnel - Wesley Seidman, Asst. Recording Engineer, StudioPersonnel - Tyler Glenn, ComposerLyricist - Neon Trees, MainArtist - Matt Wiggers, Asst. Recording Engineer, StudioPersonnel - Bill Bush, Mixer, StudioPersonnel",
    "audio_info": {
      "replaygain_track_peak": 0.999969,
      "replaygain_tr