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.
built for the awkward part of that: the api is undocumented and changes without
notice, so every model degrades instead of failing, a mutation that did not happen
is an error rather than a false, and a half-written download never reaches disk.
[]
= "0.3"
= { = "1", = ["macros", "rt-multi-thread"] }
rust 2024, msrv 1.85. no chrono, no openssl by default.
- quick start · authentication · downloads · realtime
- errors · what is covered · feature flags · design notes
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.
errors
everything funnels into one Error enum, so a single match covers the whole
surface:
# async
is_retryable() is true for transport failures, 5xx and 429. idempotent GETs
already retry internally, so seeing one usually means the retries ran out.
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.hasOptionsreads like a boolean by its very name, 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
| example | what it shows |
|---|---|
search |
the shortest useful call, with drift reporting wired up |
library |
liked tracks, albums and artists |
playlist |
creating and editing one — and why revision is unavoidable |
lyrics |
a signed endpoint, and a response that carries a url not the words |
radio |
a rotor station with the feedback a real player reports |
download |
streaming a lossless track to disk, decrypting on the way |
now_playing |
the ynison stream |
device_auth |
obtaining a token, no browser embedded |
drift |
what the api sends that this crate does not model yet |
YM_TOKEN=...
YM_TOKEN=... YM_TOKEN=...
YM_TOKEN=...
YM_TOKEN=...
documentation
- api reference — every method, every model.
- getting started — tokens, the first few calls.
- architecture — how the crate is put together, and why each load-bearing decision went the way it did.
- realtime — the ynison stream in detail.
alternatives
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