Skip to Content
Dokumentacja APIWideoObiekt wideo

Obiekt wideo

Obiekt wideo to obiekt JSON z następującymi właściwościami:

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

Status kodowania

Te pola opisują cykl życia kodowania po przesłaniu lub zastąpieniu pliku wideo.

Typowy cykl życia

  1. Po utworzeniu obiektu wideo status to NO_FILE, dopóki plik nie zostanie przesłany.
  2. Po zakończeniu przesyłania pliku rozpoczyna się kodowanie, a status przechodzi na PROGRESSING. statusProgress rośnie od 0 w kierunku 100.
  3. Po sukcesie status przechodzi na COMPLETE, statusProgress wynosi 100, a źródła odtwarzania są dostępne w src.
  4. Po błędzie status przechodzi na ERROR. Szczegóły znajdziesz w errorCode i errorMessage.

Gdy zastępujesz wideo, status na chwilę przechodzi na REPLACING podczas przesyłania nowego pliku, a potem podąża tą samą ścieżką PROGRESSING → COMPLETE / ERROR.

status

WartośćOpis
NO_FILEObiekt wideo istnieje, ale żaden plik nie został jeszcze przesłany
PROGRESSINGKodowanie jest w toku
REPLACINGNowy plik jest przesyłany, aby zastąpić istniejące wideo
COMPLETEKodowanie zakończyło się pomyślnie; źródła odtwarzania są dostępne w src
ERRORKodowanie nie powiodło się

statusProgress

Postęp kodowania jako procent od 0 do 100.

Gdy status to PROGRESSING, odpytuj GET /api/videos/[VIDEO_ID] (zob. pobieranie wideo) i odczytuj statusProgress, żeby pokazać postęp w swoim UI. Interwał odpytywania co kilka sekund zwykle wystarczy.

Możesz też subskrybować webhooki video.updated. Aktualizacje postępu mogą często wysyłać się podczas kodowania — w razie potrzeby debounce’uj aktualizacje UI. Zob. Webhooks.

Po zakończeniu kodowania status przechodzi na COMPLETE, a statusProgress wynosi 100.

errorCode i errorMessage

Gdy status to ERROR, te pola wyjaśniają przyczynę błędu. Do obsługi programowej preferuj errorCode. Użyj errorMessage jako czytelnego zapasowego opisu, jeśli sam nie mapujesz kodu.

Oba pola mają wartość null (lub są nieobecne), gdy wideo nie jest w stanie błędu.

Przykład, gdy kodowanie się nie powiedzie:

{
  "id": "[VIDEO_ID]",
  "status": "ERROR",
  "statusProgress": 42,
  "errorCode": "MEDIACONVERT_1040",
  "errorMessage": "Invalid or unsupported file format"
}
errorCodeOpis
DURATION_LIMIT_EXCEEDEDCzas trwania wideo przekracza limit twojego konta
UNKNOWN_ERRORWystąpił nieznany błąd podczas przetwarzania
MEDIACONVERT_1040Nieprawidłowy lub nieobsługiwany format pliku
MEDIACONVERT_1041Plik wejściowy jest uszkodzony lub niekompletny
MEDIACONVERT_1050Nieobsługiwany kodek wideo
MEDIACONVERT_1060Nieobsługiwany kodek audio
MEDIACONVERT_1071Nieprawidłowa rozdzielczość lub proporcje wideo
MEDIACONVERT_3000Usługa tymczasowo niedostępna; spróbuj ponownie później

Z czasem mogą pojawić się dodatkowe wartości errorCode. Dla nieznanych kodów zawsze wracaj do errorMessage (lub ogólnego komunikatu o błędzie).

Miniatury

src.thumbnails

Wielorozdzielcze warianty aktualnie aktywnej miniatury. Tablica jest posortowana malejąco po szerokości (najwyższa rozdzielczość na początku). Generowane są tylko rozmiary równe lub mniejsze niż obraz źródłowy. Dostępne rozdzielczości: 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 }
  }
}

Każdy wariant rozdzielczości jest dostępny w formacie JPEG i WebP. Użyj formats.webp.url, jeśli zależy Ci na mniejszym rozmiarze pliku, albo formats.jpeg.url dla maksymalnej kompatybilności. Aby uzyskać miniaturę w najwyższej rozdzielczości, użyj src.thumbnails[0].formats.jpeg.url (lub .webp.url). Aby wybrać konkretną rozdzielczość, przefiltruj tablicę po name, width lub height.

src.thumbnailUrl (przestarzałe)

Przestarzałe — Zamiast tego używaj src.thumbnails. To pole zostanie usunięte w przyszłej wersji.

Zawiera adres URL wariantu 1080p (lub najwyższego dostępnego) aktualnie aktywnej miniatury. Jest automatycznie aktualizowane przy każdej zmianie miniatury.

Cykl życia miniatur

Zdarzeniesrc.thumbnailssrc.thumbnailUrl
Zakończenie przetwarzania wideoWypełnione wygenerowanymi wariantamiUstawione na wariant 1080p (lub najwyższy dostępny)
Wgrana niestandardowa miniaturaZastąpione nowymi wariantamiZaktualizowane do wariantu 1080p (lub najwyższego dostępnego)
Miniatura ze znacznika czasuZastąpione nowymi wariantamiZaktualizowane do wariantu 1080p (lub najwyższego dostępnego)
Reset miniaturyPrzywrócone do automatycznie wygenerowanych wariantówPrzywrócone do wariantu 1080p (lub najwyższego dostępnego)

Źródła wideo

Tablice źródeł wideo

Tablice hls i mp4 zawierają listę wszystkich dostępnych źródeł wideo. Tablice są uporządkowane według jakości, od najwyższej. Warianty wideo generowane są do rozdzielczości wejściowego pliku. Przykładowo wgrane wideo 1080p nie będzie miało wariantów 2160p ani 1440p.

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

Adaptacyjne strumieniowanie ze zmiennym bitrate (ABR)

Jeśli chcesz udostępniać wideo przez adaptacyjne strumieniowanie ze zmiennym bitrate (skrót ABR), możesz użyć src.abr.url jako źródła wideo. Plik playlisty zawiera wszystkie dostarczone jakości wideo wymienione w tablicy src.hls.

UwierzytelnianieLista filmów