L’objet vidéo

L’objet vidéo est un objet JSON avec les propriétés suivantes :


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

Statut d’encodage

Ces champs décrivent le cycle de vie de l’encodage après le téléchargement ou le remplacement d’un fichier vidéo.

Cycle de vie typique

Après la création d’un objet vidéo, status vaut NO_FILE jusqu’à ce qu’un fichier soit téléchargé.
Une fois le téléchargement du fichier terminé, l’encodage démarre et status devient PROGRESSING. statusProgress progresse de 0 vers 100.
En cas de succès, status devient COMPLETE, statusProgress vaut 100, et les sources de lecture sont disponibles sous src.
En cas d’échec, status devient ERROR. Lis errorCode et errorMessage pour les détails.

Quand tu remplaces une vidéo, status devient brièvement REPLACING pendant le téléchargement du nouveau fichier, puis suit le même chemin PROGRESSING → COMPLETE / ERROR.

status

Valeur	Description
`NO_FILE`	L’objet vidéo existe, mais aucun fichier n’a encore été téléchargé
`PROGRESSING`	L’encodage est en cours
`REPLACING`	Un nouveau fichier est en cours de téléchargement pour remplacer la vidéo existante
`COMPLETE`	L’encodage s’est terminé avec succès ; les sources de lecture sont disponibles sous `src`
`ERROR`	L’encodage a échoué

statusProgress

Progression de l’encodage en pourcentage de 0 à 100.

Tant que status est PROGRESSING, interroge GET /api/videos/[VIDEO_ID] (voir obtenir la vidéo) et lis statusProgress pour afficher la progression dans ton interface. Un intervalle de sondage de quelques secondes suffit généralement.

Tu peux aussi t’abonner aux webhooks video.updated. Les mises à jour de progression peuvent se déclencher souvent pendant l’encodage — debounce les mises à jour de l’interface si nécessaire. Voir Webhooks.

Une fois l’encodage terminé, status devient COMPLETE et statusProgress vaut 100.

errorCode et errorMessage

Lorsque status est ERROR, ces champs expliquent l’échec. Privilégie errorCode pour le traitement programmatique. Utilise errorMessage comme repli lisible si tu ne fais pas toi-même la correspondance du code.

Les deux champs valent null (ou sont absents) lorsque la vidéo n’est pas en état d’erreur.

Exemple en cas d’échec de l’encodage :


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

`errorCode`	Description
`DURATION_LIMIT_EXCEEDED`	La durée de la vidéo dépasse la limite de ton compte
`UNKNOWN_ERROR`	Une erreur inconnue s’est produite pendant le traitement
`MEDIACONVERT_1040`	Format de fichier invalide ou non pris en charge
`MEDIACONVERT_1041`	Le fichier d’entrée est corrompu ou incomplet
`MEDIACONVERT_1050`	Codec vidéo non pris en charge
`MEDIACONVERT_1060`	Codec audio non pris en charge
`MEDIACONVERT_1071`	Résolution vidéo ou ratio d’aspect invalide
`MEDIACONVERT_3000`	Service temporairement indisponible ; réessaie plus tard

D’autres valeurs errorCode peuvent apparaître avec le temps. Pour les codes inconnus, reviens toujours à errorMessage (ou à un message d’échec générique).

Miniatures

src.thumbnails

Variantes multi-résolution de la miniature actuellement active. Le tableau est trié par largeur décroissante (résolution la plus élevée en premier). Seules les tailles inférieures ou égales à l’image source sont générées. Résolutions disponibles : 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 }
  }
}

Chaque variante de résolution est disponible au format JPEG et WebP. Utilise formats.webp.url pour des fichiers plus légers ou formats.jpeg.url pour une compatibilité maximale. Pour obtenir la miniature en plus haute résolution, utilise src.thumbnails[0].formats.jpeg.url (ou .webp.url). Pour choisir une résolution précise, filtre le tableau par name, width ou height.

src.thumbnailUrl (déprécié)

Déprécié — Utilise src.thumbnails à la place. Ce champ sera supprimé dans une version ultérieure.

Contient l’URL de la variante 1080p (ou la plus haute disponible) de la miniature active. Mis à jour automatiquement à chaque changement de miniature.

Cycle de vie des miniatures

Événement	`src.thumbnails`	`src.thumbnailUrl`
Traitement vidéo terminé	Rempli avec les variantes générées	Défini sur la variante 1080p (ou la plus haute disponible)
Miniature personnalisée téléchargée	Remplacé par de nouvelles variantes	Mis à jour vers la variante 1080p (ou la plus haute disponible)
Miniature depuis un instant dans la vidéo	Remplacé par de nouvelles variantes	Mis à jour vers la variante 1080p (ou la plus haute disponible)
Réinitialisation de la miniature	Restauré aux variantes auto-générées	Restauré à la variante 1080p (ou la plus haute disponible)

Sources vidéo

Tableaux src vidéo

Les tableaux hls et mp4 contiennent la liste de toutes les sources vidéo disponibles pour la vidéo. Les tableaux sont triés par qualité, en commençant par la plus haute. Les variantes vidéo sont générées jusqu’à la résolution de la vidéo d’entrée. Ainsi, une vidéo 1080p téléchargée n’aura pas de variante 2160p ni 1440p.


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

Adaptive Bitrate Streaming (ABR)

Si tu veux diffuser tes vidéos en streaming à débit adaptatif (abrégé ABR), tu peux utiliser src.abr.url comme source vidéo. Le fichier playlist regroupe toutes les qualités fournies listées dans le tableau src.hls.