Scan, fetch et annulation

Chaque requête utilise l’authentification d’administration. Les exemples supposent que AEDE_ADMIN_TOKEN contient le secret du serveur actif. Les chemins du corps désignent l’ordinateur serveur. Les routes de tâches refusent les paramètres d’URL.

POST /api/admin/v1/scan — sans corps#

Le mode de compatibilité rescane les racines suivies de manière synchrone, en conservant exclusions, fusions d’artistes et conclusions indépendantes. La connexion attend la sauvegarde et la publication.

curl -X POST 'http://127.0.0.1:8787/api/admin/v1/scan' \
  -H "Authorization: Bearer $AEDE_ADMIN_TOKEN"

Renvoie HTTP 200 avec {status:"completed",scanned_at,files}. La date est en secondes Unix et files compte les fichiers du catalogue découvert. Ce mode n’ajoute pas de dossiers par un corps et n’est pas une tâche HTTP asynchrone consultable. Un autre rédacteur donne 409 store_busy ; échec de scan/stockage : 500 scan_failed ou store_error. Envoyez {} pour choisir le mode asynchrone.

POST /api/admin/v1/scan — objet JSON#

Un objet, même vide, crée une tâche de scan asynchrone :

curl -X POST 'http://127.0.0.1:8787/api/admin/v1/scan' \
  -H "Authorization: Bearer $AEDE_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"folders":["/chemin/vers/musique"],"full":false,"threads":0}'

Renvoie HTTP 202, par exemple {"task_id":1,"status":"queued","status_url":"/api/admin/v1/tasks/1"}. 202 signifie accepté, pas terminé. Conservez ID/adresse et suivez la tâche. Chemin/combinaison invalide : 400 invalid_parameters ; JSON/champ inconnu : 400 invalid_body ; capacité : 503 task_limit.

POST /api/admin/v1/fetch#

Exige un objet JSON. Fetch est l’étape en ligne explicitement demandée : il obtient des informations attribuées sans remplacer les tags locaux.

curl -X POST 'http://127.0.0.1:8787/api/admin/v1/fetch' \
  -H "Authorization: Bearer $AEDE_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"targets":["Miles Davis"],"summaries":true,"lang":"fr","dry_run":true}'

Cet exemple prévisualise le travail sans contacter les services externes. Retirez dry_run:true lorsque vous souhaitez l’effectuer. Même réponse HTTP 202 de tâche en attente que pour scan ; le statut ultérieur aura task_kind:"identification".

Tous les booléens valent false par défaut ; targets est vide. {} n’est pas une absence d’action : sans choix de passe, il lance l’identification MusicBrainz habituelle de la CLI.

Dépendances et choix suivent le guide des sources. Les clés des services viennent par défaut du serveur. Un administrateur authentifié peut fournir service_keys: {fanarttv?: string, acoustid?: string} pour cette tâche uniquement : valeurs non vides, 1024 octets maximum, sans caractères de contrôle. Les clés absentes conservent les valeurs du serveur. Aède ne les enregistre pas, ne les inclut pas dans les informations de tâche et ne permet de modifier ni autres variables d’environnement, ni dossier de données, ni arguments d’exécutable. La capacité fetch_service_keys est annoncée avec le profil administratif ; HTTPS exige une session administrateur nominative. Le processus CLI reçoit les clés uniquement dans son environnement et masque leurs valeurs dans les sorties capturées. Limites de débit, sauvegarde de progression et absence d’écrasement restent actives. Images/paroles peuvent créer des fichiers dérivés à côté de la musique ; audio/tags restent intacts. Sans yes, une tâche non interactive nécessitant confirmation échoue au lieu d’attendre. Options/plages invalides : 400 ; une tâche acceptée peut ensuite échouer dans son résultat.

GET /api/admin/v1/tasks/{id}#

Utilisez l’ID numérique du scan/fetch soumis en JSON, pas une référence du catalogue ni un ID CLI délégué.

curl 'http://127.0.0.1:8787/api/admin/v1/tasks/1' \
  -H "Authorization: Bearer $AEDE_ADMIN_TOKEN"

Renvoie HTTP 200 avec :

{"task_id":1,"task_kind":"scan","status":"completed","cancel_requested":false,"result":{"exit_code":0,"stdout":"...","stderr":"","output_truncated":false},"error":null}

Statuts : queued,running,completed,failed,cancelled. Result est null jusqu’à disponibilité ; stdout et stderr sont limités chacun à 64 Kio. output_truncated:true indique un affichage incomplet. Un échec contient error:{code,message} ; un code de sortie 0 indique la réussite. Interrogez avec un délai raisonnable ; activity annonce les phases mais ne conserve pas durablement les résultats. ID inconnu/expiré : 404 task_not_found ; il doit être un entier décimal strictement positif (sinon 400 invalid_task_id). Un échec imprévu du registre donne 500 task_error. Les tâches déléguées et le scan de compatibilité sans corps ne sont pas sélectionnables ici.

HEAD /api/admin/v1/tasks/{id}#

Même authentification/validation, statut/en-têtes sans résultat. curl -I URL -H "Authorization: Bearer $AEDE_ADMIN_TOKEN" vérifie l’existence.

POST /api/admin/v1/tasks/{id}/cancel#

Sans corps ni paramètres d’URL.

