🇬🇧 English · 🇫🇷 Français

S'applique à Hydranos 4.4.

Cette page s'adresse à quiconque ajoute des torrents à Hydranos, à la main ou depuis Sonarr, Radarr ou autobrr. Elle explique comment Hydranos choisit le moteur et le dossier d'un nouveau torrent, comment créer et modifier des catégories, et à quoi servent les tags. Lisez-la avant de créer votre première catégorie : il n'y a pas de chemin de sauvegarde par défaut, donc sans une catégorie qui en définit un, la plupart des ajouts sont refusés.

En cas de doute, classez vos catégories en Hoard. Race sert à faire la course sur les uploads frais, et le drain race peut supprimer des torrents race avec leurs données (voir Moteurs : race & hoard). Les termes employés ici (moteur, graduation, drain race, obligation de seed) sont définis sur Concepts & glossaire.

Une catégorie est un nom associé à quatre réglages :

Les catégories sont enregistrées dans le store (hydra.db), pas dans default.toml. Modifier le fichier de configuration ne les change jamais. Si le store ne contient encore aucune catégorie, Hydranos se rabat sur la lecture de <data_dir>/categories.json, mais n'écrit jamais ce fichier : la première modification place toute la liste dans le store.

Les noms sont comparés à l'identique : Movies et movies sont deux catégories différentes. Le mode, lui, ne l'est pas : Hoard ou HOARD est enregistré comme hoard, et toute autre valeur est refusée (voir Avec l'API REST plus bas).

Un torrent porte sa catégorie par copie. Si le même torrent se trouve dans deux moteurs, chaque copie a sa propre catégorie.

Accepté mais ignoré en 4.4 : les champs de catégorie placement, agents, strategy et min_free_bytes sont conservés quand vous enregistrez une catégorie, mais rien ne les lit. Le placement n'utilise que mode. Au démarrage, Hydranos journalise un avertissement par champ de ce type, en nommant les catégories qui le portent. Voir Mettre à jour depuis la 3.x.

Tous les chemins d'ajout (l'onglet + Ajouter un torrent (+ Add Torrent), l'API REST, le shim qBittorrent, le serveur MCP, les dossiers surveillés, les magnets une fois leurs métadonnées arrivées, un rapatriement depuis un autre nœud) appliquent la même règle :

1. Moteur. Un engine explicite qui existe sur cette instance l'emporte. C'est le seul moyen de placer un torrent sur un moteur supplémentaire comme vpn1. Ensuite, sur les routes d'ajout natives et l'onglet d'ajout, un mode (race ou hoard) choisit le moteur qui a ce rôle. Sinon, la catégorie décide : mode hoard → moteur hoard ; mode race, une catégorie inconnue ou aucune catégorie → moteur race.
2. Chemin de sauvegarde. Un chemin de sauvegarde présent dans la requête l'emporte. Sinon, celui de la catégorie est utilisé. S'il n'y a ni l'un ni l'autre, l'ajout est refusé avec no save path: category "x" is unknown and no savepath was given. Vous obtenez le même message pour une catégorie connue dont le chemin de sauvegarde est vide. Seul le shim qBittorrent a un dernier recours : le dossier qu'un client a défini avec save_path dans setPreferences (voir Shim qBittorrent & automatisation).

Deux chemins d'ajout vérifient d'abord la catégorie : add_torrent (MCP) refuse une catégorie absente ou inconnue avant le placement, même si un chemin de sauvegarde est fourni, et un dossier surveillé ne peut être enregistré qu'avec une catégorie existante.

flowchart TD
    A["Nouveau torrent : catégorie, chemin de sauvegarde facultatif, moteur ou mode facultatif"] --> B{"engine fourni et existant sur cette instance ?"}
    B -- oui --> E1["Moteur = le moteur nommé"]
    B -- "non fourni" --> MO{"mode fourni ? (routes natives, onglet d'ajout)"}
    B -- "fourni, inconnu : routes natives, fichier MCP" --> RX["Refusé : no engine X (400 sur les routes natives ; MCP : erreur d'outil unknown engine X)"]
    B -- "fourni, inconnu : magnet MCP, dossier surveillé dont le moteur a été supprimé" --> C
    MO -- oui --> E2["Moteur = le moteur qui a ce rôle"]
    MO -- non --> C{"Catégorie connue ?"}
    C -- non --> R1["Moteur = race"]
    C -- oui --> D{"Mode de la catégorie hoard ?"}
    D -- oui --> H["Moteur = hoard"]
    D -- "non (race)" --> R2["Moteur = race"]
    E1 --> S{"Chemin de sauvegarde dans la requête ?"}
    E2 --> S
    R1 --> S
    H --> S
    R2 --> S
    S -- oui --> P1["Utiliser le chemin de la requête"]
    S -- non --> T{"Catégorie connue et son chemin non vide ?"}
    T -- oui --> P2["Utiliser le chemin de la catégorie"]
    T -- non --> X["Refusé : no save path"]

Les détails qui comptent :

• Où vous pouvez nommer un moteur : uniquement l'API REST (engine sur POST /api/torrents/upload et POST /api/torrents ; obligatoire sur POST /api/nodes/:name/fetch), l'outil MCP add_torrent et les dossiers surveillés configurés via l'API. Le shim qBittorrent n'en accepte jamais : Sonarr et Radarr routent uniquement par catégorie. L'onglet d'ajout n'a pas de champ moteur, seulement le sélecteur Mode.
• Où vous pouvez donner un mode : mode (race ou hoard, quelle que soit la casse) sur POST /api/torrents/upload et POST /api/torrents, et le sélecteur Mode de l'onglet d'ajout. Il choisit le moteur qui a ce rôle, en priorité celui nommé race ou hoard. engine l'emporte quand les deux sont envoyés.
• Un moteur ou un mode qui n'existe pas est refusé en 400 par POST /api/torrents/upload et POST /api/torrents (magnets compris) : no engine X, mode must be race or hoard, not "x" ou no engine has the hoard role. add_torrent (MCP) refuse un moteur inconnu pour un fichier, sous forme d'erreur d'outil (unknown engine `x`; this node runs: …), pas d'un HTTP 400. Un magnet venu de MCP l'ignore et se rabat sur la catégorie ; un dossier surveillé refuse un engine inconnu à l'enregistrement (400), et ne se rabat sur la catégorie que si ce moteur est supprimé ensuite.
• Le chemin de sauvegarde n'est pas vérifié à l'ajout : aucun test qu'il soit absolu ou qu'il existe. Les chemins sont ceux que voit Hydranos (à l'intérieur du conteneur sous Docker).
• Disposition sur disque : un torrent multi-fichiers va dans <save path>/<torrent name>/…, un torrent mono-fichier dans <save path>/<file>, ou <save path>/<file name without extension>/<file> avec l'option de sous-dossier ; voir Ajouter des torrents & données existantes. Une collision de chemins (isolate) déplace l'un ou l'autre type dans <save path>/<first component of its name> [<first 8 hex digits of its info hash>]/ (Ajouter des torrents & données existantes).
• Sur l'onglet d'ajout, choisir une catégorie remplace le champ Chemin d'enregistrement (Save Path) par le chemin de sauvegarde de la catégorie (vidé si elle n'en a pas) et règle le sélecteur Mode sur le mode de la catégorie. Le formulaire envoie ensuite les deux comme valeurs explicites, si bien que l'ajout suit la catégorie ; modifiez Mode ou Chemin d'enregistrement après coup et votre choix l'emporte. Mode démarre sur Race et est envoyé avec chaque ajout, même avec - none - comme catégorie (voir Ajouter des torrents & données existantes).
• Après le placement, l'ajout peut encore être refusé par le contrôle d'admission race, et les données déjà présentes sur disque sont revérifiées ou acceptées telles quelles. Ce pipeline est décrit sur Ajouter des torrents & données existantes.

Ouvrez l'onglet Catégories (Categories) et cliquez sur + Nouveau (+ New). Le formulaire contient Nom (Name), Mode, Chemin d'enregistrement (Save Path), puis, selon le mode, Passer vers (catégorie Hoard) (race) ou Transit area (hoard). L'interface exige un nom et un chemin de sauvegarde. Passer vers ne liste que les catégories hoard qui ont un chemin de sauvegarde. Le tableau affiche Nom, Mode, Chemin d'enregistrement, Passer vers (Graduate to) et les boutons Modifier (Edit) / Supprimer (Delete), suivis des libellés orphelins (voir Supprimer et renommer plus bas). Enregistrer une nouvelle catégorie sous un nom qui existe déjà échoue avec category "x" already exists.

Modifier le chemin de sauvegarde ou le mode d'une catégorie n'affecte que les torrents ajoutés ensuite. Les torrents qui y sont déjà restent où ils sont, dans le même moteur. Pour les déplacer, utilisez Changer de catégorie + déplacer les fichiers › (Change category + move files ›) (voir plus bas).

# Créer (201, la catégorie est renvoyée en écho)
curl -X POST http://localhost:8199/api/categories \
  -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"tv","mode":"hoard","save_path":"/data/library/tv"}'

