メディアリンク

Frame.ioは、プロジェクトにアップロードされたファイル（画像、動画、PDF など）を保存および処理します。APIを使用してファイルを取得する場合、基本応答にはファイル名、ステータス、Frame.ioアプリで開くためのview_urlなどのコアメタデータが含まれます。実際のファイルコンテンツ（オリジナル、プレビュー、または異なる品質のレンディション）にアクセスするには、includesを使用します。このガイドでは、List FilesおよびGet Fileエンドポイントで利用可能なメディアリンクインクルード、それぞれが返すもの、いつ使用するかについて説明します。

インクルードとは何ですか？

インクルードは、ファイル応答と一緒にリクエストできるオプションフィールドです。デフォルトでは、APIはコアファイルメタデータ（名前、ステータス、タイプ、タイムスタンプ、view_url）のみを返します。インクルードを使用すると、すべてが必要でない場合に応答を軽量に保ちながら、追加データをオプトインできます。

インクルードの追加方法

Get FileまたはList Filesリクエストで、インクルード名のカンマ区切りリストをincludeクエリパラメータとして渡します：

$
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

インクルードは、単一ファイルエンドポイントとリストエンドポイントの両方で同じように動作します。List Filesで使用する場合、インクルードは応答内のすべてのファイルに対して解決されます。

SDK例

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)

リクエストされていないインクルードは、応答から完全に省略されます。

メディアリンクインクルード概要

media_links.original

アップロードされた元のファイルそのままを指す署名付きURLを返します。処理やコンバージョンは行われません。

フィールド

使用する場合

ソースファイルが必要な場合にmedia_links.originalを使用します。例えば、ユーザーが元のMOV、MP4、MXF、AVI、PSD、PNG、またはTIFFをダウンロードできるようにする場合や、元のバイトを別のシステムに渡す場合などです。

リクエスト例

$
GET /v4/accounts/{account_id}/files/{file_id}?include=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
      "original": {
8
        "download_url": "https://s3.amazonaws.com/...",
9
        "inline_url": "https://s3.amazonaws.com/..."
10
      }
11
    }
12
  }
13
}

media_links.thumbnail

アセットのPNGプレビュー画像を返します。高さは540pxに制限されます。これは処理済みレンディションで、元のファイルではありません。アカウント設定によっては透かしが適用される場合があります。

フィールド

使用する場面

media_links.thumbnailは、グリッドビュー、ギャラリー、ファイルピッカーなどでアセットの視覚的なプレビューを表示する必要がある場合に使用します。オリジナルよりも高速に読み込まれ、常にweb対応のPNG形式です。

リクエスト例

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

レスポンス例

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

利用可能な最高品質の処理済みレンディションのダウンロードURLを返します。Frame.ioは最大2160pの解像度ラダーを通じてアップロードを処理します。APIはリクエスト時点で利用可能な最高のレンディションを返します。つまり、リクエスト時に540pレンディションのみが処理完了している場合、より高いレンディションが準備できるまでAPIは540pを返します。

フィールド

使用する場面

media_links.high_qualityは、ダウンストリーム処理用の高解像度レンディションの書き出しや、フル解像度プレビューの表示など、オリジナルを必要とせずに最高品質のバージョンが必要な場合に使用します。可能な限り最高の品質が必要な場合は、ファイルのstatusフィールドを確認し、ファイルがreadyになったらこのincludeをリクエストして、完全な解像度ラダーが処理されていることを確認してください。

リクエスト例

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

レスポンス例

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

利用可能な最小の処理済みレンディションのダウンロードURLを返します。これはhigh_qualityの反対です。Frame.ioは利用可能な最低解像度のレンディションを選択します。

フィールド

使用する場合

品質よりも帯域幅やファイルサイズが重要な場合にmedia_links.efficientを使用します。例えば、低帯域幅環境での素早いプレビュー生成や、フル解像度を必要としないサムネイルパイプラインへの供給などです。

リクエスト例

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

レスポンス例

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

アセットの低解像度180p H264動画トランスコードのストリーミングおよびダウンロードURLを返します。

フィールド

使用する場合

具体的に保証された180p H264トランスコードが必要な場合にmedia_links.video_h264_180を使用します。例えば、この正確なフォーマットを必要とするレガシープレーヤーやパイプラインとの統合などです。特定のアセットにトランスコードが存在しない場合、両方のURLがnullになります。

リクエストの例

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

応答の例

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

WebPスプライトシートを返します。これは、ビデオの長さ全体にわたって均等にサンプリングされたビデオフレームのサムネイルのグリッドを含む単一の画像です。これは、ユーザーがタイムライン上でドラッグするとプレーヤーがプレビューフレームを表示するビデオスクラビングUIの作成に使用されます。

フィールド

使用する場合

ユーザーがスクラブするときにプレビューサムネイルを表示する必要があるカスタムビデオプレーヤーやタイムライン UI を作成する場合は、media_links.scrub_sheet を使用します。各フレームに対して個別のリクエストを行うのではなく、スプライトシートはすべてのプレビューフレームを単一の画像ダウンロードにまとめます。

リクエストの例

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

レスポンスの例

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
}

スプライトシートからフレームを抽出する

スプライトシートは tile_x 列 × tile_y 行のグリッドです。指定されたフレームインデックス（ゼロベース）のサムネイルを表示するには、画像内での位置を計算します：

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
}

CSS background-position を使用して、スプライトシートから正しいタイルを表示できます：

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
}

再生位置（秒単位）をフレームインデックスにマッピングするには、ビデオの総再生時間とシート内のフレーム数を使用します：

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
}

複数のインクルードの組み合わせ

単一の API 呼び出しで複数のインクルードをリクエストできます：

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

適切なERPの選定

インクルード可用性

メディアリンクインクルードは、Frame.ioがアップロードされたファイルの処理を完了した後にのみ入力されます。アップロード直後にインクルードをリクエストした場合、トランスコーディングが進行中の間、URLはnullになる可能性があります。ファイルオブジェクトのstatusフィールドを確認してください — ステータスがreadyになると、インクルードが利用可能になります。