{"id":3854,"library":"webvtt-py","title":"WebVTT Python Library","description":"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.","status":"active","version":"0.5.1","language":"en","source_language":"en","source_url":"https://github.com/glut23/webvtt-py","tags":["webvtt","subtitles","captions","video","media","srt"],"install":[{"cmd":"pip install webvtt-py","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"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.","symbol":"webvtt","correct":"import webvtt"}],"quickstart":{"code":"import webvtt\nimport os\n\n# Create a dummy VTT file for demonstration\ndummy_vtt_content = \"\"\"\nWEBVTT\n\n1\n00:00:00.000 --> 00:00:03.000\nHello, world!\n\n2\n00:00:04.000 --> 00:00:07.000\nThis is a test caption.\n\"\"\"\n\nwith open(\"example.vtt\", \"w\", encoding=\"utf-8\") as f:\n    f.write(dummy_vtt_content)\n\n# Read a WebVTT file\nvtt = webvtt.read('example.vtt')\n\nprint(\"--- Captions from example.vtt ---\")\nfor caption in vtt:\n    print(f\"[{caption.start} --> {caption.end}] {caption.text}\")\n\n# Create a new WebVTT object and add captions programmatically\nnew_vtt = webvtt.WebVTT()\nnew_vtt.add(webvtt.Caption(start='00:00:01.000', end='00:00:05.000', text='First dynamic caption.'))\nnew_vtt.add(webvtt.Caption(start='00:00:06.000', end='00:00:10.000', text='Second dynamic caption.'))\n\n# Save the new WebVTT object to a file\nnew_vtt.save('output.vtt')\nprint(\"\\nGenerated output.vtt with 2 captions.\")\n\n# Clean up dummy files\nos.remove(\"example.vtt\")\nos.remove(\"output.vtt\")\nprint(\"Cleaned up example.vtt and output.vtt\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.7 or higher.","message":"Python 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.","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"Use `webvtt.from_buffer()` instead for reading from file-like objects or in-memory buffers.","message":"The `webvtt.read_buffer()` method was deprecated in version 0.5.0.","severity":"deprecated","affected_versions":">=0.5.0"},{"fix":"If you need the raw, uncleaned text, access `caption.raw_text`. Otherwise, `caption.text` provides a clean payload.","message":"The `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.","severity":"gotcha","affected_versions":">=0.3.3"},{"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.","message":"Since 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.","severity":"gotcha","affected_versions":">=0.5.0"},{"fix":"Upgrade to version 0.5.1 or newer to ensure SRT output is clean of WebVTT-specific cue tags.","message":"Prior 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.","severity":"gotcha","affected_versions":"<0.5.1"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}