Skip to content

CLI headless

Jump to bottom
Hydro74000 edited this page Oct 30, 2026 · 8 revisions

CLI headless

Muxiveo-cli est le point d'entrée headless de Muxiveo. Il ne lance pas l'interface graphique et reste strictement non interactif.

Lancement

python3 main.py --cli --help
./Muxiveo-cli --help

Dans les builds packages, le CLI utilise le même bundle que l'application GUI :

  • Linux/AppImage : entrée Muxiveo-cli à côté de Muxiveo;
  • Windows : entrée Muxiveo-cli.exe;
  • macOS : entrée Muxiveo-cli dans Muxiveo.app/Contents/MacOS/;
  • fallback commun : Muxiveo --cli ....

Depuis les sources, python3 main.py --cli ... lance aussi le mode CLI sans initialiser l'interface graphique.

Commandes

Commande Rôle
inspect inspecte une source et sort du JSON
inspect --hdr static|dynamic|measure inspection HDR avec comparaison et export de rapport ; voir HDR Studio
inspect --config-template génère un template JSON de départ
schema affiche le schéma JSON public du contrat CLI
plugins list/install/update/remove gère les extensions facultatives ; voir Plugins
tools affiche en JSON les chemins d'outils effectivement résolus par Muxiveo
version [--check] [--channel stable|unstable] affiche la version ; --check la compare à la dernière release du canal (stable = main, unstable = pré-versions devel-cli)
validate valide un job/template sans exécuter ffmpeg
preview affiche le plan et les commandes prévues selon le backend
remux exécute un remux headless
batch applique un template à plusieurs jobs
validate --profile valide un decision-profile, ou son application si -i est fourni
preview --profile applique un profil en dry preview JSON/commande
run/remux --profile applique un profil et remuxe
batch --profile applique un profil à un dossier
hybrid hybridation de référence et donneur (paire ou saison entière)
sync-scan corrélation acoustique FFT et extraction de calibration
shift-subs recalage physique de fichiers sous-titres (SRT, ASS)

Exemples :

Muxiveo-cli inspect source.mkv
Muxiveo-cli inspect source.mkv --config-template --output sortie.mkv
Muxiveo-cli schema --output Muxiveo-cli.schema.json
Muxiveo-cli schema --version decision-profile
Muxiveo-cli tools
Muxiveo-cli version --check --log-format jsonl
Muxiveo-cli version --check --channel unstable
Muxiveo-cli preview --config docs/cli/middle.json
Muxiveo-cli preview --config docs/cli/middle.json --json
Muxiveo-cli validate --config docs/cli/middle.json --json
Muxiveo-cli remux -i source.mkv -o sortie.mkv
Muxiveo-cli remux --config docs/cli/middle.json --dry-run
Muxiveo-cli batch --template docs/cli/complexe-toutes-options-template.json --batch docs/cli/complexe-toutes-options-batch.json --force
Muxiveo-cli batch --template template.json --batch batch.json --dry-run --log-format jsonl
Muxiveo-cli batch --template template.json --batch batch.json --summary summary.json
Muxiveo-cli batch --template exact-job.json --input-dir "Serie/Saison 01" --output-dir "out/Saison 01" --dry-run
Muxiveo-cli batch --template exact-job.json --input-dir "Serie" --recursive --include "*.mkv" --exclude "*sample*" --output-dir "out"
Muxiveo-cli batch --template exact-job.json --input-dir "Serie" --recursive --output-dir "out" --auto-tmdb
Muxiveo-cli batch --template exact-job.json --input-dir "Serie" --recursive --output-dir "out" --auto-tmdb \
    --output-template "{title}.S{season}E{episode}.{episode_title}-{group}"
Muxiveo-cli preview --profile profil.json -i source.mkv --json
Muxiveo-cli run --profile profil.json -i source.mkv -o sortie.mkv
Muxiveo-cli batch --profile profil.json --input-dir "Serie" --recursive --output-dir "out" --auto-tmdb --dry-run

Inspection HDR

inspect --hdr écrit un résultat JSON sur la sortie standard. Les trois niveaux correspondent aux examens de HDR Studio :

