Medien-Links

In Frame.io werden Dateien gespeichert und verarbeitet, die in Ihre Projekte hochgeladen werden – Bilder, Videos, PDFs und mehr.Wenn Sie eine Datei über die API abrufen, enthält die Grundantwort zentrale Metadaten wie den Dateinamen, Status und eine view_url, um sie in der Frame.io-App zu öffnen.Mit Einbindungen greifen Sie auf den tatsächlichen Dateiinhalt zu: das Original, eine Vorschau oder Ausgabedarstellungen in verschiedenen Qualitäten.In diesem Leitfaden werden die Medien-Link-Einbindungen erklärt, die an den Endpunkten Dateien auflisten und Datei abrufen verfügbar sind, was von diesen zurückgegeben wird und wann Sie sie verwenden.

Was sind Einbindungen?

Einbindungen sind optionale Felder, die Sie zusammen mit einer Dateiantwort anfordern können.Standardmäßig werden von der API nur zentrale Datei-Metadaten zurückgegeben: Name, Status, Typ, Zeitstempel und view_url.Mit Einbindungen können Sie zusätzliche Daten anfordern und dabei Antworten schlank halten, wenn Sie nicht alles benötigen.

So fügen Sie Einbindungen hinzu

Übergeben Sie bei jeder Datei abrufen- oder Dateien auflisten-Anfrage eine durch Kommas getrennte Liste der Namen von Einbindungen als include-Abfrageparameter:

$
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail

$
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail,media_links.original

$
GET /v4/accounts/{account_id}/folders/{folder_id}/files?include=media_links.thumbnail

Einbindungen funktionieren bei beiden Endpunkten, also einzelnen Dateien sowie Listen, gleichermaßen.Bei der Verwendung mit „Dateien auflisten“ werden die Einbindungen für die einzelnen Dateien in der Antwort aufgelöst.

SDK-Beispiele

1
import frameio
2
3
client = frameio.Frameio(auth="<YOUR_TOKEN>")
4
5
file = client.files.get(
6
    file_id="93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
7
    include=["media_links.thumbnail", "media_links.original"]
8
)
9
10
print(file.media_links.thumbnail.url)

Einbindungen, die nicht angefordert werden, werden vollständig aus der Antwort weggelassen.

Übersicht über Einbindungen für Medien-Links

media_links.original

Gibt signierte URLs zurück, die auf die ursprüngliche Datei verweisen, wie sie hochgeladen wurde, ohne Verarbeitung oder Konversion.

Felder

Wann verwenden

Bei der Verwendung von media_links.original erhalten Sie die Quelldatei, etwa um Benutzenden das Herunterladen der ursprünglichen MOV-, MP4-, MXF-, AVI-, PSD-, PNG- oder TIFF-Datei zu ermöglichen oder um die ursprünglichen Bytes an ein anderes System zu übergeben.

Beispielanfrage

$
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.original

Beispielantwort

1
{
2
  "data": {
3
    "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4
    "name": "hero-banner.png",
5
    "type": "file",
6
    "media_links": {
7
      "original": {
8
        "download_url": "https://s3.amazonaws.com/...",
9
        "inline_url": "https://s3.amazonaws.com/..."
10
      }
11
    }
12
  }
13
}

media_links.thumbnail

Gibt ein PNG-Vorschaubild des Assets zurück, begrenzt auf 540 px Höhe.Dies ist eine verarbeitete Ausgabedarstellung, nicht die Originaldatei. Wasserzeichen können in Abhängigkeit von den Kontoeinstellungen angewendet werden.

Felder

Wann verwenden

Mit media_links.thumbnail können Sie eine visuelle Vorschau des Assets anzeigen, zum Beispiel in einer Rasteransicht, einer Galerie oder einer Dateiauswahl.Sie wird schneller geladen als das Original und liegt immer in einem websicheren PNG-Format vor.

Beispielanfrage

$
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail

Beispielantwort

1
{
2
  "data": {
3
    "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4
    "name": "hero-banner.png",
5
    "type": "file",
6
    "media_links": {
7
      "thumbnail": {
8
        "download_url": "https://s3.amazonaws.com/...",
9
        "url": "https://s3.amazonaws.com/..."
10
      }
11
    }
12
  }
13
}

