Merge branch 'int-issue-119-STLXML2EBU-TT_store_source_STL_file_upon_…

…request' into 'dev' STLXML2EBU-TT: add binary data tunnelling support Closes #119 See merge request zzhd/scf!111
IRT-Open-Source · Jul 30, 2020 · 9699e2e · 9699e2e
2 parents 83c0efb + e12a7c0
commit 9699e2e
Show file tree

Hide file tree

Showing 11 changed files with 561 additions and 2 deletions.
diff --git a/modules/STLXML2EBU-TT/README.md b/modules/STLXML2EBU-TT/README.md
@@ -28,11 +28,18 @@ error message.
         If set to 1, the TCP value is used as the time-offset that's used for the TCP, TCI and TCO elements (default is 0). Thus this offset will be subtracted from the mentioned element's values.
 
     - ignoreManualOffsetForTCP
-        If set to 1, any manual offset (seconds or frames) will *not* be subtracted from the TCP value.
+        If set to 1, any manual offset (seconds or frames) will *not* be subtracted from the TCP value (default is 0).
 
     - timeBase
         Either the value 'smpte' or 'media'. It sets explicitly the ttp:timeBase attribute (default is 'smpte')
 
+    - storeSTLSourceFile
+        If set to 1, enables binary data tunnelling of the original STL source file (default is 0).
+
+    - storeSTLSourceFileAtEnd
+        If set to 1, enables storage of the tunnelled binary at the document end instead of the document head (only effective together with storeSTLSourceFile; default is 0).
+        Note that according to EBU Tech 3350 v1.0, a `tt:div` element shall have at least one `tt:p` child element. Therefore this alternative location is only compliant to v1.1 or later.
+
 
 ## DESCRIPTION
 The goal of the conversion is to create an EBU-TT-Part 1 file that can
@@ -44,6 +51,11 @@ Amongst others STLXML files with the following characteristics are *not* support
 * the TCS of a TTI element is set to 0 (timecode that is not intended for use)
 * the STLXML does not validate against the STLXML XSD
 
+Note that the mapping from EBU STL to EBU-TT is done according to
+EBU Tech 3360 v0.9 which targets EBU Tech 3350 v1.0. Therefore the
+mapping is slightly different compared to more recent versions of the
+related specifications.
+
 ## EXAMPLES
 If you use the Saxon parser (version 9.5) you could perform a 
 transformation as follows:
