__ ___ __ __
|__) |__ / _` \_/ |\/| | | | |__)
| \ |___ \__> / \ | | |___ |___ | |__)
INTRODUCTION
============
regxmllib is a collection of tools and libraries for the creation of
RegXML (SMPTE ST 2001-1) representations of MXF header metadata
(SMPTE ST 377-1). A RegXML Fragment example can be found at [1]
[1] src/test/resources/reference-files
Two implementations of regxmllib are provided:
* regxmllibj, which is implemented in pure Java; and
* regxmllibc, which is implemented in C++03.
KNOWN ISSUES AND LIMITATIONS
============================
regxmllib relies on SMPTE Metadata Registers that conform to SMPTE ST 335,
ST 395, ST 400, ST 2003. These registers are published at [1].
[1] https://smpte-ra.org/smpte-metadata-registry
regxmllib deviates from ST 2001-1:2013 in a few narrow instances. Such deviations
are noted in the source code and are expected to be submitted for consideration at
the next revision of ST 2001-1. In particular:
* no baseline metadictionary is used, instead one extension metadictionary per
namespace is used
Bugs are tracked at [2]
[2] https://github.com/sandflow/regxmllib/issues
REGXMLLIBJ
==========
Prerequisites
-------------
Java 11 and above
Maven
(recommended) Git
(recommended) SMPTE Metadata Registers (Types, Elements, Groups and Labels)
Quick Start
-----------
The following outputs to path PATH_TO_FRAGMENT an XML representation
of the header metadata of the MXF file at path PATH_TO_MXF_FILE
* `mvn package -Pwith-dependencies`
* choose one of the following:
* OPTION 1
* retrieve the four SMPTE Metadata Registers (see [1] above)
* build the metadictionaries from the SMPTE registers
java -cp <PATH_TO_JAR> com.sandflow.smpte.tools.XMLRegistersToDict -e <PATH_TO_ELEMENTS_REG>
-l <PATH_TO_LABELS_REG> -g <PATH_TO_GROUPS_REG> -t <PATH_TO_TYPES_REG> PATH_TO_DICT_DIR
* OPTION 2
* retrieve metadictionaries from [3]
[3] https://github.com/sandflow/IMF/tree/master/dict
* generate the RegXML fragment
run java -cp target/regxmllib-jar-with-dependencies.jar com.sandflow.smpte.tools.RegXMLDump -all -d <PATH_TO_DICT1> <PATH_TO_DICT2> ...
-i <PATH_TO_MXF_FILE> > <PATH_TO_FRAGMENT>
* (optional) generate XSDs for RegXML Fragments
run java -cp target/regxmllib-jar-with-dependencies.jar com.sandflow.smpte.tools.GenerateDictionaryXMLSchema -d <PATH_TO_DICT1> <PATH_TO_DICT2> ...
-o <PATH_TO_OUTPUT_DIR>
* (optional) generate XSDs for SMPTE registers
run java -cp target/regxmllib-jar-with-dependencies.jar com.sandflow.smpte.tools.GenerateXMLSchemaDocuments -cp <CLASS_PATH_TO_REGISTER_MODEL>
-d <PATH_TO_OUTPUT_DIR>
where <CLASS_PATH_TO_REGISTER_MODEL> is equal to com.sandflow.smpte.register.catsup.TypesRegisterModel, etc.
Architecture
------------
At the heart of regxmllib is the FragmentBuilder.fragmentFromTriplet() method
that creates an XML fragment from a KLV group given a
a RegXML metadictionary and a collection of KLV groups from which strong
references are resolved. The rules engine implemented in
FragmentBuilder.fragmentFromTriplet() is intended to follow the rules specified
in ST 2001-1 as closely as possible. A sister method, XMLSchemaBuilder.fromDictionary(),
creates a matching XML Schema that can be used to validate RegXML fragments.
Metadictionaries can be imported and exported from XML documents that conform
to the schema specified in SMPTE ST 2001-1. They can also be created
from SMPTE Metadata Registers published in XML form.
regxmllib includes a minimal MXF and KLV parser library.
Packages
--------
com.sandflow.smpte.klv : Classes for processing SMPTE KLV triplets (ST 336)
com.sandflow.smpte.mxf: Classes for processing SMPTE MXF structures (ST 377-1)
com.sandflow.smpte.register: Classes for processing SMPTE metadata registers
(ST 335, ST 395, ST 400, ST 2003)
com.sandfow.smpte.regxml: Classes for managing RegXML metadictionaries and
creating RegXML representations of MXF structures
com.sandfow.smpte.tools: Application-level tools
com.sandfow.smpte.util: Utilities classes
Tools
-----
RegXMLDump: dumps either the first essence descriptor or the entire header
metadata of an MXF file as a RegXML structure
XMLRegistersToDict: converts XML-based SMPTE metadata registers to a RegXML metadictionaries
GenerateXMLSchemaDocuments: generates XSDs for the SMPTE metadata registers
GenerateDictionaryXMLSchema: generate XSDs for RegXML Fragments from the RegXML metadictionaries
Unit Test
---------
Unit testing is performed by generating RegXML fragments from sample files located
at [1] and registers located at [2]. The resulting RegXML fragments are compared
to reference RegXML fragments located at [3].
[1] src/test/mxf-files
[2] src/test/registers
[3] src/test/regxml-files
Reference RegXML fragments can regenerated by running the package goal with the build-reference-test-files profile:
mvn package -Pbuild-reference-files
Maven Artifacts
---------------
* GroupId com.sandflow
* ArtifactId regxmllib
Snapshots are deployed at https://oss.sonatype.org/content/repositories/snapshots/
Releases are deployed at the central repository
REGXMLLIBC
==========
Prerequisites
-------------
C++03 toolchain
Metadictionaries generated by regxmllibj (see _Building Metadictionaries_ above)
Xerces-C++ Version 3.1.4 (or above) [1]
(recommended) CMake
[1] https://xerces.apache.org/xerces-c/
Architecture
------------
regxmllibc generally follows the architecture and idioms of regxmllibj.
Applications will typically call FragmentBuilder::fromTriplet() or
MXFFragmentBuilder::fromInputStream(), and the unit test at [1] provides an example.
[1] src/test/cpp/com/sandflow/smpte/dict/MetaDictionaryTest.cpp
regxmllibc does not however support the conversion of the SMPTE Metadata Registers to
RegXML metadictionaries, and instead relies on the metadictionaries generated by
regxmllibj (see _Building Metadictionaries_ above).
Unit Test
---------
As with regxmllibj, unit testing is performed by generating RegXML fragments from sample files located
at [1] and reference metadictionaries located at [2]. The resulting RegXML fragments are compared
to reference RegXML fragments located at [3].
[1] src/test/mxf-files
[2] src/test/regxml-dicts
[3] src/test/regxml-files
DIRECTORIES AND NOTABLE FILES
=============================
build.xml Helper script (Ant)
pom.xml Maven POM file
CMakeLists.txt CMake build file
target Output of the Maven build process, including the JAR
src/java regxmllibj codebase
src/cpp regxmllibc codebase
src/main/config/repoversion.properties
Template Java properties file used to host the
a unique source code version generated using
git by the build system
src/main/resources/reg.xsd
Common XML Schema definitions used when generating
XML Schemas for RegXML Fragments
src/test/resources/regxml-files
Reference RegXML fragment used for unit testing
src/test/resources/registers
Reference SMPTE registers used for unit testing
src/test/resources/mxf-files
Sample MXF files used for unit testing
src/test/resources/regxml-dicts
Reference metadictionaries used for unit testing
