Add support for document filters

#417

Author: palemieux

README.md

@@ -69,19 +69,15 @@ tt convert -i <input .scc file> -o <output .ttml file>
 
 * `--itype`: `TTML` | `SCC` | `STL` | `SRT` (extrapolated from the filename, if omitted)
 * `--otype`: `TTML` | `SRT` | `VTT` (extrapolated from the filename, if omitted)
-* `--config` and `--config_file`: JSON dictionaries with the following members:
-  * `"general": JSON object`: General configuration options (see below)
-  * `"imsc_writer": JSON object`: IMSC Writer configuration options (see below)
-  * `"stl_reader": JSON object`: STL Reader configuration options (see below)
-  * `"vtt_writer": JSON object`: WebVTT Writer configuration options (see below)
-  * `"srt_writer": JSON object`: SRT Writer configuration options (see below)
-  * `"scc_reader": JSON object`: SCC Reader configuration options (see below)
+* `--filter`: specifies by name a filter to be applied to the content
+* `--config` and `--config_file`: JSON dictionary where each property specifies
+  (optional) configuration parameters for readers, writers and filters.
 
 Example:
 
-`tt convert -i <.scc file> -o <.ttml file> --itype SCC --otype TTML --config '{"general": {"progress_bar":false, "log_level":"WARN"}}'`
+`tt convert -i <.scc file> -o <.ttml file> --itype SCC --otype TTML --filter lcd --config '{"general": {"progress_bar":false, "log_level":"WARN"}, "lcd": {"bg_color": "transparent", "color": "#FF0000"}}'`
 
-### General configuration
+### General configuration (`"general"`)
 
 #### progress_bar
 
@@ -109,7 +105,7 @@ Example: `"document_lang": "es-419"`
 
 Default: `None`
 
-### IMSC Writer configuration
+### IMSC Writer configuration (`"imsc_writer"`)
 
 ### time_format
 
@@ -131,7 +127,7 @@ Example:
 
 `--config '{"general": {"progress_bar":false, "log_level":"WARN"}, "imsc_writer": {"time_format":"clock_time_with_frames", "fps": "25/1"}}'`
 
-### STL Reader configuration
+### STL Reader configuration (`"stl_reader"`)
 
 #### disable_fill_line_gap
 
@@ -173,7 +169,7 @@ Specifies a maximum number of rows for open subtitles, either the MNR field of t
 
 Default: `23`
 
-### SRT Writer configuration
+### SRT Writer configuration (`"srt_writer"`)
 
 #### text_formatting
 
@@ -183,7 +179,7 @@ Default: `23`
 
 Default: `true`
 
-### VTT Writer configuration
+### VTT Writer configuration (`"vtt_writer"`)
 
 #### line_position
 
@@ -220,7 +216,52 @@ text alignment.
 
 Default: `"auto"`
 
-### Library
+### LCD filter configuration (`"lcd"`)
+
+#### Description
+
+The LCD filter merges regions and removes all text formatting with the exception
+of color and text alignment.
+
+#### safe_area
+
+`"safe_area" : <integer between 0 and 30>`
+
+Specifies the safe area (as a percentage of the height and width of the root container)
+
+Default: `10`
+
+#### color
+
+`"color" : <TTML color> | null`
+
+If not `null`, overrides text color. The syntax of `TTML color` is
+specified at <https://www.w3.org/TR/ttml2/#style-value-color>.
+
+Default: `null`
+
+Examples: `"#FFFFFF"` (white), `"white"`
+
+#### bg_color
+
+`"bg_color" : <TTML color>`
+
+If not `null`, overrides the background color. The syntax of `TTML color` is
+specified at <https://www.w3.org/TR/ttml2/#style-value-color>.
+
+Default: `null`
+
+Examples: `"#FF0000"` (red), `"transparent"`, `"black"`
+
+#### preserve_text_align
+
+`"preserve_text_align" : true | false`
+
+If `true`, text alignment is preserved, otherwise text is centered.
+
+Default: `false`
+
+## Library
 
 The overall architecture of the library is as follows:
 

setup.py

@@ -10,7 +10,7 @@
 
 setup(
     name='ttconv',
-    version='1.0.8',
+    version='1.1.0-beta.1',
     description='Library for conversion of common timed text formats',
     long_description=long_description,
     long_description_content_type='text/markdown',

src/main/python/ttconv/filters/__init__.py

@@ -1,36 +0,0 @@
-#!/usr/bin/env python
-# -*- coding: UTF-8 -*-
-
-# Copyright (c) 2020, Sandflow Consulting LLC
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions are met:
-#
-# 1. Redistributions of source code must retain the above copyright notice, this
-#    list of conditions and the following disclaimer.
-# 2. Redistributions in binary form must reproduce the above copyright notice,
-#    this list of conditions and the following disclaimer in the documentation
-#    and/or other materials provided with the distribution.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
-# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
-# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-"""Data model filter"""
-
-from ttconv.isd import ISD
-
-
-class Filter:
-  """Abstract base class for filters"""
-
-  def process(self, isd: ISD):
-    """Process the specified ISD and returns it."""
-    raise NotImplementedError

src/main/python/ttconv/filters/doc/__init__.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python
+# -*- coding: UTF-8 -*-
+
+# Copyright (c) 2023, Sandflow Consulting LLC
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice, this
+#    list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+# ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+# (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+"""Collects document instance filters"""
+
+import importlib
+import pkgutil
+import os.path
+import sys
+
+# registers all document instance filters
+
+for importer, package_name, _ in pkgutil.iter_modules([os.path.dirname(__file__)]):
+  full_name = f"{__name__}.{package_name}"
+  importlib.import_module(full_name)