Was macht Rust FFmpeg?
Leitfaden zur Implementierung von FFmpeg-Funktionalität in Rust: Bibliotheksauswahl, Codegenerierung und Problemlösung.
Auswahlmatrix
| Bibliothek | Wann verwenden | Async | Sicherheit | Kompromiss |
|---|---|---|---|---|
| ez-ffmpeg | Allgemeine Aufgaben, CLI-Migration, RTMP-Server, benutzerdefinierte Rust + WGSL GPU-Filter, natives Untertitel-Einbrennen, Erkennung/Messung, Ein-Schritt-Rezepte, benutzerdefinierte I/O, In-Memory-Frame/Sample-Export + Frame-Push (VideoWriter), typisierter Pro-Fortschritt | ✅ Ja | Sicher | Erfordert FFmpeg-Bibliotheken |
| ffmpeg-next | Frame-Level-Steuerung, Codec-Interna, sichere Stream-I/O (beliebige Read/Write/Seek) | ❌ Nein | Sicher | Mehr Boilerplate |
| ffmpeg-sys-next | Zero-Copy, benutzerdefinierte Speicher-I/O, maximale Leistung | ❌ Nein | Unsicher | Manuelle Speicherverwaltung |
| ffmpeg-sidecar | Keine FFmpeg-Installation möglich | ❌ Nein | Sicher | Prozess-Overhead, keine benutzerdefinierte I/O |
Entscheidungslogik
Ebene 1: Integrationsmethode
Standard: Bibliotheksintegration (ez-ffmpeg/ffmpeg-next/ffmpeg-sys-next)
- Bessere Leistung, typsichere API, direkter Frame-Zugriff
Alternative: Binär-Ansatz (ffmpeg-sidecar) – in Betracht ziehen bei:
- Keine Installation der FFmpeg-Entwicklungsbibliotheken möglich
- Eingeschränkte CI/CD-Umgebung ohne Admin-Rechte
- Reine CLI-Batchverarbeitung (keine Echtzeit-Anforderungen)
Falls Installation eingeschränkt → Lade ffmpeg_sidecar.md
Ebene 2: Szenarioerkennung
| Benutzer erwähnt | Lade Referenz |
|---|---|
| "Format konvertieren", "remuxen", "trimmen", "Größe ändern", "zuschneiden", "einfach" | video_transcoding.md |
| "Audio extrahieren", "nur Audio", "Audiospur", "MP3 extrahieren", "loudnorm", "Audio normalisieren", "Lautstärke" | audio_extraction.md |
| "Vorschaubild", "erstes Bild", "schnelles Vorschaubild", "skip_frame", "nokey", "nur Keyframes", "Mehrfachausgabe", "concat", "Wasserzeichen", "Pipeline", "Filtergraph" | pipelines_multi_output.md – für ein einmaliges Vorschaubild bevorzuge recipes::thumbnail in image_sequences.md; für den schnellsten Nur-Keyframe-Pfad (skip_frame=nokey, springt zum nächsten Keyframe) siehe ez_ffmpeg/video.md |
| "Echtzeit", "RTMP", "HLS", "live", "Stream", "Capture", "Webcam", "Puffer", "Gegendruck", "Jitter-Puffer", "Netzwerk-Jitter", "ABR-Leiter", "HLS-Leiter", "adaptive Bitrate", "Master-Playlist", "VOD-Packaging" | streaming_rtmp_hls.md |
| "GPU", "NVENC", "VideoToolbox", "Hardware", "VAAPI", "QSV", "wgpu", "WGSL", "benutzerdefinierter Shader", "GPU-Filter", "Compute-Shader", "libplacebo", "Schönheitsfilter", "Chroma Key", "Green Screen" | hardware_acceleration.md |
| "Stapel", "mehrere Dateien", "Massen", "parallel" | batch_processing.md |
| "Untertitel", "srt", "Untertitel", "Untertitel einbrennen", "Einbrennen", "hardsub", "ass", "vtt", "native Untertitel", "ohne libass", "kein libass" | subtitles.md |
| "AV1", "AVIF", "HDR", "10-Bit", "moderner Codec", "HDR zu SDR", "Tone Mapping", "tonemap", "ausgewaschene Farben", "PQ", "HLG" | modern_codecs.md |
| "Debug", "ffprobe", "inspizieren", "Metadaten", "Fehler", "Fehlerbehebung", "Sonde", "Dauer", "Auflösung", "beschädigt", "Integrität" | debugging.md |
| "schwarze Bilder erkennen", "Stille erkennen", "Szenenerkennung", "Szenenwechsel", "cropdetect", "EBU R128", "LUFS", "Lautstärke messen", "True Peak", "Inhaltsanalyse", "QC", "blackdetect", "silencedetect" | detection_analysis.md (typisierte analysis-API) |
| "Filter", "Effekt", "skalieren", "zuschneiden", "überlagern", "Wasserzeichen", "Weichzeichnen", "Schärfen", "Farbe", "Helligkeit", "drehen", "spiegeln", "ausblenden", "Geschwindigkeit", "Zeitlupe" | filters_effects.md |
| "Bildsequenz", "Frame-Extraktion", "Video zu Bildern", "Bilder zu Video", "Zeitraffer", "Bild für Bild", "Sprite Sheet", "Storyboard", "Kontaktbogen", "Vorschaubild-Gitter" | image_sequences.md |
"Ein-Schritt-Rezept", "recipes-Modul", "schnelles Vorschaubild", "Vorschaubild-Rezept", "Sprite-Sheet-Rezept", "GIF-Rezept", "HLS-Leiter-Rezept" (ez-ffmpeg recipes, kein Feature-Flag) | image_sequences.md (Vorschaubild/Sprite), gif_creation.md (GIF), streaming_rtmp_hls.md (HLS-Leiter) |
| "Test", "validieren", "verifizieren", "Goldene Datei", "Prüfsumme", "Testvideo generieren", "testsrc" | testing.md |
| "Webserver", "API", "S3", "asynchroner Job", "Integration", "Tracing", "Logging", "Log-Callback", "av_log", "Log-Weiterleitung" | integration.md |
| "GIF", "animiertes GIF", "Video zu GIF", "GIF aus Video", "GIF-Schleife", "GIF-Palette" | gif_creation.md |
| "Metadaten", "Kapitel", "Tag", "Medieninfo", "Titel", "Künstler", "Album", "Kapitelmarker" | metadata_chapters.md |
| "Bildschirmaufnahme", "Webcam", "Kameraaufnahme", "Bildschirm aufnehmen", "avfoundation", "directshow", "v4l2", "Geräteerfassung" | capture.md |
| "AVPacket", "AVFrame", "Keyframe", "GOP", "NALU", "Bitstrom", "EAGAIN", "Dekodierungsschleife", "Speicher", "Paket" | ffmpeg_next.md + ffmpeg_sys_next.md |
| "avformat_find_stream_info", "AVSEEK_SIZE", "AVFormatContext", "AVCodecID", "Raw C API", "FFI" | ffmpeg_sys_next.md + custom_io.md |
| "benutzerdefinierte I/O", "Read-Callback", "Write-Callback", "StreamIo", "Speicher-Ein-/Ausgabe", "Read/Write/Seek-Quelle" | Sichere APIs: advanced.md (ez-ffmpeg Callbacks) oder ffmpeg_next.md (StreamIo) |
| "AVIOContext", "IO-Kontext", "Raw-IO-Callback", "Zero-Copy-benutzerdefinierte I/O" | custom_io.md (unsicheres FFI) |
| "Frames in den Speicher extrahieren", "nach RGB dekodieren", "Frames für AI/ML", "Frame zu Tensor", "Frame-Export", "Video zu Frames für ein Modell", "FrameExtractor", "Whisper PCM", "Audio zu f32", "SampleExtractor", "ASR-Import", "gleichmäßige N Frames" | frame_io.md (experimentell, ez-ffmpeg 0.14) |
| "VideoWriter", "Frames pushen", "Video aus Frames generieren", "prozedurales Video", "Frames zu Video rendern", "In-Memory mp4", "aus dem Speicher kodieren", "Frames zu Video" | frame_io.md (experimentell, ez-ffmpeg 0.14) |
| "WHIP", "WebRTC-Ausgabe", "SRT-Ausgabe", "Fähigkeitsabfrage", "is_muxer_available", "Ausgabeprotokoll verfügbar", "fMP4 HLS", "fragmentierte mp4-Segmente" | streaming.md (WHIP/SRT/Fähigkeiten) + streaming_rtmp_hls.md (fMP4-Leiter) |
| "Export kodierter Pakete", "Packet Sink", "PacketSink", "WebCodecs", "EncodedVideoChunk", "EncodedAudioChunk", "H.264-Zugriffseinheiten", "AAC-Frames", "avcC", "AudioSpecificConfig", "RTP-Packetizer", "fMP4-Segmentierer", "Job-Fehler", "on_job_failed", "JobFailureSummary" | packet_sink.md (experimentell, ez-ffmpeg 0.15; Job-Fehler-Zusammenfassungen 0.16) |
| "Fortschritt", "Fortschrittsbalken", "Prozent abgeschlossen", "ETA", "wie weit", "Kodierungsgeschwindigkeit", "progress_handle", "ProgressHandle", "Fortschritts-Schnappschuss" | advanced.md; Batch-pro-Datei-Zählung: batch_processing.md |
| "Pro-Stream-Encoder", "unterschiedlicher Codec pro Stream", "StreamMap", "-c:v:0", "indizierte Stream-Optionen", "Pro-Stream-Codec-Optionen" | video.md (ez-ffmpeg 0.16) |
| "ffmpeg-Befehl in Rust ausführen", "from_cli_args", "emit_rust_code", "ffmpeg-Befehl übersetzen", "CLI-Feature", "cli-kompatibel", "verifizierte Form" | cli_compat.md (cli Feature); manuelles Mapping: cli_migration.md |
| "Versionskompatibilität", "FFmpeg 7 vs 8", "Linkfehler", "Build schlägt fehl", "links = ffmpeg", "installieren", "vcpkg" | installation.md |
| "welche Bibliothek", "vergleichen", "vs", "migrieren zu", "portieren zu", "konvertieren zu", "wechseln von", "umschreiben mit", "Machbarkeit", "sollte ich verwenden", "beste Bibliothek", "bewerten", "FFmpeg-Code überprüfen", "kann das mit funktionieren" | library_selection.md |
Mehrere Zeilen können auf eine Anfrage zutreffen — lade alle zutreffenden Referenzen, folge dann zuerst dem Ziel der spezifischsten Zeile.
Ebene 3: Bibliotheksauswahl
CLI-Migration: Sowohl ez-ffmpeg als auch ffmpeg-sidecar unterstützen CLI-ähnliche APIs. Wähle basierend auf den folgenden Einschränkungen.
- ez-ffmpeg: CLI-Migrationsleitfaden — Bibliotheksintegration, native Leistung
- ffmpeg-sidecar: CLI-zu-Rust-Migration — Prozess-Wrapper, keine FFmpeg-Bibliotheken erforderlich
- Async/Await benötigt? → ez-ffmpeg (einzige Bibliothek mit nativem Async)
- Benutzerdefinierte Rust-Frame-Verarbeitung benötigt? → ez-ffmpeg FrameFilter (sicher, einfache API)
- Benutzerdefinierte GPU-Shader (WGSL) benötigt? → ez-ffmpeg
wgpuFeature (WgpuFrameFilter, kopflos, kein Display-Server) — überprüfe zuerst den integriertenwgpu_filter::effects-Katalog (13 typisierte Effekte, 0.13+); für native Hardware-Filter (scale_cuda/scale_vaapi/libplacebo) sondiere mitget_gpu_filter_backends() - Untertitel ohne libass einbrennen müssen? → ez-ffmpeg
subtitleFeature (SubtitleFilter, reiner Rust-ASS/SRT-Renderer, kein--enable-libass) - Typisierte Erkennung/Messung (schwarz/Stille/Szene/Zuschnitt/EBU R128) benötigt? → ez-ffmpeg
analysisModul (Analysiseinmalig oderMetadataEventFilterStreaming — kein Feature-Flag) - Einmaliges Vorschaubild / Sprite Sheet / GIF / HLS ABR-Leiter benötigt? → ez-ffmpeg
recipesModul (kein Feature-Flag) - Frame-Level-Codec-Steuerung benötigt? → ffmpeg-next für Codec-Interna
- Benutzerdefinierte I/O aus dem Speicher benötigt? → ez-ffmpeg (Lese-/Schreib-/Seek-Callbacks), oder ffmpeg-next sichere Stream-I/O (
input_from_stream/output_to_stream, beliebigeRead/Write/Seek); ffmpeg-sys-next für niedrigste Steuerungsebene - Zero-Copy oder maximale Leistung benötigt? → ffmpeg-sys-next (erfordert unsicheren Code)
- FFmpeg-Bibliotheken können nicht installiert werden? → ffmpeg-sidecar (prozessbasiert, nur stdin/stdout, keine benutzerdefinierte I/O)
- Dekodierte Frames/Audio im Speicher für AI/CV/ASR benötigt? → ez-ffmpeg
frame_export(FrameExtractor→ gepacktes RGB,SampleExtractor::for_whisper→ 16 kHz Mono f32; kein Feature-Flag; experimentell, 0.14) — siehe frame_io.md - Video aus in Rust gerenderten Frames generieren/pushen müssen? → ez-ffmpeg
VideoWriter(Frame-Push in Kodierung/Mux/Stream, kein Demuxer; experimentell, 0.14) — siehe frame_io.md - WebCodecs-Decoder, RTP/SRT-Packetizer oder handgefertigten fMP4-Segmentierer direkt vom Encoder füttern müssen? → ez-ffmpeg
packet_sink(PacketSink, strenge Nur-H.264/AAC-Stufe, kein Container; kein Feature-Flag; experimentell, 0.15) — siehe packet_sink.md - Einen vorhandenen ffmpeg-CLI-Befehl ausführen oder automatisch übersetzen müssen? → ez-ffmpeg
cliFeature (from_cli_args/emit_rust_code, enge golden-getestete Teilmenge — 6 verifizierte Formen; 0.15) — siehe cli_compat.md; alles außerhalb dieser Teilmenge benötigt noch die manuellen cli_migration.md-Tabellen
Hinweis: FrameFilter (benutzerdefinierte Rust-Frame-Verarbeitung) ist getrennt von benutzerdefinierten I/O-Callbacks (benutzerdefinierte Datenquellen/senken). ez-ffmpeg unterstützt beides.
Schnellstart
Neu bei Rust FFmpeg? Siehe quick_start.md für eine 5-Minuten-Einrichtung.
Bibliotheksreferenzen
- ez-ffmpeg - Hochsprachen-API (synchron und asynchron)
- ffmpeg-next - Mittelstufen-API für erweiterte Steuerung
- ffmpeg-sys-next - Low-Level unsicheres FFI
- ffmpeg-sidecar - CLI-Wrapper
Versionskompatibilität
| Bibliothek | 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 | nicht angegeben |
| ffmpeg-sys-next | 8.1.0 | 7.0–8.x | nicht angegeben |
| ffmpeg-sidecar | 2.5.2 | Beliebig | 1.79+ |
Quelle: crates.io
FFmpeg 7 vs 8: Alle vier Bibliotheken werden mit den aktuellen Crate-Versionen oben gegen beide Hauptversionen gebaut — keine Crate-Hauptversion-zu-System-Hauptversion-Zuordnung. Achtung: Wenn ffmpeg-next zusammen mit ez-ffmpeg gezogen wird, halte es bei 8.1.0 — ein gemischtes 7.1.0 kollidiert über den links = "ffmpeg"-Schlüssel. Bindgen-Mechanik, die Legende vom 7.1-Pin und die rust-ffmpeg #246 Geschichte: siehe installation.md.
Installationsprobleme: installation.md — enthält den Windows-vcpkg-Statisch-Link-Fix unresolved external symbol (zusätzliche Systembibliotheken in der build.rs der App; VCPKG_ROOT muss in der Shell gesetzt sein, nicht über std::env::set_var in build.rs)
Richtlinien für Claude
Wenn dieser Skill aktiviert wird, befolge diesen Arbeitsablauf:
Für Implementierungsaufgaben:
- Aufgabe identifizieren — Bestimme: Video/Audio/Streaming/Inspektion? Einfach oder komplex?
- Bibliothek auswählen — Wende die Entscheidungslogik der Ebene 3 an. Nenne in einem Satz, welche Bibliothek und warum
- Referenzen laden — Folge der Szenarioerkennung der Ebene 2, um die richtigen Referenzdateien zu laden
- Code generieren — Produktionsreif: korrekte Fehlerbehandlung,
… [für die Übersetzung gekürzt]