Sharesonic

Rediscover your music library. One shuffle at a time. Share what you find.

Sharesonic is an Android client for Velvet, the self-hosted music server. It is built around a single philosophy: your music collection is too large to listen to linearly: let chance guide you, then share what surprises you.

---

Download

Download the latest APK directly from the Releases page.

Auto-updates with Obtainium

Obtainium installs Sharesonic from GitHub Releases and keeps it up to date automatically.

---

Why Sharesonic?

Most music apps are built around curation: playlists you already know, albums you already love, artists you already follow. That works fine for a library of a few hundred tracks. It breaks down when you self-host thousands of albums accumulated over years.

Sharesonic is built for the other scenario: the large, chaotic, lovingly disorganised self-hosted library where the best discoveries happen by accident.

• Shuffle a whole library: hit shuffle at the root level and let random tracks from your entire collection play back-to-back. You will hear things you forgot you had.
• Shuffle a folder: narrow the randomness to a genre, a decade, an artist. Still surprising, still exploratory, with a little more context.
• Browse by folder: the folder tree is the primary navigation mode. Your directory structure, exactly as you organised it on the server.
• Share what you find: when shuffle surfaces something worth passing on, one tap generates a public share link and opens the Android share sheet. Send it to anyone.

---

Features

Feature	Details
Folder browsing	Navigate your full directory tree from root to individual tracks
Shuffle library	Server-side random pick via native Velvet API, 30 tracks, no repeats
Shuffle folder	Shuffle every track under any sub-directory. Gathered server-side (recursive scan + batch metadata) so it scales to huge folders; very large folders (100k+ tracks) are randomly sampled down to 5000
Auto-DJ	Continuous smart queue: BPM continuity, harmonic mixing (Camelot wheel), similar artists, artist cooldown, genre filter, keyword filter (skip songs whose title / artist / album / filename contains any of these words), crossfade. Toggle the headphones icon in the mini player or Now Playing
Share link on track	Native Velvet share API → public server/shared/XXXXXXXXXX URL → Android share sheet
Share link on folder	Long-press any folder → recursively collects every track inside it (including subfolders) and generates a single public link for the whole folder
Share queue	Generate one public link for the entire current queue in a single tap, straight from the queue view
Manage shared links	"Public Links" screen (drawer) lists every link you've created with its song count and expiry: copy, open, or revoke each one
Star ratings	Rate the current track 0-5 stars from Now Playing, synced live to Velvet's native rating, with an explicit one-tap way back to "unrated"
Now Playing	Non-scrolling full-screen player: cover art with an ambient gradient tinted by the artwork's dominant colour, waveform seek bar (tap or drag to seek), title/artist/album, format/bitrate, star rating, generously spaced controls, and Share / Playlist actions
Track info dialog	Full metadata for the current track: title, artist, album, year, track, genres, BPM, key, duration, format, bitrate, sample rate, channels, rating, and the selectable file path. Missing fields are fetched fresh from the server on open
Sleep timer	Set a countdown (15 / 30 / 45 / 60 / 90 min presets or a custom value) from the Now Playing "More" sheet. Playback pauses when it fires; the remaining time shows live
Lyrics	Fetch and display lyrics for the current track from the Now Playing "More" sheet (synced or plain, whichever the server has). Loading / found / "none" / error states handled
Equalizer	Native Android per-band equalizer reachable from the drawer or Settings: on/off switch, per-band gain sliders, "reset to flat"
Add to queue	Swipe left on any track in the browser
Add to playlist	Swipe right on a track in the browser, or tap "Playlist" in Now Playing. The frosted-glass picker lets you create a new playlist inline (name it and add in one step) or pick an existing one
Playlist management	Create, rename, delete, share; add/remove tracks; drag-to-reorder tracks with long-press; play all or shuffle
Save queue as playlist	From the queue view, save every track currently queued as a brand-new named playlist in one tap
Search	Pill-shaped, Material You search bar with full-text search grouped into Folders, Artists, Albums and Songs. Tapping a folder navigates straight to it; tapping an artist opens a list of that artist's tracks (featuring/variant spellings included); swipe or long-press any song result to add it to the queue or a playlist
Scrobbling	Playback reported to Velvet, forwarded to Last.fm + ListenBrainz (no API keys needed). Requires "Scrobble from External Apps" to be enabled in Velvet's server settings; otherwise Velvet silently ignores the scrobble calls
Language	12-language UI (English, Nederlands, Deutsch, Français, Español, Italiano, Português, Polski, Русский, 中文, 日本語, 한국어) plus "System default". Pick from the drawer or Settings hub; the app relaunches instantly in the chosen language
Crash reporter	If the app ever crashes, the full stack trace is shown in a copyable dialog on the next launch. No adb needed to diagnose

---

Screenshots

---

Server compatibility