Niveau Contenu
static En-têtes et contrôles de cohérence disponibles sans lecture dynamique
dynamic Ajoute la lecture du RPU Dolby Vision et du HDR10+ lorsqu’ils sont présents
measure Ajoute la mesure de chaque image de la couche de base ; HEVC PQ et mvo-fel 0.4.0 ou plus récent requis, hors Profil 5 
Muxiveo-cli inspect film.mkv --hdr static
Muxiveo-cli inspect film.mkv --hdr dynamic --hdr-report rapport.html
Muxiveo-cli inspect film.mkv --hdr measure --hdr-report mesures.json
Muxiveo-cli inspect edition-a.mkv edition-b.mkv --hdr dynamic --hdr-compare --hdr-report comparaison.html
Option Usage
--hdr-track N Index FFprobe de la piste vidéo ; première piste vidéo par défaut
--hdr-report FICHIER Rapport HTML avec .html/.htm, JSON sinon ; une source ou deux avec --hdr-compare
--hdr-compare Compare exactement deux sources, A puis B, sans les modifier
--hdr-offset N Décalage de B en images pour la comparaison ; automatique si omis
--hdr-fast Avec --hdr measure : mesure accélérée sur images clés (mvo-fel ≥ 0.5.0)
--hdr-fel FEL Analyzer : apport réel de la couche FEL d'une source Dolby Vision profil 7 (mvo-fel ≥ 0.4.0)
--hdr-fel-interval SEC Avec --hdr-fel : fréquence d'échantillonnage en secondes (défaut : 30 ; 60 rapide, 10 fin)
--hdr-fel-survival ENC:KBPS Avec --hdr-fel : test de survie à l'encodage (ex. libx265:35000)
--hdr-fel-min NIVEAU Avec --hdr-fel : renvoie 3 si le verdict est inférieur au niveau (moderate, useful)
--hdr-no-cache Force la relecture des métadonnées et la nouvelle mesure demandées
--hdr-fail-on warn Renvoie 3 dès qu’un contrôle atteint avertissement ou erreur
--hdr-fail-on error Renvoie 3 uniquement pour une erreur de contrôle ou d’analyse

Les données mises en cache peuvent enrichir un rapport même au niveau static. Les niveaux indiquent le travail demandé, pas une suppression des résultats déjà connus. La commande d’inspection n’écrit pas de vidéo corrigée.

Sous-titres embarqués EIA-608/708

Pour les vidéos où ils sont détectés, les commandes de remuxage, batch et hybridation acceptent --remove-closed-captions et --no-remove-closed-captions. Ces options retirent ou conservent les sous-titres embarqués sans réencoder l’image ; elles ne touchent pas au texte incrusté dans les pixels.

Muxiveo-cli remux -i source.mkv -o sans-cc.mkv --remove-closed-captions
Muxiveo-cli hybrid --ref reference.mkv --donor donneur.mkv -o sorties/ --auto-sync --no-remove-closed-captions

Dans un job JSON, le champ remove_closed_captions se place sur l’édition de la piste vidéo, par exemple :

{"tracks": [{"source": 0, "id": 0, "remove_closed_captions": true}]}

Adaptez les index à l’inspection de votre source. Une option CLI explicite prend le dessus sur les réglages des pistes détectées.

Contrat JSON

Les deux contrats publics principaux sont :

  • kind: "exact-job", version: 1 pour un traitement strict;
  • kind: "decision-profile", version: 1 pour l'automapping low-code.

Le schéma peut être exporté avec Muxiveo-cli schema.

Job minimal :

{
  "version": 1,
  "kind": "exact-job",
  "sources": [
    {"path": "source.mkv"}
  ],
  "output": "sortie.mkv"
}

La sortie remux est exclusivement .mkv. Le champ additif mux_backend est facultatif et son absence conserve tous les jobs v1 existants :

{
  "version": 1,
  "kind": "exact-job",
  "sources": [{"path": "source.mkv"}],
  "output": "sortie.mkv",
  "mux_backend": "auto"
}
  • auto inspecte le plan complet, choisit le writer natif lorsqu'il peut tenir le contrat et journalise tout repli FFmpeg avec sa raison exacte ;
  • native est strict et ne replie jamais ;
  • ffmpeg conserve le chemin historique.

--mux-backend auto|native|ffmpeg surcharge le job pour validate, preview, run, remux, batch et les variantes basées sur un profil. La préférence persistée [matroska] mux_backend = auto ne remplace pas un choix explicite du job.

sources

Chaque source peut être une chaîne ou un objet :

{
  "path": "source.mkv",
  "attachments": "none",
  "copy_tags": false
}

attachments accepte :

  • "none" ou false;
  • "all" ou true;
  • une liste de noms ou indices.

decision-profile

Un profil décisionnel ne contient ni source ni sortie. Il décrit des règles réutilisables :

{
  "version": 1,
  "kind": "decision-profile",
  "name": "VF + VO",
  "variables": {
    "aliases": {
      "*": {
        "EAC3": "DDP",
        "AC3": "Dolby Digital"
      },
      "lang_name": {
        "French": "Français"
      }
    }
  },
  "groups": [
    {"id": "audio", "label": "Audio", "enabled": true, "priority": 200}
  ],
  "rules": [
    {
      "id": "rename_fr",
      "label": "Renommer VF",
      "group_id": "audio",
      "priority": 100,
      "write_mode": "priority",
      "scope": "all",
      "match": {
        "all": [
          {"field": "type", "op": "is", "value": "audio"},
          {"field": "language", "op": "is", "value": "fr-FR"},
          {"field": "source_title", "op": "contains", "expr": "(VFQ | VFF) & !Commentary", "required": false}
        ]
      },
      "actions": [
        {"type": "set_enabled", "value": true},
        {"type": "set_title", "pattern": "{lang_name} {codec} {channels} {audio_object}"},
        {"type": "remove_track_tags", "value": ["old_tag"]}
      ]
    }
  ]
}

