yb.youtube.captions

Caption (subtitle) tracks on YouTube videos: list, insert, update, upsert.

Lets you attach an SRT/VTT track at upload time and manage tracks on already-published videos — e.g. replace a hand-edited subtitle file, or add a track in a new language. upsert_caption is the convenient default: it updates an existing same-language track if present, else inserts a new one.

Note

YouTube auto-generates ASR tracks of its own (trackKind="asr"); these helpers operate on uploaded "standard" tracks and ignore ASR.

Functions

delete_caption(caption_id, *[, service])	Delete a caption track (captions.delete).
download_caption(caption_id, *[, tfmt, service])	Download a caption track's content (captions.download), default SRT.
insert_caption(video_id, path, *, language)	Insert a new caption track (captions.insert).
list_captions(video_id, *[, service])	List caption tracks on a video (each item's snippet has language/name/trackKind/status).
update_caption(caption_id, path, *[, ...])	Replace the content of an existing caption track (captions.update).
upsert_caption(video_id, track, *[, ...])	Insert a caption track, or update the existing same-language one.

Classes

CaptionTrack(path, language[, name, is_draft])

A caption track to attach to a video.

class yb.youtube.captions.CaptionTrack(path, language, name='', is_draft=False)

Bases: object

A caption track to attach to a video.

path

Path to an .srt (or .vtt) file.

language

BCP-47 language code, e.g. "en" or "fr".

name

Track name shown in the YouTube UI (e.g. "English").

is_draft

When True, uploaded but not published to viewers.

yb.youtube.captions.delete_caption(caption_id, *, service=None, **cred_kwargs)

Delete a caption track (captions.delete).

Return type:

None

yb.youtube.captions.download_caption(caption_id, *, tfmt='srt', service=None, **cred_kwargs)

Download a caption track’s content (captions.download), default SRT.

Return type:

bytes

yb.youtube.captions.insert_caption(video_id, path, *, language, name='', is_draft=False, service=None, **cred_kwargs)

Insert a new caption track (captions.insert).

Return type:

dict

yb.youtube.captions.list_captions(video_id, *, service=None, **cred_kwargs)

List caption tracks on a video (each item’s snippet has language/name/trackKind/status).

Return type:

list[dict]

yb.youtube.captions.update_caption(caption_id, path, *, is_draft=None, service=None, **cred_kwargs)

Replace the content of an existing caption track (captions.update).

Return type:

dict

yb.youtube.captions.upsert_caption(video_id, track, *, language=None, name='', is_draft=False, replace=True, service=None, **cred_kwargs)

Insert a caption track, or update the existing same-language one.

Parameters:

• video_id (str) – Target video.

• track (CaptionTrack | str | Path) – A CaptionTrack, or a path (then language required).

• replace (bool) – When an uploaded track in the same language exists, update it (True, default) rather than inserting a duplicate.

Return type:

dict

Returns:

The inserted/updated caption resource.