beta

Vorschaubild erzeugen

🤖/file/preview erzeugt für jede hochgeladene Datei ein Thumbnail, mit dem sich ihr Inhalt anzeigen lässt, ähnlich den Thumbnails in Desktop-Dateimanagern.

Anwendungsbeispiel

{
  "steps": {
    "previewed": {
      "format": "png",
      "height": 400,
      "robot": "/file/preview",
      "use": ":original",
      "width": 300
    }
  }
}

Parameter

• interpolate

  boolean | Record<string, boolean>

  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

  Record<string, boolean> | boolean | Array<string>

  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⁠ als String 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 Bilder extrahiert der Eintrag "thumbhash": true stattdessen einen base64-codierten ThumbHash⁠ nach meta.thumbhash, zusammen mit meta.has_alpha (gibt an, ob ein Alphakanal vorhanden ist, auch wenn das Bild vollständig deckend ist). Der Hash beschreibt die Pixel gemäß EXIF-Ausrichtung und verwendet bei animierten Bildern das erste Frame. Die Extraktion erfolgt nach dem Best-Effort-Prinzip: Bilder über 40 Megapixeln, nicht unterstützte Formate oder ein fehlgeschlagener bzw. durch Grenzwerte beschränkter Decodiervorgang erzeugen keinen Platzhalter. Eine erfolgreiche Extraktion verursacht eine zusätzliche Metadatengebühr in Höhe von 20 % der Bytes dieser Datei. Ist die Option deaktiviert oder wird kein Hash erzeugt, fällt kein ThumbHash-Aufschlag an.

  Setzen Sie diese Option für den Step, der das Bild erzeugt, etwa /upload/handle für hochgeladene Originale oder /image/resize für verarbeitete Ausgaben. Wird sie nur für /transloadit/store gesetzt, wird keine Extraktion angefordert: Die Speicherung behält die Metadaten des erzeugenden Steps bei. Transloadit Storage speichert einen erzeugten Hash dauerhaft zusammen mit seiner unveränderlichen Version und gibt ihn in gespeicherten Ergebnissen sowie beim nativen Lesen von Assets zurück. Direkte S3-Uploads erzeugen keine Platzhalter. Ein Platzhalter enthält Bildinformationen; schützen Sie ihn daher mit denselben Zugriffskontrollen wie das vollständige Bild.

  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 Transkodieren zu beschleunigen.

• user_meta

  Record<string, any>(Standard: {})

  Fügt jeder ausgegebenen Datei benutzerdefinierte JSON-Metadaten hinzu, ohne den Dateiinhalt zu verändern. Verschachtelte Objekte und Arrays werden unterstützt.

  Die Vererbung hängt vom Robot ab. Die Werte werden mit vorhandenen user_meta der Ausgabedatei zusammengeführt; der aktuelle Step ersetzt übereinstimmende Schlüssel auf oberster Ebene. Weisen Sie erforderliche Schlüssel explizit zu, wenn ein Robot neue Ausgabedateien erstellt.

  In Steps zur Verarbeitung bezieht sich ${file.*} auf die erste Eingabe und ${result.*} auf die ausgegebene Datei. Die Werte werden nach der Ausführung des Robots für jede Ausgabedatei ausgewertet, bevor die anschließende Metadatenextraktion und temporäre Speicherung erfolgen. Bei :original werden die Werte für jeden Upload vor der Metadatenextraktion ausgewertet.

  Nachfolgende Steps lesen ${file.user_meta.key}. Ein vollständiges Beispiel und die Vererbungsregeln finden Sie unter Benutzerdefinierte Metadaten.

• result

  boolean(Standard: false)

  Ob die Ergebnisse dieses Steps im Assembly Status JSON enthalten sein sollen

