Link multimediali

Frame.io conserva ed elabora i file caricati sui progetti, tra cui immagini, video, PDF e altro ancora. Quando recuperi un file tramite l’API, la risposta di base include metadati essenziali come nome del file, stato e view_url per aprirlo nell’app Frame.io. Per accedere al contenuto effettivo del file (originale, anteprima o rappresentazioni di qualità diversa), devi usare includes. Questa guida spiega quali sono le inclusioni disponibili dei link multimediali negli endpoint List Files e Get File, cosa restituisce ciascuno e quando utilizzarli.

Cosa sono le inclusioni?

Le inclusioni (includes) sono campi facoltativi che puoi richiedere insieme a una risposta del file. Per impostazione predefinita, l’API restituisce solo i metadati essenziali del file: nome, stato, tipo, marca temporale e view_url. Le inclusioni ti permettono di scegliere dati aggiuntivi, semplificando le risposte se non hai bisogno di tutte le informazioni.

Come aggiungere le inclusioni

Passa un elenco separato da virgole di nomi di inclusioni come parametro di richiesta include in qualsiasi richiesta 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

Le inclusioni funzionano allo stesso modo sia sull’endpoint per singolo file che su quello di elenco. Se utilizzate su List Files, le inclusioni vengono risolte per ogni file nella risposta.

Esempi 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)

Le inclusioni non richieste vengono omesse completamente dalla risposta.

Panoramica delle inclusioni dei link multimediali

media_links.original

Restituisce URL firmati che puntano al file originale esattamente come è stato caricato, senza elaborazione e senza conversione.

Campi

Quando utilizzarlo

Utilizza media_links.original quando hai bisogno del file di origine, ad esempio per permettere a un utente di scaricare il file MOV, MP4, MXF, AVI, PSD, PNG o TIFF originale oppure per passare i byte originali a un altro sistema.

Richiesta di esempio

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

Risposta di esempio

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

Restituisce un’immagine di anteprima PNG della risorsa, limitata a 540px di altezza. Questa è una rappresentazione elaborata (non il file originale) e le filigrane possono essere applicate a seconda delle impostazioni dell’account.

Campi

Quando utilizzarlo

Usa media_links.thumbnail quando devi mostrare un’anteprima visiva della risorsa, ad esempio in una vista a griglia, una galleria o un selettore di file. Si carica più velocemente dell’originale ed è sempre in formato PNG compatibile con il web.

Richiesta di esempio

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

Risposta di esempio

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

Restituisce un URL di download per la migliore rappresentazione elaborata disponibile della risorsa. Frame.io elabora i caricamenti attraverso una scala di risoluzione che arriva fino a 2160p. L’API restituisce la rappresentazione più alta disponibile al momento della richiesta. Se, perciò, l’elaborazione è terminata solo per una rappresentazione a 540p quando fai la richiesta, l’API restituisce 540p fino a quando non sono pronte delle rappresentazioni superiori.

Campi

Quando utilizzarlo

Usa media_links.high_quality quando desideri la versione di qualità migliore senza aver bisogno dell’originale, ad esempio esportando una rappresentazione ad alta risoluzione per l’elaborazione a valle o presentando un’anteprima con risoluzione completa. Se hai bisogno della qualità più alta possibile, controlla il campo status del file e richiedi questa inclusione una volta che il file è pronto (ready), in modo da assicurarti che la scala di risoluzione completa sia stata elaborata.

Richiesta di esempio

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

Risposta di esempio

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

Restituisce un URL di download per la rappresentazione elaborata più piccola disponibile. È l’opposto di high_quality: Frame.io seleziona la rappresentazione con la risoluzione più bassa disponibile.

Campi

Quando utilizzarlo

Usa media_links.efficient quando la larghezza di banda o la dimensione del file conta più della qualità, ad esempio per generare anteprime rapide in un ambiente con larghezza di banda limitata o per alimentare una pipeline di miniature che non ha bisogno della risoluzione completa.

Richiesta di esempio

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

Risposta di esempio

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

Restituisce gli URL di streaming e download per una transcodifica video a bassa risoluzione H264 a 180p della risorsa.

Campi

Quando utilizzarlo

Usa media_links.video_h264_180 quando hai bisogno specificamente di una transcodifica H264 garantita a 180p, ad esempio per l’integrazione con un lettore o una pipeline legacy che richiede esattamente questo formato. Se la transcodifica non esiste per una determinata risorsa, entrambi gli URL saranno null.

Richiesta di esempio

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

Risposta di esempio

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

Restituisce un foglio sprite WebP, ovvero una singola immagine contenente una griglia di miniature dei fotogrammi video campionati uniformemente per tutta la durata del video. Viene utilizzato per creare l’interfaccia utente di scorrimento video, dove il lettore mostra un fotogramma di anteprima mentre l’utente trascina sulla timeline.

Campi

Quando utilizzarlo

Usa media_links.scrub_sheet quando crei un lettore video personalizzato o un’interfaccia timeline che deve mostrare una miniatura di anteprima mentre l’utente scorre. Invece di fare una richiesta separata per ogni fotogramma, il foglio sprite raggruppa tutti i fotogrammi di anteprima in un unico download di immagine.

Richiesta di esempio

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

Risposta di esempio

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
}

Estrazione di un fotogramma dal foglio sprite

Il foglio sprite è una griglia di colonne tile_x × righe tile_y. Per visualizzare la miniatura per un determinato indice di fotogramma (con base zero), calcola la sua posizione all’interno dell’immagine:

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
}

Puoi quindi utilizzare background-position di CSS per mostrare la sezione corretta dal foglio sprite:

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
}

Per mappare una posizione di riproduzione (in secondi) a un indice di fotogrammi, usa la durata totale del video e il numero di fotogrammi nel foglio:

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
}

Combinare più inclusioni

Puoi richiedere più inclusioni in una singola chiamata 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
}

Scelta dell’inclusione giusta

Disponibilità delle inclusioni

I link multimediali vengono popolati solo dopo che Frame.io ha terminato l’elaborazione del file caricato. Se richiedi un’inclusione subito dopo il caricamento, gli URL potrebbero essere null mentre la transcodifica è in corso. Controlla il campo status nell’oggetto del file: le inclusioni saranno disponibili quando lo stato sarà ready.