Ссылки на медиафайлы

Frame.io хранит и обрабатывает файлы, добавленные в ваши проекты — изображения, видео, документы PDF и многое другое. Когда вы запрашиваете файл через API-интерфейс, базовый ответ содержит основные метаданные, такие как имя файла, его статус и ссылку view_url для открытия в приложении Frame.io. Для получения доступа к фактическому содержимому файла (оригинала, копии для предпросмотра или версий различного качества) используются включения (includes). В этом руководстве подробно описываются включения для ссылок на медиафайлы, доступные в конечных точках Список файлов и Получить файл, а также какие данные возвращает каждое из них и в каких случаях их следует применять.

Что такое включения?

Включения — это дополнительные поля, которые можно запросить вместе с ответом по файлу. По умолчанию API-интерфейс возвращает только основные метаданные файла: имя, статус, тип, временные метки и view_url. Включения позволяют получать дополнительные данные, сохраняя ответы краткими, когда вам не нужна вся информация целиком.

Как добавлять включения

Передайте список имен включений через запятую в параметре 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

Включения работают одинаково как для конечной точки получения отдельного файла, так и для конечной точки вывода списка. При использовании в конечной точке «Список файлов» включения применяются к каждому файлу в ответе.

Примеры 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 с максимальной высотой 540 пикселей. Это обработанная версия, а не исходный файл. В зависимости от настроек вашей учетной записи на нее могут быть наложены водяные знаки.

Поля

Когда использовать

Используйте включение media_links.thumbnail, когда нужна визуализация для предпросмотра ресурса, например в виде сетки, галереи или средства выбора файлов. Миниатюры загружаются быстрее, чем исходный файл, и всегда представлены в безопасном для веб-интерфейсов формате 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-интерфейс будет возвращать ссылку на нее до тех пор, пока не будут готовы версии в более высоком качестве.

Поля

Когда использовать

Используйте включение media_links.high_quality, когда нужна версия лучшего качества без необходимости загружать исходный файл, например для экспорта версии в высоком разрешении для последующей обработки или для предпросмотра в полном разрешении. Если требуется максимально возможное качество, проверьте поле состояния файла (status) и запросите данное включение только после перехода файла в состояние «готов» (ready). Это гарантирует, что файл прошел обработку по всей шкале разрешений.

Пример запроса

$
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

Возвращает URL-адреса для потоковой передачи и загрузки перекодированного видео в низком разрешении 180p H264.

Поля

Когда использовать

Используйте включение media_links.video_h264_180, когда вам нужно перекодированное видео в формате H264 180p, например для интеграции с устаревшим проигрывателем или цепочкой обработки, которым требуется именно этот формат. Если для данного ресурса такого перекодированного видео нет, оба 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 — одно изображение, содержащее сетку из миниатюр кадров видео, взятых через равные промежутки времени на протяжении всей длительности видеоролика. Это включение используется для реализации интерфейса перемотки, когда проигрыватель показывает кадр для предпросмотра по мере того, как пользователь перемещает ползунок по шкале времени.

Поля

Когда использовать

Используйте включение 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
}

Выбор подходящего включения

Доступность включений

Включения в ссылках на медиафайлы заполняются только после того, как Frame.io завершит обработку добавленного файла. Если вы запросите включение сразу после добавления, URL-адреса могут иметь значение null, пока выполняется перекодирование. Проверяйте поле состояния (status) объекта файла — включения станут доступны, как только состояние изменится на «готов» (ready).