A Subsonic client for the Shanling Q2 running Q2 Pod. Pick playlists, albums, artists and songs on the Q2, and it syncs them to the card over Wi-Fi, or streams a song straight from your server. It needs a Q2 Pod build that supports card apps, and a Subsonic or OpenSubsonic server (Navidrome, for one) reachable over HTTPS.
Over Wi-Fi: on the Q2, open System settings → App Store and press Subsonic.
By hand:
- Download
q2-subsonic-*.zipfrom the latest release. - Power the Q2 off, then put its microSD card in your computer.
- Unzip the file to the card's root, so the card has
.subsonic/q2-subsonic,.subsonic/run,.subsonic/q2appand its icons.subsonic/icon.pngand.subsonic/icon-40.png. The leading dot hides the folder on macOS (Cmd+Shift+. in Finder shows it) and Linux. - Eject the card, put it back in the Q2 and power it on.
Subsonic then has a row in Streaming.
- Open Streaming → Subsonic. While signed out, the only row is Sign In from Your Phone.
- Press it to start the sign-in page, then press it again to open the QR page. The Q2 shows a QR code and a PIN. Scan the code with your phone on the same Wi-Fi (or open the address and type the PIN) and fill in the server address, user name and password.
- The Q2 checks the login and the list opens. If it fails, the phone and the row say why.
Things to know:
- The sign-in page runs only after you press Sign In from Your Phone, and stops when you are signed in, when you leave the QR page, or after 10 minutes. Until you press it, the app opens no port.
- The password crosses your local Wi-Fi unencrypted, once, from the phone to the Q2. Do it on a network you trust.
- The server must be
https://;http://is refused. Certificates are verified. - The password is stored on the card, in
.subsonic/credentials. If your server offers OpenSubsonic API keys (apiKeyAuthentication), enter a key from its settings as the password instead: then only the key is stored. exFAT has no file permissions, so anyone with the card can read it. Make a server user just for the Q2, not an admin. If the card is lost, delete that user on the server and the card is worthless. - Settings → Account → Sign Out removes the stored login and empties the Stream Cache, but for a list that is still playing. Your synced music stays on the card.
On Q2 Pod 1.7.3 or later the first page is tabs: Home (everything, as one list, so the wheel reaches it all), Discover, Playlists, Albums and Artists. Swipe left or right to move between them; the title says which one you are on, such as Albums 4/5. Search is the magnifying glass at the right of the title bar on every tab (under Theme: Classic, which has no title bar, the first row of each tab). On older Q2 Pod the first page is one list: Sync Entire Library, Sync, On This Q2, Playlists, Albums, Artists, Discover, Search and Settings. A list you opened is kept for a minute, so a change made on the server can take that long to show.
Long lists: on Q2 Pod 1.7.3 or later a list shows 480 rows at a time, with Next page and Previous page at its ends, and Artists opens on the server's index (the letters A to Z, each with its count) when you have more than 60 artists. On Q2 Pod 1.7.6 or later Albums has a Sort row: Recently Added, By Artist or By Year, newest first; a server other than Navidrome may leave albums without a year out of By Year. Albums has no A to Z index of its own: use Artists, By Artist or Search. On older Q2 Pod a long list ends in More… after 500 rows, Artists is one list and Albums is A to Z only.
Covers: on Q2 Pod 1.7.3 or later the lists that are all albums or all playlists show each one's cover beside its row: Albums in every order, Playlists, Discover's album lists and a genre's albums. A list opens at once and its covers appear a few seconds later; in a long list, covers past the first rows appear the next time you open it, and they come slower while a sync runs. A server that sends no cover for an item, sends WebP, or ignores the size asked for (64 px) leaves the row plain. Covers are kept in the Q2's memory, never on the card, and are gone when the app stops. Every other page keeps the theme's plain rows: an artist's page (its albums too), an album's or playlist's songs, On This Q2, Artists, Search and Starred have none. On older Q2 Pod the lists look as before.
Choosing what to sync: hold Play/Pause on a playlist, album, artist or song to toggle it in Sync, or open it and press Add to Sync / Remove from Sync. The Q2 answers Added to Sync · N songs, Removed from Sync or, for a song already covered by something bigger, Included via <name>. On This Q2 lists what you picked, with its status and size on the card; hold Play/Pause there to take one out.
Quality is per item, with a default in Settings → Default Quality: Original (the default), MP3 320 or MP3 128. Change it with the Quality row inside a chosen item; Entire Library's and a single song's are in On This Q2. An original the Q2 can't play (WavPack, Musepack) syncs as MP3 320. AAC is not offered: Navidrome's AAC transcode can't carry tags.
Syncing: open Sync. It first checks the server (Checking server…, with a count such as 4500 of 10000 songs when Sync Entire Library is on), then shows a preview, and nothing happens until you press Start Sync: songs to add (+N), to remove (−N), to replace (Replace N), playlists to update (Update N playlists), and Needs X · Y free. A song you deleted from the card is fetched again. If the card is too small it says so and offers no Start. Then it shows progress: percent, songs, time left, the current song, and Pause, Resume and Cancel. Leave the page and the sync carries on. If Wi-Fi drops or the Q2 restarts, it picks up where it was. Songs that fail are listed under Failed Songs, with Retry Failed.
Discover has Shuffle All (100 songs the server picks), Recently Added, Recently Played, Most Played, Random Albums, Starred and Genres. A genre lists its albums, with its own Shuffle. Recently Played and Most Played count what the server user has played, songs played from the app included (Report Plays, below). Random Albums stays the same until you open Discover again. Starred shows what that user starred on the server; the Q2 can't star.
An artist's page has Play (all its albums in order), Shuffle, Radio (songs like the artist's, picked by the server) and Top Songs, above its albums. Play and Shuffle fetch the albums first, so music can start a little after the toast. Radio and Top Songs depend on the server: Navidrome has both, through Last.fm when that is set up. On a server without them they say Not available on this server.
Playing: press a song to play it and the rest of the list after it; search results, Starred and Top Songs work this way too. Songs already synced play from the card; the others stream. A song streams in its original format: FLAC and MP3 always, and other formats the Q2 plays too when the firmware has the playlist extension; without it they stream as MP3 320. Settings → Streaming Quality (Original, the default, MP3 320 or MP3 128) overrides this: anything but Original transcodes every streamed song to MP3. With the firmware's playlist extension, a song the server can't send (gone from it, or a format it can't convert) is skipped and the list plays on, and the main page says which; if the server can't be reached, or three songs in a row fail, the stream stops at that song.
Stream Cache (in Settings, 2 GB by default; needs the firmware's playlist extension): the songs you stream stay on the card, in .subsonic/stream/, hidden from the Q2's Library and playlists. A song streamed before starts at once and needs no Wi-Fi, and a list you started plays on offline as far as its songs are kept; opening a list still needs the server. Press the row to step through 512 MB, 1 GB, 2 GB, 4 GB, 8 GB and Off. A new size deletes nothing by itself: a smaller one, or Off, applies when the next song is streamed. When the cache is full the songs played longest ago go first; the list that is playing is never taken, and the cache gives way until 256 MB of the card are free (the list playing is fetched even with less). Clear Cache shows how much is kept, and a second press within 10 seconds empties it, but for the list that is playing; of a list you left, or paused for more than half an hour, only the songs around the one last played stay, until you play another list. A sync comes before the cache: the Sync page counts the cache's space as free, says Takes 1.2 GB from the Stream Cache when the sync needs it, and the sync then deletes the songs played longest ago. A kept song belongs to the account and the Streaming Quality it was fetched with, so another quality fetches it again and the old copy goes when its turn comes. Sign Out empties the cache in the same way. A song changed on the server under the same id plays from the kept copy until that is gone: Clear Cache fetches it fresh. With Off, without the playlist extension, and for a song whose server id is longer than 64 characters or holds other characters than letters, digits, ., _ and -, streamed files are deleted as you go.
Go to Album and Go to Artist (hold in Now Playing, on Q2 Pod 1.6.0 or later) on a song you stream open that album's or artist's page in the app, where you can play it or add it to your sync. An artist who has no album of their own on the server, such as a guest or one track's artist on a compilation, shows No albums; a server that doesn't name the song's album or artist says so. A synced song opens the Q2's own Library pages, also when it plays inside a streamed list. On older Q2 Pod a streamed song has no Go to rows.
Report Plays (in Settings, on by default): a song played from the app is reported to the server, which shows it as playing now and counts a play once the song has been on for half its length or 4 minutes (a song of 30 seconds or less is never counted). Play counts, Recently Played and Most Played, and a Last.fm or ListenBrainz account linked on the server follow what you hear on the Q2. A play that can't be sent waits, with up to 19 others, for the next song that counts; plays still waiting when the app stops are lost. The Q2 tells the app only which song plays, so a song paused early, or left for the Q2's own Library, still counts, and a song played twice in a row counts once. Songs played from the Q2's own Library are not reported. If the Q2 uploads its own scrobbles (.scrobble.ini) to the account the server forwards to, listens show twice there: turn one of the two off.
- An artist includes albums added to the server later. A playlist follows the server, order and duplicates included. A song reached through several items is stored once.
- Songs land at
Subsonic/<Album Artist>/<Year> - <Album>/<Disc>-<Track> - <Title>.<ext>, and each playlist as_explaylist_data/<name>.m3u, its name cut to the 63 bytes the Q2 keeps. An older version wrote longer names, and the Q2 added another copy of such a playlist at each sync: the next sync moves the file to a name that fits, but the copies already on the Q2 stay until you delete them. - Deletions happen only after the downloads have finished, and only for what the sync put there.
- With Sync Entire Library on, the songs the check found are kept in
.subsonic/library.jsonand used again, for up to a day, while the server reports the same last scan and song count (Navidrome does; other servers, and a library of more than 20,000 songs, are checked in full each time). Playlists are checked every time. Check Again, on the page a finished sync leaves, checks everything.
Only Subsonic/, the playlist .m3u files it wrote and .subsonic/. An older Navidrome/ folder is moved to Subsonic/ once, at start-up. Nothing else on the card is read or changed.
Newer Q2 Pod firmware offers extensions to card apps. Without them everything still works, a little less smoothly:
| Extension | With it | Without it |
|---|---|---|
library |
After a sync the Q2 updates its library and imports the playlists itself (it waits while music is playing). A playlist you made on the Q2 is never replaced: a server playlist with the same name arrives as " (Subsonic)". | Run Library → Update Local Music, then Playlists → Import playlist yourself. The sync page's Update Your Library row reminds you. |
progress |
A real progress bar. | A text bar such as [#####-----] 47 %. |
playlist |
Streaming plays the synced songs from the card inside a playlist, streams every format the Q2 plays as it is, and keeps streamed songs in the Stream Cache. | Everything in the list streams, synced or not, only FLAC and MP3 stream as they are (others as MP3 320), and streamed files are deleted as you go. |
A failure shows a short message on screen. Open its Details row for the operation, the HTTP status or Subsonic error code, and the time. The full trail is in .subsonic/log.txt; passwords and tokens are never logged. An internal error while one page is answered shows "Something went wrong" with Retry, and its trace goes there too; a sync or stream carries on. If the app crashed, its trace and exit code are added there at the next start. Settings shows the app's version, for a bug report.
System settings → App Store shows Update when a newer release is out. By hand, replace the five files in .subsonic listed above. Your login, settings and selection are kept.
To remove it, press Subsonic twice in System settings → App Store. On Q2 Pod 1.5.9 or later that deletes all of .subsonic/: your login, settings, selection and sync records. On older Q2 Pod it leaves that folder, login included, so first Settings → Account → Sign Out, which deletes the stored login, and delete the folder afterwards to remove everything. Synced music stays in Subsonic/, and its playlists stay as .m3u files in _explaylist_data/, beside your other playlists. Delete Subsonic/ and those playlist files to free the space and start clean: an install after a remove starts with no sync records, so it downloads your selection again and saves its playlists under new names beside the old ones.
contrib/shanlingq2/build.sh
needs Go 1.22 or later and python3 (no dependencies outside Go's standard library), and leaves the card files in target/shanlingq2/.subsonic and the release ZIP beside them. More: contrib/shanlingq2/README.
What changed in each release: CHANGELOG.md. To report a bug, suggest a feature or send a change, and for how releases are made: CONTRIBUTING.md.
MIT. Built from q2-filebrowser; see NOTICE.