write_mode définit ce qui se passe si plusieurs règles écrivent le même champ :

  • "priority" : la plus forte priorité gagne; une priorité égale reste un conflit;
  • "override" : cette règle remplace une valeur déjà proposée;
  • "add" : cette règle complète sans écraser; pour un titre, le fragment est ajouté.

Les expressions acceptent aussi ! en raccourci et NOT(...) pour exclure un critère. Le keyword {none} cible une valeur vide dans le champ courant. Les actions remove_track_tags sont appliquées avant les add_track_tags de la même règle.

Les conditions peuvent utiliser soit value, soit expr. expr accepte la même syntaxe que l'éditeur de profils :

{"field": "source_title", "op": "contains", "expr": "(VFQ | VFF) & Forced"}

Dans une expression :

  • & signifie AND;
  • | signifie OR;
  • les parenthèses fixent la priorité;
  • les atoms {atmos} ou {dtsx} ciblent les keywords booléens correspondants;
  • les champs restent combinés entre eux par AND dans un bloc all.

Pour chercher &, |, ( ou ) comme texte réel, utilisez des guillemets ou un échappement :

{"field": "source_title", "op": "contains", "expr": "\"A | B\" | Dolby \\& DTS"}

Une condition qui contient à la fois value et expr est invalide.

Commandes :

Muxiveo-cli validate --profile profil.json
Muxiveo-cli preview --profile profil.json -i source.mkv --json
Muxiveo-cli run --profile profil.json -i source.mkv -o sortie.mkv
Muxiveo-cli batch --profile profil.json --input-dir "Serie" --recursive --output-dir "out"

--profile accepte soit un chemin complet, soit le nom d'un profil enregistré dans <dossier de config muxiveo>/profiles/decision/. L'extension .json est optionnelle : --profile BestOfAll cherchera aussi BestOfAll.json.

Keywords de renommage disponibles :

{type} {source_index} {track_index}
{language} {lang} {lang_name} {source_language}
{title} {source_title}
{codec} {codec_raw} {codec_name} {channels} {channel_layout} {audio_object} {atmos} {dtsx}
{resolution} {width} {height} {hdr} {video_flags_hex}
{video_hdr} {video_hdr10} {video_hdr10plus}
{video_dolby_vision} {video_hlg} {video_sdr}
{flags} {flag_enabled} {flag_default} {flag_forced}
{flag_hearing_impaired} {flag_visual_impaired}
{flag_original} {flag_commentary}
{track_tags}

variables.aliases remplace des valeurs au rendu des patterns de titre et des templates de sortie :

{
  "variables": {
    "aliases": {
      "*": {"EAC3": "DDP"},
      "lang_name": {"French": "Français"}
    }
  }
}
  • * est global.
  • lang_name, codec, codec_name, etc. ciblent un keyword précis.
  • priorité : alias ciblé > alias global > valeur originale.
  • matching insensible à la casse et aux espaces de bord.
  • pas de remplacement récursif.
  • les aliases n'affectent pas les critères décisionnels.

variables.codec_names reste lu pour compatibilité avec les anciens profils, mais les nouveaux profils doivent utiliser variables.aliases. Pour forcer le codec technique brut, utilisez {codec_raw}.

{lang_name} masque la région pour la variante d'origine et la conserve entre parenthèses pour les variantes régionales non standard :

Langue {lang_name}
fr-FR French
fr-CA French (Canada)
pt-PT Portuguese
pt-BR Portuguese (Brazil)

tracks

Les edits explicites modifient une piste ciblée par index ou par sélecteur :

{
  "tracks": [
    {
      "source": 0,
      "id": 2,
      "enabled": true,
      "language": "fr-FR",
      "title": "French EAC3 5.1 Atmos",
      "flags": {"default": true},
      "time_shift_ms": 0,
      "sync_calibration": {
        "segments": [{"source_time_ms": 0, "shift_ms": -120}]
      }
    }
  ]
}
  • sync_calibration (objet facultatif) : définit une synchronisation propre à la piste, prioritaire sur celle de sa source. Le panneau Conteneur l'écrit notamment pour un sous-titre synchronisé de façon autonome avec sync_subtitles: "none" (coupures ou cadence) : le sous-titre est réécrit selon cette calibration, tandis que l'audio de sa source reste calé selon la sienne.
  • position_order: "source" : lorsqu'un sélecteur de piste utilise un critère de position ("position": N), la valeur "position_order": "source" garantit que l'indice correspond au rang d'origine de la piste dans sa source (parmi les pistes de même type), sans être perturbé par les réordonnancements ou les variantes audio synthétiques créées en cours de route.

