prawn

Crates.ioprawn
lib.rsprawn
version0.0.3
created_at2026-01-24 00:19:35.090557+00
updated_at2026-01-25 05:39:02.902417+00
descriptionRust Client for the Tidal API providing comprehensive API coverag, and easy OAuth management
homepage
repositoryhttps://github.com/khreezy/prawn
max_upload_size
id2065769
size3,019,088
(khreezy)

documentation

README

Prawn - Rust Client Library for the Tidal API

Prawns (shrimp actually) are one of most common crustacean you will see in a tide pool :)

Prawn is a Rust library exposing a thin wrapper client around generated API clients and models for the Tidal V2 API. The wrapper client is intended to make managing authenticating via OAuth 2.0 with Tidal easier by exposing a few simple additional methods and managing refresh tokens. The OAuth methods rely on the oauth2 crate.

The API clients/models/docs were (mostly, with some modifications) generated by the OpenAPI Generator project.

Prawn currently supports the Authorization Code flow and the Client Credentials flow, which are the only ones documented as supported in Tidal's public docs

I developed this library because the other most comprehensive Tidal library for Rust is tidalrs. However, tidalrs only supports device authorization, does not support the authorization code or client credentials flow, and only interacts with the V1 Tidal API. Changing these assumptions felt big enough to warrant its own library in the end.

Examples

Generate an authorize URL

let client_id = "<your client id>";

let redirect_uri = "https://<your callback domain and endpoint>";

let config = TidalClientConfig {
    oauth_config: OAuthConfig {
        redirect_uri,
        client_id,
        client_secret: None
    }
    
    auth_token: None // we haven't authorized yet, so we  don't have  this.
}

let client = TidalClient::new(config)?; 

let (challenge, verifier) = client.generate_pkce_challenge_and_verifier();

let scopes = vec!["user.read"];

let (auth_url, state) = client.get_authorize_url_and_state(challenge, scopes);

printf("visit {} to authorize", auth_url);

Exchange url for token and call API

... /callback implementation ...
let code: String = <extract from query params>
let verifier: String = <same question?>;

let client_id = "<your client id>";

let redirect_uri = "https://<your callback domain and endpoint>";

let config = TidalClientConfig {
    oauth_config: OAuthConfig {
        redirect_uri,
        client_id,
        client_secret: None
    }
    
    auth_token: None // we haven't authorized yet, so we  don't have  this.
}

let client = TidalClient::new(config_with_token)?;

let token: Token = client.exchange_code_for_token(verifier, code)?;

let client_with_token =  client.with_token(config_with_token)?;

let resp = client_with_token.tracks_api().get_track(<some track id>)?;

Client Credentials flow

let client_id = "<your client id>";
let client_secret = "<your client secret>";

let redirect_uri = "";

let config = TidalClientConfig {
    oauth_config: OAuthConfig {
        redirect_uri,
        client_id,
        client_secret: Some(client_secret),
    }

    auth_token: None // we haven't authorized yet, so we  don't have  this.
};

let scopes = vec!["user.read"];
let token = client.exchange_client_credentials_for_token(scopes)?;

let config_with_token = TidalClientConfig {
    oauth_config: OAuthConfig {
        redirect_uri,
        client_id,
        client_secret: None
    }

    auth_token: Some(token)
}

let client_with_token =  TidalClient::new(config_with_token)?

let resp = client_with_token.tracks_api().get_track(<some track id>)?;

Documentation for API Endpoints

All URIs are relative to https://openapi.tidal.com/v2

Class Method HTTP request Description

