yamuse 0.3.2

typed async client for the yandex music api: catalogue, likes, playlists, radio, lossless downloads and ynison realtime
Documentation
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
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
//! the track model, its nested value objects and its download variants.

use md5::{Digest, Md5};
use serde::{Deserialize, Serialize};
use serde_json::Value;

use super::album::Album;
use super::artist::Artist;
use super::landing::Chart;
use super::{ContentRestrictions, CoverDerivedColors, Id};
use crate::error::{Error, Result};
use crate::transport::Transport;

/// salt used to sign direct download links.
const SIGN_SALT: &str = "XGRlBW9FXlekgbPrRHuSiA";

/// a content provider or label major associated with a track.
#[derive(Debug, Default, Clone, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct Major {
    /// major identifier.
    pub id: Option<i64>,
    /// major name.
    pub name: Option<String>,
}

/// loudness normalization parameters, replaygain-style.
#[derive(Debug, Default, Clone, Copy, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct Normalization {
    /// gain adjustment in db.
    pub gain: Option<f64>,
    /// peak sample value.
    pub peak: Option<f64>,
}

/// a matched range of a track's lyrics, used by the "poetry lover" feature.
#[derive(Debug, Default, Clone, Copy, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct PoetryLoverMatch {
    /// start character offset within the matched line.
    pub begin: Option<i64>,
    /// end character offset within the matched line.
    pub end: Option<i64>,
    /// line number of the match.
    pub line: Option<i64>,
}

/// availability of lyrics for a track.
#[derive(Debug, Default, Clone, Copy, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct LyricsInfo {
    /// whether time-synced (lrc) lyrics are available.
    pub has_available_sync_lyrics: Option<bool>,
    /// whether plain-text lyrics are available.
    pub has_available_text_lyrics: Option<bool>,
}

/// fade-in and fade-out timing for smart previews and crossfade.
#[derive(Debug, Default, Clone, Copy, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct Fade {
    /// fade-in start time in seconds.
    pub in_start: Option<f64>,
    /// fade-in stop time in seconds.
    pub in_stop: Option<f64>,
    /// fade-out start time in seconds.
    pub out_start: Option<f64>,
    /// fade-out stop time in seconds.
    pub out_stop: Option<f64>,
}

/// parameters describing the auto-selected preview of a track.
#[derive(Debug, Default, Clone, Copy, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct SmartPreviewParams {
    /// preview duration in milliseconds.
    pub duration_ms: Option<i64>,
    /// fade timing for the preview.
    pub fade: Option<Fade>,
}

/// track metadata as embedded in file tags.
#[derive(Debug, Default, Clone, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct MetaData {
    /// album title.
    pub album: Option<String>,
    /// volume (disc) number.
    pub volume: Option<i64>,
    /// release year.
    pub year: Option<i64>,
    /// track number within the volume.
    pub number: Option<i64>,
    /// genre.
    pub genre: Option<String>,
    /// lyricist credit.
    pub lyricist: Option<String>,
    /// version, for example "remastered".
    pub version: Option<String>,
    /// composer credit.
    pub composer: Option<String>,
}

/// ebu r128 loudness measurements.
#[derive(Debug, Default, Clone, Copy, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct R128 {
    /// integrated loudness, in lufs.
    pub i: Option<f64>,
    /// true peak, in dbtp.
    pub tp: Option<f64>,
}

/// the label or major that owns a track's lyrics.
#[derive(Debug, Default, Clone, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct LyricsMajor {
    /// identifier.
    pub id: Option<i64>,
    /// internal name.
    pub name: Option<String>,
    /// display name.
    pub pretty_name: Option<String>,
}

