mopidy-suno

mopidy-suno is a Mopidy backend extension that brings the creative world of AI-generated music from Suno AI directly into your Mopidy audio server.

Whether you want to discover trending community AI songs, stream curated public playlists, or search for AI-generated tracks on the fly, mopidy-suno provides seamless integration with any Mopidy client—including web interfaces like Iris and Mopify, desktop/mobile MPD clients, and automation scripts via JSON-RPC.

✨ Key Features

• Public Playlist Streaming: Stream any public Suno playlist instantly without requiring user credentials, API keys, or browser cookies. Paste any Suno playlist UUID or URL and start listening right away. (User authentication and private library access may follow in a future update.)
• Dynamic & On-the-Fly Playlists: Load playlists pre-configured in your mopidy.conf or look up any public playlist URI (suno:playlist:<uuid>) dynamically at runtime.
• High-Speed CDN Audio: Translates Suno track references (suno:track:<uuid>) into direct, high-quality MP3 streams (cdn1.suno.ai), ensuring fast startup and reliable playback.
• Full Playback & Metadata Support: Integrates natively with Mopidy's core.playback and core.tracklist controllers—providing full support for play, pause, next, previous, seek, track titles, duration, and artist attribution.
• Built for Modern Python: Built using modern Python 3.13+ standards and managed via uv for lightning-fast dependency management and strict code hygiene.

Installation

Install by running:

python3 -m pip install mopidy-suno

Configuration

Add the following to your Mopidy configuration file (mopidy.conf):

[suno]
enabled = true
# Enable detailed debug logging for Mopidy-Suno (default: false)
debug = false
# Optional: list of specific public Suno playlist IDs or full Suno playlist URLs
playlists =
    62688394-2144-4c20-bf24-9d201899b9ae
    https://suno.com/playlist/08a079b2-a63b-4f9c-9f29-de3c1864ddef
# Suno studio API base URL (leave at default)
api_url = https://studio-api.prod.suno.com

Note: This extension streams public Suno playlists directly without needing credentials or cookies.

Using Playlists & Playback Controls

Calling applications (web UIs, client apps, or scripts interacting with Mopidy via JSON-RPC or MPD) can load and control Suno playlists using standard Mopidy APIs.

1. Pre-configured or On-the-Fly Dynamic Playlists

You can load either pre-configured playlists (from mopidy.conf) or fetch any public Suno playlist on the fly without prior configuration.

Look up a playlist and its tracks

Using Mopidy JSON-RPC (core.playlists.lookup):

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "core.playlists.lookup",
  "params": {
    "uri": "suno:playlist:62688394-2144-4c20-bf24-9d201899b9ae"
  }
}

If requested on the fly, Mopidy-Suno fetches the playlist directly from Suno's API and caches it in Mopidy's session.

2. Controlling Playback (Play, Next, Previous, Current Track)

Mopidy-Suno translates suno:track:<id> URIs directly into high-speed CDN MP3 streams (https://cdn1.suno.ai/<id>.mp3). All playback controls are handled by Mopidy's core playback controller (core.playback) and tracklist (core.tracklist).

Add playlist tracks to the queue

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "core.tracklist.add",
  "params": {
    "uris": [
      "suno:track:aa8b9ddf-6aec-4354-9307-41195783776f",
      "suno:track:481f9007-9949-44fa-aef1-e0ed3abd5f0e"
    ]
  }
}

Playback controls via API Explorer / JSON-RPC (core.playback)

• Start Playback: core.playback.play
• Pause / Resume: core.playback.pause / core.playback.resume
• Next Song: core.playback.next
• Previous Song: core.playback.previous
• Get Current Playing Song: core.playback.get_current_track
• Get Playback State: core.playback.get_state

You can test all these controls interactively in the Mopidy API Explorer at http://localhost:6680/api_explorer/#class-playback.

Project resources

• Source code
• Issues
• Releases

Development

Set up development environment

Clone the repo using, e.g. using gh:

gh repo clone mastix/mopidy-suno

Enter the directory, and install dependencies using uv:

cd mopidy-suno/
uv sync

Running Mopidy locally

To run Mopidy locally with all extension dependencies inside the virtual environment:

uv run mopidy

Tip: mopidy-api-explorer is included in the development dependencies. While Mopidy is running locally, open http://localhost:6680/api_explorer/ in your browser to interactively test Mopidy JSON-RPC methods (core.playlists.lookup, core.tracklist.add, core.playback.play, etc.).

Note for macOS (Apple Silicon / Homebrew): A .env file in the project root sets DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib. uv run automatically loads .env so GObject Introspection (PyGObject) and GStreamer find Homebrew's shared libraries (libgobject, libglib, etc.) without manual configuration.

Running tests

To run all tests and linters in isolated environments, use tox:

tox

To only run tests, use pytest:

pytest

To format the code, use ruff:

ruff format .

To check for lints with ruff, run:

ruff check .

To check for type errors, use pyright:

pyright .

Setup before first release

Before the first release, you must enable trusted publishing on PyPI so that the release.yml GitHub Action can create the PyPI project and publish releases to PyPI.

When following the instructions linked above, use the following values in the form at PyPI:

• Publisher: GitHub
• PyPI project name: mopidy-suno
• Owner: mastix
• Repository name: mopidy-suno
• Workflow name: release.yml
• Environment name: pypi (must match environment name in release.yml)

Making a release

To make a release to PyPI, go to the project's GitHub releases page and click the "Draft a new release" button.

In the "choose a tag" dropdown, select the tag you want to release or create a new tag, e.g. v0.1.0. Add a title, e.g. v0.1.0, and a description of the changes.

Decide if the release is a pre-release (alpha, beta, or release candidate) or should be marked as the latest release, and click "Publish release".

Once the release is created, the release.yml GitHub Action will automatically build and publish the release to PyPI.

Credits

• Original author: mastix
• Current maintainer: mastix
• Contributors