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",
  "language": string,
  "aiContent": "none" | "generated" | "modified",
  "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
      },
      [...]
    ],
    "audio": [
      {
        "name": string, // for example "high-quality" or "low-quality"
        "url": string
      },
      [...]
    ]
  },
  "texttracks": [
    {
      "id": string,
      "language": "en-US" | "de-DE" | "...", // region locale
      "filename": string,
      "type": "subtitles" | "captions",
      "url": string,
      "autoGenerated": boolean,
      "autoTranslated": boolean,
      "edited": boolean,
      "updatedAt": Date,
      "content": string // URL-encoded placeholder. GET the track for the WebVTT.
    },
    [...]
  ],
  "chapters": [
    {
      "id": string,
      "title": string,
      "timestamp": string, // 00:00:00
    },
    [...]
  ],
  "categories": [
    {
      "id": string,
      "title": string,
      "slug": string,
      "description": string,
    },
    [...]
  ],
  "tags": [
    {
      "id": string,
      "title": string,
      "slug": string,
      "description": 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
          },
          [...]
      ],
    },
    [...]
  ],
  "audiotracks": [ ... ], // present on the object; ignored by PATCH
  "autoTranscription": {
    "autoStart": boolean,
    "lastUpdatedAt": Date,
    "data": object // transcription records; population follows depth
  },
  "contentUpdatedAt": Date, // bumped on content writes; not writable
  "customMetadata": object,
  "passwordProtection": {
    "enabled": boolean,
    "password": string // present for callers who can update the video
  },
  "previewVideoUrl": string,
  "previewThumbnailUrl": string,
  "previewThumbnailUrlSmall": string,
  "player": {
    "selectedPreset": object | null, // player preset object
    "useCustomDesign": boolean,
    "playerDesign": { ... }, // player design properties, see "Player settings"
    "shareUrl": string
  },
  "workspace": string, // workspace id; stays an id at every depth
  "createdAt": Date,
  "updatedAt": Date
}

aiContent

Marcação de conteúdo IA para conteúdos gerados ou modificados com IA que possam parecer autênticos, como exigem regulamentos como o AI Act da UE (art. 50). none (predefinição) significa que o leitor embed nunca mostra a etiqueta IA. generated e modified mostram a etiqueta IA no leitor quando a opção de design aiContentLabel não é off.

v

Versão do ficheiro. Começa em 0 e incrementa quando um ficheiro de substituição termina a codificação.

autoTranscription

autoTranscription é um único objeto com autoStart, lastUpdatedAt e data. autoStart indica se a transcrição começa após a codificação. data contém os registos de transcrição relacionados e o seu preenchimento segue depth. Vídeos com mais de 3 horas geram vários trabalhos de transcrição. Consulta transcrever para esses registos de trabalho.

contentUpdatedAt

Timestamp incrementado nas escritas de conteúdo. Não podes definir este campo.

customMetadata

Um objeto plano de dados personalizados, com no máximo 50 chaves. Cada chave corresponde a ^[a-zA-Z0-9_-]+$ e tem no máximo 40 caracteres. Cada valor é uma string com no máximo 500 caracteres, um número finito ou um booleano. Objetos e arrays aninhados são rejeitados. Uma escrita posterior faz merge no objeto guardado. Enviar "" ou null para uma chave elimina essa chave. Podes defini-lo quando crias ou atualizas um vídeo.

passwordProtection

enabled indica se o vídeo exige uma palavra-passe. password é incluído para quem pode atualizar o vídeo, quando o workspace tem a proteção por palavra-passe ativa. Na atualização, password tem de ter pelo menos 8 caracteres. O campo só é gravável enquanto essa funcionalidade estiver ligada.

categories e tags

Na profundidade predefinida, cada entrada é um objeto com id, title, slug e description. Com depth=0, cada entrada é um id. Uma lista vazia é null.

URLs de pré-visualização

previewVideoUrl, previewThumbnailUrl e previewThumbnailUrlSmall são URLs assinados de pré-visualização. São acrescentados na leitura quando existem renditions.

Definições do leitor

A propriedade player contém o design do leitor do vídeo. Só é incluída nas respostas a pedidos com uma chave API. Os payloads de webhook não a incluem.

selectedPreset e useCustomDesign só são incluídos se o teu plano incluir designs de leitor personalizados e o workspace tiver pelo menos um preset do leitor.

Para encontrar o design que o leitor usa:

1. Se useCustomDesign for true ou selectedPreset for null, usa playerDesign.
2. Caso contrário, usa as propriedades de design de selectedPreset.

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

1. Depois de criares um objeto de vídeo, status é NO_FILE até ser carregado um ficheiro.
2. Quando o carregamento do ficheiro termina, a codificação começa e status passa a PROGRESSING. statusProgress avança de 0 para 100.
3. Em caso de sucesso, status passa a COMPLETE, statusProgress é 100, e as fontes de reprodução ficam disponíveis em src.
4. 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

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

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)

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

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.

src.audio

src.audio lista as renditions de áudio do vídeo. Cada entrada tem name e url. name é uma etiqueta como high-quality ou low-quality.