track_order

track_order permet de fixer l'ordre de sortie après filtrage. Chaque entrée peut être un objet ou un tableau court :

{
  "track_order": [
    {"source": 0, "id": 0},
    [0, 2]
  ]
}

Les erreurs de forme sont reportees avec le chemin exact, par exemple track_order[1][1].

chapters

{
  "chapters": {
    "source_index": 0,
    "include_source": true,
    "import": "chapters.ffmetadata",
    "add": [
      {"timestamp": "00:00:00.000", "chaptername": "Opening"}
    ]
  }
}

Imports acceptes :

  • JSON avec chapters ou entries;
  • ffmetadata;
  • OGM simple.

tmdb

TMDB est opt-in. Aucun appel réseau n'est fait si tmdb est absent ou faux.

{
  "tmdb": {
    "enabled": true,
    "kind": "tv",
    "query": "Series",
    "season": "1",
    "episode": "1",
    "language": "fr-FR"
  }
}

Si id ou tmdb_id est présent, cet ID est utilisé. Sinon, le premier résultat de recherche est retenu. Dans un JSON réutilisable, season et episode peuvent valoir "auto" pour être relus depuis le nom de chaque source. Les booléens auto_detect_episode et auto_metadata correspondent au comportement activé par --auto-tmdb : détection source prioritaire, puis remplacement des métadonnées TMDB statiques exportées par le GUI.

En CLI, --auto-tmdb active la recherche TMDB sans modifier le JSON. La requête est déduite du nom de fichier, le premier résultat est retenu, et Muxiveo détecte automatiquement S01E02 ou 01x02 pour renseigner saison et épisode. Si le template vient d'un export GUI et contient déjà le titre, les tags TMDB ou tmdb.season / tmdb.episode du premier épisode, --auto-tmdb les régénère pour chaque fichier traité. --tmdb reste disponible comme alias historique.

Options utiles :

Option Effet
--auto-tmdb cherche TMDB et applique tags + titre conteneur + cover
--tmdb-id ID utilise un ID TMDB précis au lieu de choisir le premier résultat
--tmdb-apikey KEY surcharge la clé API TMDB (priorité sur la config Muxiveo et le JSON job)
--no-cover applique les tags TMDB mais n'ajoute pas la cover
--no-attach n'inclut aucun attachment source, aucun extra attachment, ni cover TMDB

Sans --tmdb-apikey, la clé est lue dans ~/.config/muxiveo/config.ini (metadata/tmdb_api_key ou tmdb_bearer_token). À défaut, la variable d'environnement MUXIVEO_TMDB_BEARER_TOKEN puis un token Bearer embarqué servent de repli (parité GUI), donc --auto-tmdb fonctionne sans configuration préalable.

Exemple batch :

Muxiveo-cli batch \
  --template exact-job.json \
  --input-dir "Serie" \
  --recursive \
  --output-dir "out" \
  --auto-tmdb

Avec un profil décisionnel :

Muxiveo-cli batch \
  --profile BestOfAll \
  --input-dir "Serie" \
  --recursive \
  --output-dir "out" \
  --auto-tmdb \
  --no-cover

Depuis un exact-job exporté par le GUI pour un épisode de série, utilisez --auto-tmdb et un template de sortie pour rendre le titre conteneur, les tags SEASON/EPISODE/SUBTITLE/SYNOPSIS et le nom de fichier dynamiques : Les exports de l’interface contiennent un bloc tmdb désactivé avec season: "auto" / episode: "auto" quand ils détectent des tags de série ; --auto-tmdb l'active pour le batch.

Muxiveo-cli batch \
  --template "/chemin/vers/serie1.S01E01.MULTi.VF2.HDR.DV.2160p.WEB.H265-SUPPLY-MVO.exact-job.json" \
  --input-dir "/chemin/vers/telechargements/serie1.S*E*.MULTi.VF2.HDR.DV.2160p.WEB.H265-SUPPLY" \
  --output-dir "/chemin/vers/videos/serie1" \
  --auto-tmdb \
  --output-template "{title:release}.{season_episode}.{episode_title:release}.{audio-multi}.{audio-fr-tag}.{video-resolution:best}.{video-source}.{video-hdr:best}.{video-dolby-vision}.{video-codec-release:best}-{group}" \
  --dry-run

--input-dir accepte aussi les globs de dossiers ; l'exemple ci-dessus crée un job pour les MKV présents dans chaque dossier serie1.SxxEyy....

batch

Le batch fusionne chaque job avec le template :

