yamuse
typed, async rust client for the yandex music api.
covers the catalogue, the library, radio, search, listening history, lossless downloads and the ynison realtime player stream — the full surface of the private api the official apps use.
[]
= "0.3"
= { = "1", = ["macros", "rt-multi-thread"] }
quick start
use Client;
async
authentication
there is no public api key. authentication is an oauth token, obtained through the device flow — no browser to embed, no password to handle:
# async
tokens expire. persist the refresh token and renew with
refresh_token —
the response usually rotates it, so store the new one.
downloads
two paths exist and they are not interchangeable.
track_download_info |
track_lossless_info |
|
|---|---|---|
| codecs | mp3, aac | flac, flac-mp4, aac, mp3 |
| endpoint | /tracks/{id}/download-info |
/get-file-info (signed) |
| link lifetime | ~1 minute, resolved from an xml document | mirror urls, longer-lived |
| encryption | none | aes-ctr (transport: encraw) |
the lossless path is the one you want, and Downloader decrypts it as it streams,
so a 300 mb flac never lands in memory:
#
# async
realtime — what is playing right now
ynison is the only server-push channel yandex music offers; there are no webhooks.
Realtime owns the handshake, the keepalive and reconnection:
#
# async
realtime.now_playing() answers synchronously from the last frame, with the
position extrapolated to the moment of the call — useful for serving an http
request without waiting for the next update.
what is covered
every endpoint the api exposes, grouped as the client methods are:
| group | endpoints |
|---|---|
| account | status, settings (read and write), purchase offers, permission alerts, experiments, promo codes |
| tracks | batch lookup, lossy download info, lossless (flac) info, lyrics (plain and lrc), similar, full info, trailer, supplement, playback reporting, after-track shots |
| albums | batch lookup, with-tracks, similar entities, trailer |
| artists | batch lookup, brief info, tracks, direct/also/discography/safe-direct albums, similar, links, trailer, track ids, info, about, clips, donations, skeletons |
| playlists | read, create, delete, rename, visibility, description, diff-based edits, collective join, by uuid, personal (daily and friends), trailer, kinds, similar entities |
| likes | like and dislike tracks, artists, albums, playlists and clips; read every library |
| search | full search across all types, suggestions |
| radio | dashboard, station list, station info, track batches, all four feedback events, station settings |
| landing | landing blocks, charts, new releases, new playlists, podcasts, genres, feed, wizard state, tags |
| history | listening history by day, item resolution |
| queues | list, read, create, position updates |
| metatags | navigation trees, metatag detail, albums, artists, playlists |
| concerts | artist concerts, concert info, feed, locations, tab config, skeletons |
| clips | batch lookup, recommendations |
| pins | list, pin and unpin albums, artists, playlists, waves |
| pre-saves | list, add, remove |
| labels | label detail, albums, artists |
| credits | track and clip production credits |
| disclaimers | track, clip, album and artist disclaimers |
| device auth | code request, polling, refresh, full blocking flow |
| realtime | ynison player state, reconnecting |
feature flags
| flag | default | what it adds |
|---|---|---|
rustls-tls |
yes | tls via rustls |
native-tls |
no | tls via the platform library instead |
download |
yes | stream downloads to disk |
realtime |
no | the ynison player stream |
tracing |
no | tracing events for requests, retries, rate limits and reconnects |
full |
no | download + realtime + tracing |
design notes
resilience against a private api. this wraps an api that changes without notice, so every layer degrades rather than breaks:
- a field the api stops sending becomes
None— every model field is optional. - a field the api starts sending is ignored rather than fatal.
- a field whose type changes costs that field, not the request. a json float
standing in for an integer is narrowed; anything else is dropped, and you are
told which via
on_field_repair. this is not hypothetical —Status.hasOptionsis documented upstream as a boolean and arrives as a list. - a polymorphic payload with an unrecognized
typeis preserved as raw json (SearchEntity::Unknown,BlockEntityData::Unknown) rather than discarded, so one unfamiliar tile never fails a landing page.
#
retries only where they are safe. idempotent GETs retry transient failures
with exponential backoff and full jitter. mutations get exactly one attempt: a
replayed playlists/create would create two playlists. deterministic rejections
(400, 404, 409, 413) are never retried either — they fail the same way every time.
429 is the exception among the 4xx: being rate limited says "not now", not "not
ever". a retry-after on the response is waited out verbatim rather than
jittered, but capped at RetryPolicy::retry_after_max — this api does answer
with delays of an hour, and honouring one blocks the call for the rest of the day.
nothing half-written reaches disk. a download lands in a sibling .part file
and is renamed into place only once it completes, so the destination either holds
a whole track or is untouched. that covers both the failed transfer and the
process killed mid-stream — a truncated track looks exactly like a valid cached
one, which is a worse failure than an error.
typed parameters. what the api takes as bare strings are real enums here
(SearchType, LyricsFormat, MoodEnergy, ...), so a typo is a compile error
rather than a puzzling 400. anything that reaches the url path is percent-encoded,
so a / in a playlist uuid cannot retarget the request at another endpoint.
a mutation that did not happen is an error. every mutating method returns
Mutation, not bool. a boolean could only say "that did not work" — without
the reason, and silently, because nobody checks a returned bool. Mutation
also carries the library revision back from the two endpoints that report one.
long id lists are split. a library of several thousand liked tracks would otherwise be one request the api rejects outright. batch reads chunk transparently; batch mutations chunk too, and say so, since a failure part-way leaves the earlier chunks applied.
cheap clones. Client is Clone and shares one connection pool and one
account cache; pass clones around rather than wrapping in another Arc.
examples
YM_TOKEN=...
YM_TOKEN=...
YM_TOKEN=...
relationship to other work
this is a rust port of @dvxch/yandex-music
(mit), which reverse-engineered and documented the api surface; docs/parity.md
maps every exported symbol from that library to its counterpart here.
yandex-music is a separate, unrelated
rust crate for the same api — worth evaluating if you want an established
dependency rather than this one.
legal
this uses a private api, not a published one. the default oauth credentials are the yandex music android app's, extracted from a publicly downloadable apk; requests made with them present as that app. that is how every third-party client for this service works, and it is not endorsed by yandex. check your own terms of service before deploying anything with it.
license
MIT