mirror of
https://github.com/docling-project/docling-core.git
synced 2026-11-18 20:27:00 +00:00
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>
774 lines
34 KiB
Python
774 lines
34 KiB
Python
"""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 & 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>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 & Jerry>We charge 5 < 10 & 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 & Jerry>We charge 5 < 10 & 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's raining.\n\n"
|
||
"00:03.000 --> 00:05.000\nCafé or café?\n\n"
|
||
"00:05.000 --> 00:07.000\n<v René>Tom & 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 b")
|
||
with pytest.raises(ValidationError):
|
||
WebVTTCueSpanStartTagAnnotated(name="v", annotation="a 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&foo;d &")
|
||
|
||
|
||
@pytest.mark.parametrize(
|
||
("text", "voice"),
|
||
[
|
||
("Ask © and & me", "Tom & Jerry > Co"),
|
||
("x < y > z", "Tom & 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
|