Metadata-Version: 2.4
Name: mopidy-suno
Version: 0.1.1
Summary: Mopidy extension that allows accessing public Suno playlists
Author-email: mastix <mastixmc@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/mastix/mopidy-suno
Classifier: Environment :: No Input/Output (Daemon)
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Multimedia :: Sound/Audio :: Players
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mopidy>=4.0.0
Requires-Dist: pykka>=4.4.0
Requires-Dist: requests>=2.34.0
Dynamic: license-file

# mopidy-suno

[![Latest PyPI version](https://img.shields.io/pypi/v/mopidy-suno)](https://pypi.org/p/mopidy-suno)
[![CI build status](https://img.shields.io/github/actions/workflow/status/mastix/mopidy-suno/ci.yml)](https://github.com/mastix/mopidy-suno/actions/workflows/ci.yml)
[![Test coverage](https://img.shields.io/codecov/c/gh/mastix/mopidy-suno)](https://codecov.io/gh/mastix/mopidy-suno)

**mopidy-suno** is a [Mopidy](https://mopidy.com/) backend extension that brings the creative world of AI-generated music from [Suno AI](https://suno.com/) 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:

```sh
python3 -m pip install mopidy-suno
```

## Configuration

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

```ini
[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`):
```json
{
  "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
```json
{
  "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](https://github.com/mastix/mopidy-suno)
- [Issues](https://github.com/mastix/mopidy-suno/issues)
- [Releases](https://github.com/mastix/mopidy-suno/releases)


## Development

### Set up development environment

Clone the repo using, e.g. using [gh](https://cli.github.com/):

```sh
gh repo clone mastix/mopidy-suno
```

Enter the directory, and install dependencies using [uv](https://docs.astral.sh/uv/):

```sh
cd mopidy-suno/
uv sync
```

### Running Mopidy locally

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

```sh
uv run mopidy
```

> **Tip:** [`mopidy-api-explorer`](https://github.com/mopidy/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](https://tox.wiki/):

```sh
tox
```

To only run tests, use [pytest](https://pytest.org/):

```sh
pytest
```

To format the code, use [ruff](https://docs.astral.sh/ruff/):

```sh
ruff format .
```

To check for lints with ruff, run:

```sh
ruff check .
```

To check for type errors, use [pyright](https://microsoft.github.io/pyright/):

```sh
pyright .
```

### Setup before first release

Before the first release, you must [enable trusted publishing on
PyPI](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/)
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](https://github.com/mastix/mopidy-suno/releases)
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](https://pypi.org/project/mopidy-suno/).


## Credits

- Original author: [mastix](https://github.com/mastix)
- Current maintainer: [mastix](https://github.com/mastix)
- [Contributors](https://github.com/mastix/mopidy-suno/graphs/contributors)
