# Videos transkodieren, skalieren oder mit Wasserzeichen versehen
Robot: `/video/encode`
🤖/video/encode codiert und skaliert Videos und animierte GIFs und versieht sie mit Wasserzeichen.
Der Robot /video/encode ist ein vielseitiges Werkzeug zur Videoverarbeitung, das Transcoding, Größenänderungen und Wasserzeichen unterstützt. Er unterstützt verschiedene Formate, darunter moderne Standards wie HEVC (H.265), und bietet Funktionen wie Voreinstellungen für gängige Geräte, benutzerdefinierte FFmpeg-Parameter für erfahrene Nutzer, die Positionierung von Wasserzeichen und mehr.
## Textüberlagerungen mit FFmpeg hinzufügen
Mit dem Filter `drawtext` von FFmpeg können Sie Videos über den Parameter `ffmpeg` bei diesem Robot Textüberlagerungen hinzufügen. Hier sind zwei Beispiele — eines mit der Standardschriftart und eines mit dem Namen einer benutzerdefinierten Schriftfamilie:
```json
{
"steps": {
":original": {
"robot": "/upload/handle"
},
"text_overlay_default": {
"use": ":original",
"robot": "/video/encode",
"preset": "empty",
"ffmpeg_stack": "{{stacks.ffmpeg.recommended_version}}",
"ffmpeg": {
"codec:a": "copy",
"vf": "drawtext=text='My text overlay':fontcolor=white:fontsize=24:box=1:boxcolor=black@0.5:boxborderw=5:x=(w-text_w)/2:y=(h-text_h)/2"
},
"result": true
},
"text_overlay_custom": {
"use": ":original",
"robot": "/video/encode",
"preset": "empty",
"ffmpeg_stack": "{{stacks.ffmpeg.recommended_version}}",
"ffmpeg": {
"codec:a": "copy",
"vf": "drawtext=font='Times New Roman':text='My text overlay':fontcolor=white:fontsize=24:box=1:boxcolor=black@0.5:boxborderw=5:x=(w-text_w)/2:y=(h-text_h)/2"
},
"result": true
}
}
}
```
**Hinweise:**
* Verwenden Sie das Attribut `font`, um mit dem Filter `drawtext` von FFmpeg über den Namen auf eine Schriftfamilie zu verweisen.
* Namen von FFmpeg-Schriftfamilien enthalten üblicherweise keine Bindestriche (z. B. `Times New Roman`), während
ImageMagick Namen mit Bindestrichen verwendet (z. B. `Times-New-Roman`).
* Optionen von `drawtext` zum Laden von Dateien, etwa `textfile` und `fontfile`, werden nicht unterstützt. Verwenden Sie stattdessen
`text` inline und den Namen einer Schriftfamilie.
* Behalten Sie das Audio der Quelldatei bei, indem Sie `"codec:a": "copy"` festlegen.
* Positionieren Sie Text mit den Ausdrücken `x` und `y`. Im obigen Beispiel wird der Text zentriert.
Sehen Sie sich die [Live-Demo für Textüberlagerungen](/demos/video-encoding/add-text-overlay.md) an.
Phase: ga
## Anwendungsbeispiel
Hochgeladene Videos in \[HEVC]\(https\://en.wikipedia.org/wiki/High\_Efficiency\_Video\_Coding) (H.265) transkodieren:
```json
{
"steps": {
"hevc_encoded": {
"robot": "/video/encode",
"use": ":original",
"preset": "hevc"
}
}
}
```
## Parameter
* `interpolate`: Steuert, ob einzelne Robot-Anweisungsfelder Assembly Variables interpolieren.
Standardmäßig interpolieren die meisten Robot-Anweisungsfelder Assembly Variables. Mit dem Wert `false` behandeln Sie alle Anweisungsfelder als Literaltext. Wenn Sie stattdessen einen einzelnen Feldpfad auf `false` setzen, wird nur dieses Feld als Literaltext behandelt. Bei Feldern eines bestimmten Robots, die standardmäßig als Literaltext behandelt werden, aktivieren Sie die Interpolation wieder, indem Sie hierfür `true` festlegen oder für den jeweiligen Feldpfad den Wert `true` verwenden.
Verwenden Sie Feldnamen wie `path` oder für verschachtelte Objekte Punktpfade wie `ffmpeg.vf` als Pfadangabe.
* `output_meta`: Damit können Sie eine Reihe von Metadaten festlegen, deren Berechnung mehr CPU-Ressourcen beansprucht. Sie sind daher standardmäßig deaktiviert, damit Ihre Assemblies schnell verarbeitet werden.
Für Bilder können Sie diesem Objekt den Eintrag `"has_transparency": true` hinzufügen, um zu ermitteln, ob das Bild transparente Bereiche enthält. Mit dem Eintrag `"dominant_colors": true` können Sie außerdem ein Array mit hexadezimalen Farbcodes aus dem Bild extrahieren.
Für Bilder können Sie auch den Eintrag `"blurhash": true` hinzufügen, um einen [BlurHash](https://blurha.sh) zu extrahieren – eine kompakte Darstellung eines Platzhalters für das Bild, mit der Sie eine unscharfe Vorschau anzeigen können, während das vollständige Bild geladen wird.
Für Videos können Sie den Parameter `"colorspace": true` hinzufügen, um den Farbraum des Ausgabevideos zu extrahieren.
Für Videos können Sie außerdem den Eintrag `"interlaced": true` hinzufügen, um zu erkennen, ob das Video im Zeilensprungverfahren vorliegt. Dazu wird die ressourcenschonende ffprobe-Option `field_order` mit einem begrenzten Stichprobendurchlauf mithilfe von `idet` über die ersten Frames der Quelle kombiniert. Die Ergebnisse `interlaced` und `field_order` sowie das Diagnoseobjekt `interlace_detection` werden dabei unter `file.meta` ausgegeben. Dies ist rechenintensiv und wird entsprechend abgerechnet.
Für Audio können Sie den Eintrag `"mean_volume": true` hinzufügen, um einen einzelnen Wert für die durchschnittliche Lautstärke der Audiodatei zu erhalten.
Sie können diesen Parameter auch auf `false` setzen, um die Metadatenextraktion zu überspringen und das Transcoding zu beschleunigen.
* `user_meta`: Fügt jeder von diesem Robot ausgegebenen Datei benutzerdefinierte Metadaten hinzu, ohne den Dateiinhalt zu verändern.
Die Werte werden mit allen bereits in der Eingabedatei enthaltenen `user_meta` zusammengeführt. Wenn beide Objekte denselben Schlüssel enthalten, hat der Wert dieses Robots Vorrang. Assembly Variables werden unterstützt, zum Beispiel `{ "internal_file_id": "${file.id}" }`.
* `result`: Ob die Ergebnisse dieses Steps im Assembly Status JSON enthalten sein sollen
* `queue`: Wenn Sie die Queue auf „batch“ setzen, wird die Priorität der Jobs für diesen Step manuell herabgestuft. So vermeiden Sie, Priority Job Slots für Jobs zu belegen, die keine Wartezeit von null in der Queue benötigen.
* `force_accept`: Erzwingt, dass ein Robot einen Dateityp akzeptiert, den er sonst ignorieren würde.
Standardmäßig ignorieren Robots Dateien, deren Typ sie nicht kennen.
[🤖/video/encode](/de/docs/robots/video-encode.md) ignoriert beispielsweise problemlos Eingabebilder.
Wenn Sie den Parameter `force_accept` auf `true` setzen, können Sie erzwingen, dass Robots alle übergebenen Dateien akzeptieren.
Dies führt in der Regel zu Fehlern und sollte nur zur Fehlersuche oder zur Behandlung von Grenzfällen verwendet werden.
* `ignore_errors`: Fehler in bestimmten Verarbeitungsphasen ignorieren.
Wenn Sie hierfür `["meta"]` festlegen, ignoriert der Robot Fehler bei der Metadatenextraktion.
Wenn Sie hierfür `["execute"]` festlegen, ignoriert der Robot Fehler während der Hauptausführungsphase.
Wenn Sie hierfür `true` festlegen, entspricht dies `["meta", "execute"]` und Fehler in beiden Phasen werden ignoriert.
* `use`: Gibt an, welche Steps als Eingabe verwendet werden sollen.
* Sie können beliebige Namen für Steps wählen, außer `":original"` (reserviert für von Transloadit verarbeitete Benutzer-Uploads)
* Sie können mehrere Steps mithilfe von Arrays als Eingabe angeben:
```json
{
"use": [
":original",
"encoded",
"resized"
]
}
```
* Sie können Eingabe-Steps außerdem mit `as` kennzeichnen, um Robots die semantische Funktion zu übermitteln:
```json
{
"use": [
{
"name": ":original",
"as": "image"
},
{
"name": ":original",
"as": "mask"
}
]
}
```
> [!Tip]
> Das ist wahrscheinlich alles, was Sie über `use` wissen müssen. Sie können sich jedoch auch die [erweiterten Anwendungsfälle](/de/docs/topics/use-parameter.md) ansehen.
* `ffmpeg`: Ein Parameterobjekt, das an FFmpeg übergeben wird. Wenn eine Voreinstellung verwendet wird, werden die angegebenen Optionen mit deren Optionen zusammengeführt. Verfügbare Optionen finden Sie in der [FFmpeg-Dokumentation](https://ffmpeg.org/ffmpeg-doc.html). Die hier angegebenen Optionen haben Vorrang vor den Optionen der Voreinstellung.
* `ffmpeg_stack`: Wählt die Version des FFmpeg-Stacks aus, die zum Encoding verwendet werden soll. Derzeit empfehlen wir „v7“. Die exakten Versionen „v6.0.0“, „v7.0.0“ und „v8.0.0“ sind Legacy-Werte, die aus Gründen der Abwärtskompatibilität weiterhin akzeptiert werden. Veraltete „v5.x“-Werte werden ebenfalls akzeptiert.
* `width`: Breite des neuen Videos in Pixeln.
Wenn der Wert nicht angegeben und der Parameter `preset` verfügbar ist, wird die [angegebene Breite](/de/docs/presets/video.md) aus der Voreinstellung `preset` übernommen.
* `height`: Höhe des neuen Videos in Pixeln.
Wenn der Wert nicht angegeben und der Parameter `preset` verfügbar ist, wird die [angegebene Höhe](/de/docs/presets/video.md) aus der Voreinstellung `preset` übernommen.
* `preset`: Konvertiert ein Video gemäß einer [Voreinstellung](/de/docs/presets/video.md).
Ab `ffmpeg_stack: "v7"` können Sie hier den Wert `'empty'` verwenden, wenn Sie eigene FFmpeg-Parameter festlegen und dafür den Robot verwenden oder wenn Transloadit keine Encoding-Einstellungen festlegen soll.
* `resize_strategy`: Weitere Informationen finden Sie unter [verfügbare Strategien zur Größenanpassung](/de/docs/topics/resize-strategies.md).
* `zoom`: Wenn Sie dies auf `false` setzen, werden kleinere Videos nicht auf die gewünschte Breite und Höhe gestreckt. Einzelheiten dazu, wie sich das Zoomen bei Ihrer bevorzugten Strategie zur Größenänderung auswirkt, finden Sie in der Liste der verfügbaren [Strategien zur Größenänderung](/de/docs/topics/resize-strategies.md).
* `crop`: Geben Sie ein Objekt mit den Koordinaten der oberen linken und unteren rechten Ecke des Rechtecks an, das aus dem Originalvideo beziehungsweise den Originalvideos ausgeschnitten werden soll. Die Werte können Ganzzahlen für absolute Pixelwerte oder Strings für prozentuale Werte sein.
Beispiel:
```json
{
"x1": 80,
"y1": 100,
"x2": "60%",
"y2": "80%"
}
```
Damit wird aus einem Video mit 1000×1000 Pixeln der Bereich von `(80, 100)` bis `(600, 800)` ausgeschnitten. Das Ergebnis ist ein Quadrat mit einer Breite von 520px und einer Höhe von 700px. Wenn `crop` gesetzt ist, werden die Parameter für Breite und Höhe ignoriert und `resize_strategy` wird automatisch auf `crop` gesetzt.
Sie können auf ähnliche Weise auch einen JSON-String eines solchen Koordinatenobjekts verwenden:
```json
"{\"x1\": , \"y1\": , \"x2\": , \"y2\": }"
```
* `background`: Die Hintergrundfarbe des resultierenden Videos im Format `"rrggbbaa"` (Rot, Grün, Blau, Alpha), wenn die Größenänderungsstrategie `"pad"` verwendet wird. Die Standardfarbe ist Schwarz.
* `rotate`: Erzwingt, dass das Video um die angegebene ganzzahlige Gradzahl gedreht wird. Derzeit werden nur Vielfache von `90` unterstützt. Wir korrigieren die Ausrichtung vieler Videos automatisch, wenn die Kamera entsprechende Ausrichtungsinformationen bereitstellt. Diese Option ist nur für Videos sinnvoll, die gedreht werden müssen, weil die Kamera die erforderliche Drehung nicht erkannt hat. Wenn Sie `rotate` auf `false` setzen, wird keine Drehung vorgenommen, selbst wenn die Metadaten entsprechende Anweisungen enthalten.
* `hint`: Aktiviert Hinting für mp4-Dateien für RTP/RTSP-Streaming.
* `turbo`: Teilt das Video in mehrere Abschnitte auf, sodass jeder Abschnitt parallel codiert werden kann, bevor alle codierten Abschnitte zum Ergebnisvideo zusammengesetzt werden. Dies erfordert zusätzliche Priority Job Slots und kann sich bei sehr kleinen Videodateien als kontraproduktiv erweisen.
* `chunk_duration`: Hiermit können Sie die Dauer jedes Chunks festlegen, wenn `turbo` auf `true` gesetzt ist. So können Sie diese Funktion mit weniger Priority Job Slots nutzen. Je länger beispielsweise die einzelnen Chunks sind, desto weniger Encoding-Jobs müssen eingesetzt werden.
* `watermark_url`: Eine URL, die auf ein PNG-Bild verweist, das über dieses Bild gelegt wird. Sie können das Wasserzeichen auch [über einen anderen Assembly Step bereitstellen](/de/docs/topics/use-parameter.md#supplying-the-watermark-via-an-assembly-step).
* `watermark_position`: Die Position, an der das Wasserzeichen platziert wird.
Sie können auch ein Array möglicher Werte angeben. In diesem Fall wird ein Wert nach dem Zufallsprinzip ausgewählt, zum Beispiel `[ "center", "left", "bottom-left", "bottom-right" ]`.
Mit dieser Einstellung wird das Wasserzeichen in der angegebenen Ecke platziert. Um das Wasserzeichen um eine bestimmte Pixelanzahl zu versetzen, müssen Sie den Abstand zum Bild selbst hinzufügen.
* `watermark_x_offset`: Der x-Versatz in Pixeln, um den das Wasserzeichen relativ zu der durch `watermark_position` bestimmten Position verschoben wird.
Die Werte können positiv oder negativ sein und führen abhängig vom Parameter `watermark_position` zu unterschiedlichen Ergebnissen. Positive Werte verschieben das Wasserzeichen näher zur Bildmitte, negative Werte weiter von der Bildmitte weg.
* `watermark_y_offset`: Der y-Versatz in Pixeln, um den das Wasserzeichen relativ zu der durch `watermark_position` bestimmten Position verschoben wird.
Die Werte können positiv oder negativ sein und führen abhängig vom Parameter `watermark_position` zu unterschiedlichen Ergebnissen. Positive Werte verschieben das Wasserzeichen näher zur Bildmitte, negative Werte weiter von der Bildmitte weg.
* `watermark_size`: Die Größe des Wasserzeichens als Prozentwert, zum Beispiel `"50%"`. Wie das Wasserzeichen skaliert wird, hängt maßgeblich vom Wert für `watermark_resize_strategy` ab.
* `watermark_resize_strategy`: Um die Funktionsweise der Größenanpassungsstrategien zu erläutern, nehmen wir an, dass unser Zielvideo 800×800 Pixel groß und unser Wasserzeichenbild 400×300 Pixel groß ist. Nehmen wir außerdem an, der Parameter `watermark_size` ist auf den Wert `"25%"` gesetzt.
Bei der Größenanpassungsstrategie `"fit"` wird das Wasserzeichen so skaliert, dass seine längere Seite 25 % der entsprechenden Videoseite einnimmt. Die andere Seite wird entsprechend dem Seitenverhältnis des Wasserzeichenbilds skaliert. Bei unserem Wasserzeichen ist die Breite die längere Seite, und 25 % der Videogröße entsprechen 200px. Daher würde das Wasserzeichen auf 200×150 Pixel skaliert. Wäre `watermark_size` auf den Wert `"50%"` gesetzt, würde es auf 400×300 Pixel skaliert und damit einfach in seiner ursprünglichen Größe belassen.
Bei der Größenanpassungsstrategie `"stretch"` wird das Wasserzeichenbild gestreckt, also ohne Beibehaltung seines Seitenverhältnisses skaliert, sodass beide Seiten jeweils 25 % der entsprechenden Videoseite einnehmen. Da unser Video 800×800 Pixel groß ist, würde das Wasserzeichen bei einer Wasserzeichengröße von 25 % auf 200×200 Pixel skaliert. Seine Höhe würde gestreckt erscheinen, da es unter Beibehaltung des Seitenverhältnisses stattdessen auf 200×150 Pixel skaliert würde.
Bei der Größenanpassungsstrategie `"area"` wird das Wasserzeichen unter Beibehaltung seines Seitenverhältnisses so skaliert, dass es `"xx%"` der Fläche des Videos bedeckt. Der Wert von `watermark_size` bestimmt den prozentualen Flächenanteil.
* `watermark_start_time`: Die Verzögerung in Sekunden ab Beginn des Videos, nach der das Wasserzeichen eingeblendet wird. Standardmäßig wird das Wasserzeichen sofort angezeigt.
* `watermark_duration`: Die Dauer in Sekunden, für die das Wasserzeichen angezeigt wird. Kann zusammen mit `watermark_start_time` verwendet werden, um ansprechende Effekte zu erzeugen. Der Standardwert ist `-1.0`. Das bedeutet, dass das Wasserzeichen während der gesamten Dauer des Videos angezeigt wird.
* `watermark_opacity`: Die Deckkraft des Wasserzeichens. Gültige Werte liegen zwischen `0` (unsichtbar) und `1.0` (vollständig sichtbar).
* `segment`: Teilt die Datei in mehrere Teile auf, damit sie für [HTTP Live Streaming](https://developer.apple.com/resources/http-streaming/) von Apple verwendet werden kann.
* `segment_duration`: Gibt die Länge jedes HTTP-Segments an. Dieser Parameter ist optional. Der von Apple empfohlene Standardwert ist `10`. Ändern Sie diesen Wert nur aus gutem Grund.
* `segment_prefix`: Das für die Benennung verwendete Präfix. Beispielsweise würde das Präfix `"segment_"` Dateien mit Namen wie `"segment_0.ts"`, `"segment_1.ts"` usw. erzeugen. Diese Angabe ist optional; standardmäßig wird der Basisname der Eingabedatei verwendet. Siehe auch den zugehörigen Parameter `segment_name`.
* `segment_name`: Der für das letzte Segment verwendete Name. Als Variablen sind `${segment_prefix}` sowie `${segment_number}` und `${segment_id}` verfügbar. Die letzte Variable ist eine UUIDv4 ohne Bindestriche.
* `segment_time_delta`: Auf die Segmentdauer anzuwendendes Delta. Dieser Parameter ist optional und ermöglicht die Feinabstimmung der Segmentgrenzen.
* `font_size`
* `font_color`
* `text_background_color`