Aussagekräftige Dateivorschauen erstellen

Kevin van Zonneveld

Mitgründer · Amsterdam, Niederlande · Bio anzeigen

Wir stellen unseren neuen Robot /file/preview vor – eine Transloadit-Funktion, die automatisch Vorschauen für unterstützte Dateiformate erstellen soll, mit einem Symbol als Ersatz. Ob Video-Thumbnails, Album-Coverbilder oder Wellenformen für Audio, Dokumentseitenvorschauen, Website-Screenshots oder Archivsymbole: Dieser Robot kann Vorschauen liefern, mit denen Menschen Dateien schnell erkennen. Wir übernehmen die Komplexität der verschiedenen Dateitypen, während Sie sich auf die Entwicklung Ihrer App konzentrieren können.

Der Robot lässt sich mit wenigen Zeilen JSON einsetzen und nutzt intern dateispezifische Strategien. Er kann die Vorschauerstellung vereinfachen und Nutzern helfen, Dateien in Ihrer App zu erkennen.

Was kann der Robot?

🤖/file/preview ist darauf ausgelegt, aussagekräftige Vorschauen zu erstellen, mit denen Nutzer Dateiinhalte schnell erkennen. Er unterstützt:

• Bilder: Optimierte Thumbnails für unterstützte Bilder, einschließlich RAW-Formaten:
• Videos: Einzelbilder oder kurze Clips: (oder ein Ersatzsymbol, wenn keine Inhaltsvorschau erstellt werden kann: )
• Audio: Eingebettetes Coverbild (oder eine Wellenformdarstellung, falls keines vorhanden ist: )
• Dokumente: Vorschauen der ersten Seite
• Webseiten: Seiten-Screenshots
• Archive: Dateitypspezifische Symbole

Welche Vorschau verfügbar ist, hängt vom Format, Codec und den Mediendaten der Datei ab. Nicht für jede Datei lässt sich eine Inhaltsvorschau erstellen.

Mit den Standardstrategien greift der Robot auf ein dateitypspezifisches Symbol zurück, wenn keine aussagekräftigere Vorschau verfügbar ist, wie beim Archivbeispiel oben. Die Dokumentation zu den Strategien beschreibt die unterstützten Strategien und die Reihenfolge der Ersatzoptionen.

Der Robot ist darauf ausgelegt, direkt praktische und ansprechende Voreinstellungen zu bieten. Sein Verhalten lässt sich aber vollständig anpassen. Mehr dazu weiter unten.

Warum Transloadit?

Vorschauen für viele verschiedene Dateien zu erstellen, ist angesichts der Vielzahl an Bildformaten, Video-Codecs und Dokumenttypen komplex. Das gilt besonders für spezialisierte Kunden, etwa Fotografen, die mit RAW-Bildformaten arbeiten, oder Nutzer, die mit verschiedenen Microsoft-Office-Dokumenten arbeiten. Da sich Bild- und Videoformate ständig weiterentwickeln, sind laufende Investitionen nötig, um Schritt zu halten und die neuesten Formate zu unterstützen. Die verfügbaren Konvertierungen finden Sie auf der Seite Unterstützte Formate und in der Robot-Referenz.

Eine eigene Lösung zur Dateivorschauerstellung erfordert erhebliche Entwicklungsressourcen, selbst wenn sie nur einen Teil der zahlreichen Dateitypen abdeckt. Sie bindet diese Ressourcen langfristig, da sie gewartet und für neue Formate aktualisiert werden muss. Zudem ist die Verarbeitung von Dateien, die Nutzer hochladen, heikel: Sie kann Ihre Infrastruktur anfällig für Sicherheitslücken in den verschiedenen Dateiverarbeitungswerkzeugen machen. Überlassen Sie die Dateivorschauerstellung stattdessen Transloadit. So verlagern Sie diese Verarbeitung weg von Ihren Anwendungsservern. Ihr Entwicklungsteam kann sich darauf konzentrieren, Ihren Kunden den bestmöglichen Service zu bieten, während Transloadit den komplexen Teil der Dateivorschauen übernimmt.