{
  "jobs": [
    {
      "sources": [{"path": "S01E01.mkv"}],
      "output": "S01E01.remux.mkv",
      "tmdb": {"episode": "1"}
    }
  ]
}

Le fichier batch est validé avant le premier job. Les entrées de jobs ou inputs doivent être des objets job ou des chemins texte.

Le batch peut aussi créer les jobs depuis un dossier :

Muxiveo-cli batch \
  --template exact-job.json \
  --input-dir "Serie" \
  --recursive \
  --output-dir "out" \
  --dry-run

Dans ce mode, chaque fichier vidéo/conteneur compatible devient un job. Les fichiers audio seuls et sous-titres seuls sont ignorés. Le parcours des sous-dossiers est activé uniquement avec --recursive.

Filtres disponibles :

Option Effet
--input-dir DIR ajoute un dossier à scanner ; option répétable
--recursive inclut les sous-dossiers
--include GLOB limite les fichiers retenus ; option répétable
--exclude GLOB ignore les fichiers correspondants ; option répétable
--output-dir DIR génère les sorties en .mkv sous ce dossier

Avec --recursive et --output-dir, l'arborescence relative est conservée :

Serie/Saison 01/E01.mkv  ->  out/Saison 01/E01.mkv
Serie/Saison 02/E01.mkv  ->  out/Saison 02/E01.mkv

--batch FILE ne se mélange pas avec -i/--input ou --input-dir : utilisez soit le batch JSON, soit le mode direct.

output_template — composer le nom de sortie

--output-template (ou le champ JSON output_template) permet de composer le nom du fichier de sortie à partir de placeholders alimentés par TMDB et par parsing du nom de fichier source. L'option est disponible sur toutes les sous-commandes.

Muxiveo-cli batch \
  --template exact-job.json \
  --input-dir "Serie" --recursive --output-dir "out" --auto-tmdb \
  --output-template "{title}.S{season}E{episode}.{episode_title}.{year}-{group}"

Muxiveo-cli batch \
  --profile BestOfAll --input-dir "Films" --output-dir "out" \
  --output-template "{title:release}.{year}.{audio-multi}.{audio-fr-tag}.{audio-codec-release:best}.{audio-channels:best}.{audio-immersive}.{video-source}.{video-resolution:best}.{video-10bit}.{video-hdr:best}.{video-dolby-vision}.{video-codec-release:best}-{group}"

Tokens disponibles :

Token Source Exemple
{source_name} nom du fichier source sans extension Serie1.2025.S01E02.MULTi.1080p.WEB.x264
{title} titre TMDB (film ou série) Serie1
{title:release} titre TMDB normalisé release ASCII à points Serie1
{year} année TMDB 2025
{episode_title} titre d'épisode TMDB Pilote
{episode_title:release} titre d'épisode normalisé release ASCII à points Le.Pilote
{season} saison zéro-paddée 2 chiffres 01
{episode} épisode zéro-paddé 2 chiffres 02
{season_num} saison brute (int) — combinable :03d 1
{episode_num} épisode brut (int) 2
{season_episode} code combiné style scene S01E02
{group} tag de release extrait du nom source RARBG, NTb
{audio-lang:best} / {audio-lang:all} langue(s) audio des pistes finales fr-FR, fr-FR+en-US
{audio-lang-name:all} nom(s) de langue audio régionalisés French+French (Canada)
{sub-lang:all} langue(s) sous-titres des pistes finales fr-FR+en-US
{audio-multi} MULTi si plusieurs familles audio MULTi
{audio-fr-tag} tag FR audio final VFF, VFQ, VF2
{sub-vostfr} VOSTFR si sous-titre FR sans audio FR VOSTFR
{audio-codec-release:best} meilleur codec audio release TrueHD, DDP
{audio-channels:best} meilleurs canaux audio 7.1, 5.1
{audio-immersive} audio immersif final Atmos
{video-source} source extraite du nom source BluRay, WEB
{video-resolution:best} meilleure résolution vidéo release 2160p
{video-10bit} tag 10 bits si détecté ou implicite HDR10+/DV 10Bits
{video-hdr:best} meilleur HDR release HDR10P, HDR, HLG
{video-dolby-vision} tag Dolby Vision DV
{video-codec-release:best} codec vidéo release x265, x264, AV1