media_links.high_quality

Gibt eine Download-URL für die beste verfügbare verarbeitete Ausgabedarstellung des Assets zurück.In Frame.io werden Uploads über eine Auflösungsleiter verarbeitet, die bei 2160p ihr Maximum erreicht.Von der API wird die höchste verfügbare Ausgabedarstellung zum Zeitpunkt der Anfrage zurückgegeben. Wenn zum Zeitpunkt der Anfrage also nur eine 540p-Ausgabedarstellung fertig verarbeitet wurde, wird von der API 540p zurückgegeben, bis höhere Ausgabedarstellungen bereit sind.

Felder

Wann verwenden

Mit media_links.high_quality erhalten Sie die Version in der bestmöglichen Qualität ohne das Original, zum Beispiel beim Export einer hochauflösenden Ausgabedarstellung für die nachgelagerte Verarbeitung oder bei der Präsentation einer Vorschau in voller Auflösung.Wenn Sie die höchstmögliche Qualität benötigen, überprüfen Sie das Feld status der Datei und fordern Sie diese Einbindung an, sobald die Datei ready ist, um zu gewährleisten, dass die vollständige Auflösungsleiter verarbeitet wurde.

Beispielanfrage

$
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.high_quality

Beispielantwort

1
{
2
  "data": {
3
    "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4
    "name": "hero-banner.png",
5
    "type": "file",
6
    "media_links": {
7
      "high_quality": {
8
        "download_url": "https://s3.amazonaws.com/..."
9
      }
10
    }
11
  }
12
}

media_links.efficient

Gibt eine Download-URL für die kleinste verfügbare verarbeitete Ausgabedarstellung zurück.Das ist das Gegenteil von high_quality; in Frame.io wird die Ausgabedarstellung in der niedrigsten verfügbaren Auflösung ausgewählt.

Felder

Wann verwenden

Verwenden Sie media_links.efficient, wenn Bandbreite oder Dateigröße wichtiger sind als Qualität, zum Beispiel beim Generieren schneller Vorschauen in einer Umgebung mit geringer Bandbreite oder beim Einspeisen in eine Miniaturansichts-Pipeline, bei der keine volle Auflösung erforderlich ist.

Beispielanfrage

$
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.efficient

Beispielantwort

1
{
2
  "data": {
3
    "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4
    "name": "hero-banner.png",
5
    "type": "file",
6
    "media_links": {
7
      "efficient": {
8
        "download_url": "https://s3.amazonaws.com/..."
9
      }
10
    }
11
  }
12
}

media_links.video_h264_180

Gibt Streaming- und Download-URLs für eine niedrigauflösende 180p-H264-Videotranskodierung des Assets zurück.

Felder

Wann verwenden

Mit media_links.video_h264_180 erhalten Sie eine garantierte 180p-H264-Transkodierung, zum Beispiel bei der Integration mit einem älteren Player oder einer älteren Pipeline, der bzw. die genau dieses Format erfordert.Wenn die Transkodierung für ein gegebenes Asset nicht existiert, sind beide URLs null.

Beispielanfrage

$
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.video_h264_180

Beispielantwort

1
{
2
  "data": {
3
    "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4
    "name": "interview-clip.mp4",
5
    "type": "file",
6
    "media_links": {
7
      "video_h264_180": {
8
        "download_url": "https://s3.amazonaws.com/...",
9
        "url": "https://s3.amazonaws.com/..."
10
      }
11
    }
12
  }
13
}

media_links.scrub_sheet

Gibt ein WebP Sprite Sheet zurück, ein einzelnes Bild, das ein Raster von Miniaturansichten von Videobildern enthält, die gleichmäßig über die Dauer des Videos gesampelt wurden.Damit wird eine Bedienoberfläche zum Hin- und Herspringen in dem Video erstellt. In dem Player wird ein Vorschaubild angezeigt, während Benutzende über die Timeline ziehen.

Felder

Wann verwenden

