Registry / serialization / webvtt-py

webvtt-py

JSON →
library0.5.1pypypi✓ verified 24d ago

webvtt-py is a Python library (current version 0.5.1) for reading, writing, converting, and segmenting WebVTT caption files. It is actively maintained with regular releases, often several times a year, addressing new features, bug fixes, and Python compatibility.

pip install webvtt-py
INSTALL
IMPORT
SIG · WEBVTT-PY
W
webvtt-py
serializationpythonv0.5.1
Install
1.6s avg
Import
59ms
Disk
16MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.5.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.062s · 17.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.6s · import 0.056s · 18MB
16MB installed
● package 16MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

webvtt
import webvtt
The primary functions like `read`, `from_srt`, `from_buffer`, and `segment` are exposed directly on the imported `webvtt` module, which acts as the main entry point for most operations. There are no common incorrect import patterns as the module structure is straightforward.

This quickstart demonstrates how to read an existing WebVTT file, iterate over its captions, and then create a new WebVTT object programmatically, add captions to it, and save it to a new file. It also includes creating a dummy file for immediate execution.

import webvtt import os # Create a dummy VTT file for demonstration dummy_vtt_content = """ WEBVTT 1 00:00:00.000 --> 00:00:03.000 Hello, world! 2 00:00:04.000 --> 00:00:07.000 This is a test caption. """ with open("example.vtt", "w", encoding="utf-8") as f: f.write(dummy_vtt_content) # Read a WebVTT file vtt = webvtt.read('example.vtt') print("--- Captions from example.vtt ---") for caption in vtt: print(f"[{caption.start} --> {caption.end}] {caption.text}") # Create a new WebVTT object and add captions programmatically new_vtt = webvtt.WebVTT() new_vtt.add(webvtt.Caption(start='00:00:01.000', end='00:00:05.000', text='First dynamic caption.')) new_vtt.add(webvtt.Caption(start='00:00:06.000', end='00:00:10.000', text='Second dynamic caption.')) # Save the new WebVTT object to a file new_vtt.save('output.vtt') print("\nGenerated output.vtt with 2 captions.") # Clean up dummy files os.remove("example.vtt") os.remove("output.vtt") print("Cleaned up example.vtt and output.vtt")
webvtt --version
Debug
Known issues
breakingPython 3.4, 3.5, and 3.6 are no longer supported since version 0.5.0. The library now requires Python 3.7 or newer.
fix
Upgrade your Python environment to 3.7 or higher.
affects: >=0.5.0
deprecatedThe `webvtt.read_buffer()` method was deprecated in version 0.5.0.
fix
Use `webvtt.from_buffer()` instead for reading from file-like objects or in-memory buffers.
affects: >=0.5.0
gotchaThe `caption.text` attribute returns the cue text with HTML/WebVTT tags (like `<c.classname>`) removed. To retrieve the original text including all tags, use the `caption.raw_text` attribute. This behavior was introduced in version 0.3.3.
fix
If you need the raw, uncleaned text, access `caption.raw_text`. Otherwise, `caption.text` provides a clean payload.
affects: >=0.3.3
gotchaSince version 0.5.0, the parser is no longer strict and ignores malformed blocks. This means that invalid WebVTT syntax that might have caused errors in previous versions will now be silently skipped or processed with best effort.
fix
Be aware that malformed WebVTT files might be parsed differently (more leniently) than in older versions. If strict validation is required, consider pre-validating files or implementing custom checks.
affects: >=0.5.0
gotchaPrior to version 0.5.1, when converting and saving to SRT format, cue tags (e.g., `<c.colorE5E5E5>`) were not removed, which is typically not desired for SRT.
fix
Upgrade to version 0.5.1 or newer to ensure SRT output is clean of WebVTT-specific cue tags.
affects: <0.5.1
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'webvtt'
The `webvtt-py` package is installed, but the import statement uses an incorrect module name. The package's importable module name is `webvtt`, not `webvtt-py`.
fix
Ensure the package is installed with `pip install webvtt-py` and then import it using `import webvtt` or `from webvtt import WebVTT`.
MalformedWebVTTError
The input WebVTT file does not conform to the WebVTT specification, often due to incorrect headers, timestamps, missing blank lines, or invalid cue formats.
fix
Validate and correct the WebVTT file to ensure it strictly adheres to the WebVTT specification, particularly the `WEBVTT` header on the first line, correct timestamp formats (`HH:MM:SS.mmm --> HH:MM:SS.mmm`), and blank lines between cues.
AttributeError: 'WebVTT' object has no attribute 'read'
The `read()` method is a class method of `webvtt.WebVTT` and must be called directly on the class, not on an instance of the `WebVTT` object.
fix
Call `read()` as `webvtt.WebVTT.read('path/to/file.vtt')` or use the top-level convenience function `webvtt.read('path/to/file.vtt')`.
UnicodeDecodeError: 'utf-8' codec can't decode byte 0x__ in position __: invalid start byte
The WebVTT file is encoded using a character set other than UTF-8 (the default), causing the parser to fail when encountering non-UTF-8 bytes.
fix
Specify the correct encoding when reading the file, for example, `webvtt.read('file.vtt', encoding='latin-1')` or `webvtt.read('file.vtt', encoding='cp1252')`, replacing with the actual encoding of your file.
Upgrade
Version history
0.5.1latest on PyPI · released May 30, 2024
Audit
Dependencies

No dependency data recorded yet.

Agent activity
30 hits · last 30 days
node
26
OpenAI (training)
1
Resources
webvtt-py — pip install webvtt-py · libregistry