curl -X POST http://localhost:8199/api/categories \
  -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"tv-race","mode":"race","save_path":"/data/race/tv","graduate_to":"tv"}'

# Lister (tableau trié par nom, sans tenir compte de la casse)
curl -H "X-Api-Key: YOUR_API_KEY" http://localhost:8199/api/categories

Ce que vérifient les routes :

Rien ne vérifie save_path (un chemin vide est enregistré), ni que Passer vers (Graduate to) désigne une catégorie hoard existante.

Sonarr, Radarr et les autres clients qBittorrent peuvent aussi gérer les catégories, avec des résultats différents :

Si un client crée une catégorie sans chemin de sauvegarde, elle est enregistrée vide et tout ajout ultérieur qui n'envoie pas son propre savepath est refusé faute de chemin de sauvegarde. Créez d'abord vos catégories dans Hydranos, avec le bon mode et le bon chemin, et utilisez les mêmes noms dans Sonarr/Radarr. Voir Migrer depuis qBittorrent.

Faites un clic droit sur un ou plusieurs torrents. Le groupe Torrent contient deux entrées de catégorie :

• Changer de catégorie › (Change category ›) : libellé seulement. Le moteur et les fichiers restent en place, même si la nouvelle catégorie a un autre mode ou un autre chemin de sauvegarde.
• Changer de catégorie + déplacer les fichiers › (Change category + move files ›) : les données suivent le chemin de sauvegarde de la catégorie, sous forme de job (tâche de fond).

