Skip to content

How to use Digital Cinema Tools

Jump to bottom
Joel Brun edited this page Jun 23, 2023 · 30 revisions

dcp_inspect

How to validate and inspect a DCP with dcp_inspect

Run

dcp_inspect DCP_TEST

for a full-blown report about the package in DCP_TEST. See Examples for more.

Tips

  • How to set up autolog: dcp_inspect can -- apart from the standard logfile output you request with the --logfile <path> option -- automatically generate a logfile for each run. Add these 2 lines to your .bashrc:
export DCP_INSPECT_DIR=$HOME/dcp_inspect # This is an example location
export DCP_INSPECT_AUTOLOG=true
  • When run without any options dcp_inspect will perform full-on integrity checks, including the costly hash checks. Meaning it will have to churn through dozens if not a couple hundreds of Gigabytes. That takes time. Sometimes all you want is a quick overview of what the compositions in a package are made up of. In that case use the --no-hashoption:
dcp_inspect --no-hash DCP_TEST
  • Use the --hash-limit option when you can't afford to spend an hour on checking large assets but still would like to check as much as possible (CPLs, sound assets, subtitle trackfiles, fonts and images):
dcp_inspect --hash-limit 10GB DCP_TEST

Here dcp_inspect will skip hash checks for assets which are bigger than 10 GB. Use a number and an optional symbol (KB, MB, GB) to set the limit. Thanks to Mattias Mattsson for suggesting the feature.

  • Use the --logfile option to make dcp_inspect write a full log to a file. If requested the logfile will contain all of dcp_inspect's messages, independent from the verbosity level you've set with -v or --verbosity.

  • Standalone version packages might not include some or all of the assets a VF CPL references. If run on the VF package alone dcp_inspect will report errors regarding these missing assets. If you have the OV and the VF package sitting next to each other you can use the --as-asset-store option to merge all mapped assets and check if the VF references will be satisfied:

dcp_inspect --as-asset-store DCP_TEST
  • Run dcp_inspect in a wide terminal. It prints some long lines and reading these in a 80x24 sized terminal is no fun at all. E.g. I use a fullscreen 200x50 terminal.

How to read and interpret dcp_inspect's error messages

There are 2 answers: One is short and simple. The other is not short and a little less simple.

Here's the short answer:

  • dcp_inspect will essentially produce 3 types of messages: Errors, hints and info. Errors you want to deal with, take back to your authoring system vendor or trigger in-house procedures' checks. Hints are mostly informational but with an edge. Read them and and pick whatever you can to maybe amend authoring procedures (e.g. package and composition naming). Info is purely informational.

  • If you get Schema errors go ask the authors/vendors of the DCP authoring tool to fix those. The examined package might still play fine on a digital cinema system. But you can't rely on it.

  • All other errors will quite likely mean that the examined package won't play. Go ask the packager to fix these issues.

Here's the long answer:

Depending on your point of view a DCP (Digital Cinema Package) is either simple or complex: A bunch of files is mapped to numbers, collected and listed in a package and referenced by a playlist. Digital cinema systems will do their best to extract all critical information whenever a user hits Play. Elegant and simple indeed, no rocket science involved.

But of course, as with many apparently simple systems, le bon Dieu est dans le détail:

DCP trackfiles (pictures, sound, timed text) are wrapped in a thoroughly specified MXF container variant. Every bit, every number, every index entry in there has to be just right. The widely used asdcplib will hide away all the gory details. But once implementors steer off that track results might be up for grabs.

The descriptive infrastructure used in a DCP is written in XML. XML is a very flexible language and there is more than one way to say whatever you want to express with it. Flexibility can turn into quicksand fast, though. Thus the inventors came up with Document Type definitions and later on XML Schema which allow to constrain any given XML template. The XML infrastructure used in digital cinema is well-defined through a set of XML Schema definitions and that should be the end of that story.

Alas, it ain't that easy: One can think of the development of digital cinema up to this day as one huge transition. Early systems went out to the field while the required standards were not complete/balloted/published yet. Once out there those systems had to be upgraded whenever significant spec changes occurred (if possible at all). On the other hand the specification process had to keep legacy systems in mind whenever the standards in progress were amended and modified. It is a fascinating bootstrapping process (some call it a scary ride). And it really is quite an impressive achievement that we have the (mostly) working systems we have today.

This back and forth led to a bouquet of implementation variants, quirks and bad habits, though: Some systems will validate XML/MXF laxly or not at all and accept all kinds of creative packages (with undefined results). Others will do full validation and reject problematic packages entirely. Some systems will fail the intended validation in part, some in large parts.

Some packaging facilities have collected all those quirks and oddities and turned them into bad habits. They are cherishing their collection of trade secrets and produce packages that won't match specifications, won't pass XML Schema validation and yet play fine on most installations.

So what's the big deal then?, you may ask. And here's what:

