Main/docs/features/subsonic.md

Subsonic Streaming

Shanty includes a Subsonic-compatible API that lets you stream your music library to mobile apps, desktop players, and other Subsonic clients.

What is Subsonic?

Subsonic is a widely-supported protocol for streaming music from a personal server. Many music apps implement the Subsonic API, which means you can use any of them to stream your Shanty library to your phone, tablet, or desktop.

Important note

Shanty implements a subset of the Subsonic API -- enough for browsing, streaming, playlists, and search. If you need a full-featured Subsonic server with advanced features like sharing, podcasts, or Internet radio, consider running Navidrome pointed at the same music library directory. Both can coexist.

How to set up

1. Set a Subsonic password

The Subsonic protocol uses its own authentication system, separate from your Shanty web login.

1. Open the Shanty web UI and go to Settings.
2. Find the Subsonic API section.
3. Enter a password and click Save.

Important -- please read: The Subsonic password is stored as plain text in the database. This is not a bug or an oversight. The Subsonic protocol requires the server to verify authentication by computing md5(password + client_salt), which means the server must have access to the original password. There is no way to store it securely (like a one-way hash) and still be compatible with the protocol. This is a well-known limitation of the Subsonic standard and is how all Subsonic-compatible servers handle it, including Navidrome.

Because of this, do not reuse a password from any other account. Choose a simple, unique password that you use only for Subsonic access. Your Shanty web login password is stored securely (Argon2id hash) and is completely separate.

2. Configure your client

In your Subsonic client app, add a new server with these settings:

Field	Value
Server URL	http://your-server-ip:8085
Username	Your Shanty username
Password	The Subsonic password you set (not your web login password)

Most clients automatically append /rest to the server URL. If your client asks for just the base URL, enter http://your-server-ip:8085.

If your client has separate fields for server address and port, enter the IP/hostname and 8085 separately.

3. Test the connection

Most clients have a "Test Connection" button. Use it to verify that the server is reachable and your credentials are correct.

Recommended clients

These clients have been tested with Shanty's Subsonic implementation:

Android

• Ultrasonic -- Free and open source. Available on F-Droid and Google Play. Reliable and well-maintained.
• DSub -- Feature-rich, supports offline caching.
• Symfonium -- Modern UI, excellent playback features. Paid app.

Desktop

• Feishin -- Cross-platform desktop client with a modern interface. Free and open source.

Supported Subsonic endpoints

Shanty implements these Subsonic API endpoints:

• System: ping, getLicense
• Browsing: getMusicFolders, getIndexes, getMusicDirectory, getArtists, getArtist, getAlbum, getSong, getGenres
• Search: search3
• Media: stream, download, getCoverArt
• Playlists: getPlaylists, getPlaylist, createPlaylist, deletePlaylist
• Annotation: scrobble
• User: getUser

Transcoding

If your music is in Opus format (the default download format), many mobile clients cannot play it directly. Shanty automatically transcodes Opus files to MP3 when streaming via the Subsonic API. This requires ffmpeg, which is included in the Docker image.

If you download in MP3 format or your clients support Opus natively, you can disable transcoding:

subsonic:
  transcoding_enabled: false

Troubleshooting

"Authentication failed" in client:

• Make sure you are using the Subsonic password, not your web login password.
• Make sure the username matches exactly (case-sensitive).

Client cannot connect:

• Verify the server URL includes the port (http://ip:8085, not just http://ip).
• Check that port 8085 is accessible from the device (firewall rules, same network, etc.).

No music showing up:

• Music must be organized in the library (run the pipeline at least once) to appear in the Subsonic API.
• Only tracks with file paths in the database are served.

Audio does not play:

• If using Opus format, make sure transcoding is enabled (it is by default).
• Check that ffmpeg is installed (included in Docker, must be installed manually for source builds).