Vínculos multimedia

Frame.io almacena y procesa archivos cargados en los Projects: imágenes, vídeos, PDF, etc. Cuando recupera un archivo mediante la API, la respuesta base incluye metadatos principales como el nombre del archivo, el estado y un view_url para abrirlo en la aplicación Frame.io. Para acceder al contenido real del archivo, como el original, una previsualización o representaciones con distintos niveles de calidad, se usan includes. Esta guía explica los includes de vínculos multimedia disponibles en los extremos List Files y Get File, qué devuelve cada uno y cuándo debe usarse.

¿Qué son los includes?

Los includes son campos opcionales que se pueden solicitar junto con una respuesta de archivo. De forma predeterminada, la API solo devuelve los metadatos principales del archivo: nombre, estado, tipo, marcas de tiempo y view_url. Los includes permiten solicitar datos adicionales solo cuando se necesitan, lo que mantiene las respuestas ligeras cuando no hace falta todo.

Cómo añadir includes

Pase una lista separada por comas de nombres de include como parámetro de consulta include en cualquier solicitud Get File o List Files:

$
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

Los includes funcionan del mismo modo en los puntos finales de archivo único y de lista. Cuando se usan en List Files, los includes se resuelven para todos los archivos de la respuesta.

Ejemplos de 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)

Los includes que no se soliciten se omiten por completo de la respuesta.

Información general de includes de vínculos multimedia

media_links.original

Devuelve URL firmadas que apuntan al archivo original exactamente tal como se cargó, sin procesamiento ni conversión.

Campos

Cuándo usarlo

Use media_links.original cuando necesite el archivo de origen, por ejemplo, para permitir que un usuario descargue el archivo MOV, MP4, MXF, AVI, PSD, PNG o TIFF original, o para pasar los bytes originales a otro sistema.

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Devuelve una imagen de vista previa PNG del activo, limitada a 540 px de alto. Es una representación procesada, no el archivo original, y es posible que se apliquen marcas de agua en función de la configuración de la cuenta.

Campos

Cuándo usarlo

Use media_links.thumbnail cuando necesite mostrar una vista previa del activo, por ejemplo, en una vista de cuadrícula, una galería o un selector de archivos. Se carga más rápido que el original y siempre tiene formato PNG seguro para web.

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Devuelve una URL de descarga para la mejor representación procesada disponible del activo. Frame.io procesa las cargas mediante una escala de resoluciones que alcanza un máximo de 2160p. La API devuelve la representación de mayor calidad disponible en el momento de la solicitud. Por tanto, si solo ha terminado de procesarse una representación a 540p al realizar la solicitud, la API devuelve 540p hasta que las representaciones superiores estén listas.

Campos

Cuándo usarlo

Use media_links.high_quality cuando quiera la versión de mejor calidad sin necesitar el original, por ejemplo, para exportar una representación de alta resolución para procesamiento posterior o para presentar una previsualización a resolución completa. Si necesita la máxima calidad posible, compruebe el campo status del archivo y solicite este include cuando el archivo esté listo para asegurarse de que se haya procesado toda la escala de resoluciones.

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Devuelve una URL de descarga para la representación procesada más pequeña disponible. Es lo contrario de high_quality: Frame.io selecciona la representación de menor resolución disponible.

Campos

Cuándo usarlo

Use media_links.efficient cuando el ancho de banda o el tamaño del archivo sean más importantes que la calidad, por ejemplo, para generar previsualizaciones rápidas en un entorno con poco ancho de banda o alimentar una canalización de miniaturas que no necesita resolución completa.

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Devuelve URL de streaming y descarga para una transcodificación de vídeo H.264 de baja resolución a 180p del activo.

Campos

Cuándo usarlo

Use media_links.video_h264_180 cuando necesite específicamente una transcodificación H.264 a 180p garantizada, por ejemplo, para integrarse con un reproductor o una canalización heredados que requieran este formato exacto. Si la transcodificación no existe para un activo determinado, ambas URL serán null.

Ejemplo de solicitud

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

Ejemplo de respuesta

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

Devuelve una hoja de sprites WebP, es decir, una sola imagen que contiene una cuadrícula de miniaturas de fotogramas de vídeo muestreados de forma uniforme a lo largo de la duración del vídeo. Se usa para crear IU de barrido de vídeo, donde el reproductor muestra un fotograma de previsualización cuando el usuario arrastra el control por la línea de tiempo.

Campos

Cuándo usarlo

Use media_links.scrub_sheet al crear un reproductor de vídeo personalizado o una IU de línea de tiempo que necesite mostrar una miniatura de previsualización cuando el usuario realice un barrido. En lugar de realizar una solicitud independiente por cada fotograma, la hoja de sprites agrupa todos los fotogramas de previsualización en una sola descarga de imagen.

Ejemplo de solicitud

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

Ejemplo de respuesta

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
}

Extracción de un fotograma de la hoja de sprites

La hoja de sprites es una cuadrícula de columnas tile_x × filas tile_y. Para mostrar la miniatura de un índice de fotograma determinado, basado en cero, calcule su posición dentro de la imagen:

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
}

A continuación, puede usar background-position de CSS para mostrar el mosaico correcto de la hoja de sprites:

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
}

Para asignar una posición de reproducción (en segundos) a un índice de fotograma, use la duración total del vídeo y el número de fotogramas de la hoja:

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
}

Combinación de varios includes

Puede solicitar varios includes en una sola llamada de 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
}

Elección del include adecuado

Disponibilidad de includes

Los includes de vínculos multimedia solo se rellenan cuando Frame.io ha terminado de procesar el archivo cargado. Si solicita un include inmediatamente después de la carga, las URL pueden ser null mientras la transcodificación está en curso. Compruebe el campo status del objeto de archivo; los includes estarán disponibles cuando status sea ready.