🤖/file/preview lässt sich mit anderen Robots kombinieren, um individuelle Workflows für Ihr Unternehmen zu erstellen. Damit können Sie jeden Teil Ihrer Dateipipeline umgestalten. Transloadit kann direkt die Uploads Ihrer Endnutzer verarbeiten, große Medienbibliotheken importieren oder Dateien bei Bedarf konvertieren und optimierte Ergebnisse mit unserem Smart CDN direkt an Browser streamen.

Implementierungsmöglichkeiten

Sie können 🤖/file/preview auf verschiedene Arten einsetzen. Am besten erstellen Sie zunächst ein Template, das diesen Robot referenziert. Ein Template ist ein JSON-Rezept in Ihrem Konto, das beschreibt, was Transloadit mit Ihren Dateien tun soll. Sie können es im Template Editor in Ihrem Konto oder mit unserem Terraform Provider Plugin erstellen.

Vorverarbeitung

Bei der Vorverarbeitung erstellen Sie die Vorschauen und speichern sie in Ihrem Speicher. Das passiert üblicherweise, wenn ein Nutzer die Datei erstmals hochlädt, lange bevor ein Endnutzer eine Vorschau anfordert. Diese Vorverarbeitung kann die Latenz bei der ersten Anfrage reduzieren. Dafür entstehen höhere Encoding- und Speicherkosten, und die Integration ist komplexer als bei der Erstellung auf Abruf.

Transloadit kann die Uploads der Originale übernehmen, Vorschauen erstellen und diese anschließend in Ihrem Speicher ablegen. Damit Transloadit Uploads verarbeitet, referenzieren Sie 🤖/upload/handle in Ihrem Template wie folgt:

{
  "allow_steps_override": false,
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "previewed": {
      "robot": "/file/preview",
      "use": ":original",
      "width": 300,
      "height": 200
    },
    "stored": {
      "use": ["previewed", ":original"],
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "acl": "bucket-default",
      "path": "my_target_folder/${unique_prefix}/${file.url_name}"
    }
  }
}

Ersetzen Sie YOUR_AWS_CREDENTIALS durch den Namen Ihrer gespeicherten Template-Zugangsdaten. Das eindeutige Präfix gibt jedem Original und jeder Vorschau einen eigenen Objektpfad. acl: "bucket-default" lässt den generierten ACL-Header weg; konfigurieren Sie die Zugriffsrichtlinie Ihres Buckets separat. Befolgen Sie die Hinweise zur S3-Einrichtung und zu Berechtigungen, bevor Sie dieses Template verwenden.

Die Uploads kommen üblicherweise aus Browsern, etwa mit Uppy⁠. Auch Backend-SDKs können Dateien hochladen.

Sehen wir uns zunächst den Anwendungsfall im Browser genauer an.

Frontend-Uploads

Transloadit könnte Browser-Uploads übernehmen, die Endnutzer mit Uppy⁠ durchführen, unserem Open-Source-Dateiuploader für Webbrowser. Beim Annehmen der Dateien folgt Transloadit den Instructions im Template, erstellt also Vorschauen und speichert sie in Ihrem S3-Bucket. Auch die Originale werden gespeichert, da wir im Step "stored" Folgendes angegeben haben: "use": ["previewed", ":original"].

Implementieren Sie vor dem Ausführen des Browsercodes einen geschützten Handler für POST /api/transloadit/assembly-options in Ihrer eigenen Anwendung. Er muss Ihren Nutzer authentifizieren, den Upload autorisieren, den Ursprung der Anfrage oder das CSRF-Token Ihrer App prüfen und Ihre Upload-Limits durchsetzen. Binden Sie ihn an die feste ID des obigen Upload-Templates; signieren Sie keine beliebigen Templates oder Instructions, die der Browser übermittelt. Aktivieren Sie Signature Authentication für Ihren Workspace und behalten Sie allow_steps_override: false im gespeicherten Template bei.

Verwenden Sie in diesem Backend das Beispiel zur Signaturerstellung, um { params, signature } mit einem kurzlebigen auth.expires zurückzugeben. Geben Sie die serialisierte Zeichenfolge params unverändert zurück und behalten Sie das Auth Secret auf dem Server. Dieser Endpunkt gehört zu Ihrer App; er ist kein Transloadit-API-Endpunkt.