/// a music track.
#[derive(Debug, Default, Clone, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct Track {
    /// unique track identifier.
    pub id: Option<Id>,
    /// track title.
    pub title: Option<String>,
    /// whether the track is available for playback.
    pub available: Option<bool>,
    /// performing artists.
    pub artists: Vec<Artist>,
    /// albums the track belongs to.
    pub albums: Vec<Album>,
    /// whether available for premium users.
    pub available_for_premium_users: Option<bool>,
    /// whether lyrics are available.
    pub lyrics_available: Option<bool>,
    /// matched lyric ranges from the poetry-lover feature.
    pub poetry_lover_matches: Vec<PoetryLoverMatch>,
    /// whether this is the "best" track.
    pub best: Option<bool>,
    /// canonical track id when this track is a duplicate.
    pub real_id: Option<Id>,
    /// open graph image uri template.
    pub og_image: Option<String>,
    /// track kind, for example `music` or `podcast-episode`.
    pub r#type: Option<String>,
    /// cover uri template.
    pub cover_uri: Option<String>,
    /// content provider major.
    pub major: Option<Major>,
    /// duration in milliseconds.
    pub duration_ms: Option<i64>,
    /// storage directory.
    pub storage_dir: Option<String>,
    /// file size in bytes.
    pub file_size: Option<i64>,
    /// track substituted for this one when unavailable.
    pub substituted: Option<Box<Track>>,
    /// track this one matched against, in search results.
    pub matched_track: Option<Box<Track>>,
    /// loudness normalization parameters.
    pub normalization: Option<Normalization>,
    /// error code when the track could not be resolved.
    pub error: Option<String>,
    /// whether the track can be published.
    pub can_publish: Option<bool>,
    /// publication state.
    pub state: Option<String>,
    /// desired visibility.
    pub desired_visibility: Option<String>,
    /// original filename, for user-uploaded tracks.
    pub filename: Option<String>,
    /// embedded tag metadata.
    pub meta_data: Option<MetaData>,
    /// regions where available.
    pub regions: Vec<String>,
    /// whether available as a ringback tone.
    pub available_as_rbt: Option<bool>,
    /// content warning marker.
    pub content_warning: Option<String>,
    /// explicit marker.
    pub explicit: Option<bool>,
    /// preview duration in milliseconds.
    pub preview_duration_ms: Option<i64>,
    /// whether the full track is available without a subscription.
    pub available_full_without_permission: Option<bool>,
    /// version, for example "remastered".
    pub version: Option<String>,
    /// whether playback position is remembered, as for podcasts.
    pub remember_position: Option<bool>,
    /// background video uri for the track.
    pub background_video_uri: Option<String>,
    /// short description, for podcasts.
    pub short_description: Option<String>,
    /// whether suitable for children.
    pub is_suitable_for_children: Option<bool>,
    /// source of the track.
    pub track_source: Option<String>,
    /// options the track is available for.
    pub available_for_options: Vec<String>,
    /// lyrics availability flags.
    pub lyrics_info: Option<LyricsInfo>,
    /// sharing flag.
    pub track_sharing_flag: Option<String>,
    /// colors derived from the cover.
    pub derived_colors: Option<CoverDerivedColors>,
    /// crossfade timings.
    pub fade: Option<Fade>,
    /// smart preview parameters.
    pub smart_preview_params: Option<SmartPreviewParams>,
    /// special audio resource identifiers.
    pub special_audio_resources: Vec<String>,
    /// disclaimers.
    pub disclaimers: Vec<String>,
    /// background video identifier.
    pub background_video_id: Option<String>,
    /// player identifier.
    pub player_id: Option<String>,
    /// ebu r128 loudness measurements.
    pub r128: Option<R128>,
    /// podcast episode kind, for podcast episodes only.
    pub podcast_episode_type: Option<String>,
    /// publication date of a podcast episode, as iso 8601.
    pub pub_date: Option<String>,
    /// chart standing, when the track came from a chart context.
    pub chart: Option<Chart>,
    /// content availability restrictions.
    pub content_restrictions: Option<ContentRestrictions>,
}

impl Track {
    /// the numeric track id, dropping any `:album` suffix.
    ///
    /// # errors
    ///
    /// returns [`Error::IdMissing`] when the track carries no usable id.
    pub fn numeric_id(&self) -> Result<i64> {
        self.id
            .as_ref()
            .and_then(Id::as_number)
            .ok_or(Error::IdMissing("track id"))
    }

    /// the performing artists joined for display, for example `"a, b"`.
    #[must_use]
    pub fn artists_name(&self) -> String {
        self.artists
            .iter()
            .filter_map(|a| a.name.as_deref())
            .collect::<Vec<_>>()
            .join(", ")
    }

    /// the cover url at a concrete size, for example `400x400`.
    #[must_use]
    pub fn cover_url(&self, size: &str) -> Option<String> {
        self.cover_uri
            .as_deref()
            .map(|uri| super::normalize_image_url(uri, size))
    }

    /// the album this track is primarily attributed to.
    #[must_use]
    pub fn album(&self) -> Option<&Album> {
        self.albums.first()
    }
}

