Connor Johnstone
95 lines
4.3 KiB
Markdown
95 lines
4.3 KiB
Markdown
# 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](https://www.navidrome.org/) 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**.
|
|
|
|
**Security note:** The Subsonic protocol transmits passwords as MD5 hashes (not encrypted). This is a limitation of the protocol itself. Do not reuse a password you use for other services. The Subsonic password is stored in plain text in the database, per the protocol specification.
|
|
|
|
### 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](https://f-droid.org/packages/org.moire.ultrasonic/)** -- Free and open source. Available on F-Droid and Google Play. Reliable and well-maintained.
|
|
- **[DSub](https://play.google.com/store/apps/details?id=github.daneren2005.dsub)** -- Feature-rich, supports offline caching.
|
|
- **[Symfonium](https://play.google.com/store/apps/details?id=app.symfonik.music.player)** -- Modern UI, excellent playback features. Paid app.
|
|
|
|
### Desktop
|
|
- **[Feishin](https://github.com/jeffvli/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:
|
|
|
|
```yaml
|
|
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).
|