Installieren Sie @uppy/core, @uppy/dashboard und @uppy/transloadit mit Yarn in Ihrem Browserprojekt und fügen Sie der Seite ein Element mit id="uppy-dashboard" hinzu. Binden Sie diesen Code mit Ihrem Bundler ein:

import Uppy from '@uppy/core'
import Dashboard from '@uppy/dashboard'
import Transloadit from '@uppy/transloadit'

import '@uppy/core/dist/style.min.css'
import '@uppy/dashboard/dist/style.min.css'

const uppy = new Uppy()
  .use(Dashboard, {
    inline: true,
    // This is the element where the dashboard will be rendered:
    target: '#uppy-dashboard',
  })
  .use(Transloadit, {
    waitForEncoding: true,
    assemblyOptions: async () => {
      const response = await fetch('/api/transloadit/assembly-options', {
        method: 'POST',
        credentials: 'same-origin',
      })
      if (!response.ok) {
        throw new Error(`Could not authorize the upload (HTTP ${response.status})`)
      }
      return response.json()
    },
  })

uppy.on('transloadit:complete', (assembly) => {
  const preview = assembly.results?.previewed?.[0]
  if (preview) {
    console.log('Preview object URL:', preview.ssl_url)
  } else {
    console.log('No previews were generated.')
  }
})

Der S3-Export aktualisiert die Ergebnisse unter dem erzeugenden Step, previewed. Ein zurückgegebener Wert ssl_url gewährt weder Zugriff auf ein privates S3-Objekt noch garantiert er eine dauerhafte Download-URL. Autorisieren Sie Downloads in Ihrer Anwendung, beispielsweise mit kurzlebigen S3-Download-URLs, die Ihr Backend generiert.

Uppy wurde von Transloadit entwickelt. Es bietet mehr Funktionen, als in diesen Beitrag passen. Weitere Informationen finden Sie daher auf der Uppy-Website⁠.

Für die Integration in native mobile Apps gibt es auch SDKs für Android und iOS.

Backend-Uploads

Auch Backends können Dateien zu Transloadit hochladen. So würde das in Node.js aussehen:

Installieren Sie @transloadit/node mit yarn add @transloadit/node. Speichern Sie das Beispiel als upload.mjs und führen Sie es mit node upload.mjs aus. Setzen Sie zuvor TRANSLOADIT_KEY, TRANSLOADIT_SECRET und TRANSLOADIT_TEMPLATE_ID in der Serverumgebung. Verwenden Sie dabei die ID des obigen Upload-Templates und ersetzen Sie ./file.mp4 durch eine lesbare lokale Datei. Halten Sie das Auth Secret aus Browsercode und Versionsverwaltung heraus.

import { Transloadit } from '@transloadit/node'

const { TRANSLOADIT_KEY, TRANSLOADIT_SECRET, TRANSLOADIT_TEMPLATE_ID } = process.env
if (!TRANSLOADIT_KEY || !TRANSLOADIT_SECRET || !TRANSLOADIT_TEMPLATE_ID) {
  throw new Error('Set TRANSLOADIT_KEY, TRANSLOADIT_SECRET, and TRANSLOADIT_TEMPLATE_ID.')
}

const transloadit = new Transloadit({
  authKey: TRANSLOADIT_KEY,
  authSecret: TRANSLOADIT_SECRET,
})

const assembly = await transloadit.createAssembly({
  params: { template_id: TRANSLOADIT_TEMPLATE_ID },
  files: { file: './file.mp4' },
  waitForCompletion: true,
})

const preview = assembly.results?.previewed?.[0]
if (preview) {
  console.log('Preview object URL:', preview.ssl_url)
} else {
  console.log('No previews were generated.')
}

Für viele weitere Backend-Sprachen gibt es SDKs, die die Integration erleichtern. Sie können aber auch direkt unsere REST API ansprechen.

Dateiimporte

