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

Oznaczenie treści AI dla treści wygenerowanych lub zmodyfikowanych przez AI, które mogą wyglądać autentycznie, zgodnie z regulacjami takimi jak unijny AI Act (art. 50). none (domyślnie) oznacza, że osadzony odtwarzacz nigdy nie pokazuje etykiety AI. generated i modified pokazują etykietę AI w odtwarzaczu, gdy opcja designu aiContentLabel nie jest off.

v

Wersja pliku. Zaczyna się od 0 i zwiększa się, gdy plik zastępczy kończy kodowanie.

autoTranscription

autoTranscription to pojedynczy obiekt z autoStart, lastUpdatedAt i data. autoStart określa, czy transkrypcja startuje po kodowaniu. data zawiera powiązane rekordy transkrypcji, a ich wypełnienie zależy od depth. Wideo dłuższe niż 3 godziny generują wiele zadań transkrypcji. Odpytuj transkrypcję o te rekordy zadań.

contentUpdatedAt

Znacznik czasu podbijany przy zapisach treści. Nie możesz ustawić tego pola.

customMetadata

Płaski obiekt własnych danych, z co najwyżej 50 kluczami. Każdy klucz pasuje do ^[a-zA-Z0-9_-]+$ i ma co najwyżej 40 znaków. Każda wartość to ciąg o długości co najwyżej 500 znaków, skończona liczba albo boolean. Zagnieżdżone obiekty i tablice są odrzucane. Kolejny zapis jest scalany z zapisanym obiektem. Wysłanie "" albo null dla klucza usuwa ten klucz. Możesz ustawić to pole, gdy tworzysz albo aktualizujesz wideo.

passwordProtection

enabled określa, czy wideo wymaga hasła. password jest dołączane dla wywołujących, którzy mogą aktualizować wideo, gdy workspace ma włączoną ochronę hasłem. Przy aktualizacji password musi mieć co najmniej 8 znaków. Pole można zapisywać tylko wtedy, gdy ta funkcja jest włączona.

categories i tags

Przy domyślnej głębokości każdy wpis to obiekt z id, title, slug i description. Przy depth=0 każdy wpis to identyfikator. Pusta lista to null.

Adresy URL podglądu

previewVideoUrl, previewThumbnailUrl i previewThumbnailUrlSmall to podpisane adresy URL podglądu. Są dodawane przy odczycie, gdy istnieją rendycje.

Ustawienia odtwarzacza

Właściwość player zawiera design odtwarzacza wideo. Jest dołączana tylko do odpowiedzi na żądania z kluczem API. Payload webhooka jej nie zawiera.

selectedPreset i useCustomDesign są dołączane tylko wtedy, gdy twój plan obejmuje własne designy odtwarzacza, a workspace ma co najmniej jeden preset odtwarzacza.

Aby znaleźć design, którego używa odtwarzacz:

1. Jeśli useCustomDesign ma wartość true lub selectedPreset ma wartość null, użyj playerDesign.
2. W przeciwnym razie użyj właściwości designu z selectedPreset.

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

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

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)

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

Cykl życia miniatur

Ź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.

src.audio

src.audio zawiera listę rendycji audio dla tego wideo. Każdy wpis ma name i url. name to etykieta, na przykład high-quality albo low-quality.