/// a compact reference to a track inside a playlist.
///
/// carries the ids needed to fetch the full [`Track`]; the `track` field is only
/// populated by endpoints that inline the whole object.
#[derive(Debug, Default, Clone, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct TrackShort {
    /// track id.
    pub id: Option<Id>,
    /// timestamp the track was added at.
    pub timestamp: Option<String>,
    /// album id the track is referenced from.
    pub album_id: Option<String>,
    /// play counter.
    pub play_count: Option<i64>,
    /// whether recently added.
    pub recent: Option<bool>,
    /// chart placement, still free-form upstream.
    pub chart: Option<Value>,
    /// the full track, when inlined by the endpoint.
    pub track: Option<Track>,
    /// original index within the source list.
    pub original_index: Option<i64>,
    /// original index within the shuffled source list.
    pub original_shuffle_index: Option<i64>,
}

/// a bare track and album id pair, used by landing blocks and queues.
#[derive(Debug, Default, Clone, Copy, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct TrackId {
    /// id of the reference.
    pub id: Option<i64>,
    /// track id.
    pub track_id: Option<i64>,
    /// album id.
    pub album_id: Option<i64>,
}

/// one download variant of a track: a codec, a bitrate and a way to resolve a
/// short-lived direct file url.
///
/// this is the legacy lossy path (mp3 and aac). for flac use
/// [`LosslessDownloadInfo`].
#[derive(Debug, Default, Clone, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct DownloadInfo {
    /// audio codec, for example `mp3` or `aac`.
    pub codec: Option<String>,
    /// bitrate in kbit/s.
    pub bitrate_in_kbps: Option<i64>,
    /// whether gain is applied.
    pub gain: Option<bool>,
    /// whether this is a preview rather than the full track.
    pub preview: Option<bool>,
    /// url of the xml document describing how to build the direct link.
    pub download_info_url: Option<String>,
    /// whether the link is already direct.
    pub direct: Option<bool>,
}

impl DownloadInfo {
    /// resolve the short-lived direct download url.
    ///
    /// the api answers with a small xml document whose parts are hashed into the
    /// final path. the resolved url is valid for roughly a minute — request it
    /// immediately before downloading, or the cdn answers 410.
    ///
    /// # errors
    ///
    /// returns [`Error::IdMissing`] when there is no info url, or a transport
    /// error when the xml cannot be fetched or is malformed.
    pub async fn direct_link(&self, transport: &Transport) -> Result<String> {
        let info_url = self
            .download_info_url
            .as_deref()
            .ok_or(Error::IdMissing("downloadInfoUrl"))?;
        let xml = transport.retrieve_text(info_url).await?;
        build_direct_link(&xml)
    }
}

/// build the direct download url from the download-info xml.
fn build_direct_link(xml: &str) -> Result<String> {
    let tag = |name: &str| -> Option<&str> {
        let open = format!("<{name}>");
        let close = format!("</{name}>");
        let start = xml.find(&open)? + open.len();
        let end = xml[start..].find(&close)? + start;
        Some(&xml[start..end])
    };

    let (Some(host), Some(path), Some(ts), Some(s)) =
        (tag("host"), tag("path"), tag("ts"), tag("s"))
    else {
        return Err(Error::InvalidResponse(
            "download-info xml is missing host/path/ts/s".into(),
        ));
    };

    // the api's own scheme: md5 over the salt, the path without its leading
    // slash, and the `s` nonce.
    let mut hasher = Md5::new();
    hasher.update(SIGN_SALT.as_bytes());
    hasher.update(path.strip_prefix('/').unwrap_or(path).as_bytes());
    hasher.update(s.as_bytes());
    let sign = hex::encode(hasher.finalize());

    Ok(format!("https://{host}/get-mp3/{sign}/{ts}{path}"))
}

/// lossless (and other modern) download info from `/get-file-info`.
///
/// with `transport: encraw` the urls serve an aes-ctr-encrypted stream and
/// [`key`](Self::key) holds the hex decryption key. the endpoint falls back to a
/// lossy codec when a track has no lossless source — check
/// [`is_lossless`](Self::is_lossless).
#[derive(Debug, Default, Clone, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct LosslessDownloadInfo {
    /// track id this info belongs to.
    pub track_id: Option<String>,
    /// requested or granted quality, for example `lossless`.
    pub quality: Option<String>,
    /// actual codec served: `flac`, `flac-mp4`, `aac`, `mp3`, ...
    pub codec: Option<String>,
    /// bitrate in kbit/s.
    pub bitrate: Option<i64>,
    /// transport, typically `encraw` for an aes-ctr-encrypted raw stream.
    pub transport: Option<String>,
    /// hex aes-ctr key used to decrypt an `encraw` stream, when encrypted.
    pub key: Option<String>,
    /// candidate stream urls; any one works.
    pub urls: Vec<String>,
    /// single stream url, from the older response shape.
    pub url: Option<String>,
    /// file size in bytes, when known.
    pub size: Option<i64>,
    /// whether loudness-normalization gain data is available.
    pub gain: Option<bool>,
    /// canonical track id when the requested id is an alias.
    pub real_id: Option<String>,
}

