Files
docling-core/tests/test_webvtt.py
Cesar Berrospi Ramis df9a2ca34e fix(webvtt): skip the metadata header after the WEBVTT line
Follow-up to #975. Real yt-dlp files have the `Kind: captions` and
`Language: en` lines right after "WEBVTT". They were parsed as a cue and
emitted a "Failed to parse cue block" warning.

- Ignore the header lines after "WEBVTT", up to the first empty line or
  the first line with cue timings, as the WebVTT parsing rules do.
- Add a yt-dlp transcript to the test data.

Signed-off-by: Cesar Berrospi Ramis <ceb@zurich.ibm.com>
2026-11-14 00:14:21 +01:00

774 lines
34 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""Test the data model for WebVTT files.
Examples extracted from https://www.w3.org/TR/webvtt1/
Copyright © 2019 World Wide Web Consortium.
"""
import warnings
import pytest
from pydantic import ValidationError
from docling_core.types.doc import DocItemLabel, DoclingDocument, TrackSource
from docling_core.types.doc.webvtt import (
WebVTTCueBlock,
WebVTTCueComponentWithTerminator,
WebVTTCueInternalText,
WebVTTCueItalicSpan,
WebVTTCueLanguageSpan,
WebVTTCueLanguageSpanStartTag,
WebVTTCueRubySpan,
WebVTTCueRubyTextSpan,
WebVTTCueSpanStartTagAnnotated,
WebVTTCueTextSpan,
WebVTTCueTimings,
WebVTTCueVoiceSpan,
WebVTTFile,
WebVTTTimestamp,
)
from .test_data_gen_flag import GEN_TEST_DATA
GENERATE = GEN_TEST_DATA
def test_vtt_cue_commponents() -> None:
"""Test WebVTT components."""
valid_timestamps = [
"00:01:02.345",
"12:34:56.789",
"02:34.567",
"00:00:00.000",
]
valid_total_seconds = [
1 * 60 + 2.345,
12 * 3600 + 34 * 60 + 56.789,
2 * 60 + 34.567,
0.0,
]
for idx, ts in enumerate(valid_timestamps):
model = WebVTTTimestamp(raw=ts)
assert model.seconds == valid_total_seconds[idx]
"""Test invalid WebVTT timestamps."""
invalid_timestamps = [
"00:60:02.345", # minutes > 59
"00:01:60.345", # seconds > 59
"00:01:02.1000", # milliseconds > 999
"01:02:03", # missing milliseconds
"01:02", # missing milliseconds
":01:02.345", # extra : for missing hours
"abc:01:02.345", # invalid format
]
for ts in invalid_timestamps:
with pytest.raises(ValidationError):
WebVTTTimestamp(raw=ts)
"""Test the timestamp __str__ method."""
model = WebVTTTimestamp(raw="00:01:02.345")
assert str(model) == "00:01:02.345"
"""Test valid cue timings."""
start = WebVTTTimestamp(raw="00:10.005")
end = WebVTTTimestamp(raw="00:14.007")
cue_timings = WebVTTCueTimings(start=start, end=end)
assert cue_timings.start == start
assert cue_timings.end == end
assert str(cue_timings) == "00:10.005 --> 00:14.007"
"""Test invalid cue timings with end timestamp before start."""
start = WebVTTTimestamp(raw="00:10.700")
end = WebVTTTimestamp(raw="00:10.500")
with pytest.raises(ValidationError) as excinfo:
WebVTTCueTimings(start=start, end=end)
assert "End timestamp must be greater than start timestamp" in str(excinfo.value)
"""Test invalid cue timings with missing end."""
start = WebVTTTimestamp(raw="00:10.500")
with pytest.raises(ValidationError) as excinfo:
WebVTTCueTimings(start=start) # type: ignore[call-arg]
assert "Field required" in str(excinfo.value)
"""Test invalid cue timings with missing start."""
end = WebVTTTimestamp(raw="00:10.500")
with pytest.raises(ValidationError) as excinfo:
WebVTTCueTimings(end=end) # type: ignore[call-arg]
assert "Field required" in str(excinfo.value)
"""Test with valid text."""
valid_text = "This is a valid cue text span."
span = WebVTTCueTextSpan(text=valid_text)
assert span.text == valid_text
assert str(span) == valid_text
"""Test with text containing newline characters."""
invalid_text = "This cue text span\ncontains a newline."
with pytest.raises(ValidationError):
WebVTTCueTextSpan(text=invalid_text)
"""Test with text containing ampersand."""
# A reference that does not resolve stays literal text instead of failing the cue.
assert WebVTTCueTextSpan(text="This cue text span contains &.").text == "This cue text span contains &."
assert WebVTTCueTextSpan(text="An unknown &foo; entity").text == "An unknown &foo; entity"
valid_text = "My favorite book is Pride &amp; Prejudice"
span = WebVTTCueTextSpan(text=valid_text)
# An escape denotes the character, so the span holds the character and
# writes the escape back out.
assert span.text == "My favorite book is Pride & Prejudice"
assert str(span) == valid_text
named = {"amp": "&", "lt": "<", "gt": ">", "lrm": "\u200e", "rlm": "\u200f", "nbsp": "\u00a0"}
for name, char in named.items():
assert WebVTTCueTextSpan(text=f"a&{name};b").text == f"a{char}b"
# Only the two that cannot be written literally come back escaped.
assert str(WebVTTCueTextSpan(text="a&gt;b")) == "a>b"
"""Test with text containing less-than sign."""
invalid_text = "This cue text span contains <."
with pytest.raises(ValidationError):
WebVTTCueTextSpan(text=invalid_text)
"""Test with empty text."""
with pytest.raises(ValidationError):
WebVTTCueTextSpan(text="")
"""Test that annotation validation works correctly."""
valid_annotation = "valid-annotation"
invalid_annotation = "invalid\nannotation"
with pytest.raises(ValidationError):
WebVTTCueSpanStartTagAnnotated(name="v", annotation=invalid_annotation)
assert WebVTTCueSpanStartTagAnnotated(name="v", annotation=valid_annotation)
"""Test that classes validation works correctly."""
annotation = "speaker name"
valid_classes = ["class1", "class2"]
invalid_classes = ["class\nwith\nnewlines", ""]
with pytest.raises(ValidationError):
WebVTTCueSpanStartTagAnnotated(name="v", annotation=annotation, classes=invalid_classes)
assert WebVTTCueSpanStartTagAnnotated(name="v", annotation=annotation, classes=valid_classes)
"""Test that components validation works correctly."""
annotation = "speaker name"
valid_components = [WebVTTCueComponentWithTerminator(component=WebVTTCueTextSpan(text="random text"))]
invalid_components = [123, "not a component"]
with pytest.raises(ValidationError):
WebVTTCueInternalText(components=invalid_components)
assert WebVTTCueInternalText(components=valid_components)
"""Test valid cue voice spans."""
cue_span = WebVTTCueVoiceSpan(
start_tag=WebVTTCueSpanStartTagAnnotated(name="v", annotation="speaker", classes=["loud", "clear"]),
internal_text=WebVTTCueInternalText(
components=[WebVTTCueComponentWithTerminator(component=WebVTTCueTextSpan(text="random text"))]
),
)
expected_str = "<v.loud.clear speaker>random text</v>"
assert str(cue_span) == expected_str
cue_span = WebVTTCueVoiceSpan(
start_tag=WebVTTCueSpanStartTagAnnotated(name="v", annotation="speaker"),
internal_text=WebVTTCueInternalText(
components=[WebVTTCueComponentWithTerminator(component=WebVTTCueTextSpan(text="random text"))]
),
)
expected_str = "<v speaker>random text</v>"
assert str(cue_span) == expected_str
def test_timestamp_from_seconds_rounding() -> None:
"""Test that from_seconds carries fractional rounding across all boundaries.
A fraction in [0.9995, 1) rounds up to a full second; the second must carry
into minutes and hours correctly instead of emitting an invalid '1000' ms value.
"""
cases = [
# (input_seconds, expected_raw)
(3.9994, "00:00:03.999"), # just below boundary — stays at 999 ms
(3.9996, "00:00:04.000"), # rounds up: ms carry into seconds
(59.9996, "00:01:00.000"), # ms carry propagates seconds → minutes
(3599.9996, "01:00:00.000"), # ms carry propagates all the way to hours
(7139.9996, "01:59:00.000"), # 1h 58m 59.9996s → 1h 59m 0s
(0.0, "00:00:00.000"),
(3723.456, "01:02:03.456"),
]
for secs, expected in cases:
ts = WebVTTTimestamp.from_seconds(secs)
assert ts.raw == expected, f"from_seconds({secs!r}) → {ts.raw!r}, want {expected!r}"
def test_webvttcueblock_parse() -> None:
"""Test the method parse of _WebVTTCueBlock class."""
raw: str = "04:02.500 --> 04:05.000\nJ’ai commencé le basket à l'âge de 13, 14 ans\n" # noqa: RUF001
block: WebVTTCueBlock = WebVTTCueBlock.parse(raw)
assert str(block.timings) == "04:02.500 --> 04:05.000"
assert len(block.payload) == 1
assert isinstance(block.payload[0], WebVTTCueComponentWithTerminator)
assert isinstance(block.payload[0].component, WebVTTCueTextSpan)
assert (
block.payload[0].component.text == "J’ai commencé le basket à l'âge de 13, 14 ans" # noqa: RUF001
)
assert raw == str(block)
raw = "04:05.001 --> 04:07.800\nSur les <i.foreignphrase><lang en>playground</lang></i>, ici à Montpellier\n"
block = WebVTTCueBlock.parse(raw)
assert str(block.timings) == "04:05.001 --> 04:07.800"
assert len(block.payload) == 3
assert isinstance(block.payload[0], WebVTTCueComponentWithTerminator)
assert isinstance(block.payload[0].component, WebVTTCueTextSpan)
assert block.payload[0].component.text == "Sur les "
assert isinstance(block.payload[1], WebVTTCueComponentWithTerminator)
assert isinstance(block.payload[1].component, WebVTTCueItalicSpan)
assert len(block.payload[1].component.internal_text.components) == 1
lang_span = block.payload[1].component.internal_text.components[0].component
assert isinstance(lang_span, WebVTTCueLanguageSpan)
assert isinstance(lang_span.internal_text.components[0].component, WebVTTCueTextSpan)
assert lang_span.internal_text.components[0].component.text == "playground"
assert isinstance(block.payload[2], WebVTTCueComponentWithTerminator)
assert isinstance(block.payload[2].component, WebVTTCueTextSpan)
assert block.payload[2].component.text == ", ici à Montpellier"
assert raw == str(block)
# Cue timestamps must be stripped so that the surrounding text is preserved.
raw = "00:00:00.030 --> 00:00:02.669\nthe<00:00:00.389> quick<00:00:00.750> brown\n"
block = WebVTTCueBlock.parse(raw)
assert len(block.payload) == 1
assert isinstance(block.payload[0].component, WebVTTCueTextSpan)
assert block.payload[0].component.text == "the quick brown"
def test_webvtt_verify_signature() -> None:
"""Test WebVTTFile.verify_signature conforms to the W3C WebVTT specification.
Per https://www.w3.org/TR/webvtt1/ the magic string is "WEBVTT" optionally
followed by a space (U+0020), a tab (U+0009), or any line terminator
(CR U+000D, LF U+000A, or CRLF).
"""
# Exact 6-character "WEBVTT" with nothing after it
assert WebVTTFile.verify_signature("WEBVTT") is True
# Valid: space or tab after "WEBVTT"
assert WebVTTFile.verify_signature("WEBVTT some title") is True
assert WebVTTFile.verify_signature("WEBVTT\t") is True
# Valid: LF line terminator (already worked before this fix)
assert WebVTTFile.verify_signature("WEBVTT\ncue block") is True
# Valid: CR line terminator (CR-only files — fixed by this patch)
assert WebVTTFile.verify_signature("WEBVTT\rcue block") is True
# Valid: CRLF — the \r at position 6 is now accepted; the \n at 7 is fine too
assert WebVTTFile.verify_signature("WEBVTT\r\ncue block") is True
# Invalid: empty string
assert WebVTTFile.verify_signature("") is False
# Invalid: wrong magic bytes
assert WebVTTFile.verify_signature("WEBVT") is False
assert WebVTTFile.verify_signature("webvtt") is False
# Invalid: character other than space/tab/CR/LF after "WEBVTT"
assert WebVTTFile.verify_signature("WEBVTT!") is False
def test_webvtt_parse_cr_separator() -> None:
"""WebVTTFile.parse must handle files that use bare CR as line separator."""
# Bare CR (U+000D) as line terminator — per the W3C WebVTT spec this is valid.
cr_vtt = "WEBVTT\r\r00:00:00.000 --> 00:00:01.000\rHello world\r"
vtt = WebVTTFile.parse(cr_vtt)
assert len(vtt) == 1
component = vtt[0].payload[0].component
assert isinstance(component, WebVTTCueTextSpan)
assert component.text == "Hello world"
def test_webvtt_parse_whitespace_only_line() -> None:
"""A line holding only whitespace is cue text unless the next cue starts right after it."""
# YouTube auto-generated captions start each cue payload with a line holding a single space.
content = (
"WEBVTT\n\n"
"00:00:00.160 --> 00:00:02.869 align:start position:0%\n"
" \n"
"hello<00:00:00.640><c> everyone</c>\n\n"
"00:00:02.879 --> 00:00:05.110 align:start position:0%\n"
"hello everyone\n"
"welcome back\n"
)
with warnings.catch_warnings():
warnings.simplefilter("error")
vtt = WebVTTFile.parse(content)
assert len(vtt) == 2
assert str(vtt[0]) == "00:00:00.160 --> 00:00:02.869\n \nhello<c> everyone</c>\n"
assert str(vtt[1]) == "00:00:02.879 --> 00:00:05.110\nhello everyone\nwelcome back\n"
# A whitespace-only line right before the next cue ends the cue and stays in its text,
# like the one followed by an empty line, with or without an identifier.
content = "WEBVTT\n\n1\n00:01.000 --> 00:02.000\none\n \n2\n00:02.000 --> 00:03.000\ntwo\n \n00:03.000 --> 00:04.000\nthree\n"
with warnings.catch_warnings():
warnings.simplefilter("error")
vtt = WebVTTFile.parse(content)
assert len(vtt) == 3
assert [block.identifier for block in vtt] == ["1", "2", None]
assert str(vtt[0]) == "1\n00:01.000 --> 00:02.000\none\n \n"
assert str(vtt[1]) == "2\n00:02.000 --> 00:03.000\ntwo\n \n"
assert str(vtt[2]) == "00:03.000 --> 00:04.000\nthree\n"
content = "WEBVTT\n\n00:01.000 --> 00:02.000\nhi\n \n\n00:02.000 --> 00:03.000\nyo\n"
assert str(WebVTTFile.parse(content)[0]) == str(WebVTTFile.parse(content.replace("\n \n\n", "\n \n"))[0])
# The cue text is kept as written, including whitespace at its start and end.
content = "WEBVTT\n\n00:01.000 --> 00:02.000\n \n hello \n \n\n00:02.000 --> 00:03.000\nx\n"
with warnings.catch_warnings():
warnings.simplefilter("error")
vtt = WebVTTFile.parse(content)
assert len(vtt) == 2
assert str(vtt[0]) == "00:01.000 --> 00:02.000\n \n hello \n \n"
# Whitespace before the timings of a standalone cue block is not an identifier.
block = WebVTTCueBlock.parse(" \n00:01.000 --> 00:02.000\nhi\n")
assert block.identifier is None
assert str(block) == "00:01.000 --> 00:02.000\nhi\n"
# The identifier is kept as written.
assert WebVTTCueBlock.parse(" id \n00:01.000 --> 00:02.000\nhi\n").identifier == " id "
# Only the WebVTT line terminators split the cue text, not other Unicode line boundaries.
block = WebVTTCueBlock.parse("00:01.000 --> 00:02.000\nfirst\u2028same line\x0csame line\x85\nsecond\n")
texts = [c.component.text for c in block.payload if isinstance(c.component, WebVTTCueTextSpan)]
assert texts == ["first\u2028same line\x0csame line\x85", "second"]
assert str(WebVTTCueBlock.parse("00:01.000 --> 00:02.000\r\none\rtwo\r\n")) == "00:01.000 --> 00:02.000\none\ntwo\n"
@pytest.mark.parametrize(
"block",
[
"NOTE a\n \nstill a note",
"STYLE\n::cue { color: red; }\n \n::cue(b) { color: blue; }",
"REGION\nid:r1\n \nwidth:40%",
],
)
def test_webvtt_parse_note_with_whitespace_only_line(block: str) -> None:
"""A NOTE, STYLE or REGION block ends at an empty line, or where the next cue starts."""
with warnings.catch_warnings():
warnings.simplefilter("error")
vtt = WebVTTFile.parse(f"WEBVTT\n\n{block}\n\n00:01.000 --> 00:02.000\nhi\n")
assert [str(cue) for cue in vtt] == ["00:01.000 --> 00:02.000\nhi\n"]
# A whitespace-only line, not an empty one, between the block and the next cue.
with warnings.catch_warnings():
warnings.simplefilter("error")
vtt = WebVTTFile.parse(f"WEBVTT\n\n{block}\n \n00:01.000 --> 00:02.000\nhi\n")
assert [str(cue) for cue in vtt] == ["00:01.000 --> 00:02.000\nhi\n"]
# The next cue starts right after the block, without any separator line.
with warnings.catch_warnings():
warnings.simplefilter("error")
vtt = WebVTTFile.parse(f"WEBVTT\n\n{block}\n00:01.000 --> 00:02.000\nhi\n")
assert [str(cue) for cue in vtt] == ["00:01.000 --> 00:02.000\nhi\n"]
def test_webvtt_parse_cue_text_starting_with_block_keyword() -> None:
"""A cue text line that starts with NOTE, STYLE or REGION is cue text, not a block to ignore."""
content = (
"WEBVTT\n\n"
"00:01.000 --> 00:02.000\nNOTE: buy milk\nand eggs\n\n"
"00:03.000 --> 00:04.000\nSTYLE guide\n \nREGION x\n\n"
"NOTE a real comment\n\n"
"00:05.000 --> 00:06.000\nbye\n"
)
with warnings.catch_warnings():
warnings.simplefilter("error")
vtt = WebVTTFile.parse(content)
assert [str(cue) for cue in vtt] == [
"00:01.000 --> 00:02.000\nNOTE: buy milk\nand eggs\n",
"00:03.000 --> 00:04.000\nSTYLE guide\n \nREGION x\n",
"00:05.000 --> 00:06.000\nbye\n",
]
@pytest.mark.parametrize("newline", ["\n", "\r\n"])
def test_webvtt_parse_metadata_header(newline: str) -> None:
"""The header lines of YouTube captions (yt-dlp) are not a cue."""
content = (
"WEBVTT\nKind: captions\nLanguage: en\n\n"
"00:00:01.050 --> 00:00:04.860 align:start position:0%\n \nobviously good evening\n\n"
"00:00:04.860 --> 00:00:04.870 align:start position:0%\nobviously good evening\n \n"
).replace("\n", newline)
with warnings.catch_warnings():
warnings.simplefilter("error")
vtt = WebVTTFile.parse(content)
assert [str(cue) for cue in vtt] == [
"00:00:01.050 --> 00:00:04.860\n \nobviously good evening\n",
"00:00:04.860 --> 00:00:04.870\nobviously good evening\n \n",
]
# A cue right after "WEBVTT", without the empty line, is not a header.
with warnings.catch_warnings():
warnings.simplefilter("error")
vtt = WebVTTFile.parse("WEBVTT\n00:01.000 --> 00:02.000\nhi\n")
assert len(vtt) == 1
# A header without any cue.
assert len(WebVTTFile.parse("WEBVTT\nKind: captions\nLanguage: en\n")) == 0
# The header ends at the first cue even without an empty line, and a whitespace-only line is a header line.
for content in (
"WEBVTT\nKind: captions\nLanguage: en\n00:01.000 --> 00:02.000\nhi\n",
"WEBVTT\nKind: captions\n \n00:01.000 --> 00:02.000\nhi\n",
"WEBVTT\nKind: captions\n \nLanguage: en\n\n00:01.000 --> 00:02.000\nhi\n",
):
with warnings.catch_warnings():
warnings.simplefilter("error")
vtt = WebVTTFile.parse(content)
assert [str(cue) for cue in vtt] == ["00:01.000 --> 00:02.000\nhi\n"]
# Every line before the first cue timings is a header line, also a would-be cue identifier.
with warnings.catch_warnings():
warnings.simplefilter("error")
vtt = WebVTTFile.parse("WEBVTT\nKind: captions\n1\n00:01.000 --> 00:02.000\nhi\n")
assert [str(cue) for cue in vtt] == ["00:01.000 --> 00:02.000\nhi\n"]
def test_webvtt_file() -> None:
"""Test WebVTT files."""
with open("./tests/data/webvtt/webvtt_example_01.vtt", encoding="utf-8") as f:
content = f.read()
vtt = WebVTTFile.parse(content)
assert len(vtt) == 13
block = vtt.cue_blocks[11]
assert str(block.timings) == "00:32.500 --> 00:33.500"
assert len(block.payload) == 1
cue_span = block.payload[0]
assert isinstance(cue_span.component, WebVTTCueVoiceSpan)
assert cue_span.component.start_tag.annotation == "Neil deGrasse Tyson"
assert not cue_span.component.start_tag.classes
assert len(cue_span.component.internal_text.components) == 1
comp = cue_span.component.internal_text.components[0]
assert isinstance(comp.component, WebVTTCueItalicSpan)
assert len(comp.component.internal_text.components) == 1
comp2 = comp.component.internal_text.components[0]
assert isinstance(comp2.component, WebVTTCueTextSpan)
assert comp2.component.text == "Laughs"
with open("./tests/data/webvtt/webvtt_example_02.vtt", encoding="utf-8") as f:
content = f.read()
vtt = WebVTTFile.parse(content)
assert len(vtt) == 4
reverse = "WEBVTT\n\nNOTE Copyright © 2019 World Wide Web Consortium. https://www.w3.org/TR/webvtt1/\n\n"
reverse += "\n".join([block.format(omit_hours_if_zero=True, omit_voice_end=True) for block in vtt.cue_blocks])
assert content == reverse.rstrip()
with open("./tests/data/webvtt/webvtt_example_03.vtt", encoding="utf-8") as f:
content = f.read()
vtt = WebVTTFile.parse(content)
assert len(vtt) == 13
for block in vtt:
assert block.identifier
block = vtt.cue_blocks[0]
assert block.identifier == "62357a1d-d250-41d5-a1cf-6cc0eeceffcc/15-0"
assert str(block.timings) == "00:00:04.963 --> 00:00:08.571"
assert len(block.payload) == 1
assert isinstance(block.payload[0].component, WebVTTCueVoiceSpan)
block = vtt.cue_blocks[2]
assert block.identifier == "62357a1d-d250-41d5-a1cf-6cc0eeceffcc/16-0"
assert str(block.timings) == "00:00:10.683 --> 00:00:11.563"
assert len(block.payload) == 1
assert isinstance(block.payload[0].component, WebVTTCueTextSpan)
assert block.payload[0].component.text == "Good."
assert not vtt.title
with open("./tests/data/webvtt/webvtt_example_04.vtt", encoding="utf-8") as f:
content = f.read()
with warnings.catch_warnings():
warnings.simplefilter("error")
vtt = WebVTTFile.parse(content)
assert len(vtt) == 3
block = vtt.cue_blocks[1]
assert len(block.payload) == 5
assert str(block) == (
"00:05.000 --> 00:09.000\n"
"— It will perforate your stomach.\n"
"— You could <b.loud>die</b>.\n"
"<v John>This is true.</v>\n"
)
block = vtt.cue_blocks[2]
assert len(block.payload) == 1
assert isinstance(block.payload[0].component, WebVTTCueTextSpan)
assert block.payload[0].component.text == "the quick brown fox"
assert vtt.title == "Danger of Nitrogen"
def test_webvtt_cue_escapes_in_annotation() -> None:
"""Test that an escape in a cue span annotation keeps the cue parseable."""
# The start tag pattern used to exclude "&" from the annotation, so a cue
# whose speaker name contained an escape matched no tag at all, fell through
# to the text span, and was rejected there for containing "<" — the whole
# cue was dropped with only a warning.
content = "WEBVTT\n\n00:00.000 --> 00:02.000\n<v Ben &amp; Jerry>We charge 5 &lt; 10 &amp; win</v>"
vtt = WebVTTFile.parse(content)
assert len(vtt) == 1
component = vtt.cue_blocks[0].payload[0].component
assert isinstance(component, WebVTTCueVoiceSpan)
assert component.start_tag.annotation == "Ben & Jerry"
text_span = component.internal_text.components[0].component
assert isinstance(text_span, WebVTTCueTextSpan)
assert text_span.text == "We charge 5 < 10 & win"
# The escapes are written back, so the file still round-trips.
assert str(vtt.cue_blocks[0]).rstrip("\n").endswith("<v Ben &amp; Jerry>We charge 5 &lt; 10 &amp; win</v>")
def test_webvtt_cue_html_character_references() -> None:
"""Test that any HTML character reference in cue text or an annotation is resolved."""
# WebVTT 6.4 hands the data and annotation states to the full HTML character
# reference algorithm, so the six names of the syntax table are no whitelist.
content = (
"WEBVTT\n\n"
"00:01.000 --> 00:03.000\nIt&#39;s raining.\n\n"
"00:03.000 --> 00:05.000\nCaf&eacute; or caf&#xE9;?\n\n"
"00:05.000 --> 00:07.000\n<v Ren&eacute;>Tom &amp; Jerry</v>\n\n"
"00:07.000 --> 00:09.000\nR&foo;d &"
)
vtt = WebVTTFile.parse(content)
assert len(vtt) == 4
texts = []
for block in vtt.cue_blocks:
component = block.payload[0].component
if isinstance(component, WebVTTCueVoiceSpan):
assert component.start_tag.annotation == "Ren\u00e9"
component = component.internal_text.components[0].component
assert isinstance(component, WebVTTCueTextSpan)
texts.append(component.text)
assert texts == ["It's raining.", "Caf\u00e9 or caf\u00e9?", "Tom & Jerry", "R&foo;d &"]
# A reference to a line terminator would corrupt the cue on the way out.
with pytest.raises(ValidationError):
WebVTTCueTextSpan(text="a&#10;b")
with pytest.raises(ValidationError):
WebVTTCueSpanStartTagAnnotated(name="v", annotation="a&#13;b")
# Only the escapes that cannot be written literally are written back.
assert str(vtt.cue_blocks[0]).rstrip("\n").endswith("It's raining.")
assert str(vtt.cue_blocks[3]).rstrip("\n").endswith("R&amp;foo;d &amp;")
@pytest.mark.parametrize(
("text", "voice"),
[
("Ask &copy and &amp; me", "Tom &amp; Jerry > Co"),
("x < y > z", "Tom &amp; Jerry > Co"),
("Tom & Jerry", None),
("Hello", "Tom & Jerry > Co"),
],
)
def test_webvtt_export_keeps_text_literal(text: str, voice: str | None) -> None:
"""Test that document text and voice names resembling markup or references are exported literally."""
doc = DoclingDocument(name="refs")
doc.add_text(
label=DocItemLabel.TEXT,
text=text,
source=TrackSource(start_time=0.0, end_time=1.0, voice=voice),
)
vtt = WebVTTFile.parse(doc.export_to_vtt())
assert len(vtt) == 1
component = vtt.cue_blocks[0].payload[0].component
if voice is not None:
assert isinstance(component, WebVTTCueVoiceSpan)
assert component.start_tag.annotation == voice
component = component.internal_text.components[0].component
assert isinstance(component, WebVTTCueTextSpan)
assert component.text == text
def test_webvtt_cue_language_span_start_tag():
WebVTTCueLanguageSpanStartTag.model_validate_json('{"annotation": "en"}')
WebVTTCueLanguageSpanStartTag.model_validate_json('{"annotation": "en-US"}')
WebVTTCueLanguageSpanStartTag.model_validate_json('{"annotation": "zh-Hant"}')
with pytest.raises(ValidationError, match="BCP 47"):
WebVTTCueLanguageSpanStartTag.model_validate_json('{"annotation": "en_US"}')
with pytest.raises(ValidationError, match="BCP 47"):
WebVTTCueLanguageSpanStartTag.model_validate_json('{"annotation": "123-de"}')
def test_webvtt_unclosed_and_stray_end_tags() -> None:
"""Test that unclosed spans keep their text and that a stray end tag is ignored."""
# A span still open at the end of the cue keeps its text.
block = WebVTTCueBlock.parse("00:01.000 --> 00:02.000\nHe said <i>stop\n")
assert len(block.payload) == 2
assert isinstance(block.payload[0].component, WebVTTCueTextSpan)
assert block.payload[0].component.text == "He said "
span = block.payload[1].component
assert isinstance(span, WebVTTCueItalicSpan)
assert isinstance(span.internal_text.components[0].component, WebVTTCueTextSpan)
assert span.internal_text.components[0].component.text == "stop"
# Italics that run across two cues: the first cue leaves <i> open and the
# second cue starts with its end tag. Every cue of the file is kept.
content = (
"WEBVTT\n\n"
"00:01.000 --> 00:03.000\n<i>I'm thinking about\n\n"
"00:03.000 --> 00:05.000\nwhat she said</i>\n\n"
"00:05.000 --> 00:07.000\nLast cue\n"
)
vtt = WebVTTFile.parse(content)
assert len(vtt) == 3
assert str(vtt[0]).rstrip("\n").endswith("<i>I'm thinking about</i>")
assert str(vtt[1]).rstrip("\n").endswith("\nwhat she said")
assert str(vtt[2]).rstrip("\n").endswith("\nLast cue")
# Misnested end tags are still rejected.
with pytest.raises(ValueError, match="Incorrect end tag"):
WebVTTCueBlock.parse("00:01.000 --> 00:02.000\n<b><i>both</b></i>\n")
def test_webvtt_unknown_tags() -> None:
"""Test that tags which are not WebVTT cue spans are ignored and their text is kept."""
block = WebVTTCueBlock.parse('00:01.000 --> 00:02.000\n<font color="#ffff00">Hello</font> world\n')
assert len(block.payload) == 1
assert isinstance(block.payload[0].component, WebVTTCueTextSpan)
assert block.payload[0].component.text == "Hello world"
# Tag names are case-sensitive, so <B> is not a bold span. The voice span around it is kept.
block = WebVTTCueBlock.parse("00:01.000 --> 00:02.000\n<v Bob><B>Run</B>!</v>\n")
assert len(block.payload) == 1
span = block.payload[0].component
assert isinstance(span, WebVTTCueVoiceSpan)
assert span.start_tag.annotation == "Bob"
assert isinstance(span.internal_text.components[0].component, WebVTTCueTextSpan)
assert span.internal_text.components[0].component.text == "Run!"
def test_webvtt_file_unknown_tags() -> None:
"""Test that a file with tags that are not WebVTT cue spans keeps all of its cues."""
content = (
"WEBVTT\n\n"
"00:00:01.000 --> 00:00:03.000\nFirst cue\n\n"
'00:00:03.000 --> 00:00:05.000\n<font color="#ffff00">Where are you going?</font>\n\n'
"00:00:05.000 --> 00:00:07.000\n<v Anna><B>Home</B>, I think.</v>\n\n"
"00:00:07.000 --> 00:00:09.000\nLast cue\n"
)
with warnings.catch_warnings():
warnings.simplefilter("error")
vtt = WebVTTFile.parse(content)
assert len(vtt) == 4
assert str(vtt[0]).rstrip("\n").endswith("\nFirst cue")
assert str(vtt[1]).rstrip("\n").endswith("\nWhere are you going?")
assert str(vtt[2]).rstrip("\n").endswith("\n<v Anna>Home, I think.</v>")
assert str(vtt[3]).rstrip("\n").endswith("\nLast cue")
@pytest.mark.parametrize(
("cue_text", "expected_children", "expected_serialization"),
[
pytest.param(
"<ruby>漢字<rt>かんじ</rt></ruby> is kanji",
[("text", "漢字"), ("rt", "かんじ")],
"<ruby>漢字<rt>かんじ</rt></ruby> is kanji",
id="single_pair",
),
pytest.param(
"<ruby>漢字<rt>かんじ</ruby> is kanji",
[("text", "漢字"), ("rt", "かんじ")],
"<ruby>漢字<rt>かんじ</rt></ruby> is kanji",
id="omitted_last_rt_end_tag",
),
pytest.param(
"<ruby>日<rt>に</rt>本<rt>ほん</ruby>",
[("text", "日"), ("rt", "に"), ("text", "本"), ("rt", "ほん")],
"<ruby>日<rt>に</rt>本<rt>ほん</rt></ruby>",
id="several_pairs",
),
],
)
def test_webvtt_ruby_spans(
cue_text: str, expected_children: list[tuple[str, str]], expected_serialization: str
) -> None:
"""Test that ruby spans are parsed, keep their text and are serialized with all end tags."""
block = WebVTTCueBlock.parse(f"00:01.000 --> 00:02.000\n{cue_text}\n")
ruby = block.payload[0].component
assert isinstance(ruby, WebVTTCueRubySpan)
children: list[tuple[str, str]] = []
for child in ruby.internal_text.components:
component = child.component
if isinstance(component, WebVTTCueTextSpan):
children.append((component.kind, component.text))
else:
assert isinstance(component, WebVTTCueRubyTextSpan)
annotation = component.internal_text.components[0].component
assert isinstance(annotation, WebVTTCueTextSpan)
children.append((component.kind, annotation.text))
assert children == expected_children
assert str(block).rstrip("\n").endswith(f"\n{expected_serialization}")
def test_webvtt_ruby_text_start_tag_inside_ruby_text_is_ignored() -> None:
"""Test that an <rt> start tag inside an open <rt> is ignored and its text is kept."""
block = WebVTTCueBlock.parse("00:01.000 --> 00:02.000\n<ruby>日<rt>に<rt>ほん</rt></ruby>\n")
assert len(block.payload) == 1
ruby = block.payload[0].component
assert isinstance(ruby, WebVTTCueRubySpan)
assert [c.component.kind for c in ruby.internal_text.components] == ["text", "rt"]
rt = ruby.internal_text.components[1].component
assert isinstance(rt, WebVTTCueRubyTextSpan)
texts = [c.component.text for c in rt.internal_text.components if isinstance(c.component, WebVTTCueTextSpan)]
assert "".join(texts) == "にほん"
assert str(block).rstrip("\n").endswith("\n<ruby>日<rt>にほん</rt></ruby>")
def test_webvtt_ruby_text_outside_ruby_is_ignored() -> None:
"""Test that <rt> tags that are not directly inside a <ruby> span are ignored."""
block = WebVTTCueBlock.parse("00:01.000 --> 00:02.000\n<rt>x</rt> and <i><rt>y</rt></i>\n")
assert [type(c.component) for c in block.payload] == [
WebVTTCueTextSpan,
WebVTTCueTextSpan,
WebVTTCueItalicSpan,
]
assert str(block).rstrip("\n").endswith("\nx and <i>y</i>")
def test_webvtt_file_ruby_spans_example() -> None:
"""Test a WebVTT file with ruby spans, including an omitted last end tag."""
with open("./tests/data/webvtt/webvtt_example_05.vtt", encoding="utf-8") as f:
content = f.read()
with warnings.catch_warnings():
warnings.simplefilter("error")
vtt = WebVTTFile.parse(content)
assert len(vtt) == 5
assert vtt.title == "Ruby annotations"
assert str(vtt[0]).endswith("\n<ruby>漢字<rt>かんじ</rt></ruby> is the Japanese word for kanji.\n")
assert str(vtt[1]).endswith("\n<ruby>東京<rt>とうきょう</rt></ruby> is the capital of Japan.\n")
assert str(vtt[2]).endswith("\n<ruby>日<rt>に</rt>本<rt>ほん</rt></ruby>語 is the Japanese language.\n")
voice = vtt[3].payload[0].component
assert isinstance(voice, WebVTTCueVoiceSpan)
assert isinstance(voice.internal_text.components[0].component, WebVTTCueRubySpan)
assert str(vtt[4]).endswith("\nPlain cue between ruby cues.\n")
def test_webvtt_file_youtube_header_example() -> None:
"""Test a yt-dlp YouTube transcript with the "Kind" and "Language" header lines."""
with open("./tests/data/webvtt/webvtt_example_06.vtt", encoding="utf-8") as f:
content = f.read()
with warnings.catch_warnings():
warnings.simplefilter("error")
vtt = WebVTTFile.parse(content)
assert len(vtt) == 4
assert vtt.title is None
assert str(vtt[0]) == (
"00:00:00.200 --> 00:00:03.450\nWelcome back to the channel. Today we are looking\nat a simple example.\n"
)
assert str(vtt[1]) == (
"00:00:03.450 --> 00:00:07.100\nIf you extract subtitles using yt-dlp,\nthis is the structure you get.\n"
)
assert str(vtt[2]) == "00:00:07.100 --> 00:00:10.520\nEach block has a timestamp and a line of text.\n"
# The leading whitespace of a cue is kept: a whitespace-only line, then an indented line.
assert str(vtt[3]) == "00:00:10.520 --> 00:00:13.000\n \n This cue starts with blank spaces.\n"
# The serialized file is the original one without the "Kind" and "Language" header lines
# (and without the final newline, which the serialization does not emit).
assert str(vtt) == content.replace("Kind: captions\nLanguage: en\n", "").rstrip("\n")
# The serialized file is valid WebVTT and parses back to the same cues.
assert WebVTTFile.parse(str(vtt)).cue_blocks == vtt.cue_blocks