Copyright (c) 2015 Digital Entertainment Content Ecosystem (DECE) LLC

DECEmate - the CFF file analyzer

============
Installation
============
DECEmate, the CFF Verifier, runs on Windows, MacOS X, and Linux. The
distribution comes as a .zip file containing the following files:
--doc/sample.config, this readme, and release notes
--win32/decemate.exe
--osx/decemate
--linux32/decemate
--linux64/decemate
--schemas/
	cff-tt-image*-{DMEDIA_VERSION_POINTS}.xsd, 
	cff-tt-meta-{DMEDIA_VERSION_POINTS}.xsd, 
	cff-tt-text*-{DMEDIA_VERSION_POINTS}.xsd,
	md.xsd, 
	mddece-{DMEDIA_VERSION_POINTS}.xsd, 
	subtitle-analyzer-schema.xsd, 
	ttaf1-dfxp-core-attribs.xsd,
        xml.xsd
	W3CSoftwareNoticeandLicense.docx,
        DECE-Notices-20130923.docx
   where {DMEDIA_VERSION_POINTS} indicates the version of the [CFF] specification,
   as defined in [CFF], Annex E.
--liberation-fonts-ttf-2.00.1/
        LiberationMono-Bold.ttf
        LiberationMono-BoldItalic.ttf
        LiberationMono-Italic.ttf
        LiberationMono-Regular.ttf
        LiberationSans-Bold.ttf
        LiberationSans-BoldItalic.ttf
        LiberationSans-Italic.ttf                
        LiberationSans-Regular.ttf
        LiberationSerif-Bold.ttf
        LiberationSerif-BoldItalic.ttf
        LiberationSerif-Italic.ttf
        LiberationSerif-Regular.ttf

Place the executable appropriate to your operating system somewhere in your
path. 

Copy doc/sample.config to your current directory, and rename it to 
'decemate.config'.

Copy all schema (*.xsd) files from the schemas directory to a directory that
will be accessible when running DECEmate. If the cff-tt-meta, md, and mddece
schema file names differ from what's listed above -- e.g., mddece-1.1.xsd --
override the default file names either in the configuration file or with the
-h command-line option.

Copy all font (*.ttf) files from the liberation-fonts-ttf-2.00.1 directory to
a directory that will be accessible when running DECEmate.

Previous releases required you to acquire the W3C TTML schemas and the SMPTE-TT
schema. As of the v0.16 release, this step is no longer required. If you 
previously acquired the W3C TTML and SMPTE-TT schemas, either remove them or 
move them to a location not pointed to by the config file's schemaDirectory 
setting.

Edit the decemate.config file, taking care to set the following lines to match
your machine's configuration:

	----------------
	output_directory

	This field should be either an absolute or relative path. It will be 
	the location where DECEmate places its output files. The path MUST 
	exist; DECEmate will NOT create it for you.

	The format for the directory path depends on your operating system. 
	For Windows platforms, it might look like this:

		output_directory = D:\DecemateOutput

	while on Linux or MacOS it might look like this:

		output_directory = /var/decemate_output

	----------------
	stream_directory

	This line tells DECEmate where to look for input files (.uvu files). 
	It is formatted similarly to the output_directory line. If left empty, 
	it looks in the current directory, or an absolute path must be 
	specified on the command line. Example:

		stream_directory = E:\UVUFiles

	----------------
	md_schema_name/mddece_schema_name

	These two lines tell DECEmate to override the default schema names. For
	example, this will override the md.xsd file name:

		md_schema_name = md-1.0.3-Amendment-1.xsd

	This will override the mddece.xsd file name:

		mddece_schema_name = mddece-1.0.3-Amendment-1.xsd


	----------------
        sansregfont
        sansboldfont
        sansitalfont
        sansbolditalfont
        monoregfont
        monoboldfont
        monoitalfont
        monobolditalfont

        These lines indicate the path to the required font files, e.g.,
                sansregfont = D:\liberation-fonts-ttf-2.00.1\LiberationSans-Regular.ttf
                sansboldfont = D:\liberation-fonts-ttf-2.00.1\LiberationSans-Bold.ttf
                sansitalfont = D:\liberation-fonts-ttf-2.00.1\LiberationSans-Italic.ttf
                sansbolditalfont = D:/liberation-fonts-ttf-2.00.1\LiberationSans-BoldItalic.ttf
                monoregfont = D:\liberation-fonts-ttf-2.00.1\LiberationMono-Regular.ttf
                monoboldfont = D:\liberation-fonts-ttf-2.00.1\LiberationMono-Bold.ttf
                monoitalfont = D:\liberation-fonts-ttf-2.00.1\LiberationMono-Italic.ttf
                monobolditalfont = D:\liberation-fonts-ttf-2.00.1\LiberationMono-BoldItalic.ttf   


================
Running DECEmate
================
To analyze a CFF file, simply type on the command line:
	decemate <filename.uvu>

A directory will be created under the output_directory. Its name will be the
date plus the name of the file without the .uvu extension. Within this output
directory, several files will be created:
--box_map.txt
--box_map.xml
--results.xml
--<track files, if demux is set to true>
--subtitles/extracted subtitle files (if present)

The box_map.txt file shows a map of the boxes found within the CFF file, along
with their file offset in bytes. Any boxes that contained errors will be
marked with an 'E' in the first column. Warnings show 'W', and boxes that are
not currently processed show a '?'.

The box_map.xml file contains the boxes with additional information about each
box in XML format. The general format of the file is:
	<cff filename="filename">
	  <box ...>
	  </box>
	</cff>

Information about boxes is contained either as attributes or as lists.

VeriferReport.xml contains a list of errors and warnings generated by the 
Verifier. It is more or less the same information that is displayed in the 
output to the screen when the Verifier is run.