• queue

  batch

  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

  boolean(Standard: false)

  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 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

  boolean | Array<meta | execute>(Standard: [])

  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

  string | Array<string> | Array<object> | object

  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:

    {
      "use": [
        ":original",
        "encoded",
        "resized"
      ]
    }
    

  • Sie können Eingabe-Steps außerdem mit as kennzeichnen, um Robots die semantische Funktion zu übermitteln:

    {
      "use": [
        {
          "name": ":original",
          "as": "image"
        },
        {
          "name": ":original",
          "as": "mask"
        }
      ]
    }
    

  Tipp

  Das ist wahrscheinlich alles, was Sie über use wissen müssen. Sie können sich jedoch auch die erweiterten Anwendungsfälle ansehen.

• format

  avif | gif | jpeg | jpg | png | webp(Standard: "png")

  Das Ausgabeformat für das erzeugte Thumbnail. Wenn mit der Strategie clip ein kurzer Videoclip erzeugt wird, wird dessen Format durch clip_format festgelegt.

• quality

  string | number

  Komprimierungsqualität für statische Vorschauen, von 1 bis 100. Wenn angegeben, codiert die abschließende Größenänderung das Bild direkt im angeforderten Format mit dieser Qualität und entfernt eingebettete Metadaten. Lassen Sie den Wert weg, um das Standardverhalten beim Encoding beizubehalten. Animierte Clips verwenden eigene Encoding-Einstellungen. Wenn optimize aktiviert ist, erfolgt die Optimierung nach diesem Encoding.

• width

  number(Standard: 300)

  Breite des Thumbnails in Pixeln.

• height

  number(Standard: 200)

  Höhe des Thumbnails in Pixeln.

• resize_strategy

  crop | fit | fillcrop | min_fit | pad | stretch(Standard: "pad")

  Um die gewünschten Abmessungen des Thumbnails zu erreichen, muss der Robot möglicherweise die Größe des erzeugten Bildes ändern. Das passiert zum Beispiel, wenn die Abmessungen eines Frames, der aus einem Video extrahiert wurde, nicht den gewählten Parametern width und height entsprechen.

  Weitere Details finden Sie in der Liste der verfügbaren Größenänderungsstrategien.

• background

  string(Standard: "#ffffffff")

  Der hexadezimale Code der Farbe, mit der der Hintergrund gefüllt wird (nur bei der Größenänderungsstrategie pad verwendet). Das Format ist #rrggbb[aa] (Rot, Grün, Blau, Alpha). Verwenden Sie #00000000 für einen transparenten Rand.

• zoom

  boolean(Standard: true)

  Wenn dieser Parameter auf false gesetzt ist, werden kleinere Bilder nicht auf die gewünschten Werte für width und height gestreckt. Das ist nützlich, wenn Sie die ursprünglichen Bildabmessungen beibehalten und die Ausgabe nur auf eine maximale Größe begrenzen möchten. Details dazu, wie sich das Zoomen auf Ihre bevorzugte Resize-Strategie auswirkt, finden Sie in der Liste der verfügbaren Resize-Strategien.

  Beachten Sie, dass dieser Parameter nur Strategien betrifft, die ein Standbild erzeugen. Animierte Clips, die mit der Strategie clip erzeugt werden, sind davon nicht betroffen.

