245 lines
7.3 KiB
Rust
245 lines
7.3 KiB
Rust
//! # pmoqobuz - Client Qobuz pour PMOMusic
|
|
//!
|
|
//! Cette crate fournit un client Rust pour l'API Qobuz, inspiré de l'implémentation Python d'upmpdcli,
|
|
//! avec un système de cache en mémoire et une intégration avec les autres modules PMOMusic.
|
|
//!
|
|
//! ## Vue d'ensemble
|
|
//!
|
|
//! `pmoqobuz` permet d'accéder aux fonctionnalités de Qobuz :
|
|
//! - Authentification avec les credentials configurés
|
|
//! - Navigation dans le catalogue (albums, artistes, playlists, tracks)
|
|
//! - Recherche dans le catalogue
|
|
//! - Accès aux favoris de l'utilisateur
|
|
//! - Cache en mémoire pour minimiser les requêtes API
|
|
//! - Export des objets en format DIDL-Lite (via `pmodidl`)
|
|
//! - Cache des images d'albums (via `pmocovers`)
|
|
//!
|
|
//! ## Architecture
|
|
//!
|
|
//! La crate suit le pattern d'extension des autres crates PMO :
|
|
//! - `QobuzClient` : Client principal avec authentification et cache
|
|
//! - `models` : Structures de données (Album, Track, Artist, etc.)
|
|
//! - `api` : Couche d'accès à l'API REST Qobuz
|
|
//! - `cache` : Système de cache en mémoire avec TTL
|
|
//! - `didl` : Export des objets en format DIDL-Lite
|
|
//!
|
|
//! ## Structure des modules
|
|
//!
|
|
//! ```text
|
|
//! pmoqobuz/
|
|
//! ├── src/
|
|
//! │ ├── lib.rs # Module principal (ce fichier)
|
|
//! │ ├── client.rs # Client Qobuz principal
|
|
//! │ ├── models.rs # Structures de données
|
|
//! │ ├── api/
|
|
//! │ │ ├── mod.rs # API client
|
|
//! │ │ ├── auth.rs # Authentification
|
|
//! │ │ ├── catalog.rs # Accès au catalogue
|
|
//! │ │ └── user.rs # API utilisateur (favoris)
|
|
//! │ ├── cache.rs # Cache en mémoire
|
|
//! │ ├── didl.rs # Export DIDL-Lite
|
|
//! │ └── error.rs # Gestion des erreurs
|
|
//! ```
|
|
//!
|
|
//! ## Utilisation
|
|
//!
|
|
//! ### Exemple basique avec configuration automatique
|
|
//!
|
|
//! ```rust,no_run
|
|
//! use pmoqobuz::QobuzClient;
|
|
//!
|
|
//! #[tokio::main]
|
|
//! async fn main() -> anyhow::Result<()> {
|
|
//! // Utilise automatiquement la config depuis pmoconfig
|
|
//! let client = QobuzClient::from_config().await?;
|
|
//!
|
|
//! // Rechercher des albums
|
|
//! let results = client.search_albums("Miles Davis").await?;
|
|
//! for album in results {
|
|
//! println!("{} - {}", album.artist.name, album.title);
|
|
//! }
|
|
//!
|
|
//! Ok(())
|
|
//! }
|
|
//! ```
|
|
//!
|
|
//! ### Exemple avec credentials personnalisés
|
|
//!
|
|
//! ```rust,no_run
|
|
//! use pmoqobuz::QobuzClient;
|
|
//!
|
|
//! #[tokio::main]
|
|
//! async fn main() -> anyhow::Result<()> {
|
|
//! let client = QobuzClient::new("user@example.com", "password").await?;
|
|
//!
|
|
//! // Obtenir les albums favoris
|
|
//! let favorites = client.get_favorite_albums().await?;
|
|
//!
|
|
//! Ok(())
|
|
//! }
|
|
//! ```
|
|
//!
|
|
//! ### Export DIDL-Lite
|
|
//!
|
|
//! ```rust,no_run
|
|
//! use pmoqobuz::QobuzClient;
|
|
//!
|
|
//! #[tokio::main]
|
|
//! async fn main() -> anyhow::Result<()> {
|
|
//! let client = QobuzClient::from_config().await?;
|
|
//!
|
|
//! let album = client.get_album("12345").await?;
|
|
//! let didl_container = album.to_didl_container("parent_id")?;
|
|
//!
|
|
//! Ok(())
|
|
//! }
|
|
//! ```
|
|
//!
|
|
//! ## Cache
|
|
//!
|
|
//! Le client utilise un cache en mémoire avec TTL pour minimiser les requêtes à l'API Qobuz :
|
|
//! - Albums : 1 heure
|
|
//! - Tracks : 1 heure
|
|
//! - Artistes : 1 heure
|
|
//! - Playlists : 30 minutes
|
|
//! - Résultats de recherche : 15 minutes
|
|
//! - URLs de streaming : 5 minutes
|
|
//!
|
|
//! ## Intégration pmocovers et pmoaudiocache
|
|
//!
|
|
//! La feature `cache` active le support complet du cache pour les images et l'audio.
|
|
//!
|
|
//! ### Cache d'images (pmocovers)
|
|
//!
|
|
//! Les images de couverture sont automatiquement téléchargées et converties en WebP :
|
|
//!
|
|
//! ```rust,no_run
|
|
//! use pmoqobuz::{QobuzSource, QobuzClient};
|
|
//! use pmocovers::Cache as CoverCache;
|
|
//! use std::sync::Arc;
|
|
//!
|
|
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
|
|
//! let client = QobuzClient::from_config().await?;
|
|
//! let cover_cache = Arc::new(CoverCache::new("./cache/covers", 500)?);
|
|
//!
|
|
//! let source = QobuzSource::new_with_cache(
|
|
//! client,
|
|
//! "http://localhost:8080",
|
|
//! Some(cover_cache),
|
|
//! None,
|
|
//! );
|
|
//! # Ok(())
|
|
//! # }
|
|
//! ```
|
|
//!
|
|
//! ### Cache audio (pmoaudiocache)
|
|
//!
|
|
//! L'audio haute résolution est téléchargé et caché localement avec métadonnées enrichies :
|
|
//!
|
|
//! ```rust,no_run
|
|
//! use pmoqobuz::{QobuzSource, QobuzClient};
|
|
//! use pmocovers::Cache as CoverCache;
|
|
//! use pmoaudiocache::AudioCache;
|
|
//! use std::sync::Arc;
|
|
//!
|
|
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
|
|
//! let client = QobuzClient::from_config().await?;
|
|
//! let cover_cache = Arc::new(CoverCache::new("./cache/covers", 500)?);
|
|
//! let audio_cache = Arc::new(AudioCache::new("./cache/audio", 100)?);
|
|
//!
|
|
//! let source = QobuzSource::new_with_cache(
|
|
//! client.clone(),
|
|
//! "http://localhost:8080",
|
|
//! Some(cover_cache),
|
|
//! Some(audio_cache),
|
|
//! );
|
|
//!
|
|
//! // Add a track with caching
|
|
//! let tracks = client.get_favorite_tracks().await?;
|
|
//! if let Some(track) = tracks.first() {
|
|
//! let track_id = source.add_track(track).await?;
|
|
//! // Audio and cover are now cached with rich metadata
|
|
//!
|
|
//! // Resolve URI (returns cached version if available)
|
|
//! let uri = source.resolve_uri(&track_id).await?;
|
|
//! }
|
|
//! # Ok(())
|
|
//! # }
|
|
//! ```
|
|
//!
|
|
//! ### Métadonnées enrichies
|
|
//!
|
|
//! Qobuz fournit des métadonnées détaillées qui sont préservées dans le cache :
|
|
//! - Titre, artiste, album
|
|
//! - Numéro de piste et de disque
|
|
//! - Année de sortie
|
|
//! - Genre(s)
|
|
//! - Label
|
|
//! - Qualité audio (sample rate, bit depth, channels)
|
|
//! - Durée
|
|
//!
|
|
//! ### Exemple complet
|
|
//!
|
|
//! Voir `examples/with_cache.rs` pour un exemple complet d'utilisation avec cache.
|
|
//!
|
|
//! ## Formats audio supportés
|
|
//!
|
|
//! Qobuz propose plusieurs formats :
|
|
//! - Format 5 : MP3 320 kbps
|
|
//! - Format 6 : FLAC 16 bit / 44.1 kHz (CD Quality)
|
|
//! - Format 7 : FLAC 24 bit / jusqu'à 96 kHz (Hi-Res)
|
|
//! - Format 27 : FLAC 24 bit / jusqu'à 192 kHz (Hi-Res+)
|
|
//!
|
|
//! ## Gestion des erreurs
|
|
//!
|
|
//! La crate utilise `thiserror` pour définir des erreurs typées :
|
|
//!
|
|
//! ```rust,ignore
|
|
//! use pmoqobuz::{QobuzClient, QobuzError};
|
|
//!
|
|
//! match client.get_album("invalid").await {
|
|
//! Ok(album) => println!("Album: {}", album.title),
|
|
//! Err(QobuzError::NotFound) => println!("Album not found"),
|
|
//! Err(QobuzError::Unauthorized) => println!("Authentication failed"),
|
|
//! Err(e) => println!("Error: {}", e),
|
|
//! }
|
|
//! ```
|
|
//!
|
|
//! ## Voir aussi
|
|
//!
|
|
//! - [`pmodidl`] : Format DIDL-Lite
|
|
//! - [`pmocovers`] : Cache d'images
|
|
//! - [`pmoaudiocache`] : Cache audio
|
|
//! - [`pmoconfig`] : Configuration
|
|
//! - [`pmoserver`] : Serveur HTTP
|
|
|
|
pub mod api;
|
|
pub mod cache;
|
|
pub mod client;
|
|
pub mod didl;
|
|
pub mod error;
|
|
pub mod models;
|
|
pub mod source;
|
|
|
|
// Extension pmoserver (feature-gated)
|
|
#[cfg(feature = "pmoserver")]
|
|
pub mod api_rest;
|
|
|
|
#[cfg(feature = "pmoserver")]
|
|
pub mod pmoserver_ext;
|
|
|
|
#[cfg(feature = "pmoserver")]
|
|
mod pmoserver_impl;
|
|
|
|
pub use client::QobuzClient;
|
|
pub use error::{QobuzError, Result};
|
|
pub use models::{Album, Artist, AudioFormat, Genre, Playlist, SearchResult, Track};
|
|
pub use source::QobuzSource;
|
|
|
|
/// Ré-exporte les types DIDL pour faciliter l'utilisation
|
|
pub use didl::ToDIDL;
|
|
|
|
/// Ré-exporte le trait d'extension pmoserver
|
|
#[cfg(feature = "pmoserver")]
|
|
pub use pmoserver_ext::QobuzServerExt;
|