Skip to content

[FIX] Escape special characters in WebVTT and SMPTE-TT output (#2437) - #2438

Open
Aditya-Saroha wants to merge 1 commit into
CCExtractor:masterfrom
Aditya-Saroha:fix/escape-webvtt-smptett
Open

Aditya-Saroha wants to merge 1 commit into
CCExtractor:masterfrom
Aditya-Saroha:fix/escape-webvtt-smptett

Conversation

@Aditya-Saroha

Copy link
Copy Markdown
Contributor

In raising this pull request, I confirm the following (please check boxes):

Reason for this PR:

  • This PR adds new functionality.
  • This PR fixes a bug that I have personally experienced or that a real user has reported and for which a sample exists.
  • This PR is porting code from C to Rust.

Sanity check:

  • I have read and understood the contributors guide.
  • I have checked that another pull request for this purpose does not exist.
  • If the PR adds new functionality, I've added it to the changelog. If it's just a bug fix, I have NOT added it to the changelog.
  • I am NOT adding new C code unless it's to fix an existing, reproducible bug.

Repro instructions:

Sample: markup.bin attached to issue #2437 (a 77-byte RCWT sample containing <BOB> & HI).

Commands to reproduce:

ccextractor markup.bin --out=webvtt -o markup.vtt
ccextractor markup.bin --out=smptett -o markup.xml
python3 -c 'import xml.etree.ElementTree as E; E.parse("markup.xml")'

Before fix:

  • WebVTT writes & HI unescaped. When parsed in a browser (e.g., Chromium cue.getCueAsHTML().textContent), is parsed as an unknown HTML element and omitted from text display, leaving only & HI.
  • SMPTE-TT writes & HI.... XML parsing fails with ParseError: not well-formed (invalid token): line 20, column 21 due to the unclosed tag and bare &.

After fix:

  • WebVTT escapes literal caption characters to & HI, preserving & HI as visible text in browser cues.
  • SMPTE-TT escapes literal characters in get_decoder_line_encoded(), producing valid XML that parses cleanly with xml.etree.ElementTree.
  • Formats without HTML/XML entity requirements (such as SRT, SSA, SAMI, SPUPNG) remain untouched, preservingraw text as decided in [FIX] escape special characters ( < > & ) to HTML context #1703.

Description of Changes

Fixes #2437.

  1. src/lib_ccx/ccx_encoders_webvtt.c:
  • In write_cc_buffer_as_webvtt(), escape literal caption characters (& -> &, < -> <, > -> >). Encoder-generated styling tags (, , <c.color>, , ) are written separately and remain unescaped.
  1. src/lib_ccx/ccx_encoders_helpers.c:
  • In get_decoder_line_encoded(), escape literal caption characters when ctx->write_format == CCX_OF_SMPTETT. Encoder formatting tags (, , ) are inserted separately and remain untouched, allowing write_cc_buffer_as_smptett() to convert them to TTML style tags while producing valid XML text.
  1. src/lib_ccx/ccx_encoders_smptett.c:
  • In write_cc_buffer_as_smptett(), updated strchr calls searching for # and > in font-colored blocks to search starting from start rather than context->subline, avoiding premature matches if text preceding the tag contains # or >.

Verification

  • Verified SMPTE-TT XML parses cleanly via python3 -c "import xml.etree.ElementTree as E; E.parse('...')" with exit code 0 and text & HI.
  • Verified WebVTT cue payload decodes properly in Chromium (VTTCue.getCueAsHTML().textContent gives & HI).
  • Verified styled captions (, , color tags) retain formatting elements while escaping inner special characters.
  • Verified SRT output remains unescaped (regression check).

@cfsmp3 cfsmp3 closed this Nov 10, 2026
@cfsmp3 cfsmp3 reopened this Nov 10, 2026

@cfsmp3 cfsmp3 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is Carlos' claude doing the first pass. Before Carlos takes a look, please address these issues.

  1. Braces. The new entity selection in get_decoder_line_encoded() (ccx_encoders_helpers.c) is an if / else if chain with one-line bodies and no braces. Every if/else body needs { }.

  2. The fix only covers CEA-608. write_cc_buffer_as_webvtt() and the 608 SMPTE-TT path now escape, but the other writers into the same formats don't:

    • write_cc_subtitle_as_webvtt() and write_cc_subtitle_as_smptett() (teletext, ISDB, DVB OCR text)
    • write_stringz_as_webvtt() and write_stringz_as_smptett() (--startcreditstext / --endcreditstext)

    A teletext or credits line containing & or < still produces a broken WebVTT cue or non-well-formed SMPTE-TT XML. Please escape in all of them. Teletext text can already contain the <font color=…> / <i> tags that telxcc inserts, so the escaping has to apply to the character data only, not to those tags. Please show the result on a teletext sample as well.

  3. Please attach the sample to the PR (or link it directly), and show the before/after for each writer you change.

Aditya-Saroha added a commit to Aditya-Saroha/ccextractor that referenced this pull request Nov 10, 2026
…tractor#2438)

- Add curly braces to if/else if branches in get_decoder_line_encoded()
- Implement escape_markup_text() to escape bare '&', '<', and '>' in character data while preserving markup tags (<font>, <i>, <b>, <u>, etc.) and valid HTML/XML entities
- Escape subtitle lines in write_stringz_as_webvtt() and write_stringz_as_smptett(), covering teletext, ISDB, DVB text, and credits (--startcreditstext / --endcreditstext)
- Escape OCR text in write_cc_bitmap_as_webvtt() and write_cc_bitmap_as_smptett()
Aditya-Saroha added a commit to Aditya-Saroha/ccextractor that referenced this pull request Nov 10, 2026
…tractor#2438)

- Add curly braces to if/else if branches in get_decoder_line_encoded()
- Implement escape_markup_text() to escape bare '&', '<', and '>' in character data while preserving markup tags (<font>, <i>, <b>, <u>, etc.) and valid HTML/XML entities
- Escape subtitle lines in write_stringz_as_webvtt() and write_stringz_as_smptett(), covering teletext, ISDB, DVB text, and credits (--startcreditstext / --endcreditstext)
- Escape OCR text in write_cc_bitmap_as_webvtt() and write_cc_bitmap_as_smptett()
@Aditya-Saroha
Aditya-Saroha force-pushed the fix/escape-webvtt-smptett branch from 1f4af45 to aadca93 Compare November 10, 2026 09:58
Aditya-Saroha added a commit to Aditya-Saroha/ccextractor that referenced this pull request Nov 10, 2026
…tractor#2438)

- Add curly braces to if/else if branches in get_decoder_line_encoded()
- Implement escape_markup_text() to escape bare '&', '<', and '>' in character data while preserving markup tags (<font>, <i>, <b>, <u>, etc.) and valid HTML/XML entities
- Escape subtitle lines in write_stringz_as_webvtt() and write_stringz_as_smptett(), covering teletext, ISDB, DVB text, and credits (--startcreditstext / --endcreditstext)
- Escape OCR text in write_cc_bitmap_as_webvtt() and write_cc_bitmap_as_smptett()
@Aditya-Saroha
Aditya-Saroha force-pushed the fix/escape-webvtt-smptett branch from aadca93 to 94e5834 Compare November 10, 2026 10:12
…actor#2437)

WebVTT and SMPTE-TT outputs did not properly escape special XML/HTML
characters ('&', '<', '>'), causing XML parsers to reject SMPTE-TT
documents as malformed and browser rendering engines to drop or
misinterpret tags in WebVTT cues (e.g. '<BOB>').

Key changes:
- Escape at plain-text sources: ISDB text (ccx_decoders_isdb.c), MP4 tx3g
  subtitles (mp4.c and mp4_rust_bridge.c), start/end credits text
  (ccx_encoders_common.c), and bitmap OCR (ccx_encoders_webvtt.c and
  ccx_encoders_smptett.c).
- Escape in CEA-608 writers: in get_decoder_line_encoded()
  (ccx_encoders_helpers.c), escape characters when targeting WebVTT or
  SMPTE-TT. Add explicit braces to all conditional branches.
- Teletext handling: teletext already tags formatting (<font>, <i>, <br/>)
  and escapes character data via ENTITIES[] in telxcc.c. Pass-through
  writers (write_stringz_as_webvtt, write_stringz_as_smptett) remain
  pure pass-through to prevent double-escaping. Fixed -nofc mode in
  telxcc.c where character data previously bypassed escaping.
- Memory safety: add OOM checks with fatal(EXIT_NOT_ENOUGH_MEMORY, ...)
  on all new escaping allocations.
- Non-XML formats: SRT, SSA, SAMI, etc. remain strictly untouched and
  byte-identical to master.

Fixes CCExtractor#2437
@Aditya-Saroha
Aditya-Saroha force-pushed the fix/escape-webvtt-smptett branch from 94e5834 to 50c81ca Compare November 10, 2026 17:18
@Aditya-Saroha

Copy link
Copy Markdown
Contributor Author

Hi Carlos,

Thank you for the constructive and detailed review. Below is an itemized breakdown of how each point has been addressed, along with test evidence, CI diff analysis, and architectural details.


1. Addressing Review Points

Point 1: Braces in get_decoder_line_encoded()

All single-line if, else if, and else branches in get_decoder_line_encoded() (src/lib_ccx/ccx_encoders_helpers.c) have been updated with standard { } braces according to project conventions.

Points 2 & 3: Coverage Across Other Writers & Teletext Architecture

The review noted that write_cc_subtitle_as_* and write_stringz_as_* were not escaping plain-text inputs, and requested escaping while ensuring teletext <font color=...> and <i> tags are not broken or double-escaped.

Architectural Choice: Escaping at Plain-Text Sources

write_stringz_as_webvtt() and write_stringz_as_smptett() are shared pass-through writers. Crucially, teletext character data arrives already escaped and tagged from telxcc.c (using telxcc's internal ENTITIES[] mapping table, which converts & -> &amp;, < -> &lt;, > -> &gt; while inserting <font color="..."> and <br/> tags).

Attempting to parse tags or detect entities inside write_stringz_* via heuristics or regular expressions is inherently brittle—it risks double-escaping valid entities (&amp; -> &amp;amp;) or misidentifying caption text like <BOB> as markup.

Instead, the clean architecture is to keep write_stringz_* as a pure pass-through writer and escape character data at each plain-text source before it reaches the writer:

  1. Start & End Credits (src/lib_ccx/ccx_encoders_common.c):
    context->start_credits_text and context->end_credits_text are escaped with escape_plain_text() when targeting WebVTT or SMPTE-TT.
  2. MP4 tx3g Subtitles (src/lib_ccx/mp4.c & src/lib_ccx/mp4_rust_bridge.c):
    Raw plain-text packets decoded from tx3g atoms are escaped via escape_plain_text() immediately after extraction.
  3. ISDB Subtitles (src/lib_ccx/ccx_decoders_isdb.c):
    Plain-text decoded buffer is escaped via dynamic allocation before being handed to add_cc_sub_text().
  4. Bitmap OCR Text (src/lib_ccx/ccx_encoders_webvtt.c & src/lib_ccx/ccx_encoders_smptett.c):
    OCR string payloads in write_cc_bitmap_as_* are escaped prior to emission.
  5. Teletext -nofc (No Font Color) Fix (src/lib_ccx/telxcc.c):
    In default color mode, telxcc.c already escaped character data via ENTITIES[]. However, in -nofc mode, character output previously bypassed ENTITIES[] and emitted raw bytes. We updated the -nofc branch in telxcc.c to use entity escaping, ensuring teletext is well-formed across both color and non-color modes.

All dynamic allocations use fatal(EXIT_NOT_ENOUGH_MEMORY, ...) on failure.


2. Before & After Test Evidence

All tests below were executed using binaries compiled directly from master and this branch. SMPTE-TT XML documents were validated using Python's standard xml.etree.ElementTree.parse().

A. CEA-608 Captions (markup.bin)

WebVTT (ccextractor markup.bin --out=webvtt)

  • Master:
    WEBVTT
    
    00:00:01.001 --> 00:00:02.999 line:84.66%
    <BOB> & HI                      
    (Browser HTML/WebVTT cue parsers treat <BOB> as an unknown HTML element and discard it from display, showing only & HI)
  • Branch:
    WEBVTT
    
    00:00:01.001 --> 00:00:02.999 line:84.66%
    &lt;BOB&gt; &amp; HI                      
    (Properly rendered as visible text <BOB> & HI)

SMPTE-TT (ccextractor markup.bin --out=smptett)

  • Master:
        <div>
          <p begin="00:00:01.001" end="00:00:02.999" tts:origin="10.000% 84.667%">
            <span><BOB> & HI
            <style tts:backgroundColor="#000000FF" tts:fontSize="18px"/></span>
          </p>
        </div>
    • ElementTree.parse(): ParseError: not well-formed (invalid token): line 20, column 21 (FAIL)
  • Branch:
        <div>
          <p begin="00:00:01.001" end="00:00:02.999" tts:origin="10.000% 84.667%">
            <span>&lt;BOB&gt; &amp; HI
            <style tts:backgroundColor="#000000FF" tts:fontSize="18px"/></span>
          </p>
        </div>
    • ElementTree.parse(): PASS

B. MP4 tx3g Subtitles (out.mp4)

  • Sample: MP4 with mov_text subtitle track containing cues Q&A & R&D and 5 > 3 and 2 < 3.

WebVTT (ccextractor out.mp4 --out=webvtt)

  • Master:
    00:00:01.000 --> 00:00:02.999
    Q&A & R&D
    
    00:00:04.000 --> 00:00:05.999
    5 > 3 and 2 < 3
  • Branch:
    00:00:01.000 --> 00:00:02.999
    Q&amp;A &amp; R&amp;D
    
    00:00:04.000 --> 00:00:05.999
    5 &gt; 3 and 2 &lt; 3

SMPTE-TT (ccextractor out.mp4 --out=smptett)

  • Master:
    <p begin="00:00:01.000" end="00:00:02.999">Q&A & R&D</p>
    <p begin="00:00:04.000" end="00:00:05.999">5 > 3 and 2 < 3</p>
    • ElementTree.parse(): ParseError: not well-formed (invalid token): line 20, column 3 (FAIL)
  • Branch:
    <p begin="00:00:01.000" end="00:00:02.999">Q&amp;A &amp; R&amp;D</p>
    <p begin="00:00:04.000" end="00:00:05.999">5 &gt; 3 and 2 &lt; 3</p>
    • ElementTree.parse(): PASS

C. Start & End Credits

  • Parameters: --startcreditstext="Intro & <Opening>" and --endcreditstext="Outro & <Closing>".

WebVTT

  • Master: Emits unescaped Intro & <Opening>.
  • Branch: Emits Intro &amp; &lt;Opening&gt;.

SMPTE-TT

  • Master:
    <p begin="00:00:00.000" end="00:00:03.000">Intro & <Opening></p>
    • ElementTree.parse(): ParseError: not well-formed (invalid token) (FAIL)
  • Branch:
    <p begin="00:00:00.000" end="00:00:03.000">Intro &amp; &lt;Opening&gt;</p>
    • ElementTree.parse(): PASS

D. Teletext Formatting & Entity Preservation

  • Test: Teletext stream containing <font color="..."> tags alongside special characters (AT&T <LIVE> & <B&M>, Tom & Jerry: 1 < 2 && 4 > 3).

Colored Mode (Default)

  • Master & Branch (Identical):
    <font color="#00ff00">AT&amp;T &lt;LIVE&gt; &amp; &lt;B&amp;M&gt;</font>
    <font color="#ffff00">Tom &amp; Jerry: 1 &lt; 2 &amp;&amp; 4 &gt; 3</font>
    Formatting tags <font> and <br/> are preserved, special characters are escaped, and no double-escaping occurs (&amp; remains &amp;, never &amp;amp;).

No-Font-Color Mode (-nofc)

  • Master: Omitted entity conversion on uncolored text, emitting raw AT&T <LIVE> & <B&M> (causing SMPTE-TT XML parsing to fail).
  • Branch: Properly escapes character data to AT&amp;T &lt;LIVE&gt; &amp; &lt;B&amp;M&gt;, parsing cleanly with ElementTree.parse().

3. Non-XML / Non-HTML Regression Check (SRT)

To verify that formats without XML/HTML entity requirements were not touched:

ccextractor <input> --out=srt -o master.srt
ccextractor <input> --out=srt -o branch.srt
diff -u master.srt branch.srt

Across CEA-608, MP4 tx3g, and Teletext test streams, the diff was completely empty (exit code 0; byte-for-byte identical). SRT, SSA, SAMI, etc. remain strictly untouched.


4. CI Analysis: Sample 121 (--out=smptett)

On the CCExtractor CI regression platform, Test 161 runs ccextractor --out=smptett sample_121.ts (MPEG transport stream containing CEA-608 captions).

  • In master, speaker transitions emit literal >> characters directly into the SMPTE-TT XML baseline.
  • In this branch, > is escaped to &gt;, producing &gt;&gt;.
  • Because the CI platform compares byte-for-byte against master's baseline, it flags an output difference.

The unified diff between master and branch on sample_121.ts shows every single change:

--- sample_121_master.ttml
+++ sample_121_branch.ttml
@@ -29,11 +29,11 @@
         <style tts:backgroundColor="#000000FF" tts:fontSize="18px"/></span>
       </p>
       <p begin="00:00:04.472" end="00:00:05.838" tts:origin="10.000% 15.333%">
-        <span>>> Safety remains our number one
+        <span>&gt;&gt; Safety remains our number one
         <style tts:backgroundColor="#000000FF" tts:fontSize="18px"/></span>
       </p>
       <p begin="00:00:05.840" end="00:00:07.306" tts:origin="10.000% 10.000%">
-        <span>>> Safety remains our number one
+        <span>&gt;&gt; Safety remains our number one
         <style tts:backgroundColor="#000000FF" tts:fontSize="18px"/></span>
       </p>
       <p begin="00:00:05.840" end="00:00:07.306" tts:origin="10.000% 15.333%">
@@ -45,7 +45,7 @@
         <style tts:backgroundColor="#000000FF" tts:fontSize="18px"/></span>
       </p>
       <p begin="00:00:07.308" end="00:00:07.472" tts:origin="10.000% 15.333%">
-        <span>>>P
+        <span>&gt;&gt;P
         <style tts:backgroundColor="#000000FF" tts:fontSize="18px"/></span>
       </p>
     </div>

Zero other lines differ across the entire file. Furthermore, running --out=srt on sample_121.ts produces byte-for-byte identical output between master and branch (diff -u exit 0). The CI failure is strictly a baseline change reflecting the correct escaping of >.


5. Scope & Validation Boundaries

To maintain transparency about testing coverage:

  • Verified with Media / Synthetic Runs:
    • CEA-608 (real transport stream and RCWT samples)
    • MP4 tx3g (real muxed MP4 streams)
    • Credits (--startcreditstext / --endcreditstext options)
    • Teletext (real/synthetic streams, both color and -nofc modes)
  • Code-Audited Paths:
    • ISDB-T (src/lib_ccx/ccx_decoders_isdb.c) and Bitmap OCR (src/lib_ccx/ccx_encoders_webvtt.c / ccx_encoders_smptett.c):
      Both paths were verified via code audit to produce plain character data without markup, and both now invoke escape_plain_text() with dynamic allocation and OOM checks. However, because public live broadcast captures with unescaped special characters were not accessible, these two specific decoders remain untested against live broadcast media.
  • Pre-Existing Note:
    • In write_cc_buffer_as_smptett(), strchr(subline, '#') searches for font color hex codes. If a subtitle contains # in literal text before the color tag, it matches the earlier #. This is pre-existing behavior in master and has been left untouched to keep the PR focused strictly on character escaping.

@Aditya-Saroha
Aditya-Saroha requested a review from cfsmp3 November 10, 2026 17:38
@ccextractor-bot

Copy link
Copy Markdown
Collaborator
CCExtractor CI platform finished running the test files on linux. 171/238 tests matched the approved output:
Report Name Tests Passed
Broken 9/13
CEA-708 2/14
DVB 0/7
DVD 3/3
DVR-MS 2/2
General 26/28
Hardsubx 1/1
Hauppage 3/3
MP4 3/3
NoCC 10/10
Options 68/86
Teletext 0/21
WTV 12/13
XDS 32/34

67 tests do not match the approved output. That is the pass/fail verdict. Whether this branch caused it is a separate question, answered below.


Compared with the tip of master — test 9978, commit f4519ff:

  • 1 pass there and fail here
  • 0 fail there and pass here
  • 0 fail on both, with different output
  • 66 fail on both, byte for byte the same

Pass there, fail here:


Compared with the commit this branch was cut from: the same run as the tip of master (test 9978), so the comparison above already covers it.


This branch changes the behaviour of 1 test(s) relative to the tip of master. Those are the ones worth looking at; anything else in the list fails the same way on both sides.

@ccextractor-bot

Copy link
Copy Markdown
Collaborator
CCExtractor CI platform finished running the test files on windows. 171/238 tests matched the approved output:
Report Name Tests Passed
Broken 9/13
CEA-708 2/14
DVB 0/7
DVD 3/3
DVR-MS 2/2
General 26/28
Hardsubx 1/1
Hauppage 3/3
MP4 3/3
NoCC 10/10
Options 68/86
Teletext 0/21
WTV 12/13
XDS 32/34

67 tests do not match the approved output. That is the pass/fail verdict. Whether this branch caused it is a separate question, answered below.


Compared with the tip of master — test 9977, commit 672f012:

  • 1 pass there and fail here
  • 0 fail there and pass here
  • 0 fail on both, with different output
  • 66 fail on both, byte for byte the same

Pass there, fail here:


Compared with the commit this branch was cut from: the same run as the tip of master (test 9977), so the comparison above already covers it.


This branch changes the behaviour of 1 test(s) relative to the tip of master. Those are the ones worth looking at; anything else in the list fails the same way on both sides.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[BUG] Unescaped caption text breaks WebVTT and SMPTE-TT output

3 participants