NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI
PyPI, #2702 most downloaded on PyPI
WebVTT reader, writer and segmenter
Latest stable
0.8.0
Last release 14 days ago
08 Nov 2026
Ships unpredictably
gaps range from 2 weeks to 3.5 years
Nearly every release is documented
notes for 18 of 18 stable releases
Nothing withdrawn
no release was ever pulled
11 years old
18 releases · first in 2016
Drag across the ruler to compare, or tap a release to open it.
See the upgrade notes for what to change in code using the library.
See the upgrade notes for what to change in code using the library.
total_length returns a float with the milliseconds, from the earliest start to the latest end of the captions, instead of whole seconds from the first caption to the last one, which was wrong for captions out of order, thanks to @emirmrkaljevic (#188, #193)Style and WebVTT are equal when they have the same content, instead of only to themselves, and cannot be used in sets or as dictionary keys, as Caption and Region (#174)save_as_srt keeps the Byte Order Mark of the file that was read and saves in its encoding, as save does, instead of saving in UTF-8 without it, and from_srt and from_sbv keep the Byte Order Mark as read does, so save also keeps it for SRT and SBV files read with one (#177)font tags with a colour are read as c tags with a class named from the colour, as in <c.color-ff0000>, and a STYLE block with the colours, the inverse of save_as_srt(keep_formatting=True), and other font tags are removed, keeping their text. {\anN} tags are read as the line and align cue settings and removed from the text, and save_as_srt and write(format='srt') write them back from those settings (#178).srt and .sbv extensions as SRT and SBV, so a WebVTT file with one of them needs --format vtt (#181)errors argument to read, from_srt, from_sbv and from_buffer, passed to the decoder ('strict' by default), to read files with bytes that are not valid in their encoding, thanks to @emirmrkaljevic (#180, #212)line 42: Invalid cue block [...] (#170)parse_issues attribute to WebVTT, with the ParseIssue of each block that was skipped when reading WebVTT, SRT or SBV (#170)overlapping argument to iter_slice to also return the captions with part of them in the range, and clip to return copies of them trimmed to the range (#172)pyproject.toml, and make build builds with python -m build without regenerating the man page (#184)webvtt.__author__ and webvtt.__author_email__, as the author is in the package metadata (#184)start_in_milliseconds, end_in_milliseconds and duration to Caption, thanks to @emirmrkaljevic (#188, #193)Caption, its start and end, iter_slice and the start of shift can be Timestamp objects, numbers of seconds or timedelta objects, as with sync, besides timestamp strings (#171)sync raises ValueError for a Timestamp before zero, as it does for the other times, and TypeError for one with fields that are not integers, instead of moving the captions to timestamps that cannot be written (#171)Caption.copy() and WebVTT.copy(), which return copies that share nothing with the original, and a repr for Style (#174)drop_before_zero argument of shift and the --drop-before-zero option of the shift command of the CLI, which remove the captions that end at or before zero after shifting them, instead of keeping them at 00:00:00.000 --> 00:00:00.000 (#173)Caption.voices, the voices of every voice span in the text, in order, as Caption.voice only reads a voice span at the start of the caption (#175)WebVTT.sort(), which sorts the captions by start time, and WebVTT.validate(), which returns a ValidationIssue for each caption out of order, not ending after it starts, in a region that is not defined, overlapping an earlier one or without text, and the validate command of the CLI, which also reports the blocks skipped when reading (#176)format argument of from_string to read SRT and SBV from a string, to_string to get the captions as a string in any format, writing SBV with write(format='sbv') and save_as_sbv, and the add_bom argument of save_as_srt, as in save (#177)keep_formatting reads the colours of ::cue() selectors with a tag name, more than one class or both, as in ::cue(c.loud), ::cue(.loud.red) or ::cue(b), and of class names with any character that WebVTT allows, written with CSS escapes, as in ::cue(.c\+1), and the rule with the most classes, then with a tag name, applies before a later one, as in CSS (#179)--format option, with the new --encoding option for files in another encoding, and shift and sync write them in the same format, or in the format of the extension of the output. Added the convert command, which converts between WebVTT, SRT and SBV, as in webvtt convert captions.srt -o captions.vtt (#181)mypy --strict, the path arguments of read, from_srt, from_sbv, save, save_as_srt, save_as_sbv and segment are annotated as str | os.PathLike, as pathlib.Path objects already worked, and indexing WebVTT with a slice is typed as a list of captions (#183)--start option of the shift command of the CLI accepts a number of seconds, as in webvtt shift captions.vtt 3 --start 47, besides a timestamp, and a number of seconds after the largest timestamp is reported as an invalid --start or --point argument (#217)make release and make release_test, which are removed. CI checks the code style and types and builds the documentation, with nitpicky references and make docs, apart from the tests, and Dependabot updates the actions, pinned by commit, and the documentation requirements (#185)Your coding agent can read these notes before it upgrades. Set up the MCP server →
Fixed the read_buffer deprecation warning pointing at the library instead of the code calling it ( #139 , #153 )
See the upgrade notes for what to change in code using the library.
MalformedCaptionError for cues whose end time is not after the start time, for blocks that are not a cue, comment, style or region, such as text without cue timings, for comments where NOTE is not followed by a space, a tab or a line break, or with -->, and for styles after the first cue (#97, #133)ValueError for --> in a comment or in the header text, which WebVTT does not allow (#134, #135)NOTE blocks with --> are not read as comments, and header text with --> is read as empty, as WebVTT does, so the file can be saved again (#134, #135)Caption.CUE_TEXT_TAGS, which is no longer used (#139, #153)save, save_as_srt and the -o option of the CLI write a path with an extension as given, instead of adding .vtt or .srt to it, so captions.webvtt is no longer saved as captions.webvtt.vtt (#144, #156)save and save_as_srt without a path or with a folder, and the -o option of the CLI with a folder, keep the extension of the file when it is already of the format, so a file read from captions.webvtt is saved to it instead of captions.vtt (#159, #195)from_buffer raises TypeError for a string or bytes, instead of MalformedFileError: use from_string to read a string, or io.BytesIO to read bytes (#143, #157)NOTE is not followed by a space, a tab or a line break, such as NOTEBOOK, are ignored, as WebVTT does, and strict parsing raises MalformedFileError when WEBVTT is not followed by a space, a tab or the end of the first line, such as WEBVTTX (#141, #194)save raises ValueError for add_bom=True with an encoding without a Byte Order Mark, such as latin-1, and for add_bom=False with utf-8-sig, utf-16 or utf-32, which always write one, instead of ignoring add_bom (#160, #196)save_as_srt saves captions read with from_srt or from_buffer in SRT format and an encoding in the same encoding, instead of UTF-8, and encoding=None saves in UTF-8 instead of the encoding of the locale (#161, #197)Caption.text to a value that is not a string or a sequence of lines raises TypeError instead of AttributeError, and Caption raises it for lines that are not strings instead of accepting them (#162, #198)WebVTT keeps empty lists given as arguments, as it does with other lists, instead of replacing them with new ones, and Style copies a list of lines, as Caption does, instead of keeping it (#163, #199)segment raises FileExistsError, and the segment command of the CLI exits with an error, when the output folder has the playlist or segments of an earlier run, instead of writing over them and keeping the segments the new playlist does not have: use overwrite=True or --overwrite to replace them (#164, #200)from_buffer raises ValueError for strict=True with the srt or sbv format, which have no strict parsing, instead of ignoring it (#167, #203)from_buffer, such as files opened in 'rb' mode, with the encoding of their Byte Order Mark, kept when saving, or the new encoding argument (#143, #157)Caption.text to a sequence of lines, as when creating a Caption (#162, #198)WebVTTError as the base class of the errors, and made MalformedFileError and MalformedCaptionError subclasses of ValueError (#146, #155)MalformedRegionError, a subclass of MalformedCaptionError, raised for region settings that are not valid and, with strict parsing, for regions after the first cue (#168, #204)overwrite argument of segment and the --overwrite option of the CLI, which replace the files of an earlier segmentation and delete its segments that the new playlist does not have (#164, #200)duration argument of segment, slice_segments and write_manifest, and the --duration option of the CLI, for the length of the media, so the HLS playlist covers all of it and its last segment ends with it instead of lasting the whole target duration (#165, #201)WebVTT instance with segment, such as captions edited or read from another format, without saving them first, and reading the captions from standard input with - as the PATH of the segment command (#205, #209)--version option of the CLI, and reading the captions from standard input with - as the PATH of the shift and sync commands (#169, #207)python -m webvtt (#210)STYLE is followed by whitespace (#133)--> (#135)MalformedFileError (#142, #158)from_buffer keeping a name that is not a path as the file to save to, such as <stdin> or the file descriptor of a file opened from one, which save wrote to <stdin>.vtt or failed on with TypeError (#206, #208)Timestamp with other types raising AttributeError: == returns False and ordering comparisons raise TypeError (#137, #150)save leaving out the Byte Order Mark when the encoding is written differently, such as UTF-8 or utf8 (#160, #196)IndexError for a cue that ends before it starts, which is now written to the segment it starts in (#152, #154)read_buffer deprecation warning pointing at the library instead of the code calling it (#139, #153)Deprecated the file argument of WebVTT in favor of the file attribute
This is the last release supporting Python 3.7, 3.8 and 3.9.
WebVTT takes keyword arguments only and does not read files, so WebVTT('captions.vtt') raises TypeError: use webvtt.read to read captions from a file (#123)ValueError for text that could not be read back, such as an empty line or --> in the text of a caption (#122)MalformedCaptionError, unless strict=True (#93, #99)9999999999:59:59.999: cues past it are skipped when reading, and shift, sync and change_framerate raise ValueError instead of moving captions past it (#119)0:0:7.5, as in Microsoft Teams transcripts, thanks to @apetresc (#45, #99)Extended from_buffer support to allow BytesIO and also other format conversions
@lilaboc <https://github.com/lilaboc>_ (#56)Deprecated read_buffer in favor of from_buffer
Add capability to get WebVTT formatted content without an output file, thanks to @DawoudSheraz
Fix issue reading buffer
Allow parsing empty SBV captions, thanks to @ishunyu
Renamed and reorganized few of the modules
import webvtt
webvtt.read('captions.vtt') # this will return a WebVTT instance
Support for saving cue identifiers
The main goal of this release is a refactor of the WebVTT parser to be able to parse easier and give support to new features of the format.
The main goal of this release is a refactor of the WebVTT parser to be able to parse easier and give support to new features of the format.
New features:
Other:
The text for the caption is now returned clean (tags removed). The cue text could contain tags like:
The text for the caption is now returned clean (tags removed). The cue text could contain tags like:
Also a new attribute is available on captions to retrieve the text without cleaning tags: raw_text
The text for the caption is now returned clean (tags removed). The cue text could contain tags like: * timestamp tags: <00:19.000> * class tags: <c.classname>text</c> * and others... Important: It currently removes any tag present in the cue text. For example <b> would be removed.
Also a new attribute is available on captions to retrieve the text without cleaning tags: raw_text
The goal of this release if to allow the WebVTT parser to be able to read caption files that contain metadata headers that extend to more than one lin
The goal of this release if to allow the WebVTT parser to be able to read caption files that contain metadata headers that extend to more than one line.
Made hours in WebVTT parser optional as per specs.
Added support for YouTube SBV captions.
New features:
Other:
Refactor of the main module and parsers.
This module is released with the following initial features:
This module is released with the following initial features:
One column per quarter.