Captions

注意事項：YouTube 於 2022 年 8 月 5 日宣布變更了字幕 ID 的產生方式，這項異動也會為所有字幕軌指派新的字幕 ID。詳情請參閱 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` 字幕軌的名稱。名稱應該要在播放時向使用者顯示。
`snippet.audioTrackType`	`string` 與字幕軌相關的音軌類型。此屬性的有效值如下： `commentary` - 字幕軌對應了包含註解的替代音軌，例如目錄評論。 `descriptive`：字幕軌是替代音軌，其中包含其他描述性音訊。 `primary`：字幕軌對應到影片的主要音軌，也就是一般與影片相關的音軌。 `unknown`：這是預設值。
`snippet.isCC`	`boolean` 指明這首曲目是否含有失聰和聽障人士的字幕。預設值為 `false`。
`snippet.isLarge`	`boolean` 指出字幕軌是否使用視障者適用的大型文字。預設值為 `false`。
`snippet.isEasyReader`	`boolean` 指示字幕軌採用的格式為「easy Reader」，也就是語言學習的三年級。預設值為 `false`。
`snippet.isDraft`	`boolean` 指出字幕軌是否為草稿。如果該值為 `true`，則測試群組不會公開顯示。預設值為 `false`。
`snippet.isAutoSynced`	`boolean` 指明 YouTube 是否將字幕軌與影片音軌同步。如果在上傳字幕軌時明確要求同步，值為 `true`。例如，呼叫 `captions.insert` 或 `captions.update` 方法時，您可以將 `sync` 參數設為 `true`，指示 YouTube 將上傳的音軌同步至影片。如果值為 `false`，YouTube 會根據上傳字幕中的時間碼決定顯示字幕的時機。
`snippet.status`	`string` 字幕軌狀態。此屬性的有效值如下： `failed` `serving` `syncing`
`snippet.failureReason`	`string` YouTube 無法處理字幕軌的原因。只有在 `state` 屬性的值為 `failed` 時，系統才會顯示這項屬性。此屬性的有效值如下： `processingFailed` - YouTube 無法處理已上傳的字幕軌。 `unknownFormat` - 無法辨識字幕軌的格式。 `unsupportedFormat` - 系統不支援字幕軌格式。