126 lines
3.6 KiB
Rust
126 lines
3.6 KiB
Rust
//! Documentation OpenAPI pour l'API du cache audio
|
|
|
|
use utoipa::OpenApi;
|
|
|
|
/// Documentation OpenAPI pour l'API PMOMusic Audio Cache
|
|
///
|
|
/// L'API réutilise les handlers génériques de pmocache.
|
|
#[derive(OpenApi)]
|
|
#[openapi(
|
|
components(
|
|
schemas(
|
|
pmocache::CacheEntry,
|
|
pmocache::api::AddItemRequest,
|
|
pmocache::api::AddItemResponse,
|
|
pmocache::api::DeleteItemResponse,
|
|
pmocache::api::ErrorResponse,
|
|
pmocache::api::DownloadStatus,
|
|
)
|
|
),
|
|
tags(
|
|
(name = "audio", description = "Gestion du cache de pistes audio")
|
|
),
|
|
info(
|
|
title = "PMOMusic Audio Cache API",
|
|
version = "0.1.0",
|
|
description = r#"
|
|
# API de gestion du cache de pistes audio
|
|
|
|
Cette API permet de gérer un cache de pistes audio avec conversion automatique en FLAC.
|
|
|
|
## Fonctionnalités
|
|
|
|
- **Ajout de pistes** : Téléchargement depuis une URL avec conversion automatique en FLAC
|
|
- **Métadonnées** : Extraction et stockage automatique des métadonnées audio en JSON
|
|
- **Collections** : Organisation par artiste/album
|
|
- **Consultation** : Liste des pistes avec statistiques d'utilisation
|
|
- **Suppression** : Suppression individuelle ou purge complète
|
|
- **Maintenance** : Consolidation du cache pour réparer les incohérences
|
|
- **Statut** : Suivi des téléchargements et conversions en cours
|
|
- **Streaming progressif** : Les fichiers sont streamés dès qu'ils sont disponibles
|
|
|
|
## Endpoints principaux
|
|
|
|
### GET /api/audio
|
|
Liste toutes les pistes en cache avec leurs statistiques
|
|
|
|
### POST /api/audio
|
|
Ajoute une piste depuis une URL (conversion FLAC automatique)
|
|
|
|
### GET /api/audio/{pk}
|
|
Récupère les informations complètes d'une piste (avec metadata_json)
|
|
|
|
### DELETE /api/audio/{pk}
|
|
Supprime une piste
|
|
|
|
### GET /api/audio/{pk}/status
|
|
Récupère le statut du téléchargement et de la conversion
|
|
|
|
### DELETE /api/audio
|
|
Purge complètement le cache
|
|
|
|
### POST /api/audio/consolidate
|
|
Consolide le cache (répare les incohérences)
|
|
|
|
## Servir les fichiers
|
|
|
|
### GET /audio/flac/{pk}
|
|
Récupère le fichier FLAC (streaming progressif si en cours de téléchargement)
|
|
|
|
### GET /audio/flac/{pk}/orig
|
|
Alias pour le fichier original
|
|
|
|
## Format des fichiers
|
|
|
|
Les pistes sont stockées au format FLAC avec :
|
|
- Une version convertie (`{pk}.orig.flac`)
|
|
- Métadonnées stockées en JSON dans la base de données
|
|
|
|
## Métadonnées
|
|
|
|
Les métadonnées suivantes sont extraites et stockées :
|
|
- Titre, artiste, album
|
|
- Année, genre
|
|
- Numéro de piste/disque, total de pistes/disques
|
|
- Durée, taux d'échantillonnage, bitrate
|
|
- Nombre de canaux
|
|
|
|
## Collections
|
|
|
|
Les collections sont identifiées par une clé au format `"artist:album"` :
|
|
- Conversion en minuscules
|
|
- Remplacement des espaces par des underscores
|
|
- Exemple : `"Pink Floyd - Wish You Were Here"` → `"pink_floyd:wish_you_were_here"`
|
|
|
|
## Clés (pk)
|
|
|
|
Chaque piste est identifiée par une clé (pk) unique :
|
|
- Hash SHA1 des 8 premiers octets de l'URL source
|
|
- Encodage hexadécimal
|
|
- Exemple : `1a2b3c4d5e6f7a8b`
|
|
|
|
## Statistiques
|
|
|
|
Le système suit automatiquement :
|
|
- Le nombre d'accès (hits)
|
|
- La date du dernier accès
|
|
- L'URL source originale
|
|
- Les métadonnées JSON (accessible via CacheEntry.metadata_json)
|
|
|
|
## Streaming progressif
|
|
|
|
Les fichiers en cours de téléchargement sont automatiquement streamés dès que possible :
|
|
- Téléchargement asynchrone en arrière-plan
|
|
- Conversion FLAC progressive
|
|
- Accès aux métadonnées dès le début du téléchargement
|
|
"#,
|
|
contact(
|
|
name = "PMOMusic",
|
|
),
|
|
license(
|
|
name = "MIT",
|
|
),
|
|
)
|
|
)]
|
|
pub struct ApiDoc;
|