1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
//! 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
//!
//! ```no_run
//! use yamuse::Client;
//!
//! # async fn run() -> Result<(), yamuse::Error> {
//! 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("?"));
//! }
//! # Ok(())
//! # }
//! ```
//!
//! # 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:
//!
//! ```no_run
//! use yamuse::Client;
//!
//! # async fn run() -> Result<(), yamuse::Error> {
//! 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(""));
//! # Ok(())
//! # }
//! ```
//!
//! # 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`](download::Downloader) decrypts it as it
//! writes, so a 300 mb file never lands in memory.
//!
//! ```no_run
//! # #[cfg(feature = "download")]
//! # async fn run(client: &yamuse::Client) -> Result<(), yamuse::Error> {
//! 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?;
//! # Ok(())
//! # }
//! ```
//!
//! # 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 `GET`s 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.
pub use ;
pub use ;
pub use ;
pub use Params;
pub use ;
// listed rather than globbed: a glob at the crate root would re-export whatever
// `types` gains next, so a new enum could collide with an existing root name
// without anyone touching this file.
pub use ;
// the option structs each method group defines live next to their methods; they
// are re-exported here so callers need only `use yamuse::*`.
pub use ;