The only thing we can rely upon is a mid- to long-term convergence of all digital cinema systems towards full specifications compliance. That goes for authoring systems as well as playback systems. We are not there yet, not by a long shot. We will get there. But in order to achieve it we must insist on correct implementations down to the most minute details -- even if our DCPs ingest and playback just fine on any given legacy system.

Please help by taking dcp_inspect's error messages back to the authors of your DCP authoring system. Bug them about these issues, urge them to fix and amend whatever they can.

See the short answer above for how to deal with dcp_inspect's errors, hints and info.

How to control dcp_inspect's verbosity

The default verbositiy level of dcp_inspect is quite chatty. If you don't care for lots of UUIDs etc. flashing by use --v info (or --verbosity info). Other options are quiet, errors, hints, debug or cpl. Specify multiple cutouts like '-v errors,info' (Default: debug)

dcp_inspect DCP_TEST -v info

dcp_inspect will return proper exit codes so you can include it in scripted environments like automated testing (How to use dcp_inspect's exit codes). Use -v quiet and check $?.

See Example output from dcp_inspect for more.

How to control dcp_inspect's author's verbosity

Every once in a while Lu tells me to shut it.

How to use dcp_inspect's exit codes

Script exit codes are useful when you need to run a tool in conjunction with other tools and control flow based on the results. dcp_inspect will return these exit codes:

  • 0 : No errors in the examined DCP(s)
  • 1 : Errors in the examined DCP(s)
  • 2 : No argument given (Running dcp_inspect without argument)
  • 3 : Too many arguments given (dcp_inspect will accept exactly 1 argument: a directory on your filesystem)
  • 4 : Argument is not a directory

and

  • 5 : XML Catalog not found
  • 6 : XSD Store not found

The latter 2 shouldn't occur but if they do your installation is borked. Rerun digital-cinema-tools-setup to repair.

Then there are

  • 7 : The argument for the --hash-limit option is invalid. See dcp_inspect --help
  • 8 : Could not write logfile
  • 9 : File access error
  • 10 : Requested logfile exists and dcp_inspect refuses to overwrite (Use --overwrite-logfile or -L to overwrite)
  • 11 : Failed to load a required ruby gem
  • 12 : Required shell command not found

The next three are related to autolog (export DCP_INSPECT_AUTOLOG=true and set DCP_INSPECT_DIR to a writable location to have dcp_inspect automatically write a logfile to that location for every run):

  • 13 : Autolog requested but DCP_INSPECT_DIR is not set
  • 14 : Could not write to DCP_INSPECT_DIR
  • 15 : Could not write autolog

kdm-decrypt.rb

How to decrypt a KDM's content

Run

kdm-decrypt.rb <path to KDM file> <path to RSA private key file>

where <path to KDM file> would be the path to the KDM generated above. This will of course only work if you targeted the KDM at your own public key certificate ($CINEMACERTSTORE/leaf.signed.pem in this case).

Like always with long paths or filenames: Use tab completion in your terminal to avoid typos (never ever literally type in a UUID, one of those long numbers which will show up in digital cinema filenames): Type k_ and hit TAB to let bash automatically complete to the KDMs (long) filename.

Miscellaneous

Dolby's CP650/750 Main Fader Knob and how to adjust for 7.0

Cinema theater sound systems are setup such that rotating the Dolby CP650/750 Main Fader Knob to 7.0 will result in suitable sound pressure levels -- provided the input audio yields correct levels. Here's a crucial part of the PA and room calibration: Feed -20 dBFS pink noise into the system and adjust amplifiers until you measure 85 dBC SPL in a chosen spot in the room (while the Main Fader Knob is rotated to 7.0).

The Dolby CP650/750 Main Fader Knob ranges from 0.0 (-90 dB) to 10.0 (+10 dB). At 7.0 the system will apply 0 dB attenuation/amplification. There are 2 linear parts with different slopes, joined by a knee at 4.0 (-10 dB)

When you test in a cinema and find that you have to rotate the Main Fader Knob to something other than 7.0 in order to get suitable volume you may want to adjust your audio's levels. Using db_adjust_for_dolby_fader_ref.rb will tell you by how much. E.g.

$ db_adjust_for_dolby_fader_ref.rb --input 4.5
Dolby CP650/750 fader: You want to play at 7.0 (0.000 dB attenuation)
Dolby CP650/750 fader: You're actually playing at 4.5 (-8.333 dB attenuation)
Dolby CP650/750 fader: In order to achieve 7.0 fader setting change levels by -8.333 dB

Run db_adjust_for_dolby_fader_ref.rb --help for usage notes.

How to keep digital cinema tools up-to-date

Run

digital-cinema-tools-setup

in a terminal. The setup script will check if there are updates in the repository and install them for you.

I don't do point releases so you want to update every once in a while to get the latest and greatest.

Clone this wiki locally