Wersja API: 4.x najnowsza 3.x

Przeglądasz dokumentację API dla BigBlueButton 3.x. Aktualna wersja to BigBlueButton 4.x. Planujesz aktualizację? Przewodnik migracji zawiera wszystkie zmiany wymagane w wywołaniach API.

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 Adres URL do pobrania pliku ścieżki tekstowej w formacie WebVTT. Adres URL zawiera jednorazowy token, który wygasa po godzinie.
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 (wygenerowana automatycznie przez rozpoznawanie mowy), upload (przesłana 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/bigbluebutton/textTrack/replace-with-token/replace-with-recording-id/subtitles_de-DE.vtt",
        "kind": "subtitles",
        "label": "Deutsch",
        "lang": "de-DE",
        "source": "upload"
      },
      {
                "href": "https://api-guide.bbbserver.com/bigbluebutton/textTrack/replace-with-token/replace-with-recording-id/subtitles_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.

Wskazówki

Podobnie jak putRecordingTextTrack, ten punkt końcowy zwraca JSON zamiast XML. Upewnij się, że klient API uwzględnia 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 zawiera link do pobrania pliku WebVTT. Link zawiera jednorazowy token ważny przez godzinę, dlatego pobierz plik od razu, zamiast zapisywać lub osadzać link.
  • 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 (wygenerowana podczas spotkania przez transkrypcję na żywo), automatic (wygenerowana automatycznie przez rozpoznawanie mowy) i upload (przesłana ręcznie przez użytkownika).