0.7.0 (01-11-2026)

See the upgrade notes for what to change in code using the library.

Changes that may need updates to the code using the library

• Requires Python 3.10 or later, as Python 3.7, 3.8 and 3.9 are end-of-life (#136, #148)
• Strict parsing raises 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)
• Writing WebVTT raises 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)
• Removed 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)
• SRT cues without an index are read, as most SRT players do, instead of skipped (#142, #158)
• Styles after the first cue and blocks where 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)
• Setting 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)

Changes

• Added reading binary file-like objects with 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)
• Added setting Caption.text to a sequence of lines, as when creating a Caption (#162, #198)
• Added WebVTTError as the base class of the errors, and made MalformedFileError and MalformedCaptionError subclasses of ValueError (#146, #155)
• Added 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)
• Added the 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)
• Added the 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)
• Added segmenting a 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)
• Added the --version option of the CLI, and reading the captions from standard input with - as the PATH of the shift and sync commands (#169, #207)
• Added running the CLI with python -m webvtt (#210)
• Fixed reading SRT files with whitespace around the first cue index, thanks to @youdie006 (#130)
• Fixed WebVTT styles ignored when STYLE is followed by whitespace (#133)
• Fixed WebVTT regions ignored after header text with --> (#135)
• Fixed reading SRT and SBV files that start with blank lines or with a cue without text, which raised MalformedFileError (#142, #158)
• Fixed non-ASCII digits read as numbers in timestamps and SRT cue indexes, thanks to @emirmrkaljevic (#140, #147)
• Fixed 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)
• Fixed comparing a Timestamp with other types raising AttributeError: == returns False and ordering comparisons raise TypeError (#137, #150)
• Fixed the SRT output not ending with a line break (#138, #151)
• Fixed SRT output of captions without text, such as text of blank lines, which were written as cues without text that are lost when read back: they are left out and the others numbered consecutively (#166, #202)
• Fixed save leaving out the Byte Order Mark when the encoding is written differently, such as UTF-8 or utf8 (#160, #196)
• Fixed HLS segments repeating a cue that ends on a segment boundary, and the playlist having no segments for captions without cues, thanks to @radixun (#145, #149)
• Fixed segmenting raising IndexError for a cue that ends before it starts, which is now written to the segment it starts in (#152, #154)
• Fixed the read_buffer deprecation warning pointing at the library instead of the code calling it (#139, #153)