Verwenden Sie media_links.scrub_sheet beim Erstellen eines selbstdefinierten Video-Players oder einer Timeline-Bedienoberfläche, in der eine Vorschau-Miniaturansicht angezeigt werden muss, während Benutzende hin- und herspringen.Anstatt für jedes Bild eine separate Anfrage zu stellen, werden im Sprite Sheet alle Vorschaubilder in einem einzigen Bild-Download gebündelt.

Beispielanfrage

$
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.scrub_sheet

Beispielantwort

1
{
2
  "data": {
3
    "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4
    "name": "interview-clip.mp4",
5
    "type": "file",
6
    "media_links": {
7
      "scrub_sheet": {
8
        "download_url": "https://assets.frame.io/...",
9
        "url": "https://assets.frame.io/...",
10
        "metadata": {
11
          "tile_x": 10,
12
          "tile_y": 10,
13
          "thumb_width": 160,
14
          "thumb_height": 90,
15
          "padding": 1,
16
          "frames": 100
17
        }
18
      }
19
    }
20
  }
21
}

Extrahieren eines Bildes aus dem Sprite Sheet

Das Sprite Sheet ist ein Raster aus tile_x-Spalten × tile_y-Zeilen.Wenn Sie die Miniaturansicht für einen gegebenen Bildindex (nullbasiert) anzeigen möchten, berechnen Sie dessen Position innerhalb des Bildes:

1
function getFrameOffset(frameIndex, metadata) {
2
  const { tile_x, thumb_width, thumb_height, padding } = metadata;
3
4
  const col = frameIndex % tile_x;
5
  const row = Math.floor(frameIndex / tile_x);
6
7
  return {
8
    x: col * (thumb_width + padding),
9
    y: row * (thumb_height + padding),
10
    width: thumb_width,
11
    height: thumb_height,
12
  };
13
}

Mit dem CSS background-position können Sie dann die richtige Kachel aus dem Sprite Sheet zeigen:

1
function applyFrameToElement(el, frameIndex, scrubSheet) {
2
  const { x, y, width, height } = getFrameOffset(frameIndex, scrubSheet.metadata);
3
4
  el.style.backgroundImage = `url(${scrubSheet.url})`;
5
  el.style.backgroundPosition = `-${x}px -${y}px`;
6
  el.style.width = `${width}px`;
7
  el.style.height = `${height}px`;
8
}

Wenn Sie einem Bildindex eine Wiedergabeposition (in Sekunden) zuordnen möchten, verwenden Sie die Gesamtdauer des Videos und die Anzahl der Bilder im Sheet:

1
function positionToFrameIndex(currentSeconds, durationSeconds, metadata) {
2
  const progress = currentSeconds / durationSeconds;
3
  return Math.min(
4
    Math.floor(progress * metadata.frames),
5
    metadata.frames - 1
6
  );
7
}

Kombinieren mehrerer Einbindungen

Sie können mehrere Einbindungen in einem einzigen API-Aufruf anfordern:

$
GET /v4/accounts/{account_id}/files/{file_id}?include=media_links.thumbnail,media_links.original

1
{
2
  "data": {
3
    "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4
    "name": "hero-banner.png",
5
    "type": "file",
6
    "media_links": {
7
      "thumbnail": {
8
        "download_url": "https://s3.amazonaws.com/...",
9
        "url": "https://s3.amazonaws.com/..."
10
      },
11
      "original": {
12
        "download_url": "https://s3.amazonaws.com/...",
13
        "inline_url": "https://s3.amazonaws.com/..."
14
      }
15
    }
16
  }
17
}

Auswählen der richtigen Einbindung

Verfügbarkeit von Einbindungen

Medien-Link-Einbindungen werden erst ausgefüllt, wenn die Verarbeitung der hochgeladenen Datei in Frame.io abgeschlossen ist.Wenn Sie unmittelbar nach dem Hochladen eine Einbindung anfordern, sind die URLs möglicherweise null, während die Transkodierung ausgeführt wird.Überprüfen Sie das Feld status des Dateiobjekts. Einbindungen sind verfügbar, sobald der Status ready lautet.