Chapter 15. Command-line tools

DCP-o-matic includes some tools which allow DCP creation from the command line or from scripting languages. This chapter covers the use of those tools.

There are three command-line tools in DCP-o-matic. dcpomatic2_create creates film directories, with the associated metadata, from a list of content files. Then dcpomatic2_cli runs the transcode process on these film directories. Finally, dcpomatic2_kdm_cli can be used to create KDMs.

Some applications will benefit from setting up the films using the main DCP-o-matic GUI and then using dcpomatic2_cli to do the encode. This allows, for example, setup on a relatively low-powered machine before running the encode on a higher-powered headless server.


The syntax for dcpomatic2_create is:

dcpomatic2_create [OPTION] <CONTENT> [[OPTION] <CONTENT> ...]

[CONTENT] are the files or folders that you want to use in the DCP. They can be:

  • ‘Movie’ files in almost any common format (e.g. MP4, MOV, MKV, etc.)
  • A folder containing and image sequence in almost any common format (e.g. TIFF, DPX etc.)
  • Sound files (e.g. WAV, MP3, AIFF)
  • Subtitles files (e.g. .srt, DCP XML, .ssa etc.)

The options are:

  • -v, --version — show DCP-o-matic version
  • -h, --help — show this help
  • -n, --name <name> — film name
  • -t, --template <name> — template name
  • -e, --encrypt — make an encrypted DCP
  • -c, --dcp-content-type <type> — FTR, SHR, TLR, TST, XSN, RTG, TSR, POL, PSA or ADV
  • -f, --dcp-frame-rate <rate> — set DCP video frame rate (otherwise guessed from content)
  • --container-ratio <ratio> — 119, 133, 137, 138, 166, 178, 185 or 239
  • -s, --still-length <n> — number of seconds that still content should last
  • --standard <standard> — SMPTE or interop (default SMPTE)
  • --no-use-isdcf-name — do not use an ISDCF name; use the specified name unmodified
  • --config <dir> — directory containing config.xml and cinemas.xml
  • --twok — make a 2K DCP instead of choosing a resolution based on the content
  • --fourk — make a 4K DCP instead of choosing a resolution based on the content
  • -o, --output <dir> — output directory
  • --threed — make a 3D DCP
  • --j2k-bandwidth <Mbit/s> — J2K bandwidth in Mbit/s
  • --left-eye — next piece of content is for the left eye
  • --right-eye — next piece of content is for the right eye
  • --channel <channel> — next piece of content should be mapped to audio channel L, R, C, Lfe, Ls or Rs
  • --gain — next piece of content should have the given audio gain (in dB)
  • --cpl <id> — CPL ID to use from the next piece of content (which is a DCP)
  • --kdm <file> — KDM for next piece of content

For example, to setup a film using a MP4 file you might do:

dcpomatic2_create -o my_film --container-ratio 185 --content-ratio 185 -c FTR -n "My Film" Stuff.mp4

This will create a folder called my_film which is ready for a DCP to be made by dcpomatic2_cli.

dcpomatic2_create will use any default settings that you have configured in the main DCP-o-matic preferences.