Sharesonic is built for Velvet (v0.3.5). It uses Velvet's native API for everything: browsing, streaming, sharing, shuffle, Auto-DJ, playlist management, and search. The Subsonic compatibility layer is now only a dormant legacy fallback.

Generic Subsonic servers (Navidrome, Airsonic, etc.) are not supported yet, planned for a future release.

---

Installation

Direct download

1. Download the latest APK from Releases
2. On your Android device: Settings → Security → Install unknown apps → allow your browser or file manager
3. Open the downloaded APK and install
4. Launch Sharesonic, enter your Velvet server URL, username and password, tap Test then Save

Obtainium (recommended, auto-updates)

1. Install Obtainium
2. Tap the badge below or add https://github.com/Tiritibambix/Sharesonic manually

---

Building from source

Prerequisites

• JDK 17
• Android SDK with build tools for API 35
• A local.properties file at the project root with your SDK path:

sdk.dir=/path/to/your/Android/Sdk

Debug build

./gradlew assembleDebug
# APK: app/build/outputs/apk/debug/app-debug.apk

Release build

./gradlew assembleRelease
# APK: app/build/outputs/apk/release/app-release-unsigned.apk

---

CI / CD

GitHub Actions runs on every push and tag:

Trigger	Action
Push to any branch	Build debug APK named sharesonic-artifact-<run>.apk, upload as workflow artifact
Tag v*	Build signed release APK named sharesonic-v<version>.apk, create GitHub Release, attach APK

---

How it works

Sharesonic runs entirely on Velvet's native API; a Subsonic compatibility layer remains only as a dormant legacy fallback.

Velvet native API (primary)

Endpoint	Purpose
POST /api/v1/auth/login	JWT authentication
GET /api/v1/auth/refresh	Refresh JWT on boot
POST /api/v1/file-explorer	Folder browsing + file metadata
POST /api/v1/file-explorer/recursive	Every filepath under a folder in one request (folder shuffle)
POST /api/v1/db/metadata/batch	Batch metadata for a list of filepaths (folder shuffle)
POST /api/v1/db/search	Full-text search (folders, artists, albums, songs)
POST /api/v1/db/artist-folder-songs	All tracks for an artist tag (tapping an artist in search)
POST /api/v1/db/metadata	Fresh, full metadata for one track (bpm / musical-key / genres, for the Track Info dialog)
GET /api/v1/lyrics	Lyrics for a track (server-parsed synced or plain, for the Lyrics sheet)
GET /media/<filepath>?token=<jwt>	Audio streaming (each path segment percent-encoded)
GET /album-art/<file>?token=<jwt>	Cover art
POST /api/v1/share	Generate public share link for a track or the whole queue (time = days)
POST /api/v1/db/rate-song	Rate / clear the rating of a track (native 0–10 half-star scale)
GET /api/v1/share/list	List own share links
DELETE /api/v1/share/:id	Revoke a share link
`POST /api/v1/db/random-songs$	\text{Random} \text{song} \text{for} \text{shuffle} (\text{called} 30 \times ) \text{and} \text{Auto}-\text{DJ} (\text{called} 1 \times \text{with} \text{BPM}/\text{key}/\text{artist} \text{filters})
$GET /api/v1/lastfm/similar-artists`	Similar artists for Auto-DJ (proxied from Last.fm)
GET /api/v1/playlist/getall	List playlists
POST /api/v1/playlist/load	Load playlist tracks
POST /api/v1/playlist/add-song	Add track to playlist
POST /api/v1/playlist/remove-song	Remove track from playlist
POST /api/v1/playlist/save	Create / rename playlist
DELETE /api/v1/playlist/:name	Delete playlist
POST /api/v1/lastfm/scrobble-by-filepath	Scrobble to Last.fm at 50%
POST /api/v1/listenbrainz/playing-now	"Now playing" ping to ListenBrainz on track start
POST /api/v1/listenbrainz/scrobble-by-filepath	Scrobble to ListenBrainz at 50%

Note: scrobbling only works if "Scrobble from External Apps" is turned on in Velvet's server settings. Last.fm and ListenBrainz must also be configured there. Sharesonic just fires the calls; Velvet silently drops them if this setting is disabled.

Subsonic API (legacy / dormant)

Search moved to the native /api/v1/db/search, so these are no longer used in practice. They remain only as a defensive fallback for songs carrying a Subsonic integer ID, which native search no longer produces.

Endpoint	Purpose
search3	Legacy full-text search (superseded by native db/search)
scrobble	Scrobble integer-ID songs (dormant)

---

Roadmap / known limitations

• No offline caching or download for offline playback
• No multiple server profiles
• No Android Auto support
• No Chromecast / DLNA casting
• Generic Subsonic server support (Navidrome, Airsonic...), planned post-v1

Contributions welcome. Open an issue before submitting a large PR.

---

License

GPL-3.0