L’oggetto video

L’oggetto video è un oggetto JSON con le seguenti proprietà:


{
  "id": string,
  "status": "COMPLETE" | "PROGRESSING" | "REPLACING" | "NO_FILE" | "ERROR",
  "statusProgress": number,
  "errorCode": string | null,
  "errorMessage": string | null,
  "visibility": "public" | "private",
  "v": number,
  "title": string,
  "description": string,
  "duration": number,
  "fps": number,
  "orientation": "landscape" | "portrait",
  "sourceFolder": string,
  "language": string,
  "src": {
    "thumbnails": [
      {
        "name": "2160p" | "1440p" | "1080p" | "720p" | "480p" | "360p" | "240p",
        "width": number,
        "height": number,
        "formats": {
          "jpeg": { "url": string, "fileSize": number },
          "webp": { "url": string, "fileSize": number }
        }
      },
      [...]
    ],
    "thumbnailUrl": string, // DEPRECATED — use src.thumbnails instead
    "filename": string,
    "abr": {
      "resolution": "auto",
      "description": "Adaptive Bitrate Streaming (ABR)",
      "url": string, // .m3u8 playlist file
      "maxWidth": number,
      "maxHeight": number
    },
    "hls": [
      {
        "name": "2160p" | "1440p" | "1080p" | "720p" | "540p" | "360p" | "240p",
        "url": string, // .m3u8 playlist file
        "width": number,
        "height": number
      },
      [...]
    ],
    "mp4": [
      {
        "name": "2160p" | "1440p" | "1080p" | "720p" | "540p" | "360p" | "240p",
        "url": string, // .mp4 file
        "width": number,
        "height": number
      },
      [...]
    ]
  },
  "texttracks": [
    {
      "language": "en" | "en-US" | "de" | "de-DE" | "it" | "fr" | "...",
      "filename": string,
      "type": "subtitles" | "captions",
      "url": string,
      "id": string
      // If you need the `content` property, you have to fetch the specific texttrack by its ID.
      // See "Text tracks > Get" for details.
    },
    [...]
  ],
  "chapters": [
    {
      "id": string,
      "title": string,
      "timestamp": string, // 00:00:00
    },
    [...]
  ],
  "categories": [
    {
      "id": string,
      "title": string,
      "slug": string,
    },
    [...]
  ],
  "tags": [
    {
      "id": string,
      "title": string,
      "slug": string,
    },
    [...]
  ],
  "transcriptions": [
    {
      "language": string, // locale in de-DE format
      "autoGenerated": boolean,
      "text": string, // plain text transcript
      "segments": [
          {
            "startTime": number, // in seconds
            "endTime": number, // in seconds
            "text": string
          },
          [...]
      ],
    },
    [...]
  ],
  "autoTranscription": [
    // for videos longer then 3 hours, there will be multiple entries after auto transcription
    {
      "autoStart": boolean,
      "lastUpdatedAt": Date,
      "data": {
        "id": string,
        "status": "COMPLETED" | "QUEUED" | "IN_PROGRESS" | "FAILED" | "NONE",
        "videoDuration": number,
        "language": string,
        "subtitle": string, // webVTT format
        "transcription": string, // plain text
        "transcriptionParts": [
          {
            "id": number,
            "transcript": string,
            "start_time": number, // in seconds
            "end_time": number // in seconds
          },
          [...]
        ],
        "createdAt": Date,
        "updatedAt": Date,
      }
    },
    ...
  ],
  "createdAt": Date,
  "updatedAt": Date
}

Stato di codifica

Questi campi descrivono il ciclo di vita della codifica dopo il caricamento o la sostituzione di un file video.

Ciclo di vita tipico

Dopo la creazione di un oggetto video, status è NO_FILE finché non viene caricato un file.
Al termine del caricamento del file, inizia la codifica e status diventa PROGRESSING. statusProgress passa da 0 verso 100.
In caso di successo, status diventa COMPLETE, statusProgress è 100, e le sorgenti di riproduzione sono disponibili in src.
In caso di errore, status diventa ERROR. Leggi errorCode e errorMessage per i dettagli.

Quando sostituisci un video, status diventa brevemente REPLACING durante il caricamento del nuovo file, poi segue lo stesso percorso PROGRESSING → COMPLETE / ERROR.

status

Valore	Descrizione
`NO_FILE`	L’oggetto video esiste, ma non è ancora stato caricato alcun file
`PROGRESSING`	La codifica è in corso
`REPLACING`	Un nuovo file è in caricamento per sostituire il video esistente
`COMPLETE`	Codifica completata con successo; le sorgenti di riproduzione sono disponibili in `src`
`ERROR`	Codifica fallita

statusProgress

