Gestion des évènements d'écoute sur le cache.

pmoaudiocache/src/metadata_ext.rs

@@ -11,6 +11,9 @@ use std::sync::Arc;
 use tokio::sync::RwLock;
 
 /// Fournit un accès direct à une implémentation `TrackMetadata` basée sur le cache.
+///
+/// Utilise `AudioCacheTrackMetadata` comme backend, ce qui garantit que toutes
+/// les lectures/écritures passent par la DB `pmocache` sans recharger le FLAC.
 pub trait AudioTrackMetadataExt {
     fn track_metadata(&self, pk: impl Into<String>) -> Arc<RwLock<dyn TrackMetadata>>;
 }
@@ -27,6 +30,8 @@ impl AudioTrackMetadataExt for Arc<pmocache::Cache<AudioConfig>> {
 /// Cette version remplace l'ancienne macro `define_metadata_properties!` qui
 /// accédait directement aux clés de la DB. Les méthodes restent asynchrones et
 /// retournent `Option` ; en cas d'erreur backend, elles lèvent `anyhow::Error`.
+/// Utile dans les handlers HTTP ou les services qui n'ont besoin que de quelques
+/// champs sans manipuler explicitement un `TrackMetadata`.
 pub trait AudioMetadataExt {
     async fn get_title(&self, pk: &str) -> anyhow::Result<Option<String>>;
     async fn get_artist(&self, pk: &str) -> anyhow::Result<Option<String>>;

pmoaudiocache/src/openapi.rs

@@ -8,6 +8,13 @@ use utoipa::OpenApi;
 #[derive(OpenApi)]
 #[openapi(
     paths(
+        pmocache::api::list_items::<crate::cache::AudioConfig>,
+        pmocache::api::get_item_info::<crate::cache::AudioConfig>,
+        pmocache::api::get_download_status::<crate::cache::AudioConfig>,
+        pmocache::api::add_item::<crate::cache::AudioConfig>,
+        pmocache::api::delete_item::<crate::cache::AudioConfig>,
+        pmocache::api::purge_cache::<crate::cache::AudioConfig>,
+        pmocache::api::consolidate_cache::<crate::cache::AudioConfig>,
         crate::api::get_cover_url,
     ),
     components(

pmoaudiocache/src/streaming.rs

@@ -12,7 +12,16 @@ use pmoflac::{transcode_to_flac_stream, AudioCodec, TranscodeOptions};
 use serde_json::json;
 use tokio::io::{AsyncReadExt, AsyncWriteExt};
 
-/// Creates the transformer consumed by the audio cache.
+/// Crée le `StreamTransformer` utilisé par le cache audio.
+///
+/// - Accepte n'importe quel codec pris en charge par `pmoflac` (FLAC, MP3, OGG/Vorbis,
+///   Opus, WAV, AIFF).
+/// - Convertit en FLAC en streaming (passthrough si entrée FLAC) et écrit dans le
+///   fichier fourni par `pmocache`.
+/// - Renseigne `TransformMetadata` (codec source, mode, SR, BPS, canaux, total_samples)
+///   pour que `pmocache` puisse les stocker en DB.
+///
+/// À utiliser comme factory dans `Cache::with_transformer`.
 pub fn create_streaming_flac_transformer() -> StreamTransformer {
     Box::new(|input, mut file, context| {
         Box::pin(async move {

pmoaudiocache/src/track_metadata.rs

@@ -8,12 +8,25 @@ fn map_db_err(err: rusqlite::Error) -> MetadataError {
     MetadataError::Backend(err.to_string())
 }
 
+/// Implémentation `TrackMetadata` adossée au cache audio.
+///
+/// Cette couche lit/écrit directement dans la table `metadata` de `pmocache`
+/// pour un `pk` donné. Elle se comporte comme une façade `TrackMetadata`
+/// classique mais repose sur la DB du cache plutôt que sur un fichier taggé,
+/// ce qui permet :
+/// - d'exposer les métadonnées immédiatement après ingestion/transform ;
+/// - de servir des lecteurs UPnP/DLNA sans relire le FLAC sur disque ;
+/// - de persister les mises à jour d'un client (ex: renommer un titre).
 pub struct AudioCacheTrackMetadata {
     cache: Arc<crate::Cache>,
     pk: String,
 }
 
 impl AudioCacheTrackMetadata {
+    /// Construit un adaptateur `TrackMetadata` pour un `pk` du cache audio.
+    ///
+    /// Le type implémente ensuite toutes les méthodes du trait `pmometadata::TrackMetadata`
+    /// en stockant les données dans la base SQLite de `pmocache`.
     pub fn new(cache: Arc<crate::Cache>, pk: impl Into<String>) -> Self {
         Self {
             cache,