feat: Add parser and writer for TTML format

Author: tkarabela

Diff for: README.md

@@ -14,7 +14,7 @@ pysubs2
 pysubs2 is a Python library for editing subtitle files.
 It’s based on *SubStation Alpha*, the native format of
 [Aegisub](http://www.aegisub.org/); it also supports *SubRip (SRT)*,
-*MicroDVD*, *MPL2*, *TMP*, *WebVTT* and *SAMI* formats and *OpenAI Whisper* captions.
+*MicroDVD*, *MPL2*, *TMP*, *WebVTT*, *TTML* and *SAMI* formats and *OpenAI Whisper* captions.
 
 There is a small CLI tool for batch conversion and retiming.
 

Diff for: docs/api-reference.rst

@@ -131,6 +131,10 @@ Here you can find specific details regarding support of the individual subtitle
    :members:
    :show-inheritance:
 
+.. autoclass:: pysubs2.formats.ttml.TTMLFormat
+   :members:
+   :show-inheritance:
+
 .. autoclass:: pysubs2.formats.sami.SAMIFormat
    :members:
    :show-inheritance:

Diff for: docs/index.rst

@@ -3,7 +3,7 @@ pysubs2
 
 pysubs2 is a Python library for editing subtitle files. It’s based on *SubStation Alpha*,
 the native format of `Aegisub <http://www.aegisub.org/>`_; it also supports  *SubRip (SRT)*,
-*MicroDVD*, *MPL2*, *TMP*, *WebVTT* and *SAMI* formats. There is a small CLI tool for batch conversion and retiming.
+*MicroDVD*, *MPL2*, *TMP*, *WebVTT*, *TTML* and *SAMI* formats. There is a small CLI tool for batch conversion and retiming.
 
 .. code-block:: bash
 

Diff for: docs/supported-formats.rst

@@ -86,6 +86,19 @@ Implemented in :class:`pysubs2.webvtt.WebVTTFormat`.
 .. versionchanged:: 1.0.0
    Added basic support for WebVTT subtitle format.
 
+TTML
+~~~~
+
+A complex XML-based format from W3C, format identifier is ``"ttml"``. This format is capable of advanced styling,
+which is currently not supported at all by the parser, but there is some support in the writer.
+
+`Link to TTML specification <https://www.w3.org/TR/ttml1>`_, official name is
+"Timed Text Markup Language 1".
+Implemented in :class:`pysubs2.ttml.TTMLFormat`.
+
+.. versionchanged:: 1.8.0
+   Added basic support for TTML subtitle format.
+
 SAMI
 ~~~~
 
@@ -97,6 +110,9 @@ official name is "Synchronized Accessible Media Interchange".
 
 Implemented in :class:`pysubs2.sami.SAMIFormat`.
 
+.. versionchanged:: 1.8.0
+   Added basic support for SAMI subtitle format.
+
 OpenAI Whisper
 ~~~~~~~~~~~~~~
 
@@ -105,6 +121,11 @@ format identifier is ``"whisper_jax"``. Only parser is implemented.
 
 Implemented in :class:`pysubs2.whisper.WhisperJAXFormat`.
 
+.. versionchanged:: 1.8.0
+   Added support for parsing text representation of Whisper JAX output (previously,
+   only loading Whisper output directly from its Python API was supported).
+
+
 Frame-based Formats
 -------------------
 

Diff for: pysubs2/common.py

@@ -1,6 +1,8 @@
 from dataclasses import dataclass
-from typing import Tuple, Union
+from typing import Tuple, Union, Optional, Dict, Iterable, Iterator
 from enum import IntEnum
+import xml.etree.ElementTree as ET
+from contextlib import contextmanager
 
 
 @dataclass(init=False)
@@ -62,3 +64,74 @@ def to_ssa_alignment(self) -> int:
 
 
 IntOrFloat = Union[int, float]
+
+
+def etree_iter_child_nodes(elem: ET.Element) -> Iterator[Union[ET.Element, str]]:
+    """
+    Yield child text nodes (as str) and subelements for given XML element
+
+    Workaround for awkward ``xml.etree.ElementTree`` API.
+
+    See also:
+        `etree_append_child_nodes()`
+
+    """
+    if elem.text:
+        yield elem.text
+    for child_elem in elem:
+        yield child_elem
+        if child_elem.tail:
+            yield child_elem.tail
+
+
+def etree_append_child_nodes(elem: ET.Element, nodes: Iterable[Union[ET.Element, str]]) -> None:
+    """
+    Add child text nodes and subelements to given XML element
+
+    See also:
+        `etree_iter_child_nodes()`
+
+    """
+    last_child = elem[-1] if len(elem) > 0 else None
+    for node in nodes:
+        if isinstance(node, str):
+            if last_child is None:
+                if elem.text is None:
+                    elem.text = node
+                else:
+                    elem.text += node
+            else:
+                if last_child.tail is None:
+                    last_child.tail = node
+                else:
+                    last_child.tail += node
+        else:
+            elem.append(node)
+            last_child = node
+
+
+@contextmanager
+def etree_register_namespace_override() -> Iterator[None]:
+    """
+    Context manager that reverts global changes from ``xml.etree.ElementTree.register_namespace()``
+
+    Workaround for poor namespace handling in ``xml.etree.ElementTree``.
+
+    """
+    namespace_map: Optional[Dict[str, str]] = None
+    namespace_map_original_content = {}
+    try:
+        namespace_map = getattr(ET.register_namespace, "_namespace_map", None)
+        if namespace_map is not None:
+            namespace_map_original_content = namespace_map.copy()
+    except Exception:
+        pass
+
+    yield
+
+    try:
+        if namespace_map is not None:
+            namespace_map.clear()
+            namespace_map.update(namespace_map_original_content)
+    except Exception:
+        pass

Diff for: pysubs2/formats/__init__.py

@@ -8,6 +8,7 @@
 from .substation import SubstationFormat
 from .mpl2 import MPL2Format
 from .tmp import TmpFormat
+from .ttml import TTMLFormat
 from .webvtt import WebVTTFormat
 from .whisper import WhisperJAXFormat
 from ..exceptions import UnknownFormatIdentifierError, UnknownFileExtensionError, FormatAutodetectionError
@@ -23,6 +24,7 @@
     ".vtt": "vtt",
     ".sami": "sami",
     ".smi": "sami",
+    ".ttml": "ttml",
 }
 
 #: Dict mapping format identifiers to implementations (FormatBase subclasses).
@@ -37,6 +39,7 @@
     "vtt": WebVTTFormat,
     "sami": SAMIFormat,
     "whisper_jax": WhisperJAXFormat,
+    "ttml": TTMLFormat,
 }
 
 FORMAT_IDENTIFIERS = list(FORMAT_IDENTIFIER_TO_FORMAT_CLASS.keys())

Diff for: pysubs2/formats/subrip.py

@@ -44,6 +44,10 @@ def guess_format(cls, text: str) -> Optional[str]:
             # disambiguation vs. WebVTT
             return None
 
+        if "http://www.w3.org/ns/ttml" in text:
+            # disambiguation vs. TTML
+            return None
+
         for line in text.splitlines():
             if len(cls.TIMESTAMP.findall(line)) == 2:
                 return "srt"