impl LosslessDownloadInfo {
    /// whether this is a true lossless (flac) variant.
    #[must_use]
    pub fn is_lossless(&self) -> bool {
        matches!(self.codec.as_deref(), Some("flac" | "flac-mp4"))
    }

    /// whether the stream is aes-ctr encrypted and needs the key applied.
    #[must_use]
    pub fn is_encrypted(&self) -> bool {
        self.key.is_some()
    }

    /// every candidate stream url, deduplicated, in preference order.
    #[must_use]
    pub fn links(&self) -> Vec<String> {
        let mut seen = Vec::new();
        for url in self.urls.iter().chain(self.url.as_ref()) {
            if !url.is_empty() && !seen.contains(url) {
                seen.push(url.clone());
            }
        }
        seen
    }
}

/// lyrics of a track.
#[derive(Debug, Default, Clone, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct TrackLyrics {
    /// url the raw lyrics text is fetched from.
    pub download_url: Option<String>,
    /// lyric identifier.
    pub lyric_id: Option<i64>,
    /// external lyric identifier.
    pub external_lyric_id: Option<String>,
    /// writer credits.
    pub writers: Vec<String>,
    /// lyrics provider major.
    pub major: Option<LyricsMajor>,
}

impl TrackLyrics {
    /// fetch the raw lyrics text, plain or lrc to match the requested format.
    ///
    /// the lyrics endpoint returns a url rather than the text itself, so reading
    /// the words takes this second call.
    ///
    /// # errors
    ///
    /// returns [`Error::IdMissing`] when there is no download url, or a transport
    /// error when the text cannot be fetched.
    pub async fn text(&self, transport: &Transport) -> Result<String> {
        let url = self
            .download_url
            .as_deref()
            .ok_or(Error::IdMissing("lyrics downloadUrl"))?;
        transport.retrieve_text(url).await
    }
}

/// a track together with tracks similar to it.
#[derive(Debug, Default, Clone, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct SimilarTracks {
    /// the reference track.
    pub track: Option<Track>,
    /// tracks similar to the reference.
    pub similar_tracks: Vec<Track>,
}

/// full information about a track, including related content.
#[derive(Debug, Default, Clone, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct TrackFullInfo {
    /// the track itself.
    pub track: Option<Track>,
    /// similar tracks.
    pub similar_tracks: Vec<Track>,
    /// other albums the track appears in.
    pub also_in_albums: Vec<Track>,
    /// title aliases.
    pub aliases: Vec<String>,
    /// related artists.
    pub artists: Vec<Artist>,
    /// other versions of the track, keyed by version label such as `live`.
    pub other_versions: std::collections::HashMap<String, Vec<Track>>,
}

/// a track trailer.
#[derive(Debug, Default, Clone, Serialize, Deserialize)]
#[serde(default, rename_all = "camelCase")]
pub struct TrackTrailer {
    /// trailer title.
    pub title: Option<String>,
    /// the trailer track.
    pub track: Option<Track>,
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn a_direct_link_is_built_from_the_info_xml() {
        let xml = r#"<?xml version="1.0" encoding="utf-8"?><download-info>
            <host>storage.mds.yandex.net</host>
            <path>/get-mp3/abc/1.mp3</path>
            <ts>0005f2</ts>
            <region>225</region>
            <s>deadbeef</s>
        </download-info>"#;

        let link = build_direct_link(xml).unwrap();

        // md5(salt + path-without-leading-slash + s), verified independently
        let mut hasher = Md5::new();
        hasher.update(SIGN_SALT.as_bytes());
        hasher.update(b"get-mp3/abc/1.mp3");
        hasher.update(b"deadbeef");
        let expected = hex::encode(hasher.finalize());

        assert_eq!(
            link,
            format!("https://storage.mds.yandex.net/get-mp3/{expected}/0005f2/get-mp3/abc/1.mp3")
        );
    }

