Expand description
a typed, async client for the yandex music api.
covers the catalogue (tracks, albums, artists, playlists), the library (likes, dislikes, pins, pre-saves), radio, search, listening history, lossless downloads and the ynison realtime player stream.
§quick start
use yamuse::Client;
let client = Client::builder().token(std::env::var("YM_TOKEN").unwrap()).build()?;
client.init().await?;
let results = client.search("nine inch nails", Default::default()).await?;
for track in results.track_results() {
println!("{} — {}", track.artists_name(), track.title.as_deref().unwrap_or("?"));
}§authentication
every catalogue call needs an oauth token. Client::device_auth runs the
full device flow — show a code, poll until the user confirms — so no browser
needs embedding:
use yamuse::Client;
let client = Client::anonymous()?;
let token = client
.device_auth(Default::default(), |code| {
println!("go to {} and enter {}", code.verification_url.as_deref().unwrap_or(""), code.user_code.as_deref().unwrap_or(""));
})
.await?;
println!("token: {}", token.access_token.as_deref().unwrap_or(""));§downloads
two paths exist, and they are not interchangeable. the legacy one
(Client::track_download_info) serves mp3 and aac. the modern one
(Client::track_lossless_info) serves flac as an aes-ctr-encrypted
encraw stream — Downloader decrypts it as it
writes, so a 300 mb file never lands in memory.
use yamuse::download::Downloader;
let info = client.track_lossless_info(42, "lossless").await?;
Downloader::new(client.transport(), info.links())
.maybe_encraw_key(info.key.clone())
.to_file("track.flac")
.await?;§feature flags
rustls-tls(default) — tls via rustls.native-tls— tls via the platform library instead.download(default) — stream downloads to disk.realtime— the ynison player stream over websocket.tracing— emittracingevents for requests, retries, rate limits and ynison reconnects. without it the logging macros expand to nothing.full—download+realtime+tracing.
§resilience
this wraps a private api that changes without notice, so both layers degrade rather than break: every model field is optional and unknown fields are ignored, and polymorphic payloads whose type is unrecognized are preserved as raw json instead of being dropped.
idempotent GETs retry transient failures with jittered backoff, and a 429
with a retry-after waits out what the server asked for, up to a cap.
mutations never retry — a replayed playlists/create makes two playlists —
and a mutation the api does not acknowledge is an error rather than a false
nobody checks.
Re-exports§
pub use client::BATCH_CHUNK;pub use client::Client;pub use client::ClientBuilder;pub use client::DEFAULT_BASE_URL;pub use client::DEFAULT_DEVICE;pub use difference::DiffTrack;pub use difference::Difference;pub use error::Error;pub use error::Result;pub use params::Params;pub use transport::RetryPolicy;pub use transport::Transport;pub use types::Dislikeable;pub use types::Diversity;pub use types::Language;pub use types::Likeable;pub use types::LyricsFormat;pub use types::MoodEnergy;pub use types::RotorFeedback;pub use types::SearchType;pub use types::SortBy;pub use types::SortOrder;pub use types::StationLanguage;pub use types::StationType;pub use types::Visibility;
Modules§
- client
- the client and its builder.
- crypto
encrawstream decryption.- difference
- playlist edit diffs.
- download
download - streaming downloads.
- drift
- api drift detection.
- error
- error type raised by every fallible operation in the crate.
- models
- typed models for every api payload.
- params
- request parameter building: query strings, form bodies and path segments.
- sign
- request signing.
- tolerant
- type-tolerant deserialization.
- transport
- http transport.
- types
- typed parameter enums.
- ynison
realtime - ynison — realtime player state over websocket.
Structs§
- Artist
Albums Query - pagination and sorting for the artist-album listings.
- Device
Auth Options - options for the device flow.
- History
Query - the set of entities whose history items to resolve.
- Metatag
List Query - pagination and sorting for the metatag listing endpoints.
- Metatag
Query - per-section item counts requested from
Client::metatag. - Play
Audio Report - a playback progress report for
Client::play_audio. - Rotor
Feedback Report - one listening-feedback event for
Client::rotor_feedback. - Search
Query - options for
Client::search.