Rozdział 15 GET POST

getRecordingTextTracks – Ścieżki tekstowe

Punkt końcowy getRecordingTextTracks zwraca listę wszystkich ścieżek napisów i podpisów powiązanych z określonym nagraniem. W przeciwieństwie do większości endpointów API BigBlueButton, odpowiedź jest zwracana w formacie JSON zamiast XML.

Punkt końcowy

GET/POST https://api-guide.bbbserver.com/bigbluebutton/api/getRecordingTextTracks?<parameter>&checksum=replace-with-checksum

Obsługiwane są zarówno metody GET, jak i POST. W przypadku użycia POST należy wysłać parametry jako application/x-www-form-urlencoded w treści żądania.

Parametry

Parametr Typ Opis
recordID String Wymagane. Identyfikator nagrania, którego ścieżki tekstowe chcesz pobrać. Akceptowany jest tylko pojedynczy identyfikator nagrania — listy rozdzielane przecinkami nie są obsługiwane.

W przeciwieństwie do innych endpointów nagrań, getRecordingTextTracks akceptuje tylko pojedynczą wartość recordID. Przekazanie wielu identyfikatorów rozdzielonych przecinkami spowoduje błąd lub nieoczekiwane zachowanie.

Pola odpowiedzi

Każdy obiekt ścieżki w odpowiedzi zawiera następujące atrybuty:

Pole Typ Opis
href String URL pobierania pliku ścieżki tekstowej w formacie WebVTT.
kind String Typ ścieżki tekstowej zgodny ze specyfikacją elementu wideo HTML5. Możliwe wartości: subtitles lub captions.
label String Nazwa wyświetlana w menu wyboru napisów w interfejsie odtwarzania nagrania.
lang String Znacznik języka zdefiniowany przez RFC 5646 (np. en-US, de-DE, pt-BR).
source String Pochodzenie ścieżki tekstowej. Znane wartości: live (transkrypcja na żywo podczas spotkania), automatic (wygenerowane maszynowo po spotkaniu), upload (przesłane ręcznie).

Przykładowe żądanie

curl --request GET \
    "https://api-guide.bbbserver.com/bigbluebutton/api/getRecordingTextTracks?recordID=replace-with-recording-id&checksum=replace-with-checksum"

Przykładowa odpowiedź

Sukces

{
  "response": {
    "returncode": "SUCCESS",
    "tracks": [
      {
                "href": "https://api-guide.bbbserver.com/captions/replace-with-recording-id/de-DE.vtt",
        "kind": "subtitles",
        "label": "Deutsch",
        "lang": "de-DE",
        "source": "upload"
      },
      {
                "href": "https://api-guide.bbbserver.com/captions/replace-with-recording-id/en-US.vtt",
        "kind": "subtitles",
        "label": "English",
        "lang": "en-US",
        "source": "live"
      }
    ]
  }
}

Błąd — brak identyfikatora rekordu

{
  "response": {
    "returncode": "FAILED",
    "messageKey": "missingParamRecordID",
    "message": "You must specify a recordID."
  }
}

Odpowiedzi błędów

Klucz komunikatu Opis
checksumError Parametr checksum jest nieprawidłowy lub nie odpowiada parametrom żądania.
missingParamRecordID Wymagany parametr recordID nie został podany w żądaniu.
noRecordings Nie znaleziono nagrania pasującego do podanego identyfikatora nagrania.

Uwagi bbbserver.de

bbbserver.de: Ten punkt końcowy nie jest dostępny na platformie bbbserver.de. Ścieżek tekstowych dla nagrań nie można pobrać przez API.

Wskazówki

Jest to jedyny standardowy endpoint API BigBlueButton, który zwraca JSON zamiast XML. Upewnij się, że klient API obsługuje tę różnicę podczas parsowania odpowiedzi.

  • Użyj pola lang do filtrowania ścieżek według języka podczas tworzenia interfejsu wyboru napisów dla użytkowników.
  • Pole href dostarcza bezpośredni link do pobrania pliku WebVTT, którego można użyć z dowolnym standardowym odtwarzaczem wideo HTML5.
  • Sprawdź pole source, aby odróżnić ręcznie przesłane podpisy od tych wygenerowanych automatycznie, których jakość może się różnić.
  • Aby dodać lub zaktualizować ścieżki tekstowe, użyj towarzyszącego endpointu putRecordingTextTrack.

Najczęściej zadawane pytania

Punkt końcowy getRecordingTextTracks został dodany później w ewolucji API BigBlueButton i od początku zaprojektowano go tak, aby zwracał JSON. Jest to wyjątek od ogólnej zasady, że odpowiedzi API BigBlueButton używają XML. Kod klienta musi odpowiednio obsłużyć tę różnicę formatu.

Nie. W przeciwieństwie do innych endpointów nagrań, które akceptują listy rozdzielone przecinkami, getRecordingTextTracks przyjmuje tylko pojedynczy recordID na żądanie. Aby pobrać ścieżki dla wielu nagrań, musisz wysłać osobne wywołania API dla każdego nagrania.

Ścieżki tekstowe są udostępniane w formacie WebVTT (Web Video Text Tracks), standardowym formacie napisów dla odtwarzania wideo HTML5. Plik można pobrać bezpośrednio z URL podanego w polu href odpowiedzi.

Napisy są przeznaczone dla widzów, którzy słyszą dźwięk, ale potrzebują tłumaczenia tekstowego, natomiast podpisy są przeznaczone dla osób głuchych lub niedosłyszących i mogą zawierać opisy dźwięków niesłownych, takich jak efekty dźwiękowe. Pole kind w odpowiedzi wskazuje, którego typu dotyczy dana ścieżka.

Znane wartości to: live (wygenerowane podczas spotkania przez transkrypcję na żywo), automatic (wygenerowane maszynowo po spotkaniu) oraz upload (ręcznie przesłane przez użytkownika). Należy pamiętać, że wartości te opierają się na analizie kodu źródłowego i obserwacjach społeczności, ponieważ nie są w pełni udokumentowane w oficjalnej specyfikacji.