curl -X POST 'http://127.0.0.1:8787/api/admin/v1/tasks/1/cancel' \
  -H "Authorization: Bearer $AEDE_ADMIN_TOKEN"

Renvoie HTTP 202 {task_id,status:"cancel_requested",status_url}. C’est une demande d’arrêt à un point sûr, pas la preuve d’un arrêt déjà effectué. Suivez jusqu’au statut final. La progression enregistrée n’est pas annulée. Tâche finie : 409 task_not_cancellable ; ID inconnu/expiré : 404.

Durée de vie et nouvelle tentative#

Maximum quatre tâches HTTP actives et 64 dossiers conservés ; les plus anciennes tâches terminées sont évincées. Les tâches attendent le verrou partagé et survivent à la déconnexion du client. L’arrêt propre du serveur les attend : annulez d’abord un long fetch à interrompre. ID/résultats vivent seulement en mémoire et disparaissent au redémarrage.

Un POST dont la réponse a été perdue peut déjà avoir démarré. Les soumissions ne sont pas idempotentes : ne les répétez pas aveuglément. Reconnectez-vous/suivez un ID conservé et examinez activité/journaux avant une nouvelle soumission. La récupération ne rembobine ni requêtes externes ni résultats partiels sauvegardés.

POST /api/admin/v1/lyrics#

Un administrateur authentifié peut envoyer {track:"track:..."}. Le serveur valide le fichier actuel de cette piste et transmet uniquement celui-ci au worker d'enrichissement annulable existant avec lyrics:true,yes:true. La capacité fetch_track_lyrics annonce cette route. Aucun chemin arbitraire fourni par le client n'est accepté ; les références d'album ou d'artiste sont refusées. LRCLIB ne demande aucune clé API dans le fonctionnement actuel d'Aède. Les erreurs du fournisseur et absences de correspondance restent dans le résultat de la tâche. Les paroles existantes, fichiers audio et tags sont conservés. /api/v1/lyrics découvre un nouveau LRC adjacent sans rescanner le catalogue. HTTPS exige une session administrateur nominative.

POST /api/admin/v1/generate#

Un administrateur local peut soumettre {"steps":["analyze","spectrum","m3u","lyrics"]} pour traiter la bibliothèque par étapes successives. library_generations annonce ce contrat. Il faut une à quatre étapes distinctes ; les champs inconnus, chemins et arguments arbitraires sont refusés. Les dossiers surveillés viennent du catalogue du serveur. Les analyses FlacCompagnon et les spectrogrammes utilisent un seul worker ; les M3U sont générés dans les dossiers d’albums, sans dériver un dossier d’artiste hors des racines. Les paroles utilisent explicitement la passe LRCLIB existante. Les fichiers audio et leurs tags restent intacts.

Une seule génération réserve le registre administratif ; aucune autre tâche administrative ne peut démarrer en parallèle. Les résultats déjà présents sont réutilisés selon les règles des commandes. Une étape terminée avec des erreurs est signalée, les étapes suivantes restent exécutées et le résultat final demeure en échec. L’annulation arrête la suite et conserve ce qui a été terminé. La tâche appartient à Aède et continue quand le client ferme sa vue ou sa connexion. Les identifiants et journaux restent bornés et propres au processus serveur. Le suivi et l’annulation utilisent les routes de tâches existantes. Les types library_generation_analyze, library_generation_spectrum, library_generation_m3u, library_generation_lyrics ou library_generation identifient l’action ; l’étape paroles exige la fonctionnalité fetch.

Sur Unix, les sous-processus appartiennent à un groupe séparé et l’annulation arrête ce groupe, y compris les encodeurs imbriqués, sans signaler le serveur ou son lecteur. Les tests hôtes vérifient la fermeture des pipes hérités, même lorsque le processus principal se termine avant ses descendants. La vérification native Windows reste distincte. La limitation à un worker réduit la concurrence ; elle ne certifie pas une lecture physique sans interruption sous toute charge système.

POST /api/admin/v1/check#

Test complet de décodage d’un album: {"release":"release:…"}. Un administrateur authentifié lance un décodage neuf, séquentiel, des fichiers catalogués de cette édition uniquement. Aucun chemin, élargissement au dossier ou option supplémentaire n’est accepté. Les routes habituelles de tâche et d’annulation donnent le résultat réel. La capacité album_decode_test annonce cette fonction. La capacité supplémentaire album_decode_results annonce le rapport JSON par fichier (version 1, path exact, status: ok | no_hash | ko, verifier et message éventuel). Le moteur utilise check --decode-test --json, avec flac -t pour les FLAC si disponible sur sa machine, sinon son décodeur Rust ; les autres formats utilisent le décodeur existant. Un échec du programme externe ne déclenche pas de repli trompeur. Un MD5 absent ne vaut pas un MD5 vérifié. Les fichiers audio, tags et conclusions CRC/analyses restent intacts. Les erreurs apparaissent par fichier et font échouer la tâche. HTTPS exige une session administrateur nominative.

L’admission des tâches fetch/scan et les routes de liste/lecture/annulation des tâches revérifient la session du compte après réception du corps, avant tout accès au registre. Une déconnexion, un changement de mot de passe/rôle ou la suppression du compte durant cette réception refuse l’action. Une tâche déjà acceptée avant déconnexion reste gérée par le serveur et n’est pas annulée implicitement.