Command line

Synopsis

webvtt segment PATH -o OUTPUT [-d NUMBER] [-m NUMBER] [--duration TIME]
               [--overwrite]
webvtt shift PATH OFFSET [-o OUTPUT] [-s TIMESTAMP]
webvtt sync PATH (-p FROM TO -p FROM TO ... | --fps FROM TO) [-o OUTPUT]
webvtt -h
webvtt --version

Description

webvtt segments a WebVTT caption file for HTTP Live Streaming (HLS) and shifts or synchronizes the timestamps of its captions.

segment splits the captions in PATH into segments of a target duration. Each segment is written to OUTPUT as fileSequenceN.webvtt, where N is the segment index starting at 0, along with a playlist named prog_index.m3u8 that lists all the segments. An OUTPUT with the playlist or segments of an earlier run is an error, unless --overwrite is given.

A caption whose time span crosses a segment boundary is included in every segment it overlaps, so players display it regardless of which segment they load. Every segment also has the STYLE and REGION blocks of PATH, which its captions use, and the captions keep their identifiers and cue settings. Comments are not written to the segments.

Every segment starts with an X-TIMESTAMP-MAP header that maps the local caption time 00:00:00.000 to an MPEG-TS presentation timestamp, so the captions are kept in sync with the video stream.

shift moves the captions in PATH earlier or later by OFFSET seconds. The offset is rounded to the nearest millisecond as written, with halves rounded away from zero, so 1.0005 is 1001 milliseconds. A timestamp that would fall before zero is set to 00:00:00.000, so a caption moved entirely before the start is kept with 00:00:00.000 --> 00:00:00.000 timings. The shifted captions are written to standard output in UTF-8, or to OUTPUT when given.

sync fixes captions that drift further out of sync along the video. With -p, each point moves the time FROM in the captions to TO; times between two points are moved along the line between them, and times before the first or after the last point along the line of the outermost points. With --fps, the timing is changed from one frame rate to another. Times are rounded and set to zero like with shift, and the output is written the same way.

The commands can also be run as python -m webvtt, as in python -m webvtt shift captions.vtt 2.

segment, shift and sync read the captions from standard input when PATH is -, decoded as UTF-8 as WebVTT requires, so they can be used in pipes. A file named - can be read as ./-.

Commands

segment: Segment the WebVTT file at PATH.
shift: Shift the timestamps of the WebVTT file at PATH.
sync: Synchronize the timestamps of the WebVTT file at PATH.

Options

-h, --help: Show the help message and exit. Also available for each command, as in webvtt shift -h.
--version: Show the version of webvtt-py and exit.

Segment options

-o OUTPUT, --output OUTPUT: Directory where the segments and playlist are written. It is created if it does not exist. Required.
-d NUMBER, --target-duration NUMBER: Target duration of each segment in seconds, a whole number above zero. Also used for the #EXT-X-TARGETDURATION value of the playlist and the #EXTINF of its segments, except the last with --duration. Default: 10.
-m NUMBER, --mpegts NUMBER: MPEG-TS value written to the X-TIMESTAMP-MAP header of each segment, a whole number from 0 to 8589934591, as MPEG-TS timestamps have 33 bits. Default: 900000 (10 seconds at the 90 kHz MPEG-TS clock).
--duration TIME: Length of the media, as a timestamp such as 01:25.500 or a number of seconds such as 85.5. The playlist then covers all the media, with empty segments after the last caption, and the #EXTINF of its last segment ends with the media. A caption starting at or after it is an error. Without it, the playlist ends with the segment of the last caption, and every segment lasts the target duration.
--overwrite: Replace the playlist and segments of an earlier run in OUTPUT, and delete the segments of that run that the new playlist does not have. Other files in OUTPUT are left alone. Without it, an OUTPUT with a prog_index.m3u8 or fileSequenceN.webvtt file is an error.

Shift options

OFFSET: Number of seconds to shift the captions by, such as 2 or 0.25. Negative values move the captions earlier, as in -1.5. Required.
-o OUTPUT, --output OUTPUT: File where the shifted captions are written, keeping the encoding and Byte Order Mark of the input file. It can be the input file itself to shift it in place. A .vtt extension is added if it has no extension, and if it is a directory the file is written there with the input file name, which is an error when reading standard input. Default: standard output.
-s TIMESTAMP, --start TIMESTAMP: Only shift the captions starting at or after TIMESTAMP, in [hh:]mm:ss.mmm format. Default: shift all the captions.

