Skip to content
This repository has been archived by the owner on Jan 8, 2025. It is now read-only.

Commit

Permalink
add some docs
Browse files Browse the repository at this point in the history
  • Loading branch information
liulifox233 committed Dec 7, 2024
1 parent da5ec82 commit 48348dc
Show file tree
Hide file tree
Showing 2 changed files with 70 additions and 40 deletions.
89 changes: 70 additions & 19 deletions src/api/songs.rs
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ pub struct Song {
pub type_: String,
pub href: String,
pub attributes: Attributes,
/// The relationships for a song resource.
pub relationships: Relationships,
pub meta: Meta,
}
Expand All @@ -27,39 +28,86 @@ pub struct Artwork {
#[derive(serde::Serialize, serde::Deserialize, Debug, Clone)]
#[serde(rename_all = "camelCase")]
pub struct Attributes {
pub album_name: String,
pub has_time_synced_lyrics: bool,
pub genre_names: Vec<String>,
pub track_number: u32,
pub duration_in_millis: u64,
pub release_date: String,
pub is_vocal_attenuation_allowed: bool,
pub is_mastered_for_itunes: bool,
pub isrc: String,
/// The name of the album the song appears on.
pub album_name: Option<String>,
/// The artist’s name.
pub artist_name: String,
/// The album artwork.
pub artwork: Artwork,
pub composer_name: Option<String>,
pub audio_locale: String,
pub url: String,
pub play_params: PlayParams,
/// The Recording Industry Association of America (RIAA) rating of the content. The possible values for this rating are clean and explicit. No value means no rating.
pub content_rating: String,
/// The disc number the song appears on.
pub disc_number: u32,
/// The approximate length of the song in milliseconds.
pub duration_in_millis: u64,
/// The notes about the song that appear in the Apple Music catalog.
pub editorial_notes: Option<EditorialNotes>,
/// The genre names the song is associated with.
pub genre_names: Vec<String>,
/// Indicates whether the song has lyrics available in the Apple Music catalog. If true, the song has lyrics available; otherwise, it doesn't.
pub has_lyrics: bool,
/// Indicates whether the response delivered the song as an [Apple Digital Master](https://www.apple.com/apple-music/apple-digital-masters/).
pub is_apple_digital_master: bool,
pub audio_traits: Vec<String>,
/// The International Standard Recording Code (ISRC) for the song.
pub isrc: Option<String>,
/// (Classical music only) The movement count of the song.
pub movement_count: Option<i32>,
/// (Classical music only) The movement name of the song.
pub movement_name: Option<String>,
/// (Classical music only) The movement number of the song.
pub movement_number: Option<i32>,
/// The localized name of the song.
pub name: String,
/// When present, this attribute indicates that the song is available to play with an Apple Music subscription. The value map may be used to initiate playback. Previews of the song audio may be available with or without an Apple Music subscription.
pub play_params: Option<PlayParams>,
/// The preview assets for the song.
pub previews: Vec<Preview>,
pub artist_name: String,
pub extended_asset_urls: ExtendedAssetUrls,
/// The release date of the song, when known, in YYYY-MM-DD or YYYY format. Prerelease songs may have an expected release date in the future.
pub release_date: Option<String>,
/// The number of the song in the album’s track list.
pub track_number: Option<i32>,
/// The URL for sharing the song in Apple Music.
pub url: String,
/// (Classical music only) The name of the associated work.
pub work_name: Option<String>,
pub has_time_synced_lyrics: Option<bool>,
pub is_vocal_attenuation_allowed: bool,
pub is_mastered_for_itunes: bool,
pub composer_name: Option<String>,
pub audio_locale: Option<String>,
pub audio_traits: Option<Vec<String>>,
pub extended_asset_urls: Option<ExtendedAssetUrls>,
}

/// An object that represents a notes attribute.
/// ## Discussion
/// Notes may include XML tags for formatting (&lt;b&gt; for bold, &lt;i&gt; for italic, or &lt;br&gt; for line break) and special characters (&amp;amp; for &, &amp;lt; for <, &amp;gt; for >, &amp;apos; for ‘, and &amp;quot; for “).
#[derive(serde::Serialize, serde::Deserialize, Debug, Clone)]
pub struct EditorialNotes {
/// Abbreviated notes shown inline or when the content appears alongside other content.
pub short: Option<String>,
/// Notes shown when the content is prominently displayed.
pub standard: Option<String>,
/// Name for the editorial notes.
pub name: Option<String>,
/// The tag line for the editorial notes.
pub tagline: Option<String>,
}

#[derive(serde::Serialize, serde::Deserialize, Debug, Clone)]
pub struct PlayParams {
/// The ID of the content to use for playback.
pub id: String,
/// The kind of the content to use for playback.
pub kind: String,
}

#[derive(serde::Serialize, serde::Deserialize, Debug, Clone)]
#[serde(rename_all = "camelCase")]
pub struct Preview {
pub artwork: Option<Artwork>,
pub url: String,
pub hls_url: Option<String>,
}

#[derive(serde::Serialize, serde::Deserialize, Debug, Clone)]
Expand All @@ -74,13 +122,16 @@ pub struct ExtendedAssetUrls {

#[derive(serde::Serialize, serde::Deserialize, Debug, Clone)]
pub struct Relationships {
pub albums: RelationshipData,
pub artists: RelationshipData,
/// The albums associated with the song. By default, albums includes identifiers only.
pub albums: Option<RelationshipData>,
/// The artists associated with the song. By default, artists includes identifiers only.
pub artists: Option<RelationshipData>,
}

#[derive(serde::Serialize, serde::Deserialize, Debug, Clone)]
pub struct RelationshipData {
pub href: String,
pub href: Option<String>,
pub next: Option<String>,
pub data: Vec<RelationshipItem>,
}

Expand Down
21 changes: 0 additions & 21 deletions src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -176,13 +176,6 @@ impl AppleMusicDownloader {
}

/// Gets the song information.
/// # Examples
/// ```rust
/// # use ramdl::AppleMusicDownloader;
/// # let media_user_token = std::env::var("MEDIA_USER_TOKEN").unwrap();
/// # let apple_music = AppleMusicDownloader::new_with_media_user_token(&media_user_token).await.unwrap();
/// let song = apple_music.get_songs("1753050648").await.unwrap();
/// ```
pub async fn get_songs(&self, song_id: &str) -> Result<Song> {
let store_front = self.store_front.clone();
let res = self
Expand All @@ -199,13 +192,6 @@ impl AppleMusicDownloader {
}

/// Gets the lyrics information.
/// # Examples
/// ```rust
/// # use ramdl::AppleMusicDownloader;
/// # let media_user_token = std::env::var("MEDIA_USER_TOKEN").unwrap();
/// # let apple_music = AppleMusicDownloader::new_with_media_user_token(&media_user_token).await.unwrap();
/// let lyrics = apple_music.get_lyrics("1753050648").await.unwrap();
/// ```
pub async fn get_lyrics(&self, song_id: &str) -> Result<Vec<Option<Lyrics>>> {
let store_front = self.store_front.clone();
let res = self
Expand All @@ -225,13 +211,6 @@ impl AppleMusicDownloader {
}

/// Searches for songs, albums, artists, and playlists.
/// # Examples
/// ```rust
/// # use ramdl::AppleMusicDownloader;
/// # let media_user_token = std::env::var("MEDIA_USER_TOKEN").unwrap();
/// # let apple_music = AppleMusicDownloader::new_with_media_user_token(&media_user_token).await.unwrap();
/// let search_results = apple_music.search("サイレンは彼方より").await.unwrap();
/// ```
pub async fn search(&self, query: &str) -> Result<search::SearchResults> {
let store_front = self.store_front.clone();
let res = self
Expand Down

0 comments on commit 48348dc

Please sign in to comment.