Avanzamento della codifica come percentuale da 0 a 100.

Mentre status è PROGRESSING, interroga GET /api/videos/[VIDEO_ID] (vedi ottenere video) e leggi statusProgress per mostrare l’avanzamento nella tua UI. Un intervallo di polling di pochi secondi di solito è sufficiente.

Puoi anche iscriverti ai webhook video.updated. Gli aggiornamenti di progresso possono scattare spesso durante la codifica; debounce gli aggiornamenti dell’UI se necessario. Vedi Webhooks.

Al termine della codifica, status diventa COMPLETE e statusProgress è 100.

errorCode e errorMessage

Quando status è ERROR, questi campi spiegano il fallimento. Preferisci errorCode per la gestione programmatica. Usa errorMessage come fallback leggibile se non mappi il codice tu stesso.

Entrambi i campi sono null (o assenti) quando il video non è in stato di errore.

Esempio quando la codifica fallisce:


{
  "id": "[VIDEO_ID]",
  "status": "ERROR",
  "statusProgress": 42,
  "errorCode": "MEDIACONVERT_1040",
  "errorMessage": "Invalid or unsupported file format"
}

`errorCode`	Descrizione
`DURATION_LIMIT_EXCEEDED`	La durata del video supera il limite del tuo account
`UNKNOWN_ERROR`	Si è verificato un errore sconosciuto durante l’elaborazione
`MEDIACONVERT_1040`	Formato file non valido o non supportato
`MEDIACONVERT_1041`	Il file di input è corrotto o incompleto
`MEDIACONVERT_1050`	Codec video non supportato
`MEDIACONVERT_1060`	Codec audio non supportato
`MEDIACONVERT_1071`	Risoluzione o rapporto d’aspetto video non validi
`MEDIACONVERT_3000`	Servizio temporaneamente non disponibile; riprova più tardi

Possono comparire altri valori di errorCode nel tempo. Usa sempre errorMessage (o un messaggio di errore generico) per codici sconosciuti.

Miniature

src.thumbnails

Varianti multirisoluzione della miniatura attualmente attiva. L’array è ordinato per larghezza decrescente (risoluzione più alta per prima). Vengono generate solo dimensioni uguali o inferiori all’immagine sorgente. Risoluzioni disponibili: 2160p, 1440p, 1080p, 720p, 480p, 360p, 240p.


{
  "name": "2160p" | "1440p" | "1080p" | "720p" | "480p" | "360p" | "240p",
  "width": number,
  "height": number,
  "formats": {
    "jpeg": { "url": string, "fileSize": number },
    "webp": { "url": string, "fileSize": number }
  }
}

Ogni variante di risoluzione è disponibile sia in formato JPEG che WebP. Usa formats.webp.url per dimensioni file minori o formats.jpeg.url per la massima compatibilità. Per ottenere la miniatura alla risoluzione più alta, usa src.thumbnails[0].formats.jpeg.url (o .webp.url). Per selezionare una risoluzione specifica, filtra l’array per name, width o height.

src.thumbnailUrl (deprecato)

Deprecato — Usa src.thumbnails al suo posto. Questo campo sarà rimosso in una versione futura.

Contiene l’URL della variante 1080p (o la più alta disponibile) della miniatura attualmente attiva. Si aggiorna automaticamente ogni volta che cambia la miniatura.

Ciclo di vita delle miniature

Evento	`src.thumbnails`	`src.thumbnailUrl`
Elaborazione video completata	Popolata con le varianti generate	Impostata sulla variante 1080p (o la più alta disponibile)
Miniatura personalizzata caricata	Sostituita con le nuove varianti	Aggiornata alla variante 1080p (o la più alta disponibile)
Miniatura da timestamp	Sostituita con le nuove varianti	Aggiornata alla variante 1080p (o la più alta disponibile)
Ripristino miniatura	Ripristinate le varianti generate automaticamente	Ripristinata alla variante 1080p (o la più alta disponibile)

Sorgenti video

Array src del video

Gli array hls e mp4 contengono l’elenco di tutte le sorgenti video disponibili per il video. Gli array sono ordinati per qualità, partendo dalla qualità più alta. Le varianti video vengono generate fino alla risoluzione del video in ingresso. Quindi un video caricato in 1080p non avrà varianti 2160p e 1440p.


{
  "name": "2160p" | "1440p" | "1080p" | "720p" | "540p" | "360p" | "240p",
  "url": string,
  "width": number,
  "height": number
}

Adaptive Bitrate Streaming (ABR)

Se vuoi fornire i tuoi video tramite streaming a bitrate adattivo (in breve ABR), puoi farlo usando src.abr.url come sorgente video. Il file playlist elenca tutte le qualità video fornite nell’array src.hls.