Captions

Примечание. 13 марта 2024 г. YouTube объявил о прекращении поддержки параметра sync для конечных точек API captions.insert и captions.update. Автоматическая синхронизация субтитров по-прежнему доступна в Творческой студии YouTube. Подробная информация приведена в истории изменений API.

Ресурс caption представляет собой дорожку субтитров YouTube. Одна дорожка субтитров связана только с одним видео на YouTube.

Методы

API поддерживает следующие методы для ресурсов captions:

list
Получить список дорожек субтитров, связанных с определенным видео. Обратите внимание, что ответ API не содержит субтитров, а метод captions.download позволяет получить дорожку субтитров. Попробовать
insert
Загрузите дорожку субтитров. Перейти
update
Изменение дорожки субтитров. При обновлении дорожки субтитров можно изменить ее статус черновика, загрузить новый файл субтитров или сделать и то, и другое. Попробовать
download
Скачать дорожку субтитров. Дорожка субтитров возвращается в исходном формате, если в запросе не указано значение параметра tfmt, и на исходном языке, если в запросе не указано значение параметра tlang. Попробовать
delete
Удалить указанную дорожку субтитров. Перейти

Представление ресурса

Ниже показана структура 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 использует для уникальной идентификации дорожки субтитров.
snippet object
Объект snippet содержит основные сведения о субтитрах.
snippet.videoId string
Идентификатор, который YouTube использует для уникальной идентификации видео, связанного с дорожкой субтитров.
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.insert или captions.update можно задать параметру sync значение true, чтобы YouTube синхронизировал загруженную дорожку с видео. Если указано значение false, YouTube будет использовать временные коды из загруженной дорожки субтитров, чтобы определять, когда показывать субтитры.
snippet.status string
Статус дорожки субтитров.

Допустимые значения этого свойства:
  • failed
  • serving
  • syncing
snippet.failureReason string
Причина, по которой YouTube не удалось обработать дорожку субтитров. Это свойство присутствует, только если значение свойства state – failed.

Допустимые значения для этого свойства:
  • processingFailed – YouTube не удалось обработать загруженную дорожку субтитров.
  • unknownFormat – формат дорожки субтитров не распознан.
  • unsupportedFormat – формат дорожки субтитров не поддерживается.