Rozdział 16 POST

putRecordingTextTrack – Prześlij ścieżkę tekstową

Punkt końcowy putRecordingTextTrack umożliwia przesyłanie plików napisów lub podpisów do nagrania. Obsługiwane formaty to SRT, SSA/ASS i WebVTT. Wszystkie przesłane pliki są wewnętrznie konwertowane do WebVTT. Odpowiedź jest zwracana w formacie JSON.

Ten punkt końcowy obsługuje tylko żądania POST. Żądania GET nie są akceptowane.

Punkt końcowy

POST https://api-guide.bbbserver.com/bigbluebutton/api/putRecordingTextTrack?<parameters>&checksum=replace-with-checksum

Plik napisów musi zostać wysłany jako multipart/form-data w treści POST. Suma kontrolna jest obliczana wyłącznie na podstawie parametrów zapytania URL — treść POST nie jest uwzględniana w obliczeniu sumy kontrolnej.

Parametry URL (ciąg zapytania)

Parametr Typ Wymagane Domyślnie Opis
recordID String Tak — Pojedynczy identyfikator nagrania. W przeciwieństwie do innych endpointów ten parametr nie akceptuje listy rozdzielonej przecinkami — dozwolony jest tylko jeden identyfikator nagrania.
kind Enum Tak — Typ ścieżki tekstowej. Akceptowane wartości to napisy lub captions.
lang String Tak — Znacznik języka zgodny z RFC 5646 (np. de-DE, en-US).
label String Nie Automatycznie wykrywane z lang Czytelna dla człowieka nazwa wyświetlana ścieżki (np. „niemiecki”). Jeśli zostanie pominięta, nazwa języka jest automatycznie wyprowadzana z wartości lang.

Treść POST (multipart/form-data)

Parametr Typ Wymagane Domyślnie Opis
file Binary Tak — Plik napisów do przesłania. Obsługiwane formaty: SRT (application/x-subrip), SSA/ASS i WebVTT (text/vtt). Jeśli plik jest brakujący lub pusty, API zwraca odpowiedź FAILED.

Przykładowe żądanie

curl -X POST \
    "https://api-guide.bbbserver.com/bigbluebutton/api/putRecordingTextTrack?recordID=replace-with-recording-id&kind=subtitles&lang=de-DE&label=Deutsch&checksum=replace-with-checksum" \
  -F "file=@subtitles.srt;type=application/x-subrip"

Przykładowa odpowiedź

Pomyślne wywołanie zwraca następujący JSON: 

{
  "response": {
    "returncode": "SUCCESS",
    "messageKey": "upload_text_track_success",
    "message": "Text track uploaded successfully",
        "recordId": "replace-with-recording-id"
  }
}

Odpowiedzi błędów

messageKey Opis
paramError Brakuje wymaganego parametru (checksum, recordID, kind lub lang). Uwaga: oficjalna dokumentacja błędnie podaje to jako missingParameter.
noRecordings Nie znaleziono wskazanego identyfikatora nagrania.
invalidKind Wartość kind jest nieprawidłowa. Musi być subtitles lub captions.
invalidLang Format znacznika języka jest nieprawidłowy. Musi być zgodny z RFC 5646.
empty_uploaded_text_track Przesłany plik był pusty albo w żądaniu nie dołączono żadnego pliku.

Ważne zachowanie

Przetwarzanie ścieżek tekstowych odbywa się asynchronicznie. Po pomyślnym przesłaniu może minąć kilka minut, zanim ścieżka będzie dostępna podczas odtwarzania nagrania.

Jeśli ścieżka z tym samym kind i językiem już istnieje, zostanie nadpisana nowym plikiem.

Przesłanie pustego pliku lub wysłanie żądania bez pliku nie usuwa istniejącej ścieżki. API zwraca zamiast tego odpowiedź FAILED.

Wszystkie przesłane formaty napisów (SRT, SSA/ASS) są automatycznie konwertowane do WebVTT na potrzeby odtwarzania.

Uwagi bbbserver.de

bbbserver.de: Ten punkt końcowy nie jest dostępny na platformie bbbserver.de. Przesyłanie napisów przez API nie jest obsługiwane.

Wskazówki

Użyj endpointu getRecordingTextTracks, aby sprawdzić, czy przesłana ścieżka tekstowa została przetworzona i jest dostępna do odtwarzania, zanim podlinkujesz ją w swojej aplikacji.

  • WebVTT jest zalecanym formatem, ponieważ nie wymaga konwersji i jest natywnie obsługiwany przez przeglądarki.
  • Podczas przesyłania wielu ścieżek językowych używaj różnych znaczników języka RFC 5646, aby uniknąć przypadkowego nadpisania istniejących ścieżek.
  • Ustaw opisowy parametr label, aby pomóc widzom rozpoznać właściwą ścieżkę w selektorze języka odtwarzania.
  • Pamiętaj, że suma kontrolna jest obliczana wyłącznie na podstawie parametrów zapytania URL — nie uwzględniaj zawartości pliku w sumie kontrolnej.

Najczęściej zadawane pytania

BigBlueButton akceptuje pliki SRT (SubRip), SSA/ASS (SubStation Alpha) i WebVTT (Web Video Text Tracks). Wszystkie formaty są wewnętrznie konwertowane do WebVTT na potrzeby odtwarzania. Obsługiwane formaty poza WebVTT wynikają z kodu źródłowego i nie są wyraźnie wymienione w oficjalnej dokumentacji.

Tak. Możesz wielokrotnie wywoływać punkt końcowy putRecordingTextTrack z różnymi wartościami lang, aby przesyłać ścieżki dla różnych języków. Każda kombinacja kind i lang jest przechowywana jako osobna ścieżka.

Istniejąca ścieżka z tą samą kombinacją kind i lang zostaje nadpisana nowym plikiem. Nie ma wersjonowania ani kopii zapasowych poprzednich ścieżek.

Nie. Wysłanie żądania bez pliku lub z pustym plikiem nie usuwa istniejącej ścieżki. API po prostu zwraca odpowiedź FAILED z kluczem błędu empty_uploaded_text_track. Nie ma dedykowanego punktu końcowego do usuwania ścieżek tekstowych.

Przetwarzanie odbywa się asynchronicznie. Po pomyślnym przesłaniu zwykle mija kilka minut, zanim ścieżka tekstowa stanie się dostępna podczas odtwarzania nagrania. Dokładny czas zależy od obciążenia serwera i rozmiaru pliku.

Suma kontrolna jest obliczana wyłącznie na podstawie parametrów zapytania URL. Treść POST zawierająca plik z napisami nie jest częścią obliczania sumy kontrolnej. Jest to zamierzone i zgodne ze sposobem, w jaki BigBlueButton obsługuje żądania wieloczęściowe POST.