Video- und Audio-Codecs mit Transloadit steuern

Mit dem Kompatibilitätsziel beginnen, nicht mit einem Lieblingscodec

Halten Sie fest, wo das Ergebnis abgespielt oder bearbeitet werden muss, bevor Sie Parameter wählen. Eine Datei für die Auslieferung im Browser, ein Archivmaster, ein Podcast-Download und eine Austauschdatei haben unterschiedliche Anforderungen, selbst wenn sie von derselben Quelle ausgehen. Notieren Sie für jedes Ziel den erforderlichen Container, Video- und Audiocodec, das Profil, das Kanal-Layout, die Abmessungen, die Bildrate, die Abtastrate, Untertitel und die maximale Auslieferungsgröße.

Halten Sie Container und Codecs in dieser Matrix getrennt. MP4, WebM, Ogg und MOV beschreiben, wie Streams und Metadaten verpackt werden; H.264, HEVC, VP9, AAC, Opus und FLAC beschreiben, wie einzelne Streams repräsentiert werden. Ein Player kann einen Container erkennen und trotzdem einen seiner Streams ablehnen, weshalb ein Test allein anhand der Dateierweiterung keine Kompatibilität belegen kann.

Unterstützte Overrides auf eine gepflegte Voreinstellung schichten

Eine Voreinstellung ist eine versionierte Sammlung von Encoding-Einstellungen für ein gängiges Ziel. /video/encode und /audio/encode führen die Einträge im ffmpeg-Objekt mit der ausgewählten Voreinstellung zusammen, sodass eine explizit angegebene Option den entsprechenden Voreinstellungswert ersetzt. Das ist meist die kleinste wartbare Richtlinie: Sie übernehmen die etablierte Grundlage und hinterlegen nur das Codec-, Profil-, Ratensteuerungs-, Filter- oder Containerverhalten, das bewusst geändert wurde.

Kopieren Sie nicht jede aufgelöste Voreinstellungsoption in ein Template, nur damit es explizit aussieht. Das erzeugt eine private Voreinstellung, die die Anwendung verstehen und pflegen muss. Benennen Sie stattdessen die Voreinstellung, halten Sie das Override-Objekt fokussiert und prüfen Sie das Ergebnis. Wenn der Workflow von der Voreinstellung vorgegebene FFmpeg-Standardwerte vermeiden muss, wählen Sie preset: "empty", halten Sie den in der Dokumentation empfohlenen Selektor ffmpeg_stack: "v7" explizit und geben Sie das erforderliche Format sowie die Codecs an.

Videocodec- und Ratensteuerungs-Einstellungen gezielt steuern

Das Videobeispiel beginnt mit der Voreinstellung web/mp4/1080p, wählt die empfohlene v7-Stack-Serie aus und überschreibt dann die H.264-level-Beschränkung sowie die produktspezifischen Ratensteuerungs-Einstellungen in ffmpeg. JSON-Schlüssel lassen den Bindestrich der Kommandozeile weg: level, crf, maxrate und bufsize werden zu FFmpeg-Ausgabeoptionen. Die Voreinstellung liefert weiterhin ihren H.264-Videocodec (libx264), das high-Profil, das Pixelformat yuv420p, den AAC-Audioencoder (libfdk_aac), den MP4-Container und movflags: "+faststart"; diese geerbten Werte müssen nicht erneut angegeben werden.

Die Werte sind eine Beispielrichtlinie, keine universellen Qualitätsempfehlungen. CRF, eine Bitraten-Obergrenze, das Encoder-Profil, das Pixelformat, die Quellkomplexität und Wiedergabebeschränkungen wirken zusammen. Testen Sie Text, Animation, Filmkorn, Bewegung, dunkle Szenen und gewöhnliches Sprecher-Material in der vorgesehenen Auflösung. Prüfen Sie die Ausgabe sowohl auf visuelle Qualität als auch auf Decoder-Kompatibilität, bevor Sie die Einstellungen produktiv einsetzen.

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "web_video": {
      "use": ":original",
      "robot": "/video/encode",
      "ffmpeg_stack": "v7",
      "preset": "web/mp4/1080p",
      "ffmpeg": {
        "level": "4.1",
        "crf": 21,
        "maxrate": "5M",
        "bufsize": "10M"
      },
      "result": true
    }
  }
}