Statt Transloadit Uploads übernehmen zu lassen, kann Transloadit Dateien aus Cloud-Quellen wie S3 importieren, Vorschauen erstellen und sie zurück zu S3 oder zu anderen Speicheranbietern exportieren. Das ist für eine einzelne Datei ebenso möglich wie für ganze Buckets mit vielen Terabyte an Dateien.

Als Beispiel ergänzen wir das folgende Template um 🤖/file/filter. Damit zeigen wir, wie Sie nach Dateityp filtern und in diesem Fall nur Vorschauen für Audiodateien erstellen können. Das lässt sich auch auf andere Eigenschaften wie Dateigröße, Bitrate oder Medientyp anpassen. Hier ist das vollständige Template, das Sie im Template Editor in Ihrem Konto erstellen würden:

{
  "steps": {
    "imported": {
      "robot": "/s3/import",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "my_source_folder/"
    },
    "audio_filtered": {
      "use": "imported",
      "robot": "/file/filter",
      "accepts": [["${file.type}", "==", "audio"]],
      "error_on_decline": false
    },
    "previewed": {
      "robot": "/file/preview",
      "use": "audio_filtered",
      "width": 300,
      "height": 200,
      "format": "png"
    },
    "stored": {
      "use": "previewed",
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "acl": "bucket-default",
      "path": "my_target_folder/${unique_prefix}/${file.url_name}"
    }
  }
}

Sie können dieses Template mit jedem unserer SDKs referenzieren und ausführen. Verwenden Sie für Node.js dasselbe Paket und dieselbe Serverumgebung wie oben, setzen Sie aber TRANSLOADIT_TEMPLATE_ID auf die ID dieses Import-Templates. Speichern Sie Folgendes als import.mjs und führen Sie node import.mjs aus. Ein lokaler Upload ist nicht erforderlich. Wenn der Filter keine Audiodateien findet, gibt es keine Vorschauen zum Abrufen:

import { Transloadit } from '@transloadit/node'

const { TRANSLOADIT_KEY, TRANSLOADIT_SECRET, TRANSLOADIT_TEMPLATE_ID } = process.env
if (!TRANSLOADIT_KEY || !TRANSLOADIT_SECRET || !TRANSLOADIT_TEMPLATE_ID) {
  throw new Error('Set TRANSLOADIT_KEY, TRANSLOADIT_SECRET, and TRANSLOADIT_TEMPLATE_ID.')
}

const transloadit = new Transloadit({
  authKey: TRANSLOADIT_KEY,
  authSecret: TRANSLOADIT_SECRET,
})

const assembly = await transloadit.createAssembly({
  params: { template_id: TRANSLOADIT_TEMPLATE_ID },
  waitForCompletion: true,
})

const preview = assembly.results?.previewed?.[0]
if (preview) {
  console.log('Preview object URL:', preview.ssl_url)
} else {
  console.log('No previews were generated.')
}

Auf Abruf

Schließlich können Sie Vorschauen auch auf Abruf mit unserem Smart CDN erstellen. Transloadit wird dann erst tätig, wenn ein Nutzer die Vorschau anfordert. Anschließend importiert Transloadit die Originaldatei aus Ihrem Speicher, erstellt die Vorschau und liefert sie direkt an den Endnutzer aus. Wir speichern das Ergebnis im Cache in der Nähe des Endnutzers.

Das bietet folgende Vorteile:

• Die Vorschau wird erst erstellt, wenn Nutzer sie anfordern. So sparen Sie Kosten für Mediendateien, die tatsächlich nicht angefordert werden.
• Ein Ergebnis im Cache kann ohne weitere Encoding-Gebühr ausgeliefert werden, solange es verfügbar und cachefähig bleibt. Für die Auslieferung aus dem Cache fallen weiterhin Bandbreitengebühren an. Ein abgelaufenes oder aus dem Cache entferntes Ergebnis muss eventuell erneut verarbeitet werden, wobei neue Verarbeitungsgebühren entstehen.
• Die Integration ist einfacher, da Sie die Vorschauen nicht selbst weiterverarbeiten müssen (speichern, Referenzen ablegen usw.). Stattdessen erstellen Sie einfach ein Template und fügen Ihrer Webseite oder App eine Smart-CDN-URL für die Datei hinzu.
• Sie können die Vorschau an Gerät, Auflösung, Bandbreite usw. des Endnutzers anpassen. So verschwenden Sie bei der Auslieferung keine Bytes, die das Nutzererlebnis nicht verbessern. Das spart Bandbreite, Akkuleistung und Zeit.