• strategy

  object

  Definition des Erzeugungsprozesses für Thumbnails je Dateikategorie. Jeder Schlüssel wählt eine Dateikategorie aus, und sein Wert ist ein geordnetes Array von Strategien:

  Dateikategorie	Verfügbare Strategien
  audio	artwork, waveform, icon
  video	artwork, frame, clip, icon
  image	image, embedded-preview, icon
  document	page, icon
  archive	icon
  webpage	render, icon
  unknown	icon

  artwork extrahiert ein eingebettetes Coverbild, waveform zeichnet eine Audio-Wellenform, frame extrahiert einen Videoframe und clip erstellt eine animierte Videovorschau. Bei Bildern ändert image die Größe des Originals, und embedded-preview extrahiert eine eingebettete Vorschau, sofern vorhanden. page rendert die erste Dokumentseite, render erfasst eine Webseite, und icon erzeugt ein Dateityp-Icon.

  Für jede Datei versucht der Robot zunächst, das Thumbnail mit der ersten Strategie zu erzeugen. Schlägt dieser Vorgang fehl (z. B. weil in einer Videodatei kein Coverbild vorhanden ist), wird die nächste Strategie versucht. Dies wird wiederholt, bis entweder ein Thumbnail erzeugt wurde oder die Liste erschöpft ist. Wenn Sie die Strategie icon als letzten Eintrag wählen, steht ein Fallback-Mechanismus bereit, der sicherstellt, dass immer eine geeignete Strategie verfügbar ist.

  Der Parameter hat standardmäßig folgende Definition:

  {
    "archive": [
      "icon"
    ],
    "audio": [
      "artwork",
      "waveform",
      "icon"
    ],
    "document": [
      "page",
      "icon"
    ],
    "image": [
      "image",
      "embedded-preview",
      "icon"
    ],
    "unknown": [
      "icon"
    ],
    "video": [
      "artwork",
      "frame",
      "icon"
    ],
    "webpage": [
      "render",
      "icon"
    ]
  }
  

• artwork_outer_color

  string

  Die Farbe, die in den äußeren Bereichen des Farbverlaufs des Coverbilds verwendet wird.

• artwork_center_color

  string

  Die Farbe, die in der Mitte des Farbverlaufs des Coverbilds verwendet wird.

• waveform_center_color

  string(Standard: "#000000ff")

  Die Farbe, die in der Mitte des Farbverlaufs der Wellenform verwendet wird. Das Format ist #rrggbb[aa] (Rot, Grün, Blau, Alpha). Wird nur verwendet, wenn die Strategie waveform für Audiodateien angewendet wird.

• waveform_outer_color

  string(Standard: "#000000ff")

  Die Farbe, die in den äußeren Bereichen des Farbverlaufs der Wellenform verwendet wird. Das Format ist #rrggbb[aa] (Rot, Grün, Blau, Alpha). Wird nur verwendet, wenn die Strategie waveform für Audiodateien angewendet wird.

• waveform_height

  string | number(Standard: 100)

  Höhe der Wellenform in Pixeln. Wird nur verwendet, wenn die Strategie waveform für Audiodateien angewendet wird. Damit lässt sich sicherstellen, dass die Wellenform nur einen Teil des Thumbnails einnimmt.

• waveform_width

  string | number(Standard: 300)

  Breite der Wellenform in Pixeln. Wird nur verwendet, wenn die Strategie waveform für Audiodateien angewendet wird. Damit lässt sich sicherstellen, dass die Wellenform nur einen Teil des Thumbnails einnimmt.

• icon_style

  square | with-text(Standard: "with-text")

  Der Stil des Icons, das erzeugt wird, wenn die Strategie icon angewendet wird. Der Standardstil with-text enthält ein Icon, das den Dateityp zeigt, sowie darunter ein Textfeld, dessen Inhalt über den Parameter icon_text_content gesteuert werden kann und standardmäßig der Dateiendung entspricht (z. B. MP4, JPEG). Der Stil square enthält nur eine quadratische Variante des Icons, die den Dateityp zeigt. Unten sehen Sie beispielhafte Vorschauen, die für eine Textdatei mit den verschiedenen Stilen erzeugt wurden:

  
  
  Stil with-text:
  
  
  Stil square:
  

• icon_text_color

  string(Standard: "#a2a2a2")

  Die Farbe des Texts im Icon. Das Format ist #rrggbb[aa]. Wird nur verwendet, wenn die Strategie icon angewendet wird.

• icon_text_font

  string(Standard: "Roboto")

  Die Schriftfamilie des Texts im Icon. Wird nur verwendet, wenn die Strategie icon angewendet wird. Hier finden Sie eine Liste aller unterstützten Schriftarten.

