<section>
<title>What is DCP-o-matic?</title>
-<para>
-DCP-o-matic is a program to generate <ulink
-url="http://en.wikipedia.org/wiki/Digital_Cinema_Package">Digital
-Cinema Packages</ulink> (DCPs) from almost any video, audio and/or
-subtitle source files. The resulting DCPs will play on modern digital
-cinema projectors.
-</para>
+<para>DCP-o-matic is a set of programs to perform the following tasks:</para>
+
+<itemizedlist>
+ <listitem>Creation of <ulink
+ url="http://en.wikipedia.org/wiki/Digital_Cinema_Package">Digital
+ Cinema Packages</ulink> (DCPs) from video, audio and/or
+ subtitle files.</listitem>
+ <listitem>Playback of DCPs on a PC.</listitem>
+ <listitem>Creation of KDMs for DCPs.</listitem>
+</itemizedlist>
</section>
<para>
DCP-o-matic will run on Mac OS X version 10.6 (Snow Leopard) and
-higher. To install it, download the <code>.dmg</code> from <ulink
-url="http://dcpomatic.com/">http://dcpomatic.com/</ulink> and double
-click to open it. Then drag the DCP-o-matics icon to your
-<guilabel>Applications</guilabel> folder or wherever else you would
-like to install it.
+higher. DCP-o-matic is split into four separate applications, each of
+which can be installed by downloading the <code>.dmg</code>,
+double-clicking to open and then dragging the icon to your
+<guilabel>Applications</guilabel> folder.
</para>
<para>
-You do not have to install all the applications, but you must always
-install <code>DCP-o-matic 2.app</code> as the other applications
-depend on it.
+If you are not sure which parts of DCP-o-matic to install, start
+with the first (main) part.
</para>
</section>
<!-- ============================================================== -->
<section>
-<title>Debian or Ubuntu Linux</title>
+<title>Debian, Ubuntu or Mint Linux</title>
<para>
You can install DCP-o-matic on:
<listitem>Debian 7 (‘wheezy’)</listitem>
<listitem>Debian 8 (‘jessie’)</listitem>
<listitem>Debian unstable (‘sid’)</listitem>
- <listitem>Ubuntu 12.04 (‘Precise Pangolin’)</listitem>
<listitem>Ubuntu 14.04 (‘Trusty Tahr’)</listitem>
<listitem>Ubuntu 16.04 (‘Xenial Xerus’)</listitem>
+ <listitem>Ubuntu 17.10 (‘Artful Aardvark’)</listitem>
+ <listitem>Mint 17</listitem>
+ <listitem>Mint 18</listitem>
</itemizedlist>
<para>
<!-- ============================================================== -->
<section>
- <title>Fedora Linux</title>
-
- <para>There are <code>.rpm</code> packages for Fedora 22 and 23 on
- <ulink url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>
- </para>
-</section>
-<!-- ============================================================== -->
-
+ <title>Fedora, Centos and Mageia Linux</title>
-<!-- ============================================================== -->
-<section>
- <title>Centos Linux</title>
- <para>There are <code>.rpm</code> packages for Centos 5, 6.5 and 7 on
+ <para>There are <code>.rpm</code> packages for Fedora 25, 26 and 27, Centos 6 and 7 and Mageia 6 on
<ulink url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>
</para>
</section>
<!-- ============================================================== -->
-
<!-- ============================================================== -->
<section>
<title>Arch Linux</title>
Let's make a very simple DCP to see how DCP-o-matic works. First, we
need some content. Download the low-resolution trailer for the open
movie <ulink url="http://sintel.org/">Sintel</ulink> from <ulink
-url="http://ftp.nluug.nl/ftp/graphics/blender/apricot/trailer/Sintel_Trailer1.480p.DivX_Plus_HD.mkv">their
+url="https://download.blender.org/durian/trailer/Sintel_Trailer.480p.DivX_Plus_HD.mkv">their
website</ulink>. Generally one would want to use the
highest-resolution material available, but for this test we will use
the low-resolution version to save everyone's bandwidth bills.
<para>
Dragging the slider will move through your video. You can also click
-the <guilabel>Play</guilabel> button to play the content back. <emphasis>Note
-that there will be no sound</emphasis>, and playback might not be entirely
-accurate (it may be slightly slower or faster than it should be, for
-example). This player is really only intended for brief inspection of
-content; if you need to check it more thoroughly, use another player
-such as <ulink
-url="http://projects.gnome.org/totem/index.html">Totem</ulink>, <ulink
-url="http://www.mplayerhq.hu/design7/news.html">mplayer</ulink> or
-<ulink url="http://www.videolan.org/vlc/index.html">VLC</ulink>.
+the <guilabel>Play</guilabel> button to play the content back.
</para>
</section>
<para>
If you want to do something to an existing DCP the first step is to
-import it. Click <guilabel>Add folder...</guilabel> and select your
+import it. Click <guilabel>Add DCP...</guilabel> and select your
DCP's folder. It will be added to the DCP-o-matic project. If the
DCP is unencrypted you can preview it in the normal way, though
playback will be very slow as decoding of DCPs is almost as
</para>
<para>
-If your DCP is a Version File (VF), in other words it refers to
-another DCP's assets, you should import it as follows:
+If your DCP is a Version File (VF) (i.e.\ it refers to
+another DCP's assets) you should import it as follows:
</para>
<itemizedlist>
-<listitem>Use <guilabel>Add folder...</guilabel> to import the VF DCP.
+<listitem>Use <guilabel>Add DCP...</guilabel> to import the VF DCP.
The VF DCP will be added to the content list and marked “NEEDS
OV”.</listitem>
<listitem>Right-click on the VF DCP in the content list and choose <guilabel>Add OV...</guilabel> from the menu.</listitem>
<para>
Once you have your KDM, right-click the DCP's name in DCP-o-matic and
-choose <guilabel>Add KDM...</guilabel>. Specify your KDM and (all
-being well) the DCP will be decrypted and become available for preview.
+choose <guilabel>Add KDM...</guilabel>. Specify your KDM and the DCP
+will be decrypted and become available for preview.
</para>
</section>
<listitem>Import your ‘Content DCP’ to a DCP-o-matic project.</listitem>
<listitem>Add whatever replacement you want in your new DCP (replacement subtitles or audio files, for example).</listitem>
<listitem>Select the DCP in the content list</listitem>
-<listitem>Tick the <guilabel>Refer to existing DCP</guilabel> checkbox
+<listitem>Tick the <guilabel>Use's this DCP's ... as OV and make VF</guilabel> checkbox
in the tabs for the parts of the DCP that you want to refer to in your
-new DCP. For example, to refer to the Content DCP's video and audio you would select the <guilabel>Video</guilabel> tab, click <guilabel>Refer to existing DCP</guilabel> then select the <guilabel>Audio</guilabel> tab and do the same.</listitem>
+new DCP. For example, to refer to the Content DCP's video and audio you would select the <guilabel>Video</guilabel> tab, click <guilabel>Use this DCP's video as OV and make VF</guilabel> then select the <guilabel>Audio</guilabel> tab and click <guilabel>Use this DCP's audio as OV and make VF</guilabel>.</listitem>
<listitem>Do <guilabel>Make DCP</guilabel> as usual and your VF DCP will be created.</listitem>
</itemizedlist>
</para>
<para>
-To add a directory (folder) of images or a DCP, choose <guilabel>Add
-folder...</guilabel> and choose the directory from the selector. If
-you select a folder of images DCP-o-matic will open a small dialogue
-box where you can enter the frame rate that the image sequence should
-be run at.
+To add a directory (folder) of images, choose <guilabel>Add
+folder...</guilabel> and choose the directory from the selector.
+DCP-o-matic will open a small dialogue box where you can enter the
+frame rate that the image sequence should be run at.
+</para>
+
+<para>
+To add a DCP, choose <guilabel>Add DCP...</guilabel> and choose the
+DCP's directory from the selector.
</para>
<para>
<!-- ============================================================== -->
<section>
-<title>Refer to existing DCP</title>
+<title>Use this DCP's video as OV and make VF</title>
<para>
This option is only applicable if the selected content is an existing
-DCP. It allows you to get the video content from the existing DCP by
-referencing it (rather than copying). See <xref
+DCP. It allows you make a VF DCP, using the video content from the
+existing DCP by referencing it (rather than copying). See <xref
linkend="sec-overlay"/>.
</para>
<title>Other controls</title>
<para>
-The <guilabel>Refer to existing DCP</guilabel> checkbox isonly
-applicable if the selected content is an existing DCP. It allows you
-to get the audio content from the existing DCP by referencing it
-(rather than copying). See <xref linkend="sec-overlay"/>.
+The <guilabel>Use this DCP's audio as OV and make VF</guilabel>
+checkbox is only applicable if the selected content is an existing
+DCP. It allows you to make a VF DCP, using the audio content from the
+existing DCP by referencing it (rather than copying). See <xref
+linkend="sec-overlay"/>.
</para>
<para>
<itemizedlist>
<listitem>Extract subtitles that are embedded in video files, or</listitem>
<listitem>Use subtitles from SubRip (<code>.srt</code>), SubStation
- Alpha (<code>.ssa</code>) or DCP XML files. You may find the great
+ Alpha (<code>.ssa</code> or <code>.ass</code>) or DCP XML files. You may find the great
free program <ulink
url="http://www.nikse.dk/subtitleedit/">Subtitle Edit</ulink> useful
for creating such files.</listitem>
</section>
+
+<section>
+ <title>Copy and paste settings</title>
+
+<para>
+Once you have set up a piece of content it is possible to copy the
+settings you have applied to another piece of content. To do this,
+select the content to copy from and choose <guilabel>Copy</guilabel>
+from the <guilabel>Edit</guilabel> menu. Then select the content to
+copy to and choose <guilabel>Paste</guilabel>. A dialogue box will
+open to allow you to choose which settings you want to copy. Clicking
+<guilabel>OK</guilabel> will apply the copied settings.
+</para>
+
+</section>
+
+
</chapter>
+
+<!-- ============================================================== -->
<chapter xml:id="ch-dcp" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<title>DCP settings</title>
</section>
+<section>
+<title>Encryption keys</title>
+
+<para>
+ You must be careful when using encryption not to lose important keys.
+</para>
+
+<para>
+If you are making KDMs from a DCP-o-matic film you
+<emphasis>must</emphasis> ensure that you have a backup of the
+<code>metadata.xml</code> file from the project, as well as the DCP
+itself.
+</para>
+
+<para>
+If you are using a DKDM you <emphasis>must</emphasis> ensure that you
+have a backup of DCP-o-matic's <code>config.xml</code> file, since it
+contains the only key which can decrypt the DKDM. The
+<code>config.xml</code> file location depends on your operating
+system; possible locations are listed in <xref linkend="ch-config"/>
+</para>
+
+</section>
+
<section>
<title>Encryption overview</title>
</para>
<para>
- There are two command-line tools in DCP-o-matic.
+ There are three command-line tools in DCP-o-matic.
<code>dcpomatic2_create</code> creates film directories, with the
associated metadata, from a list of content files. Then
<code>dcpomatic2_cli</code> runs the transcode process on these
- film directories.
+ film directories. Finally, <code>dcpomatic2_kdm_cli</code> can be
+ used to create KDMs.
</para>
-
+
<para>
Some applications will benefit from setting up the films using the
main DCP-o-matic GUI and then using <code>dcpomatic2_cli</code> to
<section>
<title><code>dcpomatic2_create</code></title>
-
+
<para>
The syntax for <code>dcpomatic2_create</code> is:
</para>
-
+
<para>
<code>dcpomatic2_create [OPTION] [CONTENT] [<CONTENT> ...]</code>
</para>
-
+
<para>
- <code>[CONTENT]</code> are the files that you want to use in the
- DCP (e.g. MP4 or MOV files).
+ <code>[CONTENT]</code> are the files or folders that you want to use in the
+ DCP. They can be:
+ <itemizedlist>
+ <listitem>‘Movie’ files in almost any common format (e.g. MP4, MOV, MKV, etc.)</listitem>
+ <listitem>A folder containing and image sequence in almost any common format (e.g. TIFF, DPX etc.)</listitem>
+ <listitem>Sound files (e.g. WAV, MP3, AIFF)</listitem>
+ <listitem>Subtitles files (e.g. <code>.srt</code>, DCP XML, <code>.ssa</code> etc.)</listitem>
+ </itemizedlist>
</para>
-
+
<para>
The options are:
</para>
-
+
<itemizedlist>
<listitem><code>-v</code>, <code>--version</code> — show DCP-o-matic version</listitem>
<listitem><code>-h</code>, <code>--help</code> — show this help</listitem>
<listitem><code>--no-sign</code>— do not sign the DCP</listitem>
<listitem><code>-o</code>, <code>--output <dir></code> — output directory</listitem>
</itemizedlist>
-
+
<para>
For example, to setup a film using a MP4 file you might do:
</para>
-
+
<para>
- <code>dcpomatic2_cli -o my_film --container-ratio 185 --content-ratio 185 -c FTR -n "My Film" Stuff.mp4</code>
+ <code>dcpomatic2_create -o my_film --container-ratio 185 --content-ratio 185 -c FTR -n "My Film" Stuff.mp4</code>
</para>
-
+
<para>
This will create a folder called <code>my_film</code> which is ready for a DCP to be made by <code>dcpomatic2_cli</code>.
</para>
<section>
<title><code>dcpomatic2_cli</code></title>
-
+
<para>
The syntax for <code>dcpomatic2_cli</code> is:
</para>
-
+
<para>
<code>dcpomatic2_cli [OPTION] [FILM]</code>
</para>
<code>dcpomatic2_cli my_film</code>
</para>
</section>
+
+ <section>
+ <title><code>dcpomatic2_kdm_cli</code></title>
+
+ <para>
+ The syntax for <code>dcpomatic2_kdm_cli</code> is:
+ </para>
+
+ <para>
+ <code>dcpomatic2_kdm_cli [OPTION] <FILM|CPL-ID></code>
+ </para>
+
+ <para>
+ <itemizedlist>
+ <listitem><code>-o</code>, <code>--output</code> — output file or directory</listitem>
+ <listitem><code>-f</code>, <code>--valid-from</code> — valid from time (in local time zone of the cinema) (e.g. "2013-09-28 01:41:51") or "now"</listitem>
+ <listitem><code>-t</code>, <code>--valid-to</code> — valid to time (in local time zone of the cinema) (e.g. "2014-09-28 01:41:51")</listitem>
+ <listitem><code>-d</code>, <code>--valid-duration</code> — valid duration (e.g. "1 day", "4 hours", "2 weeks")</listitem>
+ <listitem><code>--formulation</code> — modified-transitional-1, dci-any or dci-specific [default modified-transitional-1]</listitem>
+ <listitem><code>-z</code>, <code>--zip</code> — ZIP each cinema's KDMs into its own file</listitem>
+ <listitem><code>-v</code>, <code>--verbose</code> — be verbose</listitem>
+ <listitem><code>-c</code>, <code>--cinema</code> — specify a cinema, either by name or email address</listitem>
+ <listitem><code>--certificate</code> — file containing projector certificate</listitem>
+ <listitem><code>--cinemas</code> — list known cinemas from the DCP-o-matic settings</listitem>
+ <listitem><code>--dkdm-cpls</code> — list CPLs for which DCP-o-matic has DKDMs</listitem>
+ </itemizedlist>
+ </para>
+
+ </section>
</chapter>
-
+
<!-- ============================================================== -->
<listitem>Click <guilabel>Add folder...</guilabel> and specify your existing DCP's folder.</listitem>
<listitem>Go to the <guilabel>DCP</guilabel> tab and choose <guilabel>Split by video content</guilabel> for <guilabel>Reel type</guilabel>.</listitem>
<listitem>Go to the <guilabel>Video</guilabel> and
-<guilabel>Audio</guilabel> tabs in turn and tick the <guilabel>Refer to existing DCP</guilabel> checkboxes.</listitem>
+<guilabel>Audio</guilabel> tabs in turn and tick the <guilabel>Use this DCP's audio as OV and make VF</guilabel> checkboxes.</listitem>
<listitem>Add your subtitles to the film in whatever format you have.</listitem>
<listitem>Check the subtitle appearance in the preview; it will be
slow to respond as it is having to decompress images from the existing
<listitem>Create a new DCP-o-matic project for the OV, as normal, adding video and perhaps sound. Make the DCP.</listitem>
<listitem>Create a new DCP-o-matic project for the VF.</listitem>
<listitem>Use <guilabel>Add folder...</guilabel> to add your OV DCP to the project.</listitem>
-<listitem>Select the video tab and tick <guilabel>Refer to existing DCP</guilabel> (you may need to select <guilabel>By video content</guilabel> for <guilabel>Reel type</guilabel> in the <guilabel>DCP</guilabel> tab).</listitem>
+<listitem>Select the video tab and tick <guilabel>Use this DCP's video as OV and make VF</guilabel> (you may need to select <guilabel>By video content</guilabel> for <guilabel>Reel type</guilabel> in the <guilabel>DCP</guilabel> tab).</listitem>
<listitem>Do the same in the <guilabel>Audio</guilabel> tab if your OV has audio.</listitem>
<listitem>Add your language-specific audio and/or subtitles and Make DCP.</listitem>
</itemizedlist>
</chapter>
+<chapter xml:id="ch-player" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+ <title>Playing DCPs</title>
+
+ <para>DCP-o-matic includes a DCP player, and although it requires a
+ very high-speed CPU to play DCPs in full resolution, it can also
+ play DCPs at reduced resolutions with slower CPUs.</para>
+
+ <para>To use the player, start <guilabel>DCP-o-matic
+ Player</guilabel>, and load a DCP using the
+ <guilabel>Open</guilabel> option on the <guilabel>File</guilabel>
+ menu.</para>
+
+ <para>If you load a VF and/or encrypted DCP you can add your OV
+ and/or KDM using the appropriate options on the
+ <guilabel>File</guilabel> menu.</para>
+
+ <para>During playback the <guilabel>Performance</guilabel> area at
+ the bottom right of the window will give details of how many frames
+ are being dropped; these are frames that were not decoded from the
+ DCP quickly enough. If this number is high you can increase
+ performance at the cost of rendering quality by choosing an option
+ from the <guilabel>View</guilabel> menu. If you set the player to
+ decode at less than full resolution the DCP's data will be decoded
+ at this lower resolution, which is quicker than decoding at full
+ resolution.
+ </para>
+
+</chapter>
+
+<!-- ============================================================== -->
+<chapter xml:id="ch-config" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<title>Configuration files</title>
+
+<para>Most of DCP-o-matic's configuration is stored in an XML file called <code>config.xml</code>. This is stored in different places depending on your operating system:</para>
+
+<itemizedlist>
+ <listitem>Windows: <code>c:\Users\your_user_name\AppData\Local\dcpomatic</code></listitem>
+ <listitem>OS X: <code>/Users/your_user_Name/Library/Preferences/com.dcpomatic/2</code></listitem>
+ <listitem>Linux: <code>~/.config/dcpomatic2</code></listitem>
+</itemizedlist>
+
+<para>Possible XML tags are as follows:</para>
+
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="config.xml"/>
+
+</chapter>
+
</book>