vid_convert/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Projet

Script Python standalone de conversion vidéo vers AV1 (libsvtav1) / Opus (libopus) en conteneur MKV, avec sélection automatique du CRF via ab-av1 crf-search (VMAF 96), support HDR10/HDR10+, détection de bandes noires, et normalisation audio.

Utilisation

./vid_convert.py <fichier_entree>
./vid_convert.py -h                   # aide
./vid_convert.py -d <fichier>         # mode debug
./vid_convert.py -s <fichier>         # avec stabilisation vidéo
./vid_convert.py -a <fichier>         # tuning animation
./vid_convert.py -c <fichier>         # restauration VHS
./vid_convert.py --interlaced <fichier>   # forcer le désentrelacement (yadif)

Pas de build, pas de tests, pas de linter configuré. Exécution directe Python 3.

Dépendances externes requises

• ffmpeg et ffprobe — encodage et extraction de métadonnées (libsvtav1 + libopus requis)
• ab-av1 — sélection automatique du CRF par crf-search (VMAF 96)
• mkvmerge (MkvToolNix) — assemblage du conteneur MKV final
• hdr10plus_parser (binaire inclus) — extraction/injection des métadonnées HDR10+

Architecture

Fichier unique : vid_convert.py. Flux d'exécution séquentiel :

1. get_infos(file) — ffprobe JSON → métadonnées vidéo/audio/sous-titres, détection HDR10+, Dolby Vision, conteneur source
2. cropping(file, infos) — cropdetect FFmpeg → suppression des bandes noires
3. volume_audio(file, infos) — volumedetect FFmpeg → ajustement par piste audio
4. find_crf(file, enc_options, hdr) — ab-av1 crf-search → CRF optimal pour VMAF 96
5. extract_subs(file, track, lang) — extraction des pistes de sous-titres
6. convert_audio(...) — encodage libopus VBR par piste (128k/320k/450k selon canaux)
7. convert_video(...) — encodage libsvtav1 (preset=3, tune=0), HDR10/HDR10+ via -svtav1-params
8. create_mkv(filename) — mkvmerge → assemblage MKV final (NEW_{basename}.mkv)

Points clés

• Sortie vidéo : yuv420p10le (10 bits), encodage en une seule passe
• HDR10 statique : mastering display + content-light via -svtav1-params
• HDR10+ : injection native SVT-AV1 via hdr10plus-json= dans -svtav1-params
• Dolby Vision : détection uniquement, fallback automatique vers HDR10 (Profile 8) ou avertissement (Profile 5)
• Les fichiers temporaires passent par /tmp/ (métadonnées HDR10+, options mkvmerge JSON)
• Le filtre VHS combine hqdn3d + unsharp
• La stabilisation utilise vidstabdetect + vidstabtransform en deux passes

Gotchas

• libsvtav1 + libopus requis : le binaire FFmpeg doit être compilé avec --enable-libsvtav1 et --enable-libopus. Vérifier avec ffmpeg -codecs | grep -E 'svt|opus'.
• ab-av1 dans le PATH : ab-av1 crf-search doit être accessible. En cas d'échec, fallback automatique sur CRF 32.
• Fichier de sortie : NEW_{nom_source}.mkv, généré dans le même répertoire que la source. Les fichiers temporaires (_video.mkv, _audio_*.mka, _subtitle_*.mkv) sont supprimés après assemblage.
• Fichiers temporaires orphelins : en cas d'interruption, les intermédiaires peuvent rester dans le répertoire de la source. Les supprimer manuellement si besoin.
• HDR10+ et conteneur source : hevc_mp4toannexb est appliqué uniquement pour les sources MP4/MOV (pas MKV) lors de l'extraction HDR10+ par hdr10plus_parser.
• --animation non fonctionnel : le flag est parsé mais n'a pas d'effet (tune=0 est utilisé pour tous les contenus). Conservé pour compatibilité future.