    #[test]
    fn an_incomplete_xml_is_rejected() {
        assert!(build_direct_link("<download-info><host>h</host></download-info>").is_err());
        assert!(build_direct_link("not xml").is_err());
        assert!(build_direct_link("").is_err());
    }

    #[test]
    fn lossless_detection_covers_both_flac_codecs() {
        let flac = LosslessDownloadInfo {
            codec: Some("flac".into()),
            ..Default::default()
        };
        let flac_mp4 = LosslessDownloadInfo {
            codec: Some("flac-mp4".into()),
            ..Default::default()
        };
        let aac = LosslessDownloadInfo {
            codec: Some("aac".into()),
            ..Default::default()
        };
        assert!(flac.is_lossless());
        assert!(flac_mp4.is_lossless());
        assert!(!aac.is_lossless());
        assert!(!LosslessDownloadInfo::default().is_lossless());
    }

    #[test]
    fn links_merge_both_url_shapes_and_deduplicate() {
        let info = LosslessDownloadInfo {
            urls: vec!["https://a".into(), "https://b".into(), "https://a".into()],
            url: Some("https://b".into()),
            ..Default::default()
        };
        assert_eq!(
            info.links(),
            vec!["https://a".to_string(), "https://b".to_string()]
        );

        let only_single = LosslessDownloadInfo {
            url: Some("https://c".into()),
            ..Default::default()
        };
        assert_eq!(only_single.links(), vec!["https://c".to_string()]);

        assert!(LosslessDownloadInfo::default().links().is_empty());
    }

    #[test]
    fn encryption_is_flagged_by_the_presence_of_a_key() {
        assert!(!LosslessDownloadInfo::default().is_encrypted());
        let encrypted = LosslessDownloadInfo {
            key: Some("ab".into()),
            ..Default::default()
        };
        assert!(encrypted.is_encrypted());
    }

    #[test]
    fn tracks_accept_both_id_shapes_and_normalize_them() {
        let numeric: Track = serde_json::from_str(r#"{"id":42}"#).unwrap();
        let compound: Track = serde_json::from_str(r#"{"id":"42:1001"}"#).unwrap();
        assert_eq!(numeric.numeric_id().unwrap(), 42);
        assert_eq!(compound.numeric_id().unwrap(), 42);
        assert!(Track::default().numeric_id().is_err());
    }

    #[test]
    fn artist_names_join_for_display() {
        let track: Track =
            serde_json::from_str(r#"{"artists":[{"name":"A"},{"name":"B"},{}]}"#).unwrap();
        assert_eq!(track.artists_name(), "A, B");
        assert_eq!(Track::default().artists_name(), "");
    }

    #[test]
    fn cover_urls_resolve_the_size_placeholder() {
        let track: Track =
            serde_json::from_str(r#"{"coverUri":"avatars.yandex.net/get-music/1/%%"}"#).unwrap();
        assert_eq!(
            track.cover_url("200x200").as_deref(),
            Some("https://avatars.yandex.net/get-music/1/200x200")
        );
        assert!(Track::default().cover_url("200x200").is_none());
    }

    #[test]
    fn a_substituted_track_nests_without_blowing_the_stack() {
        let track: Track =
            serde_json::from_str(r#"{"id":1,"substituted":{"id":2,"title":"other"}}"#).unwrap();
        let substituted = track.substituted.as_ref().unwrap();
        assert_eq!(substituted.title.as_deref(), Some("other"));
    }

    #[test]
    fn other_versions_deserialize_as_a_keyed_map() {
        let info: TrackFullInfo = serde_json::from_str(
            r#"{"track":{"id":1},"otherVersions":{"live":[{"id":2}],"remix":[{"id":3},{"id":4}]}}"#,
        )
        .unwrap();
        assert_eq!(info.other_versions["live"].len(), 1);
        assert_eq!(info.other_versions["remix"].len(), 2);
    }

    #[test]
    fn track_models_survive_an_empty_object() {
        serde_json::from_str::<Track>("{}").unwrap();
        serde_json::from_str::<TrackShort>("{}").unwrap();
        serde_json::from_str::<TrackId>("{}").unwrap();
        serde_json::from_str::<DownloadInfo>("{}").unwrap();
        serde_json::from_str::<LosslessDownloadInfo>("{}").unwrap();
        serde_json::from_str::<TrackLyrics>("{}").unwrap();
        serde_json::from_str::<SimilarTracks>("{}").unwrap();
        serde_json::from_str::<TrackFullInfo>("{}").unwrap();
        serde_json::from_str::<TrackTrailer>("{}").unwrap();
    }
}