Bölüm 16 POST

putRecordingTextTrack – Metin İzi Yükle

putRecordingTextTrack uç noktası, bir kayıt için altyazı veya açıklama dosyaları yüklemenize olanak tanır. Desteklenen biçimler SRT, SSA/ASS ve WebVTT'dir. Yüklenen tüm dosyalar dahili olarak WebVTT biçimine dönüştürülür. Yanıt JSON biçiminde döndürülür.

Bu uç nokta yalnızca POST isteklerini destekler. GET istekleri kabul edilmez.

Uç Nokta

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

Altyazı dosyası multipart/form-data gövdesinde POST olarak gönderilmelidir. Checksum yalnızca URL sorgu parametrelerinden hesaplanır — POST gövdesi checksum hesaplamasına dahil edilmez.

URL Parametreleri (Sorgu Dizgesi)

Parametre Tür Gerekli Varsayılan Açıklama
recordID String Evet — Tek bir kayıt kimliği. Diğer uç noktaların aksine, bu parametre virgülle ayrılmış bir liste kabul etmez — yalnızca bir kayıt kimliğine izin verilir.
kind Enum Evet — Metin parçasının türü. Kabul edilen değerler altiesazilar veya aciklamalar değerleridir.
lang String Evet — RFC 5646 ile uyumlu bir dil etiketi (ör. de-DE, en-US).
label String Hayır lang değerinden otomatik algılanır Parça için insan tarafından okunabilir bir görünen ad (ör. "Almanca"). Belirtilmezse, dil adı lang değerinden otomatik olarak türetilir.

POST Gövdesi (multipart/form-data)

Parametre Tür Gerekli Varsayılan Açıklama
file Binary Evet — Yüklenecek altyazı dosyası. Desteklenen biçimler: SRT (application/x-subrip), SSA/ASS ve WebVTT (text/vtt). Dosya eksikse veya boşsa API bir FAILED yanıtı döndürür.

Örnek İstek

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"

Örnek Yanıt

Başarılı bir çağrı aşağıdaki JSON değerini döndürür: 

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

Hata Yanıtları

messageKey Açıklama
paramError Gerekli bir parametre eksik (checksum, recordID, kind veya lang). Not: resmî belgelerde bu yanlışlıkla missingParameter olarak listelenmiştir.
noRecordings Belirtilen kayıt kimliği bulunamadı.
invalidKind kind değeri geçersiz. altiesazilar veya aciklamalar olmalıdır.
invalidLang Dil etiketi biçimi geçersiz. RFC 5646 ile uyumlu olmalıdır.
empty_uploaded_text_track Yüklenen dosya boştu veya isteğe hiç dosya eklenmemişti.

Önemli Davranış

Metin parçası işleme süreci eşzamansızdır. Başarılı bir yüklemeden sonra, parçanın kayıt oynatımında kullanılabilir hâle gelmesi birkaç dakika sürebilir.

Aynı kind ve dil ile bir parça zaten varsa, yeni dosyayla üzerine yazılır.

Boş bir dosya yüklemek veya dosya olmadan istek göndermek mevcut bir parçayı silmez. API bunun yerine bir FAILED yanıtı döndürür.

Yüklenen tüm altyazı biçimleri (SRT, SSA/ASS) oynatma için otomatik olarak WebVTT biçimine dönüştürülür.

bbbserver.de Notlar

bbbserver.de: Bu uç nokta bbbserver.de platformunda mevcut değildir. API aracılığıyla altyazı yükleme desteklenmez.

İpuçları

Yüklediğiniz metin parçasının işlendiğini ve uygulamanızda bağlantı vermeden önce oynatım için kullanılabilir olduğunu doğrulamak için getRecordingTextTracks uç noktasını kullanın.

  • WebVTT önerilen biçimdir; çünkü dönüştürme gerektirmez ve tarayıcılar tarafından yerel olarak desteklenir.
  • Birden fazla dil parçası yüklerken, mevcut parçaların yanlışlıkla üzerine yazılmasını önlemek için farklı RFC 5646 dil etiketleri kullanın.
  • İzleyicilerin oynatma dil seçicisinde doğru parçayı belirlemesine yardımcı olmak için açıklayıcı bir label parametresi ayarlayın.
  • Checksum'un yalnızca URL sorgu parametrelerinden hesaplandığını unutmayın — dosya içeriğini checksum'a dahil etmeyin.

Sıkça Sorulan Sorular

BigBlueButton, SRT (SubRip), SSA/ASS (SubStation Alpha) ve WebVTT (Web Video Text Tracks) dosyalarını kabul eder. Tüm biçimler oynatma için dahili olarak WebVTT biçimine dönüştürülür. WebVTT dışındaki desteklenen biçimler kaynak koddan türetilmiştir ve resmî belgelerde açıkça listelenmemiştir.

Evet. Farklı diller için parça yüklemek üzere putRecordingTextTrack uç noktasını farklı lang değerleriyle birden çok kez çağırabilirsiniz. kind ve lang değerlerinin her birleşimi ayrı bir parça olarak saklanır.

Aynı kind ve lang birleşimine sahip mevcut parça yeni dosyayla üzerine yazılır. Önceki parçaların sürümleme veya yedeklemesi yoktur.

Hayır. Dosya olmadan veya boş dosyayla istek göndermek mevcut bir parçayı silmez. API yalnızca FAILED hata anahtarıyla bir empty_uploaded_text_track yanıtı döndürür. Metin parçalarını silmek için özel bir uç nokta yoktur.

İşleme eşzamansızdır. Başarılı bir yüklemeden sonra, metin parçasının kayıt oynatımında kullanılabilir hâle gelmesi genellikle birkaç dakika sürer. Kesin süre sunucu yüküne ve dosya boyutuna bağlıdır.

Sağlama toplamı yalnızca URL sorgu parametrelerinden hesaplanır. Altyazı dosyasını içeren POST gövdesi sağlama toplamı hesaplamasının bir parçası değildir. Bu, tasarım gereğidir ve BigBlueButton'nin çok parçalı POST isteklerini ele alma biçimiyle tutarlıdır.