5 releases

0.1.0	Jan 30, 2026
0.0.4	Jan 30, 2026
0.0.3	Jan 25, 2026
0.0.2	Jan 24, 2026
0.0.1	Jan 24, 2026

#57 in Video

MIT license

1.5MB
31K SLoC

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

Dependencies

~8–23MB
~277K SLoC