SunoDL

sunodl is a simple command-line program that downloads songs and playlists from Suno, applying appropriate filenames and ID3 tags as it goes, so that you can listen to them in your media player of choice. This is annoying to do from Suno’s own site; as I understand it, Suno used to have a “download” button, but it no longer exists. Hence this program.

This is not a general-purpose interface to Suno’s API. If you’re looking for that, you are in the wrong place.

sunodl has only been tested on my own narrow use cases and may break the moment it is off my system. You have been warned.

Installation

You can install sunodl with any python package-management tool; this example uses pipx because that’s what I use:

pipx install sunodl

After installing, check that sunodl --help does the Right Thing.

Usage

On Suno’s site, navigate to the playlist or song you want to download, then copy/paste the URL as an argument to sunodl:

$ sunodl https://suno.com/playlist/${UUID}/

By default, songs download to the current directory with a file name of {title}.mp3. If the url is for a playlist, a subdirectory is created named after the playlist, and the output filenames are prefixed with a track number. You can override the output path with the --output option.

Where possible, upstream metadata is used to populate any corresponding ID3 tags, so music players can display things like title, artist, cover image, etc.

Configuration

While there is a configuration directory, you shouldn’t need to touch it unless you are debugging sunodl itself. That said, you can view the default configuration and the user directory path in the output of sunodl --debug. The path varies by OS. Any .yaml files in the configuration directory will be read, and values in them will override the defaults.

Troubleshooting

sunodl has several debugging options; see sunodl --help for a list.

Annoyingly, Suno’s API documentation specifies endpoints for uploading and generating music, but not for retrieving the resulting files. The endpoints that sunodl relies on are, as far as I can tell, undocumented, and sunodl will break if Suno moves or changes them -- which they may well do.

If that happens, and if you don’t want to wait on a code update, in theory you can update the endpoint urls yourself using the config directory mentioned above. However, finding the new endpoint urls is your problem. You can start by looking at your browser’s network-monitoring tools for json requests associated with a particular playlist/song.

License

This program is distributed under GPLv3+. See LICENSE.txt for the complete license.