Improved EBU-TT-D encoding, including better tests and denester

.gitignore

@@ -51,6 +51,9 @@ coverage.xml
 *,cover
 .hypothesis/
 
+# Pytest cache
+.pytest_cache/
+
 # Translations
 *.mo
 *.pot

docs/source/configurator.rst

@@ -125,6 +125,9 @@ Node type dependent options for [nodeN] : ::
 
    type="distributor" : No options
 
+   type="denester"
+   └─sequence_identifier : sequence identifier, default "Denester1"
+
 Output carriage type dependent options for "carriage": ::
 
    type="direct"

docs/source/denesting.rst

@@ -0,0 +1,37 @@
+Denesting of EBU-TT-Live documents
+======================================
+
+DenesterNode should be used when a EBU-TT-3 document has a div that contains
+other divs, or a span contains another span, and those nested elements need
+to be flattened, for example before conversion to EBU-TT-D. These elements
+are not able to be nested inside each other in EBU-TT-D documents.
+
+When documents are Denested, any nested elements must be removed from
+their parent elements, while retaining attributes they would have inherited.
+To address this, the DenesterNode node processes the
+document(s) with the
+:py:func:`ebu_tt_live.node.denester.DenesterNode.recurse` and
+:py:func:`ebu_tt_live.node.denester.DenesterNode.recurse_span`
+functions. These will iterate through the file to locate the deepest
+nested element, and create a new copy of it with its content and
+expected inherited attributes. The end result is a file containing
+these newly created divs/spans in place of the nested ones.
+
+Once the new divs and spans are created, divs that are sequential in
+the list of divs and have the same attributes are combined into a single
+div. This is done by the
+:py:func:`ebu_tt_live.node.denester.DenesterNode.combine_divs`
+function to reduce the number of divs in the resulting file.
+
+In the combined divs, every p element should have the same region
+as its parent div. Any p elements that specify a different region
+to their inherited region are removed here: as per TTML semantics,
+such p elements are never presented.
+The
+:py:func:`ebu_tt_live.node.denester.DenesterNode.check_p_regions`
+function iterates through the divs that have an assigned region and
+removes any p where its region does not match.
+It then removes the region attribute from any remaining p, as it will
+inhert the region of its parent div and the attribute is unnecessary.
+It will also remove any now-empty divs that exist as a result of having
+their p elements removed.

docs/source/ebu_tt_live.node.rst

@@ -80,3 +80,11 @@ node Package
     :members:
     :undoc-members:
     :show-inheritance:
+
+:mod:`denester` Module
+----------------------
+
+.. automodule:: ebu_tt_live.node.denester
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/inode.puml

@@ -70,6 +70,11 @@ class BufferDelayNode {
   +process_document()
 }
 
+class DenesterNode{
+  ..methods..
+  +process_document()
+}
+
 class RetimingDelayNode{
   ..methods..
   +process_document()

docs/source/overview.rst

@@ -18,4 +18,5 @@ The components mimic the nodes and carriage mechanisms defined in the specificat
     timing_resolution
     segmentation
     deduplication
+    denesting
     conversion

docs/source/scripts_and_their_functions.rst

@@ -107,6 +107,17 @@ attributes are duplicated.
 For the default configuration of the node, see:
 ``ebu-run --admin.conf=ebu_tt_live/examples/config/deduplicator_fs.json``
 
+Denester Node
+-------------
+This node flattens nested ``div`` and ``span`` elements such that no
+``div`` ends up containing a ``div`` and no ``span`` ends up containing
+a ``span``. It also removes any ``p`` elements that specify a ``region``
+attribute that differs from a specified region on an ancestor element.
+
+If nested ``div`` or ``span`` elements might be present in a document, the
+Denester node should be used to flatten them before passing them to the
+EBU-TT-D Encoder, because EBU-TT-D does not permit such nested elements.
+
 Retiming Delay Node
 -------------------
 This script modifies the times within each Document and issues them without

ebu_tt_live/adapters/document_data.py

@@ -106,7 +106,7 @@ def __init__(self, media_clock=None):
         self._converter = EBUTT3EBUTTDConverter(media_clock=media_clock)
 
     def convert_data(self, data, **kwargs):
-        return EBUTTDDocument.create_from_raw_binding(self._converter.convert_document(data)), kwargs
+        return EBUTTDDocument.create_from_raw_binding(self._converter.convert_document(data.binding)), kwargs
 
 
 def get_document_data_adapter(expects, provides):