Mehr über Vorschauen auf Abruf, signierte URLs und Auslieferungsmessungen erfahren Sie in unserem Beitrag: Medienvorschauen auf Abruf mit Smart CDN.

Dieses Beispiel-Template weist Transloadit an, eine Mediendatei aus S3 zu importieren, eine Vorschau zu erstellen und sie mit unserem Smart CDN auszuliefern:

{
  "steps": {
    "imported": {
      "robot": "/s3/import",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "${fields.input}"
    },
    "previewed": {
      "use": "imported",
      "robot": "/file/preview",
      "width": "${fields.w}"
    },
    "served": {
      "use": "previewed",
      "robot": "/file/serve"
    }
  }
}

Die URL-Struktur für dieses Template lautet:

https://my-workspace.tlcdn.com/my-template/file.mp4?w=300

Verwenden Sie für YOUR_AWS_CREDENTIALS den Namen Ihrer gespeicherten Template-Zugangsdaten und legen Sie die Quelldatei unter file.mp4 in diesem S3-Bucket ab. Hier ist my-template der Template-Name, ${fields.input} erhält file.mp4, und ${fields.w} erhält 300 aus der URL. Ersetzen Sie die Platzhalter für Workspace und Template durch Ihre eigenen Werte. Dies zeigt die URL-Struktur. Für eine geschützte Auslieferung autorisieren Sie die angeforderte Datei und die Abmessungen in Ihrem Backend und generieren eine signierte URL mit Ablaufzeit, bevor Sie diese an den Browser senden. Befolgen Sie die Anleitung zum Signieren von Smart-CDN-URLs. Setzen Sie require_signature_auth auf 1 mithilfe der Template API. Dies ist eine Template-Einstellung außerhalb des obigen Instructions-JSON. Stellen Sie keinen allgemein verwendbaren Signierungsendpunkt bereit, der beliebige Pfade oder Transformationen akzeptiert.

Vorschau anpassen

🤖/file/preview bietet direkt praktische und ansprechende Voreinstellungen. Mit verschiedenen Parametern können Sie die Ausgabe an das Erscheinungsbild Ihrer App anpassen:

