Skip to main content

Crate yamuse

Crate yamuse 

Source
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 — emit tracing events 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
encraw stream decryption.
difference
playlist edit diffs.
downloaddownload
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.
ynisonrealtime
ynison — realtime player state over websocket.

Structs§

ArtistAlbumsQuery
pagination and sorting for the artist-album listings.
DeviceAuthOptions
options for the device flow.
HistoryQuery
the set of entities whose history items to resolve.
MetatagListQuery
pagination and sorting for the metatag listing endpoints.
MetatagQuery
per-section item counts requested from Client::metatag.
PlayAudioReport
a playback progress report for Client::play_audio.
RotorFeedbackReport
one listening-feedback event for Client::rotor_feedback.
SearchQuery
options for Client::search.