Eine explizite Audioausgabe mit der leeren Voreinstellung erstellen

Das Audio-Beispiel verwendet preset: "empty" mit dem in der Dokumentation empfohlenen ffmpeg_stack: "v7"-Selektor, sodass das Template seine Encoding-Einstellungen selbst liefert, statt sie von einer Voreinstellung zu übernehmen. Geben Sie diesen Selektor explizit an, statt sich auf den impliziten v6-Laufzeit-Fallback zu verlassen. Das Beispiel wählt den Ogg-Container, den Opus-Encoder, eine Ziel-Bitrate, eine Abtastrate von 48 kHz, zwei Ausgabekanäle und einen einfachen Hochpassfilter. /audio/encode akzeptiert Audiodateien und Videodateien, die einen Audio-Stream enthalten, wodurch sich derselbe Step sowohl für reine Audio-Uploads als auch für die Extraktion von Soundtracks eignet.

Die leere Voreinstellung entfernt die von der Voreinstellung bereitgestellten Encoding-Standardwerte, nicht aber alle vom Robot hinzugefügten Argumente. /audio/encode fügt weiterhin ein Standard-Stream-Mapping hinzu, damit das eingebettete Coverbild nicht als Audio codiert wird, und leitet Format oder Bitrate aus der Eingabe ab, wenn einer der beiden Werte fehlt. Dieses Beispiel gibt beide Werte im ffmpeg-Objekt mit f und b:a explizit an.

Dieses Audio-Beispiel verwendet das ffmpeg-Objekt, weil es explizite Encoding-Einstellungen mit leerer Voreinstellung demonstriert. Für einfache Konvertierungen, die nur Bitrate oder Abtastrate ändern, sollten Sie stattdessen die dokumentierten Robot-Parameter bitrate und sample_rate auf oberster Ebene verwenden. Diese erwarten Ganzzahlen in Bit pro Sekunde und Hertz – zum Beispiel 256000 und 48000 –, während ffmpeg.b:a Zeichenketten wie "128k" akzeptiert. Der Audio Encode Robot wendet die Werte auf oberster Ebene nach dem ffmpeg-Merge an, sodass sie widersprüchliche b:a- oder ar-Werte überschreiben. Vermeiden Sie es, denselben Sachverhalt an beiden Stellen anzugeben: Ein maßgeblicher Wert lässt sich leichter prüfen, testen und ändern.

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "podcast_audio": {
      "use": ":original",
      "robot": "/audio/encode",
      "ffmpeg_stack": "v7",
      "preset": "empty",
      "ffmpeg": {
        "f": "ogg",
        "codec:a": "libopus",
        "b:a": "128k",
        "ar": 48000,
        "ac": 2,
        "af": "highpass=f=80"
      },
      "result": true
    }
  }
}

FFmpeg-Flexibilität innerhalb der verwalteten Sicherheitsgrenze nutzen

Der Wert ffmpeg ist ein strukturiertes Optionsobjekt, kein Shell-Befehl. Transloadit wandelt dessen Schlüssel und Werte in Argumente für den ausgewählten, verwalteten FFmpeg-Stack um. Diese Abgrenzung ermöglicht erhebliche Kontrolle, ohne den Worker-Host offenzulegen. Sie bedeutet auch, dass ein Template weder einen anderen FFmpeg-Build installieren noch eine nicht verfügbare Encoder-Bibliothek hinzufügen noch davon ausgehen kann, dass jede Option aus der neuesten Upstream-Dokumentation in jedem Stack vorhanden ist.