• format: Ausgabeformat des Thumbnails
• width und height: Abmessungen in Pixeln
• resize_strategy: Anpassung der Vorschau an die Abmessungen
• background: Hintergrundfarbe für Auffüllflächen im Hexadezimalformat (#rrggbb[aa])
• strategy: Vorschauerstellung je Dateityp anpassen (Audio, Video, Bild usw.)

Für Audiowellenformen:

• waveform_center_color und waveform_outer_color: Verlaufsfarben im Hexadezimalformat
• waveform_height und waveform_width: Abmessungen der Wellenform

Für Symbole:

• icon_style: Erscheinungsbild des Ersatzsymbols
• icon_text_color: Textfarbe im Hexadezimalformat
• icon_text_font: Schriftfamilie
• icon_text_content: Text auf dem Symbol

Für Videoclips:

• clip_format: Animationsformat
• clip_offset: Startposition in Sekunden
• clip_duration: Länge in Sekunden
• clip_framerate: Bilder pro Sekunde
• clip_loop: Animation wiederholen

Für die Bildoptimierung:

• optimize: Dateigrößenoptimierung aktivieren
• optimize_priority: Verhältnis zwischen Konvertierungsgeschwindigkeit und Kompressionsrate
• optimize_progressive: Progressives Laden aktivieren

Zulässige Werte, Voreinstellungen, Limits und das strategiespezifische Verhalten finden Sie in der Dokumentation zu 🤖/file/preview.

Sicherheitsaspekte

Um Ihre Dateien zu schützen und den Zugriff auf die Vorschaufunktion zu steuern, empfehlen wir, Anfragen bei Frontend-Integrationen (Uppy, Smart CDN, mobil) zu signieren. Autorisieren Sie insbesondere bei der Smart-CDN-Auslieferung den Zugriff auf die angeforderte Datei und Transformation, bevor Sie eine Smart-CDN-URL signieren. Die Signatur schützt die URL; jeder, der sie erhält, kann sie während ihrer Gültigkeit verwenden.

Ausführliche Informationen mit Beispielen in vielen Programmiersprachen finden Sie in unserer Dokumentation zu signierten Smart-CDN-URLs.

Denken Sie daran:

• Generieren Sie signierte URLs immer in Ihrem Backend.
• Legen Sie Ihr Auth Secret niemals in clientseitigem Code offen.
• Legen Sie für Ihre signierten URLs eine Ablaufzeit fest.

Kürzere Gültigkeitsdauern verkleinern das Replay-Zeitfenster. Eine längere Gültigkeitsdauer lässt eine URL länger nutzbar bleiben; sie garantiert weder die Aufbewahrung im Cache noch Cache-Treffer oder niedrigere Verarbeitungskosten. Die Auslieferung aus dem Cache bleibt kostenpflichtig, und abgelaufene oder aus dem Cache entfernte Ergebnisse können eine erneute Verarbeitung erfordern.

Fortgeschrittene Anwendungsfälle

Dieser Beitrag behandelt die grundlegenden Möglichkeiten, 🤖/file/preview zu nutzen. Es gibt aber viele Wege, den Robot in komplexere Pipelines zu integrieren:

• Automatisierte Stapelerstellung: Planen Sie die Vorschauerstellung für ganze Speicher-Buckets, um aktuelle Vorschauen in großem Umfang bereitzuhalten.
• Ereignisgesteuerte Integrationen: Lösen Sie die Vorschauverarbeitung automatisch aus, sobald neue Dateien eintreffen, damit Vorschauen immer bereitstehen, wenn sie benötigt werden.
• Hybride Workflows zusammenstellen: Kombinieren Sie 🤖/file/preview mit anderen Transloadit Robots – etwa 🤖/image/facedetect oder 🤖/video/encode –, um mehrstufige Transformationen in einem einzigen Workflow zu erstellen.
• Erweiterte Speicheroptionen: Neben AWS S3 können Sie alle wichtigen Cloud-Speicheranbieter sowie Ihre eigene Infrastruktur (S3-kompatiblen Speicher oder SFTP) nahtlos integrieren.
• Anpassbares Caching: Kombinieren Sie 🤖/file/preview mit Smart-CDN-Konfigurationen, die Ihre Anforderungen an Leistung und Zuverlässigkeit erfüllen.
• Eigenes CDN nutzen: Bei Bereitstellungen mit hohem Volumen können Kunden bestehende Verträge und Infrastruktur nutzen, indem sie unsere Encoding-Plattform mit ihrem eigenen CDN kombinieren.

Preise und Verfügbarkeit

Aktuelle Tarife, Preise und Tarifbeschränkungen finden Sie auf unserer Preisseite und in der Preisdokumentation des Robots.

Weiterführende Informationen

Vielleicht interessieren Sie sich für unsere

• Demos EN (English), um weitere Funktionen und ihre Kombinationsmöglichkeiten kennenzulernen.
• Smart CDN, um mehr darüber zu erfahren, wie Sie Dateien, Vorschauen und andere Konvertierungen auf Abruf ausliefern können.
• Medienvorschauen auf Abruf mit Smart CDN mit einer Demo, Auslieferungsmessungen und einem Beispiel für serverseitiges Signieren.

Nächste Schritte

So starten Sie:

1. Registrieren Sie sich für ein Transloadit-Konto.
2. Erstellen Sie Ihr erstes Template mit 🤖/file/preview.
3. Testen Sie verschiedene Vorschau- und Integrationsoptionen mit unserem Template Editor.
4. Integrieren Sie Vorschauen in Ihre Anwendung.

Brauchen Sie Starthilfe? Wir bauen Robots, sind aber Menschen, die Ihnen gerne helfen! Kontaktieren Sie uns einfach unter support@transloadit.com.

Ansonsten viel Spaß beim Transloading 🙂