Pour l’application graphique serveur, le choix des dossiers, la connexion HTTPS, le statut et les journaux, consultez le guide de l’App Aède. Cette page décrit l’API des clients natifs comme Phémios.
Ces routes utilisent l’authentification par session Aède et les limites des travailleurs existants. Les lectures ne récupèrent jamais de données externes automatiquement.
GET /api/v1/presentation/artistsetGET /api/v1/presentation/albums: pages du catalogue, références stables, participations, compilations, origines attribuées, biographies avec leurs crédits et disponibilité des images locales. Paginationoffsetetlimitde 1 à 200. Les annotations personnelles sont exclues.GET /api/v1/artwork: paramètresref,kind(cover,portrait,banner,background,spectrum) et éventuellementsizede 1 à 2048. Les chemins sont résolus sur le serveur ; aucun chemin libre ni URL externe n’est accepté. Les vérifications de fichiers ouverts et les miniatures reprennent le lecteur d’images Subsonic, sans modifier les originaux.GET /api/me/v1/annotations: annotations paginées du compte connecté, uniquement pour les références présentes. L’édition reste sur la route singulière existante.POST /api/me/v1/m3u: objetreleaseetname, création d’une liste privée et d’un M3U dans le dossier de données du serveur.GET /api/me/v1/m3uliste les résumés privés ;GET /api/me/v1/m3u/{id}prépare le téléchargement complet. Les répétitions sont conservées, les références manquantes et les chemins avec saut de ligne provoquent une erreur. Les chemins du M3U sont ceux du serveur ; la portabilité vers un lecteur relève du moteur de copie.POST /api/admin/v1/analyzeetPOST /api/admin/v1/spectrum: objetrelease,forcefacultatif etthreadsfacultatif de 0 à 64. Réservées aux sessions administrateur en HTTPS ou HTTP local. La référence est résolue vers un album catalogué ; aucun argument exécutable libre n’est accepté. Le suivi et l’annulation utilisent les routes de tâches existantes. Une réponse 202 signifie accepté, pas terminé.
Les analyses et spectres créent des fichiers dérivés à côté de la musique du serveur ; ils ne modifient ni audio ni tags. Les essais doivent porter sur des copies isolées. La lecture physique, les sorties audio et la copie vers les lecteurs restent des étapes distinctes de validation du client.
Téléchargement des rapports FlacCompagnon#
GET /api/v1/analysis/report?ref=TOKEN sélectionne une piste ou un album du catalogue actuel. HEAD valide la même sélection sans corps. Le JSON reprend l’enveloppe FlacCompagnon d’origine : format, version, report.root, report.files, report.has_flac, avec un nom de pièce jointe. Une piste fournit uniquement l’entrée de son fichier ; un album réunit les fichiers distincts dans l’ordre des pistes du catalogue, que les rapports initiaux couvrent un titre, un album ou un artiste. Tous les champs conservés de l’entrée source, y compris les champs inconnus et les anciens chemins après déplacement, restent présents. La racine décrit le dossier sélectionné du catalogue. Aucun sidecar n’est rouvert, aucun scan, enrichissement, analyse ou écriture ne démarre.
Chaque entrée exportée contient aussi la date exacte de la mesure conservée, sous la forme d’une chaîne décimale aede_result_at_ns, dont "0" pour une date inconnue. Cette métadonnée reprend la date des conclusions, même si une ancienne entrée source ne la contient pas, pour éviter qu’une réimportation donne à un ancien résultat la date de modification du téléchargement. Les mesures originales et les données source enregistrées restent inchangées ; ce champ est ajouté ou normalisé uniquement dans la réponse et compte dans sa limite finale de taille.
L’authentification de lecture et l’admission bornée existantes s’appliquent ; le compte est revérifié avant réponse. JSON no-store et nosniff. Seul ref est accepté, pour piste ou album, jamais un chemin. Limites : 2048 pistes et 16 Mio. Entité/analyse absente : 404 ; résultat périmé, ancienne donnée sans entrée source complète ou schéma non pris en charge : 409 ; sélection trop volumineuse : 413. Un album auquel il manque des analyses est refusé comme incomplet. Importer un rapport complet plus récent ou lancer explicitement une analyse permet de compléter les données. Les entrées d’erreur conservées restent celles de la source ; aucune mesure n’est inventée. La validité emploie la règle existante taille/date du catalogue, sans vérification supplémentaire du fichier sur disque.
Collections dynamiques depuis les filtres#
Une collection peut conserver une expression browse-v1: suivie d’un objet JSON versionné : view (artists, albums, compilations, countries, genres), mode (none, years, alphabet, both), bornes inclusives years et alphabet, includeUnknownYear, query, et éventuellement countries (union des origines attribuées, null pour les origines inconnues) et genre. Les initiales vont de #=0 à Z=26. Une réglette masquée ne filtre pas. Les vues artistes appliquent les initiales aux artistes principaux ; les vues albums les appliquent aux titres. Les albums retenus contribuent toutes leurs pistes.
Ces critères restent dans le stockage existant des règles de collection. Leur résultat évolue avec le catalogue, les sources fiables et les annotations du compte courant. La recherche conserve ponctuation et articles, ignore la casse et les accents/ligatures occidentaux usuels, et porte sur les métadonnées projetées, les noms et valeurs des tags locaux et les annotations personnelles. Aucune récupération réseau n’est déclenchée. Champs inconnus, types, bornes ou taille invalides sont refusés. Les collections ordinaires gardent leur grammaire. La route publique /api/v1/query refuse ces critères qui peuvent lire des annotations privées.
GET /api/me/v1/collection/albums?name=… évalue la règle avec le compte authentifié et renvoie les références des albums actuels. L’option create_only: true à l’enregistrement refuse de remplacer une collection de même nom.
DELETE /api/me/v1/history exige le corps { "confirm": true } : écoutes, scrobbles et compteurs du seul compte courant sont effacés ensemble. Annotations, collections, curseurs de lecture et autres comptes sont préservés. Une lecture active peut ensuite publier une nouvelle écoute. Un auditeur ne peut pas effectuer cette action.
GET /api/v1/presentation/playback?ref=… renvoie la discographie principale dans l’ordre chronologique partagé avec le CLI, ou les pistes d’un album, avec numéro et nombre total de pistes par album (limite de 4096 pistes). Les années inconnues viennent en dernier ; les pistes gardent leur ordre. Cette consultation ne lance pas de lecture.
La capacité additive m3u_playback_selection active les lectures authentifiées GET /api/me/v1/m3u-files/{id}/playback et GET /api/me/v1/m3u/{id}/playback. Elles renvoient la même projection ordonnée items et scanned_at, sans lancer de lecture ni écrire l’historique. Les fichiers surveillés conservent les contrôles de racines, exclusions, identité et isolation des exports privés. Les chemins relatifs sont résolus depuis le dossier de la liste, uniquement par correspondance avec les fichiers du catalogue actuel : aucune entrée ne déclenche de lecture de fichier ou de requête réseau. Une entrée inconnue, ambiguë ou désignant un flux refuse la sélection entière. Les exports privés utilisent uniquement les références du compte authentifié. L’ordre et les répétitions sont conservés, dans la limite de 4096 occurrences. Les deux sources refusent un fichier associé à plusieurs pistes du catalogue ; un index de chemins par requête évite de reparcourir le catalogue pour chaque occurrence privée. Un ancien serveur doit être mis à jour puis redémarré.
Pistes d’album légères et capacités#
GET /api/v1/status, authentifié, conserve la version d’API 1 et annonce capabilities, dont dynamic_browse_collections et album_track_pages. Un processus ancien peut ne pas les annoncer même si son exécutable a été reconstruit : redémarrer Aède charge le nouveau code. Le client peut alors refuser clairement une création depuis les filtres avant d’envoyer une règle non prise en charge.
GET /api/v1/presentation/tracks?ref=RELEASE&offset=0&limit=50 renvoie {items,total,offset,limit,scanned_at}, avec 1 à 200 pistes par page dans l’ordre complet de l’édition. Chaque ligne contient reference,title,disc_no,track_no,album_position,duration_ms,analysis_available,spectrum_available. La position globale commence à 1 ; les numéros de disque/piste absents restent nuls. Les titres identiques sur des CD différents conservent des références distinctes. Cette lecture ne transporte aucun corps d’analyse, n’ouvre pas l’audio et ne réalise aucune mutation. L’ouverture explicite d’un résultat lit le détail /api/v1/track existant ; les exports JSON gardent leur contrat. Les références invalides ou ne désignant pas un album et les paramètres de pagination non pris en charge sont refusés.
Catalogue complet des pistes et dates d’entrée#
Sans ref, GET /api/v1/presentation/tracks parcourt toutes les positions du catalogue, y compris les titres sans album. q facultatif (1024 octets maximum) cherche dans les titres, noms d’albums/artistes, crédits et noms/valeurs des tags normalisés. Les pages gardent la limite de 1 à 200 lignes. La recherche parcourt les crédits une fois par requête, plutôt que de reparcourir toute leur table pour chaque piste. Chaque ligne ajoute release et album_title, nuls sans album ; album_position est également nul dans ce cas. /api/v1/track expose aussi numéros de disque/piste, propriétés audio, tags bruts et crédits avec leur source. La sélection de lecture accepte une référence de piste : une seule entrée, avec sa position et le nombre de pistes de son album réel ; sans album, référence nulle et 1/1.
Le statut annonce aussi track_catalog_pages et catalog_added_dates. Les albums ajoutent added_at nullable : première observation la plus ancienne des fichiers dans le catalogue, en secondes Unix. Les scans préservent les dates connues par chemin. Les fichiers déjà présents dans les anciens catalogues restent sans date, même après relecture forcée ; un album qui en contient reste inconnu. Les nouveaux chemins sont datés au premier scan réussi. Un chemin supprimé puis ajouté à nouveau constitue une nouvelle observation. Ce champ persistant facultatif est distinct de la date de modification et de l’année de sortie. Ni audio ni tags ne sont écrits.
Publication M3U dans la bibliothèque#
POST /api/me/v1/m3u accepte aussi library:true, réservé au compte administrateur avec le profil administratif, en HTTPS ou HTTP local. Aède reprend le plan de la commande playlist : fichier nommé d’après le dossier, chemins relatifs, album complet et discographie chronologique dans le dossier artiste lorsqu’il est identifiable et distinct d’une racine surveillée. library_files confirme les destinations ; library_m3u_publication annonce cette capacité. Les fichiers audio et leurs tags restent intacts. Les destinations doivent appartenir aux racines disponibles du catalogue. Une erreur sur plusieurs fichiers est signalée, mais les fichiers déjà publiés et la liste privée peuvent subsister. Une sélection privée identique réutilise son identifiant et recrée son export supprimé.
Couverture des analyses conservées#
GET /api/v1/presentation/analysis accepte offset, limit (200 maximum) et une recherche q sur le titre de l’album ou son artiste principal. La capacité analysis_coverage annonce cette lecture. Chaque album expose sa référence, son titre, son artiste, ses pistes et les nombres disjoints current, stale, failed, missing, ainsi que spectra pour les images disponibles. Seuls les résultats FlacCompagnon comptent ; une erreur actuelle est un échec, et une ancienne taille/date de modification signifie un résultat périmé. La couverture suit le dernier scan, sans refaire de contrôle. Le résumé porte sur tous les fichiers du catalogue, y compris sans album ; les spectres sont vérifiés uniquement dans la fenêtre affichée. Cette lecture ne lance aucun traitement et n’écrit aucun fichier.
Lecture de label et sélections dynamiques#
La sélection de lecture accepte aussi une référence de label : seules ses éditions associées sont sélectionnées, dans l’ordre chronologique commun des albums, puis l’ordre original des pistes. Les positions/nombres par album et la limite de 4096 pistes restent inchangés. label_playback annonce cette extension.
Une règle browse-v1: avec view: "label" exige une référence stable originale label de type Label. Les filtres d’années, d’initiales des titres et de recherche s’appliquent aux éditions de ce label. Les autres vues refusent ce champ ; une référence absente ou d’un autre type est refusée ; un label valide retiré donne une sélection vide. Les futures éditions correspondantes rejoignent la collection à son évaluation, sans enregistrer d’identifiant numérique de catalogue. dynamic_browse_label annonce cette extension. Le client conserve séparément la bibliothèque et le compte d’origine, sans enregistrer son espace de noms dans la règle.
Si l’administration fetch est disponible avec le réseau activé, fetch_discogs annonce le champ explicite discogs des tâches. Le GET d’un label reste local et ne lance jamais d’enrichissement.
Les pages de labels acceptent également sort=albums et order=asc|desc pour trier tous les labels filtrés par nombre d’albums avant pagination. Les égalités utilisent le nom et la clé de manière déterministe. Ce tri est refusé pour les autres listes du catalogue. La capacité label_album_sort l’annonce. La lecture d’un label et sa discographie chronologique partagent la règle d’ordre des albums du serveur.
Intégrité conservée#
Chaque ligne de couverture expose integrity:{ok,ko,no_hash,unchecked,unsupported,stale,md5,crc}. Les six premiers compteurs répartissent toutes les pistes de l’album. Pour FLAC, seuls les résultats FlacCompagnon applicables donnent un MD5 OK, KO ou une signature absente. Un résultat manquant, non vérifié ou une erreur ne prouve pas l’intégrité ; un rapport ancien reste périmé. Ogg utilise séparément le CRC des pages enregistré par Aède, pas un MD5 audio. Les autres formats affichent une absence de contrôle disponible, jamais un succès inventé. La consultation ne décode pas l’audio et ne lance aucun contrôle.
Albums par compositeurs#
La présentation des albums ajoute composers, une liste dédupliquée de lignes {reference} contenant les identités stables d’artistes possédant un crédit local exact composer sur l’édition, une de ses pistes, un enregistrement ou une œuvre associée. L’artiste principal, un interprète ou un parolier n’est jamais considéré automatiquement comme compositeur. L’index du graphe est calculé une seule fois par page ou évaluation, sans ouvrir l’audio ni interroger de service externe. Les affirmations externes non acceptées ne sont pas incluses. Une liste vide confirme l’absence de crédit ; les anciens serveurs omettent ce champ.
La capacité dynamic_browse_composers annonce la vue composers de browse-v1, avec un tableau requis composers contenant au maximum 100 références originales d’artistes. Une sélection vide inclut toutes les éditions ayant un compositeur ; plusieurs références forment une union croisée avec les autres filtres. Chaque édition retenue contribue toutes ses pistes. Une identité supprimée ne correspond plus à rien. Les autres vues refusent ce champ. Aucun changement de format du catalogue ou de version d’API : mettre à jour et redémarrer le moteur, puis synchroniser explicitement le catalogue du client pour conserver ces associations hors connexion.
Export des originaux vers un lecteur externe#
La capacité authentifiée original_exports fournit un plan borné de pistes sélectionnées et un flux des fichiers originaux, indépendamment de la lecture et sans événement d’historique. Voir la copie pour les limites, jetons de version et autorisations. Phémios prépare temporairement un original puis réutilise les règles de copie et conversion d’Aède.
Les routes sont POST /api/me/v1/exports/plan et GET /api/me/v1/exports/original ; cette dernière exige les paramètres ref et stamp. Les plans renvoient les clés conservatrices key de chaque composant du chemin, issues de la politique de nommage de la copie, pour refuser les collisions entre lots.