Les deux s'exécutent comme une tâche groupée avec un panneau de progression. Les sous-menus listent les catégories existantes ; Changer de catégorie › commence aussi par Aucune catégorie (No category), qui retire le libellé (libellé seulement : il n'y a pas de dossier vers lequel déplacer, donc + déplacer les fichiers ne la propose pas).

Avec + déplacer les fichiers (+ move files), Hydranos décide copie par copie :

flowchart TD
    A["Changer de catégorie + déplacer les fichiers"] --> B{"Catégorie connue et dotée d'un chemin de sauvegarde ?"}
    B -- non --> E["400, rien ne change"]
    B -- oui --> C{"Le mode de la catégorie correspond au rôle<br/>du moteur qui détient cette copie ?"}
    C -- oui --> D{"Données déjà au chemin de la catégorie ?"}
    D -- oui --> L["Libellé changé, rien ne bouge (200)"]
    D -- non --> M["Job move_data, même moteur"]
    C -- non --> G["Job graduate, vers le moteur race ou hoard"]
    M --> K{"Contrôles préalables OK ?"}
    G --> K
    K -- non --> F["409 : shared, unsafe_path, destination_taken,<br/>hardlinks ou space, ou un déplacement déjà en file"]
    K -- oui --> J["202 : job en file, voir l'onglet Jobs"]