Vom Nutzer kontrollierte Optionen durchlaufen Sicherheitsprüfungen. Filterskripte und Filterdirektiven, die lokale Dateien lesen, werden abgelehnt, einschließlich dateibasierter Untertitel-, Schrift- und Texteingaben. Verwenden Sie, wo verfügbar, dedizierte Robot-Parameter und -Robots, etwa watermark_url, /video/subtitle oder inline drawtext-Text mit einer verfügbaren Schriftfamilie. Betrachten Sie eine Ablehnung als Grenze, um die herum neu zu gestalten ist, nicht als Grund, einen weiteren Befehl in einer Filterzeichenkette zu verstecken.

Codec-Varianten als unabhängige Assembly Steps erstellen

Ein einzelner Quell-Step kann mehrere unabhängige Encoding-Steps versorgen. Das Beispiel erstellt die Video-Varianten H.264/MP4 und VP9/WebM sowie die Audio-Ausgaben AAC und Opus. Diese Zweige benötigen keine anwendungsseitigen Schleifen oder wiederholten Uploads: Ihr gemeinsamer use-Wert deklariert die Abhängigkeit, und jedes Encoding kann starten, sobald die Quelldatei verfügbar ist.

Geben Sie jedem Step einen Namen, der den Ausgabevertrag beschreibt statt ein Implementierungsdetail, das sich wahrscheinlich ändert. Eine Anwendung interessiert sich unter Umständen mehr für browser_fallback und modern_web als für die heutigen Encoder-Namen. Markieren Sie nur beabsichtigte Ausgaben als Ergebnisse, exportieren Sie jede dauerhafte Variante, und bewahren Sie die Assembly-ID auf, damit ein Bediener eine abgelehnte Datei genau dem Step und den Einstellungen zuordnen kann, die sie erzeugt haben.

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "browser_fallback": {
      "use": ":original",
      "robot": "/video/encode",
      "ffmpeg_stack": "v7",
      "preset": "web/mp4/720p",
      "result": true
    },
    "modern_web": {
      "use": ":original",
      "robot": "/video/encode",
      "ffmpeg_stack": "v7",
      "preset": "web/webm/720p",
      "result": true
    },
    "download_aac": {
      "use": ":original",
      "robot": "/audio/encode",
      "ffmpeg_stack": "v7",
      "preset": "aac",
      "result": true
    },
    "download_opus": {
      "use": ":original",
      "robot": "/audio/encode",
      "ffmpeg_stack": "v7",
      "preset": "opus",
      "result": true
    }
  }
}

Das Template versionieren und die erzeugten Medien testen

Bewahren Sie die Voreinstellung, die FFmpeg-Overrides und ffmpeg_stack in einem gespeicherten Template auf, damit Aufträge in der Produktion einer einzigen, überprüfbaren Richtlinie folgen. Die Dokumentation des in der Produktion eingesetzten Robots empfiehlt den Major-Selektor v7, während eine Anfrage, die ohne Selektor die API-Laufzeit erreicht, auf den impliziten v6-Fallback zurückgreift; deshalb speichern die Beispiele v7 explizit. Ein Major-Selektor wird zum höchsten verfügbaren Build innerhalb dieser Hauptversion aufgelöst – v7 wird beispielsweise zu einem v7-Build aufgelöst, nicht zu v8. Der veraltete Selektor v5 ist kein gültiger Stack mehr und wird inzwischen zu v6 aufgelöst. Testen Sie Änderungen an Stack, Voreinstellung oder Overrides neben der aktuellen Richtlinie, bevor Sie alle neuen Aufträge darauf umstellen.

Eine erfolgreiche Assembly belegt, dass der Befehl abgeschlossen wurde, nicht, dass die Ausgabe dem Produktvertrag entspricht. Lesen Sie die Ergebnismetadaten für Codecs, Abmessungen, Dauer, Bildrate, Kanalanzahl und Abtastrate, und spielen Sie die Dateien anschließend auf repräsentativen Clients ab. Bewahren Sie bekannt gute und schwierige Fixtures auf, vergleichen Sie Dateigröße und Verarbeitungskosten, prüfen Sie Audio-/Video-Synchronisation und Spulen, und behalten Sie einen Fallback bei, während eine geänderte Richtlinie ausgerollt wird.