Skip to content

How to use Digital Cinema Tools

Jump to bottom
wolfgangw edited this page Mar 22, 2013 · 30 revisions
## [cinemaslides](https://github.com/wolfgangw/digital_cinema_tools/wiki/Cinemaslides) ### How to generate a DCP with [cinemaslides](https://github.com/wolfgangw/digital_cinema_tools/wiki/Cinemaslides)

Open a terminal and run

cinemaslides -t dcp -o DCP_TEST -x cut,10 --audio-fade 0,4 <path to an image file> <path to another image file> <path to an audio file>

This will build a digital cinema package:

  • -t dcp (or --type dcp) tells cinemaslides to make a DCP (instead of a preview or fullpreview).

  • -o DCP_TEST (or --dcp-out DCP_TEST) specifies the final output location of the DCP.

  • -x cut,10 (or --transition-and-timing cut,10) means the transition between 2 adjacent images will be a simple cut and each image will last for 10 seconds. Mind cut,10 which has no spaces between cut and , and 10. The other transition options are fade,<in time>,<hold time>,<out time> (like fade,1,5,1) and crossfade,<cross time>,<hold time> (like crossfade,3.5,5.0)

  • --audio-fade 0,4 will fade in sound for 0 seconds and fade out sound at the end of the composition for 4 seconds.

  • <path to image file> is just generic notation for the path to a file, like images/master/foo.tif

Add --encrypt to generate an encrypted DCP. Content keys will be stored in plaintext in $CINEMASLIDESDIR/keys. When generating KDMs cinemaslides will pick up content keys from there.

Say cinemaslides --help for all possible options (There are a lot, you don't need each and every one). See cinemaslides' main page for more.

### How to generate a KDM for an encrypted package with [cinemaslides](https://github.com/wolfgangw/digital_cinema_tools/wiki/Cinemaslides)

In a terminal run

cinemaslides --kdm --cpl DCP_TEST/cpl_<long number>_.xml --target $CINEMACERTSTORE/leaf.signed.pem --start 1

  • --kdm tells cinemaslides to generate a KDM.

  • --cpl <path to CPL> tells cinemaslides to find the content keys referenced in this CPL and pack them up in the KDM. As always, use tab completion for long paths or filenames and never actually type in a UUID (Like cpl_ and TAB to complete to the full filename).

  • --target $CINEMACERTSTORE/leaf.signed.pem will tell cinemaslides for whom the KDM is intended (Or more exactly: Encrypt the delivered content keys with the public key in leaf.signed.pem. Only the owner of the related private key will be able to decrypt the content keys delivered by the KDM). This is the option where you will specify the certificate of a digital cinema server (You will not be able to decrypt the keys stored in that KDM). But for demonstration purposes we target this KDM at our own example certificate (leaf.signed.pem, generated by Setup) so we can decrypt it later on and confirm that everything is working ok.

  • --start 1 will set the start of the KDM's validity period to 1 day from now. We use 1 day from now here to ensure that if you run this immediately after installing cinemaslides will not complain about overlapping validity of the KDM signer's certificate and the requested KDM validity (There are extensive checks in place to make sure the generated KDM is valid and will be accepted by servers, Matrjoschka validity periods being crucial here).

  • Keep in mind that this will work only with cinemaslides' plaintext keystore. Storing content keys in plaintext is of course not suited for production. But it is good enough for demonstration purposes which is the point of this excercise.

### How to generate a preview with [cinemaslides](https://github.com/wolfgangw/digital_cinema_tools/wiki/Cinemaslides)

Run

cinemaslides --type preview <path to an image file> <path to another image file> <path to an audio file>

for a half-size sequence preview (faster to generate) or

cinemaslides --type fullpreview [...]

for a full-sized preview (slower to generate).

cinemaslides knows 3 sequence types: preview, fullpreview and dcp.

## [dcp_inspect](https://github.com/wolfgangw/backports#readme) ### How to validate and inspect a DCP with [dcp_inspect](https://github.com/wolfgangw/backports#readme)

Run

dcp_inspect DCP_TEST

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

### Tips
  • 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.

  • 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
### How to read and interpret [dcp_inspect](https://github.com/wolfgangw/backports#readme)'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:

  • 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.

[tbc ...]

### How to control [dcp_inspect](https://github.com/wolfgangw/backports#readme)'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 and 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](https://github.com/wolfgangw/backports#readme)'s author's verbosity

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

### How to use [dcp_inspect](https://github.com/wolfgangw/backports#readme)'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.

## 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 ### How to keep [digital cinema tools](https://github.com/wolfgangw/digital_cinema_tools_distribution/wiki) 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.

My development model is not focused on point releases so you want to update every once in a while to get the latest and greatest.

Clone this wiki locally