AlbumsApi | create_album | POST /albums | Create single album. AlbumsApi | delete_album | DELETE /albums/{id} | Delete single album. AlbumsApi | get_album | GET /albums/{id} | Get single album. AlbumsApi | get_album_artists | GET /albums/{id}/relationships/artists | Get artists relationship ("to-many"). AlbumsApi | get_album_cover_art | GET /albums/{id}/relationships/coverArt | Get coverArt relationship ("to-many"). AlbumsApi | get_album_genres | GET /albums/{id}/relationships/genres | Get genres relationship ("to-many"). AlbumsApi | get_album_items | GET /albums/{id}/relationships/items | Get items relationship ("to-many"). AlbumsApi | get_album_owners | GET /albums/{id}/relationships/owners | Get owners relationship ("to-many"). AlbumsApi | get_album_providers | GET /albums/{id}/relationships/providers | Get providers relationship ("to-many"). AlbumsApi | get_album_replacement_replationship | GET /albums/{id}/relationships/replacement | Get replacement relationship ("to-one"). AlbumsApi | get_album_suggested_cover_arts | GET /albums/{id}/relationships/suggestedCoverArts | Get suggestedCoverArts relationship ("to-many"). AlbumsApi | get_albums | GET /albums | Get multiple albums. AlbumsApi | get_similar_albums | GET /albums/{id}/relationships/similarAlbums | Get similarAlbums relationship ("to-many"). AlbumsApi | patch_a_lbum_items | PATCH /albums/{id}/relationships/items | Update items relationship ("to-many"). AlbumsApi | patch_album | PATCH /albums/{id} | Update single album. AlbumsApi | patch_album_cover_art | PATCH /albums/{id}/relationships/coverArt | Update coverArt relationship ("to-many"). AppreciationsApi | create_appreciation | POST /appreciations | Create single appreciation. ArtistBiographiesApi | get_artist_biographies | GET /artistBiographies | Get multiple artistBiographies. ArtistBiographiesApi | get_artist_biography | GET /artistBiographies/{id} | Get single artistBiographie. ArtistBiographiesApi | get_artist_biography_owners | GET /artistBiographies/{id}/relationships/owners | Get owners relationship ("to-many"). ArtistBiographiesApi | patch_artist_biography | PATCH /artistBiographies/{id} | Update single artistBiographie. ArtistClaimsApi | create_artist_claim | POST /artistClaims | Create single artistClaim. ArtistClaimsApi | get_artist_claim | GET /artistClaims/{id} | Get single artistClaim. ArtistClaimsApi | get_artist_claim_accepted_artists | GET /artistClaims/{id}/relationships/acceptedArtists | Get acceptedArtists relationship ("to-many"). ArtistClaimsApi | get_artist_claim_owners | GET /artistClaims/{id}/relationships/owners | Get owners relationship ("to-many"). ArtistClaimsApi | get_artist_claim_recommended_artists | GET /artistClaims/{id}/relationships/recommendedArtists | Get recommendedArtists relationship ("to-many"). ArtistClaimsApi | patch_artist_claim | PATCH /artistClaims/{id} | Update single artistClaim. ArtistClaimsApi | update_artist_claim_accepted_artists | PATCH /artistClaims/{id}/relationships/acceptedArtists | Update acceptedArtists relationship ("to-many"). ArtistRolesApi | get_artist_role | GET /artistRoles/{id} | Get single artistRole. ArtistRolesApi | get_artist_roles | GET /artistRoles | Get multiple artistRoles. ArtistsApi | add_artist_followers | POST /artists/{id}/relationships/following | Add to following relationship ("to-many"). ArtistsApi | create_artist | POST /artists | Create single artist. ArtistsApi | delete_artist_followers | DELETE /artists/{id}/relationships/following | Delete from following relationship ("to-many"). ArtistsApi | get_artist | GET /artists/{id} | Get single artist. ArtistsApi | get_artist_albums | GET /artists/{id}/relationships/albums | Get albums relationship ("to-many"). ArtistsApi | get_artist_artist_biography | GET /artists/{id}/relationships/biography | Get biography relationship ("to-one"). ArtistsApi | get_artist_artist_roles | GET /artists/{id}/relationships/roles | Get roles relationship ("to-many"). ArtistsApi | get_artist_follower | GET /artists/{id}/relationships/following | Get following relationship ("to-many"). ArtistsApi | get_artist_followers | GET /artists/{id}/relationships/followers | Get followers relationship ("to-many"). ArtistsApi | get_artist_owners | GET /artists/{id}/relationships/owners | Get owners relationship ("to-many"). ArtistsApi | get_artist_profile_art | GET /artists/{id}/relationships/profileArt | Get profileArt relationship ("to-many"). ArtistsApi | get_artist_radio | GET /artists/{id}/relationships/radio | Get radio relationship ("to-many"). ArtistsApi | get_artist_similar_artists | GET /artists/{id}/relationships/similarArtists | Get similarArtists relationship ("to-many"). ArtistsApi | get_artist_track_providers | GET /artists/{id}/relationships/trackProviders | Get trackProviders relationship ("to-many"). ArtistsApi | get_artist_tracks | GET /artists/{id}/relationships/tracks | Get tracks relationship ("to-many"). ArtistsApi | get_artist_videos | GET /artists/{id}/relationships/videos | Get videos relationship ("to-many"). ArtistsApi | get_artists | GET /artists | Get multiple artists. ArtistsApi | patch_artist | PATCH /artists/{id} | Update single artist. ArtistsApi | patch_artist_profile_art | PATCH /artists/{id}/relationships/profileArt | Update profileArt relationship ("to-many"). ArtworksApi | create_artwork | POST /artworks | Create single artwork. ArtworksApi | get_artwork | GET /artworks/{id} | Get single artwork. ArtworksApi | get_artwork_owners | GET /artworks/{id}/relationships/owners | Get owners relationship ("to-many"). ArtworksApi | get_artworks | GET /artworks | Get multiple artworks. DynamicPagesApi | get_dynamic_page | GET /dynamicPages | Get multiple dynamicPages. DynamicPagesApi | get_dynamic_pages_subject | GET /dynamicPages/{id}/relationships/subject | Get subject relationship ("to-one"). GenresApi | get_genre | GET /genres/{id} | Get single genre. GenresApi | get_genres | GET /genres | Get multiple genres. LyricsApi | create_lyric | POST /lyrics | Create single lyric. LyricsApi | delete_lyric | DELETE /lyrics/{id} | Delete single lyric. LyricsApi | get_lyric | GET /lyrics/{id} | Get single lyric. LyricsApi | get_lyric_owners | GET /lyrics/{id}/relationships/owners | Get owners relationship ("to-many"). LyricsApi | get_lyric_track | GET /lyrics/{id}/relationships/track | Get track relationship ("to-one"). LyricsApi | get_lyrics | GET /lyrics | Get multiple lyrics. LyricsApi | patch_lyric | PATCH /lyrics/{id} | Update single lyric. ManualArtistClaimsApi | create_manual_artist_claim | POST /manualArtistClaims | Create single manualArtistClaim. PlayQueuesApi | create_future_play_queue | POST /playQueues/{id}/relationships/future | Add to future relationship ("to-many"). PlayQueuesApi | create_play_queue | POST /playQueues | Create single playQueue. PlayQueuesApi | delete_future_play_queues | DELETE /playQueues/{id}/relationships/future | Delete from future relationship ("to-many"). PlayQueuesApi | delete_play_queue | DELETE /playQueues/{id} | Delete single playQueue. PlayQueuesApi | get_current_play_queue | GET /playQueues/{id}/relationships/current | Get current relationship ("to-one"). PlayQueuesApi | get_future_play_queue | GET /playQueues/{id}/relationships/future | Get future relationship ("to-many"). PlayQueuesApi | get_past_play_queues | GET /playQueues/{id}/relationships/past | Get past relationship ("to-many"). PlayQueuesApi | get_play_queue | GET /playQueues/{id} | Get single playQueue. PlayQueuesApi | get_play_queue_owners | GET /playQueues/{id}/relationships/owners | Get owners relationship ("to-many"). PlayQueuesApi | get_play_queues | GET /playQueues | Get multiple playQueues. PlayQueuesApi | patch_current_play_queue | PATCH /playQueues/{id}/relationships/current | Update current relationship ("to-one"). PlayQueuesApi | patch_future_play_queue | PATCH /playQueues/{id}/relationships/future | Update future relationship ("to-many"). PlayQueuesApi | patch_play_queue | PATCH /playQueues/{id} | Update single playQueue. PlaylistsApi | add_items_to_playlist | POST /playlists/{id}/relationships/items | Add to items relationship ("to-many"). PlaylistsApi | create_playlist | POST /playlists | Create single playlist. PlaylistsApi | delete_playlist | DELETE /playlists/{id} | Delete single playlist. PlaylistsApi | delete_playlist_items | DELETE /playlists/{id}/relationships/items | Delete from items relationship ("to-many"). PlaylistsApi | get_playlist | GET /playlists/{id} | Get single playlist. PlaylistsApi | get_playlist_cover_art | GET /playlists/{id}/relationships/coverArt | Get coverArt relationship ("to-many"). PlaylistsApi | get_playlist_items | GET /playlists/{id}/relationships/items | Get items relationship ("to-many"). PlaylistsApi | get_playlist_owner_profiles | GET /playlists/{id}/relationships/ownerProfiles | Get ownerProfiles relationship ("to-many"). PlaylistsApi | get_playlist_owners | GET /playlists/{id}/relationships/owners | Get owners relationship ("to-many"). PlaylistsApi | get_playlists | GET /playlists | Get multiple playlists. PlaylistsApi | patch_playlist | PATCH /playlists/{id} | Update single playlist. PlaylistsApi | patch_playlist_cover_art | PATCH /playlists/{id}/relationships/coverArt | Update coverArt relationship ("to-many"). PlaylistsApi | patch_playlist_items | PATCH /playlists/{id}/relationships/items | Update items relationship ("to-many"). ProvidersApi | get_provider | GET /providers/{id} | Get single provider. ProvidersApi | get_providers | GET /providers | Get multiple providers. ReactionsApi | create_reaction | POST /reactions | Create single reaction. ReactionsApi | delete_reaction | DELETE /reactions/{id} | Delete single reaction. ReactionsApi | get_reaction_owner_profile | GET /reactions/{id}/relationships/ownerProfiles | Get ownerProfiles relationship ("to-many"). ReactionsApi | get_reactions | GET /reactions | Get multiple reactions. SavedSharesApi | create_saved_share | POST /savedShares | Create single savedShare. SearchResultsApi | get_search_result | GET /searchResults/{id} | Get single searchResult. SearchResultsApi | get_search_result_albums | GET /searchResults/{id}/relationships/albums | Get albums relationship ("to-many"). SearchResultsApi | get_search_result_artists | GET /searchResults/{id}/relationships/artists | Get artists relationship ("to-many"). SearchResultsApi | get_search_result_playlists | GET /searchResults/{id}/relationships/playlists | Get playlists relationship ("to-many"). SearchResultsApi | get_search_result_tracks | GET /searchResults/{id}/relationships/tracks | Get tracks relationship ("to-many"). SearchResultsApi | get_search_result_videos | GET /searchResults/{id}/relationships/videos | Get videos relationship ("to-many"). SearchResultsApi | get_search_results_top_hits | GET /searchResults/{id}/relationships/topHits | Get topHits relationship ("to-many"). SearchSuggestionsApi | get_search_suggestion | GET /searchSuggestions/{id} | Get single searchSuggestion. SearchSuggestionsApi | get_search_suggestion_direct_hits | GET /searchSuggestions/{id}/relationships/directHits | Get directHits relationship ("to-many"). SharesApi | create_share | POST /shares | Create single share. SharesApi | get_share | GET /shares/{id} | Get single share. SharesApi | get_share_owners | GET /shares/{id}/relationships/owners | Get owners relationship ("to-many"). SharesApi | get_share_shared_resources | GET /shares/{id}/relationships/sharedResources | Get sharedResources relationship ("to-many"). SharesApi | get_shares | GET /shares | Get multiple shares. StripeConnectionsApi | create_stripe_connection | POST /stripeConnections | Create single stripeConnection. StripeConnectionsApi | get_stripe_connection_owners | GET /stripeConnections/{id}/relationships/owners | Get owners relationship ("to-many"). StripeConnectionsApi | get_stripe_connections | GET /stripeConnections | Get multiple stripeConnections. TrackFilesApi | get_track_file | GET /trackFiles/{id} | Get single trackFile. TrackManifestsApi | get_track_manifest | GET /trackManifests/{id} | Get single trackManifest. TrackSourceFilesApi | create_track_source_file | POST /trackSourceFiles | Create single trackSourceFile. TrackSourceFilesApi | get_track_source_file | GET /trackSourceFiles/{id} | Get single trackSourceFile. TrackSourceFilesApi | get_track_source_file_owners | GET /trackSourceFiles/{id}/relationships/owners | Get owners relationship ("to-many"). TrackSourceFilesApi | get_track_source_files | GET /trackSourceFiles | Get multiple trackSourceFiles. TrackStatisticsApi | get_track_statistic | GET /trackStatistics/{id} | Get single trackStatistic. TrackStatisticsApi | get_track_statistic_owners | GET /trackStatistics/{id}/relationships/owners | Get owners relationship ("to-many"). TrackStatisticsApi | get_track_statistics | GET /trackStatistics | Get multiple trackStatistics. TracksApi | create_track | POST /tracks | Create single track. TracksApi | delete_track | DELETE /tracks/{id} | Delete single track. TracksApi | get_track | GET /tracks/{id} | Get single track. TracksApi | get_track_albums | GET /tracks/{id}/relationships/albums | Get albums relationship ("to-many"). TracksApi | get_track_genres | GET /tracks/{id}/relationships/genres | Get genres relationship ("to-many"). TracksApi | get_track_lyrics | GET /tracks/{id}/relationships/lyrics | Get lyrics relationship ("to-many"). TracksApi | get_track_owners | GET /tracks/{id}/relationships/owners | Get owners relationship ("to-many"). TracksApi | get_track_providers | GET /tracks/{id}/relationships/providers | Get providers relationship ("to-many"). TracksApi | get_track_radio | GET /tracks/{id}/relationships/radio | Get radio relationship ("to-many"). TracksApi | get_track_replacement_relationship | GET /tracks/{id}/relationships/replacement | Get replacement relationship ("to-one"). TracksApi | get_track_shares | GET /tracks/{id}/relationships/shares | Get shares relationship ("to-many"). TracksApi | get_track_similar_tracks | GET /tracks/{id}/relationships/similarTracks | Get similarTracks relationship ("to-many"). TracksApi | get_track_track_source_file | GET /tracks/{id}/relationships/sourceFile | Get sourceFile relationship ("to-one"). TracksApi | get_track_track_statistics | GET /tracks/{id}/relationships/trackStatistics | Get trackStatistics relationship ("to-one"). TracksApi | get_tracks | GET /tracks | Get multiple tracks. TracksApi | patch_track | PATCH /tracks/{id} | Update single track. TracksApi | patch_track_albums | PATCH /tracks/{id}/relationships/albums | Update albums relationship ("to-many"). TracksApi | patch_track_artists | GET /tracks/{id}/relationships/artists | Get artists relationship ("to-many"). UserCollectionFoldersApi | add_user_collection_folder_items | POST /userCollectionFolders/{id}/relationships/items | Add to items relationship ("to-many"). UserCollectionFoldersApi | create_user_collection_folder | POST /userCollectionFolders | Create single userCollectionFolder. UserCollectionFoldersApi | delete_user_collection_folder | DELETE /userCollectionFolders/{id} | Delete single userCollectionFolder. UserCollectionFoldersApi | delete_user_collection_folder_items | DELETE /userCollectionFolders/{id}/relationships/items | Delete from items relationship ("to-many"). UserCollectionFoldersApi | get_user_collection_folder | GET /userCollectionFolders/{id} | Get single userCollectionFolder. UserCollectionFoldersApi | get_user_collection_folder_items | GET /userCollectionFolders/{id}/relationships/items | Get items relationship ("to-many"). UserCollectionFoldersApi | get_user_collection_folder_owners | GET /userCollectionFolders/{id}/relationships/owners | Get owners relationship ("to-many"). UserCollectionFoldersApi | get_user_collection_folders | GET /userCollectionFolders | Get multiple userCollectionFolders. UserCollectionFoldersApi | patch_user_collection_folder | PATCH /userCollectionFolders/{id} | Update single userCollectionFolder. UserCollectionsApi | add_user_collection_albums | POST /userCollections/{id}/relationships/albums | Add to albums relationship ("to-many"). UserCollectionsApi | add_user_collection_artists | POST /userCollections/{id}/relationships/artists | Add to artists relationship ("to-many"). UserCollectionsApi | add_user_collection_playlists | POST /userCollections/{id}/relationships/playlists | Add to playlists relationship ("to-many"). UserCollectionsApi | add_user_collection_tracks | POST /userCollections/{id}/relationships/tracks | Add to tracks relationship ("to-many"). UserCollectionsApi | add_user_collection_videos | POST /userCollections/{id}/relationships/videos | Add to videos relationship ("to-many"). UserCollectionsApi | delete_user_collection_albums | DELETE /userCollections/{id}/relationships/albums | Delete from albums relationship ("to-many"). UserCollectionsApi | delete_user_collection_artists | DELETE /userCollections/{id}/relationships/artists | Delete from artists relationship ("to-many"). UserCollectionsApi | delete_user_collection_tracks | DELETE /userCollections/{id}/relationships/tracks | Delete from tracks relationship ("to-many"). UserCollectionsApi | delete_user_collection_videos | DELETE /userCollections/{id}/relationships/videos | Delete from videos relationship ("to-many"). UserCollectionsApi | deleteuser_collection_playlists | DELETE /userCollections/{id}/relationships/playlists | Delete from playlists relationship ("to-many"). UserCollectionsApi | get_user_collection | GET /userCollections/{id} | Get single userCollection. UserCollectionsApi | get_user_collection_albums | GET /userCollections/{id}/relationships/albums | Get albums relationship ("to-many"). UserCollectionsApi | get_user_collection_artists | GET /userCollections/{id}/relationships/artists | Get artists relationship ("to-many"). UserCollectionsApi | get_user_collection_owners | GET /userCollections/{id}/relationships/owners | Get owners relationship ("to-many"). UserCollectionsApi | get_user_collection_playlists | GET /userCollections/{id}/relationships/playlists | Get playlists relationship ("to-many"). UserCollectionsApi | get_user_collection_tracks | GET /userCollections/{id}/relationships/tracks | Get tracks relationship ("to-many"). UserCollectionsApi | get_user_collection_videos | GET /userCollections/{id}/relationships/videos | Get videos relationship ("to-many"). UserEntitlementsApi | get_user_entitlement | GET /userEntitlements/{id} | Get single userEntitlement. UserEntitlementsApi | get_user_entitlement_owners | GET /userEntitlements/{id}/relationships/owners | Get owners relationship ("to-many"). UserRecommendationsApi | get_user_recommendation | GET /userRecommendations/{id} | Get single userRecommendation. UserRecommendationsApi | get_user_recommendation_discovery_mixes | GET /userRecommendations/{id}/relationships/discoveryMixes | Get discoveryMixes relationship ("to-many"). UserRecommendationsApi | get_user_recommendation_my_mixes | GET /userRecommendations/{id}/relationships/myMixes | Get myMixes relationship ("to-many"). UserRecommendationsApi | get_user_recommendation_new_arrival_mixes | GET /userRecommendations/{id}/relationships/newArrivalMixes | Get newArrivalMixes relationship ("to-many"). UserReportsApi | create_user_report | POST /userReports | Create single userReport. UsersApi | get_me | GET /users/me | Get current user's user. VideosApi | get_video | GET /videos/{id} | Get single video. VideosApi | get_video_albums | GET /videos/{id}/relationships/albums | Get albums relationship ("to-many"). VideosApi | get_video_artists | GET /videos/{id}/relationships/artists | Get artists relationship ("to-many"). VideosApi | get_video_providers | GET /videos/{id}/relationships/providers | Get providers relationship ("to-many"). VideosApi | get_video_replacement_relationship | GET /videos/{id}/relationships/replacement | Get replacement relationship ("to-one"). VideosApi | get_video_thumbnail_art | GET /videos/{id}/relationships/thumbnailArt | Get thumbnailArt relationship ("to-many"). VideosApi | get_videos | GET /videos | Get multiple videos.

Documentation For Models

To get access to the crate's generated documentation, use:

cargo doc --open

Author

Commit count: 16

cargo fmt