Règles :

  • Priorité : --output / -o explicite > --output-template (rendu) > output direct (job/JSON).
  • Texte libre mélangeable avec les tokens : "{title}.{year}.texte libre.{group}".
  • Keywords pistes : les préfixes canoniques sont video-*, audio-*, sub-*; subtitle-* et les variantes _ sont acceptés en alias.
  • Décisions : les keywords pistes se basent sur les pistes finales activées, après profil ou edits exact-job. Les modifiers disponibles sont :best, :first et :all; :best est le défaut.
  • Aliases : variables.aliases s'applique aussi aux keywords de pistes rendus par --output-template. Par exemple {audio-codec:best} peut rendre DDP avec {"variables": {"aliases": {"*": {"EAC3": "DDP"}}}}.
  • --output-all : force les keywords pistes en mode all, même si le template contient :best ou aucun modifier.
  • Tokens inconnus rendent une chaîne vide (pas d'erreur).
  • Nettoyage release : les segments vides sont compactés pour éviter les doubles points ou les séparateurs .- / -..
  • Extension : si le template ne se termine pas par une extension vidéo connue (.mkv, .mp4, .m4v, .mov, .avi, .webm, .mka, .m4a, .ts, .m2ts), .mkv est ajouté automatiquement.
  • Sanitization : les caractères interdits filesystem (/ \ : * ? " < > |) présents dans les valeurs de tokens sont remplacés par ..
  • Batch + --output-dir : le template est résolu dans --output-dir. Si le template ne discrimine pas deux sources (collision de sortie rendue), une erreur explicite est levée et le batch s'arrête (sauf --continue-on-error).
  • Sans TMDB : {source_name} et {group} restent utilisables ; les tokens TMDB rendent vide.

Le champ peut également être posé dans le JSON job :

{
  "version": 1,
  "kind": "exact-job",
  "sources": [{"path": "S01E02.mkv"}],
  "output_template": "{title}.S{season}E{episode}.{episode_title}-{group}",
  "output_all": false,
  "tmdb": {"enabled": true}
}

--output-template en ligne de commande surcharge la valeur JSON.

Avec --summary FILE, le batch ecrit un rapport JSON final :

{
  "total": 1,
  "successes": 1,
  "failures": 0,
  "exit_code": 0,
  "jobs": [
    {
      "job_index": 0,
      "input": "S01E01.mkv",
      "output": "S01E01.remux.mkv",
      "status": "success",
      "exit_code": 0
    }
  ]
}

Sorties JSON de validation et preview

validate --json et preview --json gardent les mêmes codes retour que les commandes texte, mais ecrivent un objet JSON sur stdout.

Exemple preview --json :

{
  "valid": true,
  "errors": [],
  "output": "sortie.mkv",
  "sources": [{"index": 0, "path": "source.mkv"}],
  "track_order": [{"source": 0, "id": 0}],
  "selected_backend": "native",
  "plan_version": 1,
  "preparation_commands": [],
  "native_diagnostics": [],
  "execution_preview": {"backend": "native", "action": "internal_matroska_write"},
  "command": ["ffmpeg", "-hide_banner", "..."],
  "command_text": "ffmpeg \\\n    -hide_banner \\\n    ..."
}

command et la commande FFmpeg de référence restent présents pour la compatibilité des consommateurs v1. selected_backend, plan_version, execution_preview, preparation_commands et native_diagnostics décrivent l'exécution réelle. La preview texte commence par le backend choisi. En JSONL, l'événement mux_backend expose séparément le backend demandé/sélectionné, le repli, sa raison et les diagnostics.

Verbosité

Par défaut, la sortie brute de ffmpeg (lignes frame=, fps=, bitrate=, time= …) n'est pas affichée — seuls les évènements de workflow (début d'étape, fin de tâche, erreurs) le sont. Pour suivre la progression ffmpeg en direct, ajouter --verbose :

Muxiveo-cli remux -i source.mkv -o sortie.mkv --verbose
Muxiveo-cli batch --template t.json --input-dir Serie --output-dir out --verbose

--verbose s'applique à toutes les sous-commandes (remux, run, batch, profile apply, profile batch).

Codes retour

Code Signification
0 succes
2 arguments, JSON ou contrat invalide
3 validation metier echouee
4 outil externe introuvable
5 sortie existante sans --force
6 echec workflow
7 batch partiellement echoue
8 version --check : mise a jour disponible

Batch JSON Lines

Avec --log-format jsonl, le batch emet des evenements structurés :

{"level":"info","message":"Batch job 1 demarre","event":"batch_job","job_index":0,"input":"S01E01.mkv","output":"S01E01.remux.mkv","status":"started"}
{"level":"info","message":"Batch job 1 termine","event":"batch_job","job_index":0,"input":"S01E01.mkv","output":"S01E01.remux.mkv","status":"success"}
{"level":"info","message":"Batch termine : 1/1 succes.","event":"batch_summary","total":1,"failures":0}

Cas concrets et synchronisation (Remux & Hybridation)

Cette section illustre l'usage du CLI à travers des cas d'usage réels et progressifs, utilisant des désignations génériques (film1, film2, serie1, serie2).

Aide de la CLI Muxiveo — hybridation et synchronisation

Flux de décision global

flowchart TD
    Start["Fichiers multimédias d'entrée"] --> Decision{"Quel est l'objectif ?"}

    Decision -->|"Nettoyer 1 fichier, réordonner ses pistes,<br/>ou synchroniser 2 fichiers manuellement"| ModeRemux["Mode REMUX"]
    Decision -->|"Fusionner automatiquement 2 sources<br/>(Vidéo de référence + Langues d'un donneur)"| ModeHybrid["Mode HYBRID"]

    subgraph ModeRemux ["Mode REMUX (Conteneur & Synchronisation)"]
        R_In["film1.mkv (ou film1_video.mkv + film1_audio.mkv)"]
        R_In --> R_Choice{"Besoin de synchronisation ?"}
        R_Choice -->|"Non (copie directe simple)"| R_Fast["Passthrough direct natif v4"]
        R_Choice -->|"Oui (acoustique dynamique)"| R_Auto["--auto-sync<br/>--detect-cuts (coupures)<br/>--cadence-auto (PAL/Cinéma)"]
        R_Choice -->|"Oui (fichier enregistré)"| R_Manual["--calibration calibration.json"]
        R_Auto --> R_ZeroDelay["--sync-mode physical (Zero Delay)"]
        R_Manual --> R_ZeroDelay
        R_Fast --> R_Out["film1_propre.mkv"]
        R_ZeroDelay --> R_Out
    end

    subgraph ModeHybrid ["Mode HYBRID (Studio d'Hybridation v4)"]
        H_Ref["Référence : film1_ref.mkv (Vidéo 4K/VO)"]
        H_Don["Donneur : film1_donor.mkv (Audio/Subs FR)"]
        H_Ref & H_Don --> H_Core["Appariement auto + FFT acoustique<br/>+ Détection cadence et coupures"]
        H_Core --> H_Out["film1.Hybrid.mkv (Zero Delay)"]
    end
Loading

Cas 1 : REMUX unitaire et par lot avec synchronisation & détection de coupures

Le mode remux traite un fichier unique ou plusieurs flux associés. L'assemblage s'effectue via le muxer natif v4 sans réencodage vidéo. Lorsque des pistes audio doivent être recalées ou converties en cadence, Muxiveo applique une synchronisation physique propre (Zero Delay).

A. Remux avec synchronisation acoustique automatique (--auto-sync)

Dans ce cas concret, on associe une vidéo film1_video.mkv avec une piste audio externe film1_audio.mkv. On demande à Muxiveo de comparer le son pour calculer le décalage, de détecter les coupures intermédiaires (ex: passages publicitaires TV) et d'adapter la cadence :

Muxiveo-cli remux \
  -i "film1_video.mkv" \
  -i "film1_audio.mkv" \
  -o "film1_final.mkv" \
  --auto-sync \
  --detect-cuts \
  --drift-threshold-ms 25 \
  --cadence-auto \
  --cadence-method auto \
  --sync-mode physical \
  --crossfade-ms 80 \
  --auto-tmdb \
  --mux-backend native \
  --verbose
  • --auto-sync : Compare automatiquement les pistes audio pour identifier le décalage temporel initial.
  • --detect-cuts : Détecte les ruptures temporelles (coupures ou insertions) et scinde le calage en plusieurs segments.
  • --drift-threshold-ms 25 : Seuil de décalage (en ms) à partir duquel une discontinuité temporelle est considérée comme une coupure.
  • --cadence-auto : Détecte un éventuel écart de cadence (ex: source TV à 25 FPS PAL vs source vidéo à 23.976 FPS Cinéma).
  • --cadence-method auto : Analyse acoustique de la hauteur tonale (F0) pour appliquer atempo (préservation du timbre) ou asetrate (hauteur naturelle).
  • --sync-mode physical : Ajuste physiquement l'audio (coupe ou insertion de silence) pour matérialiser le calage sans décalage virtuel, selon le codec et la stratégie retenue.
  • --crossfade-ms 80 : Micro-fondu enchaîné aux points de découpe pour supprimer tout bruit ou claquement numérique.

B. Remux avec calibration manuelle préétablie (--calibration)

Si une calibration a déjà été générée (via le Synchro Studio de l'interface graphique ou via sync-scan), elle peut être injectée directement :

Muxiveo-cli remux \
  -i "film1_video.mkv" \
  -i "film1_audio.mkv" \
  -o "film1_calibre.mkv" \
  --calibration "calibration_film1.json" \
  --sync-mode physical \
  --auto-tmdb \
  --mux-backend native

C. Remux par lot pour une saison complète (batch)

Pour traiter l'ensemble des épisodes d'une série sans intervention manuelle :

Muxiveo-cli batch \
  --profile "ProfilSerie" \
  --input-dir "/chemin/sources/serie1/Saison 01" \
  --output-dir "/chemin/sorties/serie1/Saison 01" \
  --recursive \
  --auto-tmdb \
  --output-template "{title:release}.S{season}E{episode}.{episode_title:release}.MULTi.{video-resolution:best}-{group}" \
  --auto-sync \
  --detect-cuts \
  --sync-mode physical \
  --dry-run

Cas 2 : HYBRID (le Studio d’Hybridation en ligne de commande)

La commande hybrid orchestre automatiquement l'appariement d'une source de référence (qui fournit la vidéo et les chapitres) et d'une source donneuse (qui fournit l'audio et les sous-titres additionnels).

Schéma d'analyse hybride

RÉFÉRENCE (film1_ref.mkv)   : [Introduction] ── [ Scène 1 (23.976 fps) ] ── [ Scène 2 ]
DONNEUR   (film1_donor.mkv) :     [Intro TV] ── [ Scène 1 (25.000 fps) ] ── [ Scène 2 ]
                                       │
                             [ Scanner Acoustique ]
                                       │
  • Calage au départ        ──► Écart mesuré à la milliseconde près.
  • Écart de cadence        ──► Détection 25 FPS (PAL) ↔ 23.976 FPS (Cinéma).
  • Discrimination pitch    ──► Choix automatique atempo ou asetrate.
  • Découpage des coupures  ──► Alignement indépendant des segments temporels.
  • Calage des sous-titres  ──► Décalage proportionnel des pistes SRT/ASS.
                                       │
SORTIE HYBRIDE              : [Vidéo Référence 1:1] + [Audio Donneur Calé Zero Delay]

A. Hybridation d'un film unitaire

Muxiveo-cli hybrid \
  --ref "film1_ref.mkv" \
  --donor "film1_donor.mkv" \
  -o "/chemin/sorties/film1" \
  --auto-sync \
  --detect-cuts \
  --cadence-auto \
  --cadence-method auto \
  --sync-mode physical \
  --auto-tmdb \
  --tag "MVO"

B. Hybridation d'une saison complète de série

Muxiveo-cli hybrid \
  --ref-dir "/chemin/sources/serie1_ref_2160p" \
  --donor-dir "/chemin/sources/serie1_donor_1080p" \
  -o "/chemin/sorties/serie1_hybride" \
  --auto-sync \
  --detect-cuts \
  --cadence-auto \
  --cadence-method auto \
  --auto-tmdb \
  --tag "MVO"
  • Muxiveo analyse les noms de fichiers dans les deux dossiers, apparie automatiquement chaque épisode (S01E01 avec S01E01, S01E02 avec S01E02, etc.), applique l'analyse acoustique individuelle et assemble les fichiers finaux.

Cas 3 : Outils dédiés sync-scan et shift-subs

Pour tester ou dissocier l'analyse acoustique du multiplexage final :

1. Extraire une calibration acoustique sans remuxer (sync-scan)

Muxiveo-cli sync-scan \
  --ref "film1_ref.mkv" \
  --target "film1_donor.mkv" \
  --detect-cuts \
  --output-json "calibration_film1.json"

Ce fichier JSON contient les décalages mesurés, les coupures repérées et les facteurs de cadence, prêt à être réutilisé avec --calibration.

2. Recaler physiquement un fichier de sous-titres externe (shift-subs)

# Recalage par décalage linéaire fixe (+1250 millisecondes) :
Muxiveo-cli shift-subs \
  -i "film1_sous-titre.srt" \
  -o "film1_sous-titre_cale.srt" \
  --offset-ms 1250

# Ou recalage complet à partir d'un fichier de calibration multi-coupures :
Muxiveo-cli shift-subs \
  -i "film1_sous-titre.ass" \
  -o "film1_sous-titre_cale.ass" \
  --calibration "calibration_film1.json"

Documents JSON et sorties protégées

Les documents utilisateur acceptent UTF-8 avec ou sans BOM. Les chemins relatifs sont résolus depuis le dossier du JSON, ce qui permet de déplacer un projet avec ses sources. NaN et Infinity sont refusés ; les timecodes de chapitres et les valeurs énumérées doivent respecter le schéma public.

Les sorties de batch sont vérifiées avant le premier traitement : deux jobs ne peuvent pas écrire au même endroit, même avec --force. Un fichier candidat est validé avant publication. Voir Protection des fichiers.

La CLI présentée ici couvre le remuxage, l’hybridation et les profils de pistes. Les réglages d’encodage et d’interpolation du panneau graphique sont décrits dans Encodage vidéo et HDR ; ne les ajoutez pas à un job JSON sans champ correspondant dans le schéma.

Documentation utilisateur de Muxiveo · Choisir son workflow · HDR Studio · Plugins · Mises à jour · Licence

Communauté Discord Muxiveo · Code source · Soutenir Muxiveo via PayPal

Navigation

Clone this wiki locally