• Un changement de mode devient une graduation : le torrent passe au moteur race ou hoard et ses données le suivent, dans un sens comme dans l'autre. Une copie dans un moteur supplémentaire dont le rôle correspond déjà au mode reste dans ce moteur. Le menu contextuel agit sur la copie que montre la ligne (il nomme le moteur supplémentaire avec ?engine=) : une ligne de vpn1 déplace donc la copie vpn1.
• destination_taken signifie que des fichiers de mêmes noms existent déjà dans le dossier cible ; déplacer par-dessus les écraserait.
• hardlinks signifie que certains fichiers ont des hardlinks ailleurs (en général votre bibliothèque Sonarr/Radarr) et que la cible est sur un autre système de fichiers (sous Docker, vérifiez que les chemins de sauvegarde et la bibliothèque sont sous le même montage : voir Docker et Jobs, actions groupées & déplacement). L'interface demande une seule fois pour toute la sélection (Les déplacer quand même ? (Move them anyway?)) et réessaie avec votre accord. Les autres motifs ne peuvent pas être forcés.
• Avec un job move_data (même moteur), le torrent continue de seeder pendant la copie des données. Une graduation retire d'abord le torrent de son moteur, puis déplace les fichiers, puis l'ajoute à l'autre moteur avec son état (compteurs, trackers, arrêté ou non) : il ne seed pas pendant le déplacement. Un échec est annulé : les fichiers reviennent et le torrent retrouve son moteur tel qu'il était. La notification qui suit l'action indique dans quel cas vous êtes : Il continue de partager pendant la copie de ses données (It keeps seeding while its data is copied) pour un job move_data, qui tourne dans un autre engine : il cesse de seeder pendant la copie de ses données, puis reprend là-bas tel qu'il était (which runs in another engine: it stops seeding while its data is copied, then carries on there as it was) pour une graduation. Son libellé de catégorie change quand le job se termine. Le comportement des jobs et les cas d'échec sont décrits sur Jobs, actions groupées & déplacement.

Équivalent REST, par torrent (/api/race/… ou /api/hoard/… désigne le moteur qui détient la copie ; ajoutez ?engine=vpn1 pour un moteur supplémentaire) :

curl -X POST http://localhost:8199/api/race/torrents/0123456789abcdef0123456789abcdef01234567/category \
  -H "X-Api-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"category":"tv","move_files":true}'

Sans "move_files": true, la route ne fait que changer le libellé de cette copie. Ajoutez "allow_breaking_hardlinks": true pour passer outre un refus hardlinks.

Autres façons de changer une catégorie :

Sur les lignes provenant d'un autre nœud, les deux entrées de catégorie sont envoyées au nœud qui détient le torrent, qui applique sa propre catégorie de ce nom (son propre mode et son propre chemin de sauvegarde) : voir Nœuds & plusieurs machines.

Renommer. Cliquez sur Modifier (Edit), changez Nom (Name), enregistrez. La définition passe au nouveau nom et chaque torrent étiqueté avec l'ancien nom reçoit le nouveau (l'API indique combien dans relabelled). Les fichiers et les moteurs ne changent pas. Si le nouveau nom est déjà une catégorie, l'enregistrement échoue avec category "x" already exists.

Tout ce qui nomme la catégorie suit le renommage : le Passer vers (Graduate to) des autres catégories, les règles RSS, les dossiers surveillés, les conditions de workflow category is / is not et les actions set category, les magnets qui attendent encore leurs métadonnées, et les jobs en file. L'API indique ce qui a suivi dans followed ({"rss_rules","watch_folders","workflows","magnets","jobs"}, des nombres). Une condition de workflow qui compare le nom avec contains ou une expression régulière est votre texte et n'est pas modifiée : vérifiez-les à la main.