@@ -58,4 +70,5 @@ where `[dir]` is the directory of the Saxon jar-file.
 
 ## RESOURCES
 * [EBU STL (EBU Tech 3264)](https://tech.ebu.ch/docs/tech/tech3264.pdf)
-* [MAPPING EBU STL TO EBU-TT SUBTITLE FILES (EBU Tech 3360)](https://tech.ebu.ch/docs/tech/tech3360.pdf)
+* [MAPPING EBU STL TO EBU-TT SUBTITLE FILES (EBU Tech 3360) v0.9 (link currently refers to v1.0)](https://tech.ebu.ch/docs/tech/tech3360.pdf)
+* [EBU-TT PART 1 SUBTITLING FORMAT DEFINITION (EBU Tech 3350) v1.0](https://tech.ebu.ch/docs/tech/tech3350v1-0.pdf)
diff --git a/modules/STLXML2EBU-TT/STLXML2EBU-TT.xslt b/modules/STLXML2EBU-TT/STLXML2EBU-TT.xslt
@@ -39,6 +39,10 @@ limitations under the License.
     <xsl:param name="offsetTCP" select="0"/>
     <!--** If set to 1, any manual offset (seconds or frames) will *not* be subtracted from the TCP value -->
     <xsl:param name="ignoreManualOffsetForTCP" select="0"/>
+    <!--** If set to 1, enables binary data tunnelling of the original STL source file -->
+    <xsl:param name="storeSTLSourceFile" select="0"/>
+    <!--** If set to 1, enables storage of the tunnelled binary at the document end instead of the document head -->
+    <xsl:param name="storeSTLSourceFileAtEnd" select="0"/>
     <!--** Format that shall be used for the Time Code; supported by this transformation are 'smpte' and 'media' -->
     <xsl:param name="timeBase" select="'smpte'"/>
     <!--** Provides the tt:style elements the mapped color is located in -->
@@ -157,6 +161,12 @@ limitations under the License.
                 Files with a TCS value set to 0 are not supported by this transformation.
             </xsl:message>
         </xsl:if>
+        <!--@ Interrupt if the original STL source file is necessary, but not present -->
+        <xsl:if test="$storeSTLSourceFile = '1' and not(StlSource)">
+            <xsl:message terminate="yes">
+                If binary data tunnelling is requested, the original STL source file must be present.
+            </xsl:message>
+        </xsl:if>
         <!--@ Set frame rate according to DFC element, interrupt if the element's value is not supported; this implementation only supports a value of '25' -->
         <xsl:variable name="frameRate">
             <xsl:choose>
@@ -322,6 +332,10 @@ limitations under the License.
                 <xsl:apply-templates select="ECD"/>
                 <xsl:apply-templates select="UDA"/>
             </ebuttm:documentMetadata>
+            <!--@ Insert STL source file, if desired -->
+            <xsl:if test="$storeSTLSourceFile = '1' and $storeSTLSourceFileAtEnd != '1'">
+                <xsl:apply-templates select="/StlXml/StlSource"/>
+            </xsl:if>
             <xsl:apply-templates select="CD"/>
             <xsl:apply-templates select="RD"/>
             <xsl:apply-templates select="RN"/>
@@ -627,6 +641,14 @@ limitations under the License.
             </ebuttExt:stlRevisionNumber>
         </xsl:if>
     </xsl:template>
+
+    <xsl:template match="StlSource">
+        <!--** Structure containing the source STL file. Steps: -->
+        <!--@ Map data and filename -->
+        <ebuttm:binaryData textEncoding="BASE64" binaryDataType="EBU Tech 3264" fileName="{Filename}">
+            <xsl:value-of select="Data"/>
+        </ebuttm:binaryData>
+    </xsl:template>
 
     <xsl:template match="BODY">
         <!--** Container for the TTICONTAINER element. Steps: -->
@@ -661,6 +683,14 @@ limitations under the License.
                     <xsl:message terminate="yes">The required functions of neither EXSLT nor XSLT 2.0 are available. These are needed to retrieve the distinct TTI block SGN values.</xsl:message>
                 </xsl:otherwise>
             </xsl:choose>
+            <!--@ Insert STL source file, if desired -->
+            <xsl:if test="$storeSTLSourceFile = '1' and $storeSTLSourceFileAtEnd = '1'">
+                <tt:div>
+                    <tt:metadata>
+                        <xsl:apply-templates select="/StlXml/StlSource"/>
+                    </tt:metadata>
+                </tt:div>
+            </xsl:if>
         </tt:body>
     </xsl:template>
 

diff --git a/modules/STLXML2EBU-TT/documentation/requirements_stlxml2ebutt.pdf b/modules/STLXML2EBU-TT/documentation/requirements_stlxml2ebutt.pdf
diff --git a/modules/STLXML2EBU-TT/tests/schema/requirement-0447-001.sch b/modules/STLXML2EBU-TT/tests/schema/requirement-0447-001.sch
@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+Copyright 2014 Institut für Rundfunktechnik GmbH, Munich, Germany
+
+Licensed under the Apache License, Version 2.0 (the "License"); 
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License 
+
+at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, the subject work
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<schema xmlns="http://purl.oclc.org/dsdl/schematron"
+    queryBinding="xslt"
+    schemaVersion="ISO19757-3">
+    <ns uri="http://www.w3.org/ns/ttml" prefix="tt"/>
+    <ns uri="urn:ebu:tt:metadata" prefix="ebuttm"/>
+    <title>Testing storeSTLSourceFile Parameter without value</title>
+    <pattern id="storeSTLSourceFile">
+        <rule context="/">
+            <assert test="tt:tt/tt:head/tt:metadata">
+                The tt:metadata element must be present.
+            </assert> 
+        </rule>
+        <rule context="tt:tt/tt:head/tt:metadata">
+            <assert test="not(ebuttm:binaryData)">
+                The ebuttm:binaryData element must not be present.
+            </assert> 
+        </rule>
+    </pattern>            
+</schema>
diff --git a/modules/STLXML2EBU-TT/tests/schema/requirement-0447-002.sch b/modules/STLXML2EBU-TT/tests/schema/requirement-0447-002.sch
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+Copyright 2014 Institut für Rundfunktechnik GmbH, Munich, Germany
+
+Licensed under the Apache License, Version 2.0 (the "License"); 
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License 
+
+at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, the subject work
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<schema xmlns="http://purl.oclc.org/dsdl/schematron"
+    queryBinding="xslt"
+    schemaVersion="ISO19757-3">
+    <ns uri="http://www.w3.org/ns/ttml" prefix="tt"/>
+    <ns uri="urn:ebu:tt:metadata" prefix="ebuttm"/>
+    <title>Testing storeSTLSourceFile Parameter with value 1</title>
+    <pattern id="storeSTLSourceFile">
+        <rule context="/">
+            <assert test="tt:tt/tt:head/tt:metadata/ebuttm:binaryData">
+                The ebuttm:binaryData element must be present.
+            </assert> 
+        </rule>
+        <rule context="tt:tt/tt:head/tt:metadata/ebuttm:binaryData">
+            <assert test="@textEncoding = 'BASE64'">
+                Expected value: BASE64. Value from test: <value-of select="@textEncoding"/>
+            </assert>
+            <assert test="@binaryDataType = 'EBU Tech 3264'">
+                Expected value: EBU Tech 3264. Value from test: <value-of select="@binaryDataType"/>
+            </assert>
+            <assert test="@fileName = 'input.stl'">
+                Expected value: input.stl. Value from test: <value-of select="@fileName"/>
+            </assert>
+            <let name="expected" value="'ODUwU1RMMjUuMDExMDAwOFNUTCBUZXN0IERhdGEgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBzdWJ0aXRsZXNAaXJ0LmRlICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAxNDA1MDIxNDA1MDIwMTAwMDA1MDAwMDMwMDE0MDIzMTAwMDAwMDAwMDAwMDAwMDAxMURFVUluc3RpdHV0IGZ1ZXIgUnVuZGZ1bmt0ZWNobmlrICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIFVEQSAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIAEBAP8AAAAAAAAAAwAUAgANCwtUZXN0OiB0cmFuc2Zvcm1hdGlvbiBwYXJhbSAtYgoKj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+PAQIA/wAAAAsAAAAPABYBACAgICAgICAgICAgDQsLRW5kIG9mIFRlc3QuCgogICAgICAgICAgICCPj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj48='"/>
+            <assert test=". = $expected">
+                Expected value: "<value-of select="$expected"/>" Value from test: "<value-of select="."/>"
+            </assert>
+        </rule>
+    </pattern>            
+</schema>
diff --git a/modules/STLXML2EBU-TT/tests/schema/requirement-0448-001.sch b/modules/STLXML2EBU-TT/tests/schema/requirement-0448-001.sch
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+Copyright 2014 Institut für Rundfunktechnik GmbH, Munich, Germany
+
+Licensed under the Apache License, Version 2.0 (the "License"); 
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License 
+
+at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, the subject work
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<schema xmlns="http://purl.oclc.org/dsdl/schematron"
+    queryBinding="xslt"
+    schemaVersion="ISO19757-3">
+    <ns uri="http://www.w3.org/ns/ttml" prefix="tt"/>
+    <ns uri="urn:ebu:tt:metadata" prefix="ebuttm"/>
+    <title>Testing storeSTLSourceFileAtEnd Parameter without value</title>
+    <pattern id="storeSTLSourceFileAtEnd">
+        <rule context="/">
+            <assert test="tt:tt/tt:head/tt:metadata/ebuttm:binaryData">
+                The ebuttm:binaryData element must be present.
+            </assert> 
+        </rule>
+    </pattern>            
+</schema>
diff --git a/modules/STLXML2EBU-TT/tests/schema/requirement-0448-002.sch b/modules/STLXML2EBU-TT/tests/schema/requirement-0448-002.sch
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+Copyright 2014 Institut für Rundfunktechnik GmbH, Munich, Germany
+
+Licensed under the Apache License, Version 2.0 (the "License"); 
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License 
+
+at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, the subject work
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<schema xmlns="http://purl.oclc.org/dsdl/schematron"
+    queryBinding="xslt"
+    schemaVersion="ISO19757-3">
+    <ns uri="http://www.w3.org/ns/ttml" prefix="tt"/>
+    <ns uri="urn:ebu:tt:metadata" prefix="ebuttm"/>
+    <title>Testing storeSTLSourceFileAtEnd Parameter with value 1</title>
+    <pattern id="storeSTLSourceFileAtEnd">
+        <rule context="/">
+            <assert test="tt:tt/tt:body/tt:div[last()]/tt:metadata/ebuttm:binaryData">
+                The ebuttm:binaryData element must be present.
+            </assert> 
+        </rule>
+    </pattern>            
+</schema>
diff --git a/modules/STLXML2EBU-TT/tests/test_files/requirement-0447-001.xml b/modules/STLXML2EBU-TT/tests/test_files/requirement-0447-001.xml
@@ -0,0 +1,86 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+Copyright 2014 Institut für Rundfunktechnik GmbH, Munich, Germany
+
+Licensed under the Apache License, Version 2.0 (the "License"); 
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License 
+
+at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, the subject work
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+<!-- Testing storeSTLSourceFile Parameter without value -->
+<StlXml>
+    <HEAD>
+        <GSI>
+            <CPN>850</CPN>
+            <DFC>STL25.01</DFC>
+            <DSC>1</DSC>
+            <CCT>00</CCT>
+            <LC>09</LC>
+            <OPT/>
+            <OET/>
+            <TPT/>
+            <TET/>
+            <TN/>
+            <TCD/>
+            <SLR>String length 16</SLR>
+            <CD>991231</CD>
+            <RD>991231</RD>
+            <RN>0</RN>
+            <TNB>1</TNB>
+            <TNS>1</TNS>
+            <TNG>1</TNG>
+            <MNC>40</MNC>
+            <MNR>23</MNR>
+            <TCS>1</TCS>
+            <TCP>00000000</TCP>
+            <TCF>00000000</TCF>
+            <TND>1</TND>
+            <DSN>1</DSN>
+            <CO>GBR</CO>
+            <PUB/>
+            <EN/>
+            <ECD/>
+        </GSI>
+    </HEAD>
+    <BODY>
+        <TTICONTAINER>
+            <TTI>
+                <SGN>1</SGN>
+                <SN>1</SN>
+                <EBN>FF</EBN>
+                <CS>00</CS>
+                <TCI>00000000</TCI>
+                <TCO>00000200</TCO>
+                <VP>1</VP>
+                <JC>02</JC>
+                <CF>00</CF>
+                <TF>
+                    <StartBox/>
+                    <space/>
+               <space/>
+               <space/>
+               <space/>
+               <space/>Test<space/>Subtitle<space/>
+               <space/>
+               <space/>
+               <space/>
+               <space/>
+               <space/>
+                    <EndBox/>
+                </TF>
+            </TTI>
+        </TTICONTAINER>
+    </BODY>
+    <StlSource>
+        <Filename>input.stl</Filename>
+        <Data>ODUwU1RMMjUuMDExMDAwOFNUTCBUZXN0IERhdGEgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBzdWJ0aXRsZXNAaXJ0LmRlICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAxNDA1MDIxNDA1MDIwMTAwMDA1MDAwMDMwMDE0MDIzMTAwMDAwMDAwMDAwMDAwMDAxMURFVUluc3RpdHV0IGZ1ZXIgUnVuZGZ1bmt0ZWNobmlrICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIFVEQSAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIAEBAP8AAAAAAAAAAwAUAgANCwtUZXN0OiB0cmFuc2Zvcm1hdGlvbiBwYXJhbSAtYgoKj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+PAQIA/wAAAAsAAAAPABYBACAgICAgICAgICAgDQsLRW5kIG9mIFRlc3QuCgogICAgICAgICAgICCPj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj4+Pj48=</Data>
+    </StlSource>
+</StlXml>