Running under Linux os requires glibc version 2.15 or greater

================
Filtering Output
================
The output of the Verifier may be filtered to show more or less information.
While this does not affect the contents of the box_map.txt or box_map.xml
files, it does limit what is printed to the console.

The general output level is set in the config file with the message_level
line, or with the -l command-line option. The message_level may be set to 
one of:

  error         The default, only prints out errors
  warning       Prints out errors and warnings
  info          Prints out errors, warnings and detailed information about
                each box (this is a LOT of information!)
  hexdump       In addition to data printed out by the info setting, also
                prints out the data found in the box in hexadecimal and 
                ASCII

For more fine-grained control, the message level for particular boxes can also
be set using the box_message_level line, or the -b command-line option, e.g.:

	box_message_level traf=info, moof=warning


============
Color Output
============
The color line in the config file, or the -p command-line option, enables
color output on a terminal that supports such output.

In Windows, color in a DOS box is not supported. To see color output on
Windows, install Cygwin and the rxvt-native terminal emulator, and run
DECEmate from within the rxvt window.


===================================================
Demultiplexing Tracks and Validating Track Contents
===================================================
To enable the demultiplexing of tracks, and to validate that track contents 
meet the constraints described by the CFF specification, either specify 
'demux = true' in the config file or use the -x command-line option. Tracks 
will be demultiplexed into the output_directory with filenames in this format:

	track-<track ID>-<box name>.dat

These files can be used to compare the decrypted output of encrypted tracks vs.
the output of the same, unencrypted tracks; or for finding where certain  
sequences of data ended up in the file. Note that, with the exception of AC-3 
audio, the demuxed track data will NOT be playable. 

HEVC conformance tests will also be enabled to validate constraints as specified
by the Hypothetical Reference Decoder (HRD) through a Coded Picture Buffer
(CPB).  The HRD operates at the Access Unit level (as compared to a Decoding 
Unit) and selects the Highest Temporal ID present in the bitstream (performing 
no Sub-bitstream extraction process).
  - Comma separated value files will be generated with filenames in this format:

      cpb_decoding_series-<SchedSelIdx>.csv
      cpb_time_series-<SchedSelIdx>.csv
      cpb_rates-<SchedSelIdx>.csv

  - Gnuplot plot scripts will be generated with filenames in this format:

      cpb_decoding_series-<SchedSelIdx>.plt
      cpb_time_series-<SchedSelIdx>.plt

Where applicable, 'SchedSelIdx' is the index of the selected Hypothetical 
Stream Scheduler's (HSS) schedule.

The 'cpb_decoding_series' plots Access Unit Size versus Access Unit
Number and 'cpb_time_series' plots Coded Picture Buffer (CPB) Occupancy 
versus Time.  It may be necessary to specify the directory containing both
the comma separated value files and gnuplot plot script file using the
gnuplot directive 'set loadpath'.  This can be done by manually editing 
the gnuplot script or via gnuplot's command window.  The x-axis in both 
plots can be independently zoomed using CTRL-SHIFT-<mouse wheel> and 
scrolled by SHIFT-<mouse wheel>.  Gnuplot version 4.6 is sufficient.

=================
Decrypting Tracks
=================
If demultiplexing is enabled, tracks can also be decrypted if the key is
provided. Add one or more lines into the config file with the key ID and key.
The format should be:

	KeyID:Key

Each value should be 32 characters long (16 bytes). Note that the KeyID is not 
a little-Endian GUID, but rather the actual hex value of the KeyID, exactly as 
it appears in the CFF file, e.g.,:

	key = fffffffffffffff00000000000000000:ABCDEF01234567890FEDCBA987654321

For security reasons, the key does not appear in any output.  Instead, the text
"***redacted***" appears.  This may be overridden with the -y command-line 
option.


=====================
Output Subdirectories
=====================
The default behavior of DECEmate is to create a subdirectory under
output_directory for each run. The output subdirectory is generally in the
format:

	<date+time>-<filename without .uvu extension>

During testing, this can lead to a large number of subdirectories. To have
output placed only in output_directory without creating subdirectories,
specify:

	skip_subdirectory = yes

in the config file.


====================
Command-Line Options
====================
Options specified on the command line override options set in the config file,
with the exception of KID:key lines, which are appended to the list of KIDs.

The various options are listed here:

 -c <config file>                  Configuration file path
 -n                                Do Not use config file
 -l <level>                        Set default message Level. Options are:
                                   error, warning, info
 -p                                Pretty color output
 -o <directory>                    Output directory path
 -s <directory>                    Source (stream) directory
 -u                                Analyze sUbtitle XML documents
 -j                                Analyze MP containers
 -m <directory>                    ScheMa directory (default: schemas)
 -h [md=filename1][,mddece=filename2]
                                   Set the xml schema names (default: md.xsd, 
                                   mddece.xsd)
 -b box1=level,[box2=level2],...   Set box output levels
 -z                                Enable debug output
 -r                                Print Release version and exit
 -k KID:key                        Specify a decryption Key ID / key as a hex 
                                   string
 -y                                Print keYs in output
 -x                                DemultipleX tracks
 -v                                Verbose output
 -t                                Validate DTS audio elementary stream biTrates
 -d                                set Dcc state.  Options are:
                                   o, original, f, fulfillmentready, 
                                   l, licensed
 -a <report file>                  ReAd and validate a report file
 -w <subtitle track(s) metadata xml file>
                                   Validate standalone CFF-tt files prior to 	
				   integrating into .uvu file
 -e <initial_cpb_removal_delay>,<initial_cpb_removal_delay_offset>,<cbr_mode>
                                   HRD paramEters
