tidalv2
A Rust client library for TIDAL's v2 JSON:API.
This library provides type-safe, async access to TIDAL's music catalog and user data through their v2 API. The models and API clients are generated from TIDAL's OpenAPI specification, with hand-written client utilities for authentication and configuration.
Note: For TIDAL's v1 API, see tidalrs.
Features
- JSON:API Support: Full support for TIDAL's JSON:API v2 endpoints
- Type-Safe Models: Strongly-typed data models generated from OpenAPI spec
- Async/Await: Built on
reqwestandtokiofor async operations - OAuth2 Authentication: Device-code, PKCE, client-credentials, and direct access-token flows, plus optional
tidalrsinteroperability - Comprehensive API Coverage:
- Albums, artists, tracks, videos
- Playlists and user collections
- Search and recommendations
- Track manifests and streaming
- User management
Installation
Add this to your Cargo.toml:
[]
= "0.3"
All default functionality is available without optional features. To create a
v2 client from an existing tidalrs
client, enable the tidalrs feature:
[]
= { = "0.3", = ["tidalrs"] }
= "0.5"
Usage
Basic Setup
use TidalClient;
async
Searching for Content
use ResourceType;
let search_result = client
.search_result_get
.await?;
Getting Album Details
let album = client
.album_get
.await?;
println!;
Managing User Collections
let user_id = "user_id_here";
// Get user's playlists
let playlists = client
.user_collection_playlists
.await?;
// Get user's favorite albums
let albums = client
.user_collection_albums
.await?;
Authentication
Credentials are always caller-supplied. The same Bearer token is used for all API calls, including HiRes streaming. HiRes availability depends on the OAuth client that issued the token, not on a separate streaming credential.
Device-code flow
use TidalClient;
# async
You can still complete the flow yourself by polling authorize(device_code, client_secret) after the user approves.
PKCE flow (HiRes-capable clients)
Use a client ID that TIDAL associates with HiRes playback, and the matching
redirect URI (the Android app uses https://tidal.com/android/login/auth).
Official developer-portal clients may not unlock HiRes.
use TidalClient;
# async
Client-credentials flow
use TidalClient;
# async
Direct access token
use ;
// Token only — no automatic refresh
let client = new
.with_access_token;
// Persisted user session with refresh
let authz = new;
let client = new.with_authz;
With the tidalrs feature enabled, an existing tidalrs::TidalClient can
create a v2 client with the same HTTP client, country code, and current
authorization credentials:
use TidalClient as TidalV1Client;
use TidalV2ClientExt;
let client_id = "your_client_id";
let v1_client = new;
// Authenticate using device flow
let device_auth = v1_client.device_authorization.await?;
println!;
println!;
// After the user completes authorization, poll as described in the tidalrs docs.
v1_client
.authorize
.await?;
let v2_client = v1_client.tidalv2_client;
let album = v2_client.album_get.await?;
The two clients own separate copies of the authorization state after conversion. Use the same client ID for both so the v2 client can refresh its copy of the credentials.
API Documentation
The library follows TIDAL's JSON:API specification. All response types implement the JSON:API resource structure with:
data: The primary resource(s)attributes: Resource propertiesrelationships: Related resourcesincluded: Embedded related resources
Requirements
- Rust 1.70+
- Rust 1.85+ when the optional
tidalrsfeature is enabled - Valid TIDAL API client credentials
- For streaming features, appropriate TIDAL subscription
Testing
The library includes comprehensive integration tests that validate API parsing and resource walking. Tests require TIDAL API credentials:
Contributing
Contributions are welcome! Please note:
- Models and API clients in
src/models/andsrc/apis/are OpenAPI-generated - Hand-written code is in
src/client.rs,src/auth.rs,src/error.rs, andsrc/tidalrs.rs - Tests use real TIDAL API endpoints and require credentials
License
This project is licensed under the Unlicense - see the LICENSE file for details.
Disclaimer
This library is not officially affiliated with TIDAL. Use at your own risk and ensure compliance with TIDAL's Terms of Service.