Captions

注意:YouTube 已於 2024 年 3 月 13 日宣布,將淘汰 captions.insertcaptions.update API 端點的 sync 參數。YouTube 工作室仍會提供字幕自動同步功能。詳情請參閱「API 修訂版本記錄」。

caption 資源代表 YouTube 字幕軌。字幕軌僅與一部 YouTube 影片相關聯。

方法

這個 API 支援下列 captions 資源方法:

list
擷取與指定影片相關聯的字幕軌清單。請注意,API 回應不包含實際字幕,且 captions.download 方法能夠擷取字幕軌。立即試用
插入
上傳字幕軌。
更新
更新字幕軌。更新字幕軌時,您可以變更曲目的草稿狀態和/或上傳該曲目的新字幕檔。
刪除
刪除指定的字幕軌。立即試用
下載
下載字幕軌。除非要求指定 tfmt 參數值和原文值,否則字幕軌會以原始格式傳回 (除非要求指定 tlang 參數值)。

資源表示法

下列 JSON 結構顯示 captions 資源的格式:

{
  "kind": "youtube#caption",
  "etag": etag,
  "id": string,
  "snippet": {
    "videoId": string,
    "lastUpdated": datetime,
    "trackKind": string,
    "language": string,
    "name": string,
    "audioTrackType": string,
    "isCC": boolean,
    "isLarge": boolean,
    "isEasyReader": boolean,
    "isDraft": boolean,
    "isAutoSynced": boolean,
    "status": string,
    "failureReason": string
  }
}

屬性

下表定義了這項資源中顯示的屬性:

屬性
kind string
識別 API 資源的類型。值為 youtube#caption
etag etag
這項資源的 Etag。
id string
YouTube 用來識別字幕軌的專屬 ID。
snippet object
snippet 物件包含字幕的基本詳細資料。
snippet.videoId string
YouTube 用來識別與字幕軌相關影片的專屬 ID。
snippet.lastUpdated datetime
字幕軌上次更新的日期和時間。這個值是以 ISO 8601 格式指定。
snippet.trackKind string
字幕軌的類型。

這個屬性的有效值如下:
  • ASR:使用自動語音辨識功能產生的字幕軌。
  • forced:在播放器未選取其他音軌時播放的字幕軌。舉例來說,如果影片中出現外星人使用外星人交談,可能會加上強製字幕軌,只顯示外星語言的字幕。
  • standard:一般字幕軌。這是預設值。
snippet.language string
字幕軌的語言。屬性值為 BCP-47 語言標記。
snippet.name string
字幕軌的名稱。標題會在播放過程中向使用者顯示。名稱長度上限為 150 個半形字元。
snippet.audioTrackType string
與字幕軌相關聯的音軌類型。

這個屬性的有效值如下:
  • commentary:字幕軌對應的替代音軌,且包含評論,例如目錄解說。
  • descriptive:字幕軌對應的另一個音軌,包含其他描述性音訊。
  • primary:字幕軌對應至影片的主要音軌,也就是通常與影片相關聯的音軌。
  • unknown:此為預設值。
snippet.isCC boolean
指出曲目是否含有失聰和聽障人士適用的隱藏式輔助字幕。預設值為 false
snippet.isLarge boolean
指出字幕軌是否使用較大的文字來處理視障人士。預設值為 false
snippet.isEasyReader boolean
指出字幕軌格式是否適合「容易理解」,也就是為語言學習者提供三年級。預設值為 false
snippet.isDraft boolean
指出字幕軌是否為草稿。如果值為 true,就表示曲目不會公開顯示。預設值為 false
snippet.isAutoSynced boolean
指出 YouTube 是否已經將字幕軌與影片中的音軌同步。如果系統在上傳字幕軌時明確要求同步處理,這個值將是 true。舉例來說,呼叫 captions.insertcaptions.update 方法時,您可以將 sync 參數設為 true,指示 YouTube 將上傳的曲目同步到影片。如果值為 false,YouTube 就會使用已上傳字幕軌中的時間碼來判斷顯示字幕的時機。
snippet.status string
字幕軌的狀態。

這個屬性的有效值如下:
  • failed
  • serving
  • syncing
snippet.failureReason string
YouTube 無法處理字幕軌的原因。只有在 state 屬性值為 failed 時,才會顯示此屬性。

此屬性的有效值如下:
  • processingFailed:YouTube 無法處理已上傳的字幕軌。
  • unknownFormat:系統無法辨識字幕軌格式。
  • unsupportedFormat:不支援字幕軌格式。