Rust FFmpeg
Guide pour implémenter des fonctionnalités FFmpeg en Rust : sélection de bibliothèque, génération de code et résolution de problèmes.
Cadre de sélection
| Bibliothèque | Quand l'utiliser | Async | Sécurité | Compromis |
|---|---|---|---|---|
| ez-ffmpeg | Tâches générales, migration CLI, serveur RTMP, filtres GPU personnalisés Rust + WGSL, incrustation de sous-titres native, détection/mesure, recettes ponctuelles, I/O personnalisé, export de trames/échantillons en mémoire + poussée de trames (VideoWriter), progression typée par sortie | ✅ Oui | Sûre | Nécessite les bibliothèques FFmpeg |
| ffmpeg-next | Contrôle au niveau des trames, internes des codecs, I/O de flux sécurisé (tout Read/Write/Seek) | ❌ Non | Sûre | Plus de code standard |
| ffmpeg-sys-next | Zéro-copie, I/O mémoire personnalisé, performances maximales | ❌ Non | Non sûre | Gestion manuelle de la mémoire |
| ffmpeg-sidecar | Aucune installation FFmpeg possible | ❌ Non | Sûre | Surchage de processus, pas d'I/O personnalisé |
Logique de décision
Couche 1 : Méthode d'intégration
Par défaut : Intégration de bibliothèque (ez-ffmpeg/ffmpeg-next/ffmpeg-sys-next)
- Meilleures performances, API typée sécurisée, accès direct aux trames
Alternative : Approche binaire (ffmpeg-sidecar) - à considérer quand :
- Impossible d'installer les bibliothèques de développement FFmpeg
- Environnement CI/CD restreint sans accès administrateur
- Traitement par lots CLI pur (sans besoin temps réel)
Si installation contrainte → Charger ffmpeg_sidecar.md
Couche 2 : Détection de scénario
| L'utilisateur mentionne | Charger la référence |
|---|---|
| "convertir format", "remuxer", "découper", "redimensionner", "rognage", "simple" | video_transcoding.md |
| "extraire audio", "audio uniquement", "piste audio", "extraire mp3", "loudnorm", "normaliser audio", "volume" | audio_extraction.md |
| "miniature", "première image", "miniature rapide", "skip_frame", "nokey", "uniquement les images-clés", "sorties multiples", "concaténer", "filigrane", "pipeline", "graphe de filtres" | pipelines_multi_output.md — pour une miniature ponctuelle, préférer recipes::thumbnail dans image_sequences.md ; pour le chemin le plus rapide avec seulement les images-clés (skip_frame=nokey, accroche à l'image-clé suivante) voir ez_ffmpeg/video.md |
| "temps réel", "RTMP", "HLS", "en direct", "stream", "capture", "webcam", "tampon", "contre-pression", "tampon de gigue", "gigue réseau", "échelle ABR", "échelle HLS", "débit adaptatif", "playlist maître", "packaging VOD" | streaming_rtmp_hls.md |
| "GPU", "NVENC", "VideoToolbox", "matériel", "VAAPI", "QSV", "wgpu", "WGSL", "shader personnalisé", "filtre GPU", "shader de calcul", "libplacebo", "filtre de beauté", "incrustation chromatique", "fond vert" | hardware_acceleration.md |
| "par lots", "plusieurs fichiers", "en masse", "parallèle" | batch_processing.md |
| "sous-titres", "srt", "sous-titres codés", "incruster sous-titres", "incrustation", "sous-titres durs", "ass", "vtt", "sous-titres natifs", "sans libass", "pas de libass" | subtitles.md |
| "AV1", "AVIF", "HDR", "10 bits", "codec moderne", "HDR vers SDR", "mappage de tons", "tonemap", "couleurs délavées", "PQ", "HLG" | modern_codecs.md |
| "déboguer", "ffprobe", "inspecter", "métadonnées", "erreur", "dépanner", "sonder", "durée", "résolution", "corrompu", "intégrité" | debugging.md |
| "détecter images noires", "détection silence", "détection scène", "changement de scène", "cropdetect", "EBU R128", "LUFS", "mesurer le volume", "pic réel", "analyse de contenu", "CQ", "blackdetect", "silencedetect" | detection_analysis.md (API analysis typée) |
| "filtre", "effet", "échelle", "rognage", "superposition", "filigrane", "flou", "accentuation", "couleur", "luminosité", "rotation", "retournement", "fondu", "vitesse", "ralenti" | filters_effects.md |
| "séquence d'images", "extraction de trames", "vidéo vers images", "images vers vidéo", "timelapse", "image par image", "planche de sprites", "storyboard", "planche contact", "grille de miniatures" | image_sequences.md |
"recette ponctuelle", "module recipes", "miniature rapide", "recette miniature", "recette planche de sprites", "recette gif", "recette échelle HLS" (ez-ffmpeg recipes, sans indicateur de fonctionnalité) | image_sequences.md (miniature/sprite), gif_creation.md (gif), streaming_rtmp_hls.md (échelle HLS) |
| "test", "valider", "vérifier", "fichier de référence", "somme de contrôle", "générer vidéo de test", "testsrc" | testing.md |
| "serveur web", "API", "S3", "tâche asynchrone", "intégration", "tracing", "journalisation", "rappel de journal", "av_log", "redirection de journal" | integration.md |
| "gif", "gif animé", "vidéo vers gif", "gif à partir de vidéo", "boucle gif", "palette gif" | gif_creation.md |
| "métadonnées", "chapitre", "balise", "informations média", "titre", "artiste", "album", "marqueur de chapitre" | metadata_chapters.md |
| "capture d'écran", "webcam", "capture caméra", "enregistrer écran", "avfoundation", "directshow", "v4l2", "capture périphérique" | capture.md |
| "AVPacket", "AVFrame", "image-clé", "GOP", "NALU", "flux binaire", "EAGAIN", "boucle de décodage", "mémoire", "paquet" | ffmpeg_next.md + ffmpeg_sys_next.md |
| "avformat_find_stream_info", "AVSEEK_SIZE", "AVFormatContext", "AVCodecID", "API C brute", "FFI" | ffmpeg_sys_next.md + custom_io.md |
| "I/O personnalisé", "rappel de lecture", "rappel d'écriture", "StreamIo", "entrée/sortie mémoire", "source Read/Write/Seek" | API sécurisées : advanced.md (rappels ez-ffmpeg) ou ffmpeg_next.md (StreamIo) |
| "AVIOContext", "contexte IO", "rappel IO brut", "I/O personnalisé zéro-copie" | custom_io.md (FFI non sécurisée) |
| "extraire trames en mémoire", "décoder en RGB", "trames pour IA/ML", "trame vers tenseur", "export de trame", "vidéo en trames pour un modèle", "FrameExtractor", "whisper PCM", "audio en f32", "SampleExtractor", "ingestion ASR", "N trames uniformes" | frame_io.md (expérimental, ez-ffmpeg 0.14) |
| "VideoWriter", "pousser des trames", "générer vidéo à partir de trames", "vidéo procédurale", "restituer trames en vidéo", "mp4 en mémoire", "encoder depuis la mémoire", "trames vers vidéo" | frame_io.md (expérimental, ez-ffmpeg 0.14) |
| "WHIP", "sortie WebRTC", "sortie SRT", "sonde de capacité", "is_muxer_available", "protocole de sortie disponible", "fMP4 HLS", "segments mp4 fragmentés" | streaming.md (WHIP/SRT/capacités) + streaming_rtmp_hls.md (échelle fMP4) |
| "export de paquets encodés", "récepteur de paquets", "PacketSink", "webcodecs", "EncodedVideoChunk", "EncodedAudioChunk", "unités d'accès h.264", "trames aac", "avcC", "AudioSpecificConfig", "packetizer rtp", "segmenteur fmp4", "échec de tâche", "on_job_failed", "JobFailureSummary" | packet_sink.md (expérimental, ez-ffmpeg 0.15 ; résumés d'échec de tâche 0.16) |
| "progression", "barre de progression", "pourcentage terminé", "ETA", "avancement", "vitesse d'encodage", "progress_handle", "ProgressHandle", "instantané de progression" | advanced.md ; comptage par fichier pour lots : batch_processing.md |
| "encodeur par flux", "codec différent par flux", "StreamMap", "-c:v:0", "options de flux indexées", "options de codec par flux" | video.md (ez-ffmpeg 0.16) |
| "exécuter commande ffmpeg en rust", "from_cli_args", "emit_rust_code", "traduire commande ffmpeg", "fonctionnalité cli", "cli-compat", "forme vérifiée" | cli_compat.md (fonctionnalité cli) ; mappage manuel : cli_migration.md |
| "compatibilité de version", "FFmpeg 7 vs 8", "erreur de liaison", "échec de compilation", "links = ffmpeg", "installer", "vcpkg" | installation.md |
| "quelle bibliothèque", "comparer", "vs", "migrer vers", "porter vers", "convertir vers", "passer de", "réécrire avec", "faisabilité", "devrais-je utiliser", "meilleure bibliothèque", "évaluer", "réviser du code FFmpeg", "cela peut-il fonctionner avec" | library_selection.md |
Plusieurs lignes peuvent correspondre à une seule requête — chargez toutes les références applicables, puis suivez d'abord la cible de la ligne la plus spécifique.
Couche 3 : Sélection de bibliothèque
Migration CLI : ez-ffmpeg et ffmpeg-sidecar prennent en charge les API de style CLI. Choisissez en fonction des contraintes ci-dessous.
- ez-ffmpeg : Guide de migration CLI — intégration de bibliothèque, performances natives
- ffmpeg-sidecar : Migration CLI vers Rust — wrapper de processus, aucune bibliothèque FFmpeg nécessaire
- Besoin d'async/await ? → ez-ffmpeg (seule bibliothèque avec async natif)
- Besoin de traitement de trames Rust personnalisé ? → ez-ffmpeg FrameFilter (API sécurisée et simple)
- Besoin de shaders GPU personnalisés (WGSL) ? → fonctionnalité
wgpud'ez-ffmpeg (WgpuFrameFilter, sans tête, sans serveur d'affichage) — vérifiez d'abord le catalogue intégréwgpu_filter::effects(13 effets typés, 0.13+) ; pour les filtres matériels natifs (scale_cuda/scale_vaapi/libplacebo), sondez avecget_gpu_filter_backends() - Besoin d'incruster des sous-titres sans libass ? → fonctionnalité
subtitled'ez-ffmpeg (SubtitleFilter, rendu ASS/SRT pur Rust, pas de--enable-libass) - Besoin de détection/mesure typée (noir/silence/scène/rognage/EBU R128) ? → module
analysisd'ez-ffmpeg (Analysisponctuel ouMetadataEventFilteren flux — sans indicateur de fonctionnalité) - Besoin d'une miniature / planche de sprites / GIF / échelle ABR HLS ponctuelle ? → module
recipesd'ez-ffmpeg (sans indicateur de fonctionnalité) - Besoin de contrôle du codec au niveau des trames ? → ffmpeg-next pour les internes des codecs
- Besoin d'I/O personnalisé depuis la mémoire ? → ez-ffmpeg (rappels read/write/seek), ou ffmpeg-next sécurisé I/O de flux (
input_from_stream/output_to_stream, toutRead/Write/Seek) ; ffmpeg-sys-next pour le contrôle le plus bas niveau - Besoin de zéro-copie ou de performances maximales ? → ffmpeg-sys-next (nécessite du code non sécurisé)
- Impossible d'installer les bibliothèques FFmpeg ? → ffmpeg-sidecar (basé sur processus, stdin/stdout uniquement, pas d'I/O personnalisé)
- Besoin de trames/audio décodés en mémoire pour IA/CV/ASR ? →
frame_exportd'ez-ffmpeg (FrameExtractor→ RGB compressé,SampleExtractor::for_whisper→ 16 kHz mono f32 ; sans indicateur de fonctionnalité ; expérimental, 0.14) — voir frame_io.md - Besoin de générer/pousser une vidéo à partir de trames rendues en Rust ? →
VideoWriterd'ez-ffmpeg (poussée de trames dans encodage/muxage/flux, sans démultiplexeur ; expérimental, 0.14) — voir frame_io.md - Besoin d'alimenter un décodeur WebCodecs, un packetizer RTP/SRT ou un segmenteur fMP4 fait maison directement depuis l'encodeur ? →
packet_sinkd'ez-ffmpeg (PacketSink, niveau strict H.264 uniquement/AAC, sans conteneur ; sans indicateur de fonctionnalité ; expérimental, 0.15) — voir packet_sink.md - Besoin d'exécuter ou de traduire automatiquement une commande ffmpeg CLI existante ? → fonctionnalité
clid'ez-ffmpeg (from_cli_args/emit_rust_code, sous-ensemble restreint testé avec des golden — 6 formes vérifiées ; 0.15) — voir cli_compat.md ; tout ce qui est en dehors de ce sous-ensemble nécessite toujours les tableaux manuels de cli_migration.md
Remarque : FrameFilter (traitement de trames Rust personnalisé) est distinct des rappels I/O personnalisés (sources/puits de données personnalisées). ez-ffmpeg prend en charge les deux.
Démarrage rapide
Nouveau dans Rust FFmpeg ? Voir quick_start.md pour une configuration en 5 minutes.
Références de bibliothèques
- ez-ffmpeg - API de haut niveau (synchrone et asynchrone)
- ffmpeg-next - API de niveau intermédiaire pour un contrôle avancé
- ffmpeg-sys-next - FFI non sécurisée de bas niveau
- ffmpeg-sidecar - Wrapper CLI
Compatibilité des versions
| Bibliothèque | Version | FFmpeg | Rust MSRV |
|---|---|---|---|
| ez-ffmpeg | 0.18.0 | 7.1–8.x | 1.80+ (wgpu : 1.85+) |
| ffmpeg-next | 8.1.0 | 7.0–8.x | non spécifié |
| ffmpeg-sys-next | 8.1.0 | 7.0–8.x | non spécifié |
| ffmpeg-sidecar | 2.5.2 | Tout | 1.79+ |
Source : crates.io
FFmpeg 7 vs 8 : les quatre bibliothèques se compilent avec les deux versions majeures avec les versions actuelles ci-dessus — pas de correspondance majeure-de-caisse à majeure-du-système. Attention : lorsque vous utilisez ffmpeg-next en parallèle d'ez-ffmpeg, conservez-le à 8.1.0 — un 7.1.0 mélangé entre en collision via la clé links = "ffmpeg". Les mécanismes de Bindgen, la justification de l'épinglage 7.1 hérité et l'historique rust-ffmpeg #246 : voir installation.md.
Problèmes d'installation : installation.md — inclut le correctif Windows vcpkg avec lien statique unresolved external symbol (bibliothèques système supplémentaires dans le build.rs de votre application ; VCPKG_ROOT doit être défini dans le shell, pas via std::env::set_var dans build.rs)
Directives pour Claude
Lorsque ce skill est activé, suivez ce flux de travail :
Pour les tâches d'implémentation :
- Identifier la tâche — Déterminer : vidéo/audio/streaming/inspection ? Simple ou complexe ?
- Sélectionner la bibliothèque — Appliquer la logique de décision de la Couche 3. Indiquer quelle bibliothèque et pourquoi en une phrase
- Charger les références — Suivre la détection de scénario de la Couche 2 pour charger les fichiers de référence appropriés
- Générer le code — Prêt pour la production : gestion d'erreur appropriée,
…
[coupé pour la traduction]