Supprimer. Supprimer (Delete) demande Supprimer la catégorie « x » ? (Delete category "x"?), supprime la définition et retire le libellé de chaque torrent qui le portait (cleared dans la réponse). Les torrents restent où ils sont, dans le même moteur. Les nouveaux ajouts qui le nomment encore sont routés comme pour une catégorie inconnue : moteur race, refusés sans chemin de sauvegarde explicite.

Libellés orphelins. Un libellé porté par des torrents sans catégorie de ce nom (laissé par une mise à jour, ou par un client qui appelle qBit setCategory avec un nom qui n'existe pas) est listé sous les catégories comme <name> orphaned, la colonne Chemin d'enregistrement affichant no longer configured, still on N torrent(s), avec deux boutons :

• Adopter (Adopt) ouvre le formulaire + Nouveau (+ New) prérempli d'après ces torrents : le nom, le mode du rôle de moteur dans lequel tourne la majorité d'entre eux, et le chemin de sauvegarde que la plupart utilisent, avec le message Prérempli d’après les {n} torrents déjà étiquetés {label} : ils tournent en {mode}, principalement sous {path}. Vérifier, puis enregistrer pour les adopter. (Filled in from the {n} torrent(s) already labelled {label}: they run in {mode}, mostly under {path}. Check it, then save to adopt them.). L'enregistrement crée la catégorie ; les torrents lui appartiennent aussitôt, rien ne bouge.
• Supprimer retire le libellé de ces torrents.

Dans le shim qBittorrent, un torrent sans catégorie est présenté sous le nom de son moteur, par exemple race ou hoard. Un client qui demande torrents/info?category=race obtient donc les torrents race étiquetés race et tous les torrents race sans catégorie. Évitez de nommer vos propres catégories race ou hoard, sauf si c'est voulu. Le shim liste tous les moteurs, moteurs supplémentaires compris (un torrent sans catégorie y est présenté sous l'identifiant du moteur), mais n'ajoute que dans race ou hoard, par catégorie (voir Shim qBittorrent & automatisation).

Donnez à chaque *arr sa propre catégorie. En cas de doute, choisissez Hoard : un torrent race peut être supprimé par le drain race dès que son obligation de seed est remplie, que Sonarr ou Radarr l'ait déjà importé ou non. N'utilisez race que pour faire la course sur les uploads frais, avec Passer vers renseigné.

Une catégorie race dont Passer vers est renseigné indique au drain race où déplacer un torrent qui doit quitter le disque race avant que son obligation de seed soit remplie. Une catégorie hoard dont Transit area est cochée supprime, avec leurs fichiers, tous les torrents qui y sont classés dès que leur obligation de seed est déclarée et remplie, y compris les torrents ajoutés directement dedans. Elle ne le fait que si une catégorie la désigne dans Passer vers ; un torrent dont le tracker ne déclare aucune obligation n'est jamais supprimé. Ne cochez pas Transit area sur une catégorie de bibliothèque. Les règles complètes sont sur Drain race & graduation.

Les tags sont des libellés libres. Ils n'ont aucun effet sur le placement, le moteur ou les fichiers : servez-vous-en pour filtrer et pour piloter des workflows.

Où les tags servent de filtre : la facette Tags de l'onglet Hoard (voir Visite de l'interface web), qBit torrents/info?tag= (correspondance exacte), les sélections groupées par filtre, et les conditions de workflow has_tag / not_has_tag. GET /api/v2/torrents/tags liste tous les tags enregistrés.

qBit deleteTags retire les tags de la liste et de chaque torrent ; détails sur Shim qBittorrent & automatisation.

• Ajouter des torrents & données existantes : le pipeline d'ajout après le placement.
• Moteurs : race & hoard : ce que font les deux rôles, moteurs supplémentaires.
• Drain race & graduation.
• Jobs, actions groupées & déplacement.
• Shim qBittorrent & automatisation.
• API REST : toutes les routes de catégories et de tags.