O objeto de vídeo

O objeto de vídeo é um objeto JSON com as seguintes propriedades:


{
  "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
}

Estado de codificação

Estes campos descrevem o ciclo de vida da codificação depois de carregares ou substituíres um ficheiro de vídeo.

Ciclo de vida típico

Depois de criares um objeto de vídeo, status é NO_FILE até ser carregado um ficheiro.
Quando o carregamento do ficheiro termina, a codificação começa e status passa a PROGRESSING. statusProgress avança de 0 para 100.
Em caso de sucesso, status passa a COMPLETE, statusProgress é 100, e as fontes de reprodução ficam disponíveis em src.
Em caso de falha, status passa a ERROR. Lê errorCode e errorMessage para obteres detalhes.

Quando substituís um vídeo, status passa brevemente a REPLACING enquanto o novo ficheiro é carregado e depois segue o mesmo percurso PROGRESSING → COMPLETE / ERROR.

status

Valor	Descrição
`NO_FILE`	O objeto de vídeo existe, mas ainda não foi carregado nenhum ficheiro
`PROGRESSING`	A codificação está em curso
`REPLACING`	Está a ser carregado um novo ficheiro para substituir o vídeo existente
`COMPLETE`	A codificação terminou com sucesso; as fontes de reprodução estão disponíveis em `src`
`ERROR`	A codificação falhou

statusProgress

Progresso da codificação como percentagem de 0 a 100.

Enquanto status for PROGRESSING, consulta GET /api/videos/[VIDEO_ID] (ver obter vídeo) e lê statusProgress para mostrar o progresso na tua UI. Um intervalo de polling de alguns segundos costuma ser suficiente.

Também podes subscrever webhooks video.updated. As atualizações de progresso podem disparar-se com frequência durante a codificação; faz debounce às atualizações da UI se necessário. Ver Webhooks.

Quando a codificação termina, status passa a COMPLETE e statusProgress é 100.

errorCode e errorMessage

Quando status é ERROR, estes campos explicam a falha. Prefere errorCode para tratamento programático. Usa errorMessage como alternativa legível quando não mapeares o código tu próprio.

Ambos os campos são null (ou estão ausentes) quando o vídeo não está num estado de erro.

Exemplo quando a codificação falha:


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

`errorCode`	Descrição
`DURATION_LIMIT_EXCEEDED`	A duração do vídeo excede o limite da tua conta
`UNKNOWN_ERROR`	Ocorreu um erro desconhecido durante o processamento
`MEDIACONVERT_1040`	Formato de ficheiro inválido ou não suportado
`MEDIACONVERT_1041`	O ficheiro de entrada está corrompido ou incompleto
`MEDIACONVERT_1050`	Codec de vídeo não suportado
`MEDIACONVERT_1060`	Codec de áudio não suportado
`MEDIACONVERT_1071`	Resolução ou proporção de aspeto de vídeo inválida
`MEDIACONVERT_3000`	Serviço temporariamente indisponível; tenta novamente mais tarde

Podem aparecer valores adicionais de errorCode ao longo do tempo. Recorre sempre a errorMessage (ou a uma mensagem de falha genérica) para códigos desconhecidos.

Miniaturas

src.thumbnails

Variantes do thumbnail ativo atual em várias resoluções. O array está ordenado por largura descendente (maior resolução primeiro). Só são gerados tamanhos iguais ou inferiores à imagem de origem. Resoluções disponíveis: 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 }
  }
}

Cada variante de resolução está disponível em JPEG e WebP. Usa formats.webp.url para ficheiros mais pequenos ou formats.jpeg.url para máxima compatibilidade. Para obter a miniatura com maior resolução, usa src.thumbnails[0].formats.jpeg.url (ou .webp.url). Para escolher uma resolução específica, filtra o array por name, width ou height.

src.thumbnailUrl (deprecated)

Obsoleto — Usa src.thumbnails em alternativa. Este campo será removido numa versão futura.

Contém o URL da variante 1080p (ou a mais alta disponível) da miniatura ativa. É atualizado automaticamente sempre que a miniatura muda.

Ciclo de vida da miniatura

Evento	`src.thumbnails`	`src.thumbnailUrl`
O processamento do vídeo conclui	Preenchido com variantes geradas	Definido para a variante 1080p (ou a mais alta disponível)
Miniatura personalizada carregada	Substituído por novas variantes	Atualizado para 1080p (ou a mais alta disponível)
Miniatura a partir de timestamp	Substituído por novas variantes	Atualizado para 1080p (ou a mais alta disponível)
Repor miniatura	Restaurado às variantes auto-geradas	Restaurado para 1080p (ou a mais alta disponível)

Fontes de vídeo

Arrays src do vídeo

Os arrays hls e mp4 contêm a lista de todas as fontes de vídeo disponíveis. Os arrays estão ordenados por qualidade, começando pela mais alta. As variantes de vídeo são geradas até à resolução do vídeo de entrada. Por isso, um vídeo 1080p carregado não terá variantes 2160p nem 1440p.


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

Adaptive Bitrate Streaming (ABR)

Se quiseres disponibilizar os teus vídeos com streaming de bitrate adaptativo (ABR), podes fazê-lo usando src.abr.url como fonte de vídeo. O ficheiro de playlist inclui todas as qualidades de vídeo indicadas no array src.hls.