Sync options

-p FROM TO, --point FROM TO: Move the time FROM in the captions to TO. Each time is a timestamp in [hh:]mm:ss.mmm format or a number of seconds. Give it two or more times, in any order. Two points cannot have the same FROM, and the TO times must be in the same order as the FROM times.
--fps FROM TO: Change the timing from the frame rate FROM the captions are timed for to the frame rate TO of the video, such as 25 23.976. A frame rate can also be a ratio, such as 24000/1001 for the exact NTSC rate. Times are multiplied by FROM / TO. Cannot be used with -p.
-o OUTPUT, --output OUTPUT: File where the synchronized captions are written, as with shift. Default: standard output.

Exit status

0

The command completed successfully.

1

The input could not be read or is not a valid WebVTT file, the captions could not be moved as asked, or the output could not be written. For segment, it is also an error when the output directory has the files of an earlier run without --overwrite, or when a caption starts at or after --duration. An error message is printed to standard error, for example:

webvtt: error: captions.vtt: not a valid WebVTT file

2

Invalid command line arguments, such as an offset that is not a number, an invalid --start timestamp or sync points that cannot be used.

Examples

Given captions.vtt:

WEBVTT

00:00:01.000 --> 00:00:04.000
Hello and welcome.

00:00:06.000 --> 00:00:12.000
This caption spans two segments.

00:00:14.500 --> 00:00:18.000
Thanks for watching!

Segment it into 10-second segments:

$ webvtt segment captions.vtt --output out
$ ls out
fileSequence0.webvtt  fileSequence1.webvtt  prog_index.m3u8

out/prog_index.m3u8:

#EXTM3U
#EXT-X-TARGETDURATION:10
#EXT-X-VERSION:3
#EXT-X-PLAYLIST-TYPE:VOD
#EXTINF:10.00000,
fileSequence0.webvtt
#EXTINF:10.00000,
fileSequence1.webvtt
#EXT-X-ENDLIST

out/fileSequence0.webvtt:

WEBVTT
X-TIMESTAMP-MAP=MPEGTS:900000,LOCAL:00:00:00.000

00:00:01.000 --> 00:00:04.000
Hello and welcome.

00:00:06.000 --> 00:00:12.000
This caption spans two segments.

out/fileSequence1.webvtt:

WEBVTT
X-TIMESTAMP-MAP=MPEGTS:900000,LOCAL:00:00:00.000

00:00:06.000 --> 00:00:12.000
This caption spans two segments.

00:00:14.500 --> 00:00:18.000
Thanks for watching!

Segment it again into out, with 6-second segments and a different MPEG-TS value, replacing the earlier segments:

$ webvtt segment captions.vtt -o out
webvtt: error: out: has the files of an earlier segmentation, such as fileSequence0.webvtt; use --overwrite to replace them
$ webvtt segment captions.vtt -o out -d 6 -m 0 --overwrite

Show the captions 1.5 seconds earlier:

$ webvtt shift captions.vtt -1.5
WEBVTT

00:00:00.000 --> 00:00:02.500
Hello and welcome.

00:00:04.500 --> 00:00:10.500
This caption spans two segments.

00:00:13.000 --> 00:00:16.500
Thanks for watching!

Show the last caption 2 seconds later, updating the file in place:

$ webvtt shift captions.vtt 2 --start 00:14.500 -o captions.vtt

Keep the first caption in place and move the last one from 00:14.500 to 00:15.850, synchronizing the captions in between:

$ webvtt sync captions.vtt -p 00:01.000 00:01.000 -p 00:14.500 00:15.850
WEBVTT

00:00:01.000 --> 00:00:04.300
Hello and welcome.

00:00:06.500 --> 00:00:13.100
This caption spans two segments.

00:00:15.850 --> 00:00:19.700
Thanks for watching!

Fix captions timed for a 25 fps video played with a 23.976 fps one, updating the file in place:

$ webvtt sync captions.vtt --fps 25 23.976 -o captions.vtt

Shift and synchronize the captions in a pipe, reading them from standard input:

$ webvtt shift captions.vtt 2 | webvtt sync - --fps 25 23.976 > fixed.vtt

Synchronize the captions and segment them, without a file in between:

$ webvtt sync captions.vtt --fps 25 23.976 | webvtt segment - -o out