qobuz_api_rust/lib.rs
1/// # Qobuz API Rust Client
2///
3/// A comprehensive Rust client library for interacting with the Qobuz music streaming API.
4/// This library provides functionality for authentication, content retrieval, favorites management,
5/// and metadata handling for Qobuz music content.
6///
7/// ## Features
8///
9/// - **API Access**: Full access to Qobuz API endpoints for albums, artists, tracks, playlists, and more
10/// - **Authentication**: Support for both user-based and token-based authentication
11/// - **Content Management**: Search, retrieve, and manage Qobuz content including albums, tracks, and playlists
12/// - **Metadata Handling**: Extract and embed comprehensive metadata in audio files
13/// - **Download Support**: Download tracks and albums with various quality options
14/// - **Format Support**: Support for various audio formats including FLAC and MP3 with different quality levels
15///
16/// ## Getting Started
17///
18/// To use this library, you'll need to initialize the [QobuzApiService] which handles API communication
19/// and authentication. The service can automatically fetch application credentials from the Qobuz
20/// web player or use custom credentials.
21///
22/// ```no_run
23/// use qobuz_api_rust::QobuzApiService;
24///
25/// #[tokio::main]
26/// async fn main() -> Result<(), qobuz_api_rust::QobuzApiError> {
27/// // Initialize the service with automatic credential fetching
28/// let mut service = QobuzApiService::new().await?;
29///
30/// // Authenticate using environment variables
31/// service.authenticate_with_env().await?;
32///
33/// // Search for content
34/// let search_results = service.search_albums("Miles Davis", Some(10), None, None).await?;
35///
36/// Ok(())
37/// }
38/// ```
39///
40/// ## Authentication
41///
42/// The library supports multiple authentication methods:
43/// - Token-based authentication using user ID and auth token
44/// - Email/password authentication
45/// - Username/password authentication
46///
47/// Set the appropriate environment variables in your `.env` file:
48/// - For token-based: `QOBUZ_USER_ID` and `QOBUZ_USER_AUTH_TOKEN`
49/// - For email-based: `QOBUZ_EMAIL` and `QOBUZ_PASSWORD`
50/// - For username-based: `QOBUZ_USERNAME` and `QOBUZ_PASSWORD`
51///
52/// ## Modules
53///
54/// - [api](api/index.html): Core API functionality and service implementation
55/// - [errors](errors/index.html): Custom error types for the library
56/// - [metadata](metadata/index.html): Metadata extraction and embedding utilities
57/// - [models](models/index.html): Data models for API responses
58/// - [utils](utils/index.html): Utility functions for common operations
59///
60/// ## License
61///
62/// This library is distributed under the GPL-3.0-or-later license.
63pub mod api;
64/// Error types for the Qobuz API Rust library.
65///
66/// This module defines custom error types that can occur when using the Qobuz API library.
67/// It includes errors from API responses, network operations, parsing, and authentication.
68/// All errors implement the `Error` trait and provide detailed error information for
69/// proper error handling throughout the library.
70pub mod errors;
71/// Metadata handling utilities for audio files.
72///
73/// This module provides functionality for extracting and embedding metadata in audio files.
74/// It includes utilities for working with various audio formats (FLAC, MP3, etc.) and
75/// handling comprehensive metadata including artist information, album details, track data,
76/// and cover art.
77pub mod metadata {
78 /// Module for embedding metadata into audio files.
79 ///
80 /// This module provides functionality to embed comprehensive metadata into audio files.
81 /// It handles different audio formats with format-specific tagging approaches to ensure
82 /// compatibility and consistency. The embedder can handle various metadata fields
83 /// including track titles, artist information, album details, release dates, and cover art.
84 pub mod embedder;
85 /// Module for extracting metadata from Qobuz API responses.
86 ///
87 /// This module provides functionality to extract comprehensive metadata from Qobuz API
88 /// response objects into a standardized key-value format. The extracted metadata can
89 /// be used for various purposes such as embedding in audio files, displaying in
90 /// applications, or processing in audio workflows.
91 pub mod extractor;
92}
93/// Data models for Qobuz API responses.
94///
95/// This module contains all the data structures used to represent Qobuz API responses.
96/// These models are used for deserializing JSON responses from the API into Rust structs.
97/// The models cover all major Qobuz content types including albums, artists, tracks,
98/// playlists, users, and various metadata fields.
99pub mod models;
100/// Utility functions for the Qobuz API Rust library.
101///
102/// This module provides various utility functions used throughout the library including
103/// MD5 hashing, query string building, timestamp generation, credential management,
104/// filename sanitization, and HTTP response handling. These utilities support the core
105/// API functionality and provide common operations needed for working with the Qobuz API.
106pub mod utils;
107
108/// Re-exports of commonly used types and functions for convenience.
109///
110/// This section re-exports the most important types and functions from the library
111/// to provide a convenient and streamlined API for users. These re-exports allow
112/// direct access to the core functionality without having to specify full module paths.
113pub use {
114 api::service::QobuzApiService, // The main Qobuz API service struct that provides access to all API functionality.
115 errors::QobuzApiError, // The main error type for the library that encompasses all possible errors.
116 metadata::{embedder::embed_metadata_in_file, extractor::extract_comprehensive_metadata}, // Functions to embed and extract metadata in audio files using extracted Qobuz data.
117 utils::download_image, // Utility function to download images from URLs.
118};