• icon_text_content

  extension | none(Standard: "extension")

  Der Inhalt des Textfelds in erzeugten Icons. Wird nur verwendet, wenn der Parameter icon_style auf with-text gesetzt ist. Der Standardwert extension fügt dem Icon die Dateiendung hinzu (z. B. MP4, JPEG). Der Wert none lässt das Textfeld leer und reserviert gleichzeitig Platz für ein eigenes Text-Overlay, zum Beispiel mithilfe von HTML in Ihrer Anwendung.

• optimize

  boolean(Standard: true)

  Gibt an, ob das erzeugte Vorschaubild optimiert werden soll, um seine Dateigröße bei gleichbleibender visueller Qualität zu verringern. Wenn aktiviert, wird das Bild mit 🤖/image/optimize optimiert.

• optimize_priority

  compression-ratio | conversion-speed(Standard: "conversion-speed")

  Gibt an, ob bei der Optimierung von Bildern die Konvertierungsgeschwindigkeit oder das Kompressionsverhältnis priorisiert wird. Wird nur verwendet, wenn optimize aktiviert ist. Weitere Details finden Sie bitte in der Dokumentation zu 🤖/image/optimize.

• optimize_progressive

  boolean(Standard: false)

  Gibt an, ob Bilder im Interlaced-Verfahren gespeichert werden sollen, sodass das Ergebnisbild im Browser progressiv geladen wird. Wird nur verwendet, wenn optimize aktiviert ist. Weitere Details finden Sie bitte in der Dokumentation zu 🤖/image/optimize.

• clip_format

  apng | avif | gif | webp(Standard: "webp")

  Das animierte Bildformat für den erzeugten Videoclip. Wird nur verwendet, wenn die Strategie clip für Videodateien angewendet wird.

  Ausführliche Informationen zu den Bildformaten und ihren Eigenschaften finden Sie bitte in den MDN Web Docs⁠. GIF genießt breite Unterstützung in Software, bietet aber nur eine begrenzte Farbpalette. APNG unterstützt verschiedene Farbtiefen, doch seine verlustfreie Komprimierung erzeugt bei Videos große Bilder. AVIF bietet eine effiziente Komprimierung, die Unterstützung für Animationen variiert jedoch zwischen Browsern. WebP bietet ein ausgewogenes Verhältnis zwischen kleinen Dateigrößen und visueller Qualität und ist das Standardformat für Clips.

• clip_offset

  string | number(Standard: 1)

  Die Startposition in Sekunden, an der der Clip geschnitten wird. Wird nur verwendet, wenn die Strategie clip für Videodateien angewendet wird. Bei großen Videos werden möglicherweise nur Teile der Datei importiert, um die Geschwindigkeit zu verbessern. Ein Offset außerhalb der verfügbaren Mediendaten kann die Erzeugung des Clips verhindern.

• clip_duration

  string | number(Standard: 5)

  Die Dauer des erzeugten Videoclips in Sekunden. Wird nur verwendet, wenn die Strategie clip für Videodateien angewendet wird. Beachten Sie, dass ein längerer Clip auch zu einer größeren Datei führt, was für Vorschauen unerwünscht sein kann.

• clip_framerate

  string | number(Standard: 5)

  Die Framerate des erzeugten Videoclips. Wird nur verwendet, wenn die Strategie clip für Videodateien angewendet wird. Beachten Sie, dass eine höhere Framerate flüssiger wirkt, aber auch zu einer größeren Datei führt, was für Vorschauen unerwünscht sein kann.

• clip_loop

  boolean(Standard: true)

  Gibt an, ob das erzeugte animierte Bild endlos wiederholt werden soll (true) oder nach einmaligem Abspielen der Animation stoppt (false). Wird nur verwendet, wenn die Strategie clip für Videodateien angewendet wird.

Verwandte Blogbeiträge