Leitfaden: Uploads (Echtzeit)
Leitfaden: Uploads (Echtzeit)
Einführung
Aufbauend auf unseren Grundkenntnissen zum Hochladen wollen wir uns nun damit befassen, wie man Assets in Echtzeit hochlädt, während sie erstellt werden.Mit diesem Ansatz werden Dateien während der Aufnahme, des Renderns oder des Streamings hochgeladen, noch bevor deren endgültige Größe bekannt ist.
Die Echtzeit-Upload-API gestattet es, dass Assets bereits wenige Sekunden nach Abschluss der Aufnahme in Frame.io abgespielt werden können, was die Effizienz des Workflows erheblich steigert.
Demovideo
Um sich einen kurzen Überblick über diese Funktion zu verschaffen, sehen Sie sich bitte unsere Videovorführung an.Die Demo zeigt, wie ein Rendering in Echtzeit aus Adobe Media Encoder hochgeladen wird, wobei das Video bereits 5 Sekunden nach Abschluss des Renderings in Frame.io abgespielt werden kann.
Voraussetzungen
Wenn Sie es noch nicht getan haben, lesen Sie bitte den Leitfaden C2C implementieren: Einrichtung.Sie benötigen den access_token, den Sie während des Authentifizierungs- und Autorisierungsprozesses erhalten haben.Für unsere Beispiele verwenden wir das Test-Asset aus dem Leitfaden zu einfachen Uploads.Es wird empfohlen, sich mit dem Leitfaden zu einfachen Uploads vertraut zu machen, da wir auf diesen Konzepten aufbauen werden.
Ein Echtzeit-Asset erstellen
Echtzeit-Uploads beginnen mit einem angepassten Verfahren zur Erstellung von Assets.Legen Sie beim Erstellen des Assets is_realtime_upload auf true fest und lassen Sie den Parameter filesize weg (oder setzen Sie ihn auf null), da die endgültige Größe zum Zeitpunkt der Erstellung noch nicht bekannt ist:
Spezifikation des API-Endpunkts
Die Dokumentation für /v2/devices/assets findet sich hier.
Erweiterung und Dateiname
Echtzeit-Assets benötigen eine Dateierweiterung.Falls der Dateiname beim Erstellen des Assets noch nicht bekannt ist, können Sie stattdessen das Feld Erweiterung verwenden (Format: '.mp4').Dieser Ansatz ist vorzuziehen, wenn Sie beabsichtigen, den Namen des Assets später zu ändern.
Die Vorgehensweise bei der Erstellung von Echtzeit-Assets ist im Vergleich zur Erstellung von Standard-Assets vereinfacht:
Beachten Sie, dass upload_urls fehlt – für Echtzeit-Uploads generieren wir die Upload-URLs nach Bedarf, sobald die Datei erstellt wird.
Upload-URLs anfordern
Lassen Sie uns eine URL für die erste Hälfte unserer Datei (10.568.125 Byte) anfordern, wobei wir die asset_id aus der vorherigen Antwort verwenden:
Spezifikation des API-Endpunkts
Die Dokumentation zu /v2/devices/assets/{asset_id}/realtime_upload/parts finden Sie hier.
Die Anfrageparameter verstehen:
-
parts: Eine Liste der Upload-Teile, für die wir URLs benötigen.Die Anfrage mehrerer URLs in einem einzigen Aufruf erhöht die Effizienz. -
number: Die fortlaufende Artikelnummer, beginnend mit 1.Nummern können übersprungen und Teile in beliebiger Reihenfolge hochgeladen werden, sie werden jedoch der Reihe nach zusammengesetzt.Darf 10.000 nicht überschreiten (AWS-Limit).*size: Teilgröße in Byte.Die Einschränkungen für mehrteilige Uploads bei AWS müssen eingehalten werden.*is_final: Gibt an, ob es sich um den letzten Dateiteil handelt.
Die Antwort enthält die angeforderten Upload-URLs:
Die Liste upload_urls entspricht direkt der Reihenfolge der Teileanfragen unter parts.
Laden Sie nun den ersten Chunk wie im Leitfaden zu einfachen Uploads beschrieben hoch:
Fordern Sie als Nächstes eine URL für den zweiten und letzten Teil an:
Beachten Sie folgende wichtige Ergänzungen:
- Für den letzten Teil wird
is_finalauftruegesetzt, was bedeutet, dass der Upload nach diesem Chunk abgeschlossen sein wird asset_filesizegibt die gesamte Dateigröße an, die erforderlich ist, wenn ein Teilis_final: truehat
Nachdem Sie die URL in der Antwort erhalten haben:
Laden Sie den letzten Chunk hoch:
Den letzten Teil verarbeiten
Sobald der letzte Teil hochgeladen ist, beginnt Frame.io mit der Zusammenführung der vollständigen Datei.Dieser Vorgang umfasst eine Nachfrist von 60 Sekunden, damit noch ausstehende Teile abgeschlossen werden können.Wir empfehlen, den letzten Teil erst dann hochzuladen, wenn alle anderen Teile erfolgreich hochgeladen wurden.
Das ist alles!Rufen Sie Frame.io auf, um Ihr erfolgreich hochgeladenes Echtzeit-Asset anzuzeigen.🎉
Asset-Namen verwalten
Falls der Dateiname bei der Erstellung des Assets noch nicht bekannt ist, können Sie das Feld extension ohne name verwenden:
Das System weist dann einen Standardnamen zu:
Sie können diesen Namen aktualisieren, indem Sie bei der Anfrage von Upload-URLs ein Feld asset_name angeben:
Der Name wird nur aktualisiert, wenn das Asset noch seinen Standardnamen trägt; wurde es in der Frame.io-Benutzeroberfläche umbenannt oder bereits zuvor aktualisiert, wird die Anfrage ignoriert.
URL-Anfragen optimieren
Um die Effizienz zu steigern, rufen Sie die URLs für so viele Teile ab, wie Ihnen derzeit Daten vorliegen, anstatt sie einzeln abzufragen.Dieser Ansatz ist besonders bei großen Dateien von Vorteil, bei denen die Upload-Geschwindigkeit hinter der Datengenerierung zurückbleiben könnte.
Header für Mediendateien verarbeiten
Bei einigen Medienformaten sind am Anfang der Datei Header erforderlich, die erst geschrieben werden, wenn die gesamte Datei vollständig ist.Dies stellt eine Herausforderung dar, wenn der Header kleiner ist als die von AWS festgelegte Mindestgröße von 5 MiB (5.242.880 Byte).
Unsere Empfehlung:
- Reservieren Sie die ersten 5.242.880 Byte der Mediendaten, ohne sie hochzuladen
- Beginnen Sie mit dem Hochladen der Teile, beginnend mit
part_number=2 - Wenn die Datei vollständig ist, stellen Sie den Header an den Anfang der reservierten Daten
- Fordern Sie eine URL für
part_number=1an und laden Sie diesen kombinierten Chunk hoch
Dieser Ansatz stellt sicher, dass Ihr erster Chunk die Mindestgrößenanforderung erfüllt und gleichzeitig die korrekte Dateistruktur beibehalten wird.
Teilgröße für optimale Leistung skalieren
AWS legt Limits fest, die sich auf die Upload-Strategie auswirken:
- Maximale Dateigröße: 5 TiB (5.497.558.138.880 Byte)
- Maximale Anzahl Teile: 10.000
- Minimale Teilgröße: 5 MiB (5.242.880 Byte)
Eine feste Teilgröße schafft Kompromisse:
- Bei Verwendung der Mindestgröße (5 MiB) für alle 10.000 Teile wird die Gesamtdateigröße auf ca. 52,4 GB begrenzt
- Um die maximale Dateigröße gleichmäßig zu verteilen, wären Chunks von etwa 550 MB erforderlich, die für ein effizientes Streaming kleinerer Dateien zu groß sind
Wir benötigen eine Formel, die diese Begrenzungen in Einklang bringt: Sie sollte zunächst kleine Teile für responsive Uploads nutzen und gleichzeitig sicherstellen, dass wir bei Bedarf auch sehr große Dateien verarbeiten können.
Empfohlene Formel für die Teilgröße
Hier ist unser Lösungsvorschlag in Python:
… wobei part_number zwischen 1 und 10_000 (einschließlich) liegt und format_bytes_per_second die voraussichtliche durchschnittliche Anzahl an Bytes angibt, die Ihre Datei pro Sekunde verbrauchen wird.Wir werden später noch näher darauf eingehen, wie man zu dieser Formel gelangt ist.
Skalarer Wert
Die Variable scalar und die Berechnung mögen auf den ersten Blick etwas verwirrend wirken, doch handelt es sich um ein mathematisches Hilfsmittel, das sicherstellt, dass wir – unabhängig davon, welchen Wert wir für format_bytes_per_second verwenden – bei Eingabe aller zulässigen Werte für part_number von 1 bis 10_000 in die Funktion eine Reihe von Werten erhalten, deren Summe genau unserem Dateigrößenlimit von 5 TiB entspricht – nun ja, so genau wie möglich.Im Folgenden erläutern wir näher, wie wir zu dieser Formel gelangt sind.
Auf die nächste ganze Zahl abrunden
Durch die Verwendung der Abrundung auf die nächste ganze Zahl lassen wir zwar einige Bytes ungenutzt, stellen jedoch sicher, dass eine reguläre Rundung bei Werten über 10.000 nicht versehentlich dazu führt, dass wir unsere maximal zulässige Dateigröße überschreiten.Auf diese Weise bleiben höchstens 10.000 Byte bzw. 10 KB ungenutzt – ein akzeptabler Kompromiss.
Die wesentlichen Merkmale dieser Formel sind:
- Beim Hochladen von 10.000 Teilen wird die Gesamtdatenmenge weniger als 10 KB unter unserem Dateigrößenlimit von 5 TiB liegen.
- Optimiert zu Beginn auf kleinere, effizientere Payloads, um die Reaktionsgeschwindigkeit bei kurzen und mittellangen Clips zu erhöhen.
- Bei sehr langen Clips kommt es zu einer verzögerten Reaktionszeit zwischen dem Ende des Schreibvorgangs und dem Zeitpunkt, zu dem der Clip im Frame wiedergegeben werden kann.
Der Kompromiss zwischen dem zweiten und dritten Punkt wird dadurch gemildert, dass die meisten Clips nicht die Größe erreichen, bei der Punkt drei zum Tragen kommt.Wir tauschen eine verbesserte Reaktionsgeschwindigkeit bei den MEISTEN Dateien gegen eine geringere Reaktionsgeschwindigkeit bei einigen wenigen ein.
Eine weiterentwickelte und effizientere Version unserer Formel (die eine anonyme Funktion part_size_calculator generiert, in der unser statischer Skalar und die Datenrate bereits vorberechnet und integriert sind) könnte wie folgt aussehen:
Wie sich die Formel bewährt.
Betrachten wir die Ausgabeeigenschaften der obigen Formel für verschiedene gängige Dateiformate.
Beispiel 1: Webformat
Bei im Web abspielbaren Formaten mit einer Bitrate von ca. 5,3 MB/s oder weniger (die meisten H.264-/H.265-/HEVC-Dateien) ergibt sich folgende Entwicklung der Payload-Größe:
Diese Werte sind für Echtzeit-Uploads gut ausbalanciert, insbesondere bei Codecs für die Web-Wiedergabe wie H.264; die meisten liegen unter 10,7 GB und sind daher innerhalb von 1.000 Teilen abgeschlossen.Die Payload-Größe würde niemals 21,6 MB überschreiten.
Wenn wir uns durch die Hälfte unserer Teile durcharbeiten würden, würde die Payload-Größe dennoch niemals 413,5 MB überschreiten.Der Upload würde insgesamt 707 GB betragen, was für die allermeisten Webdateien mehr als ausreichend ist.
Erst wenn wir uns dem Ende unserer zulässigen Teileanzahl nähern, beginnt die Dateigröße, stark anzusteigen.Allerdings überschreitet sie niemals 1,7 GB und liegt damit deutlich unter dem AWS-Limit von 5 GiB pro Teil.
Beispiel 2: Prores 422 LT Prores 422 LT hat eine Datenrate von 102 MBit/s und generiert eine Tabelle wie folgt:
Diese Tabelle zeigt nützliche Eigenschaften im Vergleich zu unserer Web-optimierten Formel auf.Innerhalb der ersten 1.000 Teile können wir 8 GB mehr der Datei hochladen.Größere anfängliche Payloads bedeuten, dass wir zu Beginn nicht zu schnell URLs abfragen müssen, wodurch der Upload bei der höheren Datenrate effizienter wird.Die Größe unserer Payload bleibt gegen Ende des Upload-Vorgangs weiterhin groß.
Beispiel 2: Camera Raw
Probieren wir zum Schluss ein Camera-Raw-Format mit einer Datenübertragungsrate von 280 MB/s aus.Angesichts dieser rasanten Datenübertragung ergibt es einfach keinen Sinn, zu Beginn zu versuchen, die Daten in 5-MiB-Chunks hochzuladen:
Frühe Payloads sind nicht nur effizienter, sondern wir sparen zudem am oberen Ende über ein halbes Gigabyte ein, wodurch diese Netzwerkaufrufe weniger anfällig für Störungen im Netzwerk sind.
Unsere Arbeit präsentieren
Bevor wir alles in einem Beispiel-Uploader zusammenführen, wollen wir uns zunächst ansehen, wie wir zu unserer Formel gelangt sind.
Wir mussten eine Formel entwickeln, bei der große, ressourcenintensive Payloads am Ende der uns zur Verfügung stehenden Teileanzahl – die die meisten Uploads niemals erreichen werden – gegen leichte, effiziente Payloads am Anfang eingetauscht werden, von denen jeder Upload profitieren kann.Gleichzeitig wollten wir sicherstellen, dass unser Algorithmus genau bei der Teilenummer 10.000 in den Bereich des Dateigrößenlimits von 5 TiB fällt.
Es war an der Zeit, sich mit der Analysis zu befassen.
Wir möchten, dass unser Graph exponentiell wächst, daher sollte unsere Formel in etwa so aussehen:
… wobei n die Teilnummer ist.Wir möchten außerdem sicherstellen, dass jeder Teil mindestens die Datenrate unserer Formel erreicht, die wir mit r bezeichnen:
Nun müssen wir eine Formel finden, die uns die Summe dieser Formel für die ersten 10.000 natürlichen Zahlen (1, 2, 3 …) angibt.Das Sigma-Zeichen Σ steht für die Summe.Fügen wir es unserer Formel hinzu:
… und definieren n als die Folge der natürlichen Zahlen zwischen 1 und 10.000 (einschließlich).Diese Gleichung ist für uns noch nicht besonders nützlich.Die Formel ist zwar intuitiv richtig, doch wenn wir n=10,000 und r=5,242,880 wie gewünscht eingeben, gibt sie einfach ein Ergebnis aus: 385,812,135,000 (385 GB).Das Ergebnis liegt nicht nur weit unter unserer Dateigrößenbeschränkung von 5 TiB, es gibt auch keine Möglichkeit, die Formel so anzupassen, dass sie dieses Ergebnis liefert.
Versuchen wir doch einmal, am Rad zu drehen:
… wobei x ein Skalar ist, den wir berechnen können, um als Ergebnis 5 TiB zu erhalten.Nun können wir die Gleichung unserem Dateigrößenlimit gleichsetzen und nach x lösen:
Häufig müssen Summen iterativ berechnet werden, beispielsweise in einer for- oder while-Schleife.Es stellt sich jedoch heraus, dass es für uns eine perfekte Formel gibt: eine bekannte Methode, um die Summe der Quadrate der ersten n natürlichen Zahlen günstig zu berechnen:
Wenn man sie in ein Polynom umformuliert, lässt sie sich leichter überblicken:
Wir können unsere Variablen x und r auf beiden Seiten hinzufügen:
Und schließlich setzen wir unsere neue Formel gleich 5 TiB:
Nun müssen wir nur noch x berechnen, indem wir n=10.000 setzen, also unsere Gesamtteilzahl.Auf diese Weise können wir einen statischen Skalar für eine bestimmte Datenrate berechnen.Anstatt dies von Hand zu erledigen, geben wir es in Wolfram Alpha ein:
Jetzt kommen wir der Sache schon näher!Wenn unsere Datenrate der minimalen Teilgröße (5 MiB) entspräche, würden wir einen statischen Skalar erhalten von:
In der Welt der Informatik entspricht dies einem Float64-Wert von 16.33293799427617.Unsere Formel zur Bestimmung der Teilegröße würde in diesem Fall wie folgt lauten:
Wobei s unsere Teilgröße ist.
Wir haben noch ein weiteres Problem.In der Praxis ist eine Payload mit nicht ganzzahligen Bytes nicht zulässig.Wir müssen jeden Wert runden.Wir verwenden Python und runden ab:
Wir sind nun bei einem konkreten Beispiel für die in dieser Anleitung vorgestellte ursprüngliche Funktion angelangt.
Einen einfachen Uploader aufbauen
Werfen wir einen Blick auf einen einfachen, Python-ähnlichen Pseudocode zum Hochladen einer Datei, die in Echtzeit gerendert wird, und nutzen dabei alles, was wir in dieser Anleitung gelernt haben:
Erweiterte Uploads
Der obige Code veranschaulicht lediglich den grundlegenden Ablauf des Hochladens einer Datei in Echtzeit.In der Praxis muss diese Logik jedoch um Fehlerbehandlung und erweiterte Upload-Techniken erweitert werden.
Als Nächstes
Echtzeit-Uploads bieten die Möglichkeit, Ihre Integration so responsiv wie möglich zu gestalten, da die Dateien bereits wenige Sekunden nach Abschluss der Aufnahme in Frame.io abgespielt werden können.In einer späteren Anleitung werden erweiterte Upload-Techniken und -Anforderungen behandelt.Auch wenn diese Anleitung ursprünglich für einfache Uploads verfasst wurde, gilt der Großteil der darin enthaltenen Informationen dennoch für Echtzeit-Uploads.
Falls Sie dies noch nicht getan haben, empfehlen wir Ihnen, sich an unser Team zu wenden und anschließend mit der nächsten Anleitung fortzufahren.Wir freuen uns darauf, von Ihnen zu hören!