]>
<book xmlns="http://docbook.org/ns/docbook" xmlns:mml="http://www.w3.org/1998/Math/MathML" version="5.0" xml:lang="en">
-<!-- By good luck or good management, the scale parameter to imagedata
- appears only to affect PDF output. HTML scaling is done in the
- Makefile.
--->
-
<bookinfo>
-<title>DCP-o-matic</title>
+<title>DCP-o-matic users' manual</title>
<author><firstname>Carl</firstname><surname>Hetherington</surname></author>
</bookinfo>
Hello, and welcome to DCP-o-matic!
</para>
+<!-- ============================================================== -->
<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 DVDs, Blu-Rays, video files such as MP4
-and AVI, or still images. The resulting DCPs will play on modern digital
-cinema projectors.
-</para>
+<para>DCP-o-matic is a set of programs to allow you to:</para>
-<para>
-You might find it useful to make DVDs easier to present, to encode
-independently-shot feature films, or to generate local advertising for
-your cinema.
-</para>
+<itemizedlist>
+ <listitem>Create <ulink
+ url="https://en.wikipedia.org/wiki/Digital_Cinema_Package">Digital
+ Cinema Packages</ulink> (DCPs) from video, audio, subtitle and closed-caption files.</listitem>
+ <listitem>Play and verify DCPs.</listitem>
+ <listitem>Create KDMs for DCPs.</listitem>
+ <listitem>Write cinema-format drives containing DCPs.</listitem>
+</itemizedlist>
</section>
+
+<!-- ============================================================== -->
<section>
<title>Licence</title>
<para>
-DCP-o-matic is licensed under the <ulink url="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GNU GPL</ulink>.
+DCP-o-matic is free and open-source and is licensed under the <ulink
+url="https://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GNU
+GPL</ulink>.
</para>
</section>
+
+<!-- ============================================================== -->
<section>
<title>Acknowledgements</title>
This manual uses icons from the <ulink url="http://tango.freedesktop.org/">Tango Desktop Project</ulink>, with thanks.
</para>
+</section>
+
+<!-- ============================================================== -->
+<section>
+<title>This manual</title>
+
+<para>
+This manual presents bits of DCP-o-matic's user interface (such as menu items or buttons) <guilabel>like this</guilabel>.
+</para>
+
+<note>
+Notes of an advanced nature are presented like this. Ignore them unless you want to know the details.
+</note>
+
</section>
</chapter>
+
+<!-- ============================================================== -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<title>Installation</title>
+
+<!-- ============================================================== -->
<section>
<title>Windows</title>
<para>
To install DCP-o-matic on Windows, download the installer from
-<ulink url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>
+<ulink url="https://dcpomatic.com/">https://dcpomatic.com/</ulink>
and double-click it. Click through the installer wizard, and
DCP-o-matic will be installed onto your machine.
</para>
<para>
-If you are using a 32-bit version of Windows, you will need the 32-bit
-installer. For 64-bit Windows, either installer will work, but I
-suggest you used the 64-bit version as it will allow DCP-o-matic to
-use more memory. You may find that DCP-o-matic crashes if you run
-many parallel encoding threads (more than 4) on the 32-bit
-version.
+Use the 64-bit installer unless you are using a 32-bit version of Windows.
+You may find that DCP-o-matic crashes if run the 32-bit version on a CPU with more than 4 cores.
</para>
</section>
+
+<!-- ============================================================== -->
<section>
-<title>Mac OS X</title>
+<title>macOS</title>
<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-matic icon to your
-<guilabel>Applications</guilabel> folder or wherever else you would
-like to install it.
+DCP-o-matic versions 2.16.0 and higher will run on macOS version 10.10 (Yosemite) and
+higher. DCP-o-matic is split into eight 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>
-</section>
-
-<section>
-<title>Ubuntu Linux</title>
+<para>
+If you don't know which parts of DCP-o-matic to install, start
+with the first (main) part.
+</para>
<para>
-You can install DCP-o-matic on Ubuntu 12.04 (‘Precise
-Pangolin’), 12.10 (‘Quantal Quetzal’), 13.10 (‘Saucy
-Salamander’) or 14.04 (‘Trusty Tahr’) using <code>.deb</code> packages: download the
-appropriate package from <ulink
-url="http://dcpomatic.com/">http://dcpomatic.com/</ulink> and
-double-click it. Ubuntu will install the necessary bits and pieces
-and set DCP-o-matic up for you.
+If you are using macOS 10.9 (Mavericks) or older you will need to install the latest 2.14.x version of DCP-o-matic.
</para>
</section>
+<!-- ============================================================== -->
<section>
-<title>Debian Linux</title>
-<para>
-Packages are available for Debian 7 (squeeze) from <ulink
-url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>.
+<title>Debian, Ubuntu and Mint Linux</title>
+
+<para>There are <code>.deb</code> packages for Debian, Ubuntu and Mint on
+ <ulink url="https://dcpomatic.com/">https://dcpomatic.com/</ulink>
</para>
</section>
+<!-- ============================================================== -->
+
+<!-- ============================================================== -->
<section>
-<title>Centos Linux</title>
-<para>
-Packages are available for Centos 6.5 from <ulink
-url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>.
-</para>
+ <title>Fedora, Centos and Mageia Linux</title>
+
+ <para>There are <code>.rpm</code> packages for Fedora, Centos and Mageia on
+ <ulink url="https://dcpomatic.com/">https://dcpomatic.com/</ulink>
+ </para>
</section>
+<!-- ============================================================== -->
+<!-- ============================================================== -->
<section>
<title>Arch Linux</title>
<para>
</section>
<section>
-<title>Other Linux distributions</title>
-
-<para>
-Installation on non-Ubuntu Linux is currently a little involved, as
-there are no packages available (yet); you will have to compile it
-from source. If you are using a non-Ubuntu distribution, do let me
-know via the <ulink url="mailto:carl@dcpomatic.com">mailing
-list</ulink> and I will see about building some packages.
-</para>
-
+<title>Building from source</title>
<para>
-The following dependencies are required:
-<itemizedlist>
-<listitem><ulink url="http://ffmpeg.org/">FFmpeg</ulink></listitem>
-<listitem><ulink url="http://www.mega-nerd.com/libsndfile/">libsndfile</ulink></listitem>
-<listitem><ulink url="http://www.openssl.org/">OpenSSL</ulink></listitem>
-<listitem><ulink url="http://www.openjpeg.org/">libopenjpeg</ulink></listitem>
-<listitem><ulink url="http://www.imagemagick.org/script/index.php">ImageMagick</ulink></listitem>
-<listitem><ulink url="http://www.boost.org/">Boost</ulink></listitem>
-<listitem><ulink url="http://www.libssh.org/">libssh</ulink></listitem>
-<listitem><ulink url="http://www.gtk.org/">GTK (on Linux)</ulink></listitem>
-<listitem><ulink url="http://www.wxwidgets.org/">wxWidgets</ulink></listitem>
-<listitem><ulink url="http://freecode.com/projects/libquickmail">libquickmail</ulink></listitem>
-<listitem><ulink url="http://libxmlplusplus.sourceforge.net/">libxml++</ulink></listitem>
-<listitem><ulink url="http://www.aleksey.com/xmlsec/">xmlsec</ulink></listitem>
-<listitem><ulink url="http://curl.haxx.se/">curl</ulink></listitem>
-<listitem><ulink url="http://www.nih.at/libzip/">libzip</ulink></listitem>
-<listitem><ulink url="http://carlh.net/software/libdcp/">libdcp</ulink></listitem>
-<listitem><ulink url="http://carlh.net/software/libcxml/">libcxml</ulink></listitem>
-</itemizedlist>
-</para>
-
-<para>
-Once you have installed the development packages for the dependencies,
-download the source code from <ulink
-url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>,
-unpack it and run the following commands from inside the source
-directory:
-</para>
-
-<programlisting>
-./waf configure
-./waf build
-sudo ./waf install
-</programlisting>
-
-<para>
-With any luck, this will build and install DCP-o-matic on your system. To run it, enter:
+Since DCP-o-matic is open-source you can also build it yourself,
+though this can be quite a difficult process (especially on Windows and macOS).
+There are instructions for how to do it on <ulink url="https://dcpomatic.com/development">https://dcpomatic.com/</ulink>
</para>
+</section>
+</chapter>
-<programlisting>
-dcpomatic
-</programlisting>
-<para>
-in a shell.
-</para>
-</section>
-</chapter>
+<!-- ============================================================== -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
-<title>Creating a video DCP</title>
+<title>Creating a DCP from a video</title>
<para>
-In this chapter we will see how to create a video DCP using
+In this chapter we will see how to create a DCP from a video file using
DCP-o-matic. We will gloss over the details and look at the basics.
</para>
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
-website</ulink>. Generally, of course, one would want to use the
+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.
+the low-resolution version to save on download time.
</para>
<para>
Now, start DCP-o-matic and its window will open. First, we will
create a new ‘film’. A ‘film’ is how DCP-o-matic refers to
some pieces of content, along with some settings, which we will make into
-a DCP. DCP-o-matic stores its data in a folder on your disk while it
-creates the DCP. You can create a new film by selecting
+a DCP. DCP-o-matic stores its ‘film’ data in a folder on your disk while it
+creates the DCP.
+</para>
+
+<para>
+You can create a new film by selecting
<guilabel>New</guilabel> from the <guilabel>File</guilabel> menu, as
shown in <xref linkend="fig-file-new"/>.
</para>
<figure id="fig-file-new">
- <title>Creating a new film</title>
+ <title>Creating a new film</title>
<mediaobject>
- <imageobject>
+ <imageobject>
<imagedata fileref="screenshots/file-new&scs;"/>
- </imageobject>
+ </imageobject>
</mediaobject>
</figure>
</para>
<figure id="fig-video-new-film">
- <title>Dialogue box for creating a new film</title>
+ <title>Dialogue box for creating a new film</title>
<mediaobject>
- <imageobject>
- <imagedata fileref="screenshots/video-new-film&scs;"/>
- </imageobject>
+ <imageobject>
+ <imagedata fileref="screenshots/new-film&scs;"/>
+ </imageobject>
</mediaobject>
</figure>
<para>
In this dialogue box you can choose a name for the film. This will be
used to name the folder to store its data in, and also as the initial
-name for the DCP itself. You can also choose whereabouts you want to create
+name for the DCP itself. You can also choose where you want to create
the film. In the example from the figure, DCP-o-matic will create a
-folder called ‘DCP Test’ inside my home folder (carl) into which it
+folder called ‘DCP Test’ inside my existing folder <code>DCP</code> into which it
will write its working files.
</para>
</section>
+
+<!-- ============================================================== -->
<section>
<title>Adding content</title>
<para>
The next step is to add the content that you want to use. DCP-o-matic
-can make DCPs from multiple pieces of content, but in this simple
-example we will just use a single piece. Click the <guilabel>Add
+can make DCPs from multiple pieces of content, but in this example we
+will use a single piece. Click the <guilabel>Add
file(s)...</guilabel> button, as shown in <xref
linkend="fig-add-file"/>, and a file chooser will open for you to
select the content file to use, as shown in <xref
linkend="fig-video-select-content-file"/>.
</para>
-<figure id="fig-add-file">
- <title>Adding content files</title>
+<figure id="fig-add-file">
+ <title>Adding content files</title>
<mediaobject>
- <imageobject>
+ <imageobject>
<imagedata fileref="screenshots/add-file&scs;"/>
- </imageobject>
+ </imageobject>
</mediaobject>
</figure>
-<figure id="fig-video-select-content-file">
- <title>Selecting a video content file</title>
+<figure id="fig-video-select-content-file">
+ <title>Selecting a video content file</title>
<mediaobject>
- <imageobject>
+ <imageobject>
<imagedata fileref="screenshots/video-select-content-file&scs;"/>
- </imageobject>
+ </imageobject>
</mediaobject>
</figure>
the right of the window, as shown in <xref linkend="fig-examine-content"/>.
</para>
-<figure id="fig-examine-content">
+<figure id="fig-examine-content">
<title>Examining the content</title>
<mediaobject>
- <imageobject>
+ <imageobject>
<imagedata fileref="screenshots/examine-content&scs;"/>
- </imageobject>
+ </imageobject>
</mediaobject>
</figure>
<para>
Dragging the slider will move through your video. You can also click
-the <guilabel>Play</guilabel> button to play the content back. Note
-that there will be no sound, 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>
+
+<!-- ============================================================== -->
<section>
<title>Making the DCP</title>
<figure id="fig-making-dcp">
<title>Making the DCP</title>
<mediaobject>
- <imageobject>
- <imagedata scale="30" fileref="screenshots/making-dcp&scs;"/>
- </imageobject>
+ <imageobject>
+ <imagedata fileref="screenshots/making-dcp&scs;"/>
+ </imageobject>
</mediaobject>
</figure>
<para>
-When it has finished, the DCP will end up on your disk inside the
-film's folder. You can then copy this to a projector via a USB
-stick, hard-drive or network connection. See <xref
+When it has finished, the DCP will be written into its own folder inside the film's folder.
+You can copy this to a projector via a USB stick, hard-drive or network connection. See <xref
linkend="ch-files"/> for details about the files that DCP-o-matic creates.
</para>
<para>
-Alternatively, if you have a projector or TMS that is accessible via
-SCP across your network, you can upload the content directly from
-DCP-o-matic. See the preferences in <xref linkend="sec-prefs-tms"/>.
+Alternatively, DCP-o-matic can upload your DCP directly to a projector
+or Theatre Management System (TMS) that is accessible via SCP or FTP
+across your network. See <xref linkend="sec-prefs-tms"/>.
</para>
</section>
</chapter>
+
+<!-- ============================================================== -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
-<title>Creating a still-image DCP</title>
+<title>Creating a DCP from a still image</title>
<para>
DCP-o-matic can also be used to create DCPs of one or more still images, perhaps
</para>
<para>
-As with video DCPs, the first step is to create a new
+As with DCPs made from video files, the first step is to create a new
‘Film’; select <guilabel>New</guilabel> from the
<guilabel>File</guilabel> menu and the new film dialogue will open as
shown in <xref linkend="fig-still-new-film"/>.
</para>
-<figure id="fig-still-new-film">
- <title>Dialogue box for creating a new film</title>
+<figure id="fig-still-new-film">
+ <title>Dialogue box for creating a new film</title>
<mediaobject>
- <imageobject>
- <imagedata fileref="screenshots/still-new-film&scs;"/>
- </imageobject>
+ <imageobject>
+ <imagedata fileref="screenshots/new-film&scs;"/>
+ </imageobject>
</mediaobject>
</figure>
linkend="fig-still-select-content-file"/>.
</para>
-<figure id="fig-still-select-content-file">
- <title>Selecting a still content file</title>
+<figure id="fig-still-select-content-file">
+ <title>Selecting a still content file</title>
<mediaobject>
- <imageobject>
+ <imageobject>
<imagedata fileref="screenshots/still-select-content-file&scs;"/>
- </imageobject>
+ </imageobject>
</mediaobject>
</figure>
<para>
-As with video DCPs, most of the default settings will be fine for a
-simple test. The one thing that you might wish to change is the
-length of the still. Select the <guilabel>Timing</guilabel> tab and
-you will see a <guilabel>Length</guilabel> setting, as shown in <xref
+Most of the default settings will be fine for a simple test. The one
+thing that you might wish to change is the length of the still.
+Select the <guilabel>Timing</guilabel> tab and you will see a
+<guilabel>Full length</guilabel> setting, as shown in <xref
linkend="fig-timing-tab"/>.
</para>
-<figure id="fig-timing-tab">
+<figure id="fig-timing-tab">
<title>The timing tab</title>
<mediaobject>
- <imageobject>
+ <imageobject>
<imagedata fileref="screenshots/timing-tab&scs;"/>
- </imageobject>
+ </imageobject>
</mediaobject>
</figure>
<para>
Finally, as with video, you can choose <guilabel>Make DCP</guilabel>
from the <guilabel>Jobs</guilabel> menu to create your DCP. This will
-be much quicker than creating a video DCP, as DCP-o-matic only needs
+be much quicker than creating a DCP from a video file, as DCP-o-matic only needs
to encode a single frame which it can then repeat.
</para>
</chapter>
+
+<!-- ============================================================== -->
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en" id="ch-disk-writer">
+<title>Writing DCP drives</title>
+
+<para>
+Once a DCP has been created it must often be transferred to a cinema for playback. The most reliable way to do this is to write a specially-formatted drive (in the ext2 format) containing your DCP.
+</para>
+
+<para>
+Writing ext2-formatted drives is difficult from macOS and Windows without custom software. DCP-o-matic includes a tool called the ‘DCP-o-matic Disk Writer’ which makes it easy.
+</para>
+
+</chapter>
+
+
+<!-- ============================================================== -->
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en" id="ch-manipulating-existing-dcps">
+<title>Manipulating existing DCPs</title>
+
+<para>
+DCP-o-matic is often used to take content in formats such as MP4 and
+make it into a DCP. It can also be used to take existing DCPs and
+modify them in various ways.
+</para>
+
+<section>
+<title>Importing a DCP into DCP-o-matic</title>
+
+<para>
+The first step in manipulating an existing DCP is to 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 may be slow as
+decoding of DCPs is almost as computationally intensive as encoding
+them.
+</para>
+
+<para>
+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 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>
+<listitem>Choose the folder that contains the OV DCP. The VF will now be playable as normal.</listitem>
+</itemizedlist>
+
+</section>
+
+
+<section xml:id="sec-decrypting">
+<title>Decrypting encrypted DCPs</title>
+
+<para>
+DCPs can be encrypted (see <xref linkend="ch-encryption"/> for
+details). If you import an encrypted DCP you will need a key, in the
+form of a Key Delivery Message (KDM), to decrypt it.
+</para>
+
+<para>
+KDMs must be prepared by the organisation which created the DCP. They
+contain the keys to decrypt the DCP wrapped up in such a way that only
+the intended recipient can read them. You will need to provide the
+organisation with a certificate which identifies your copy of
+DCP-o-matic and allows them to create a KDM for you.
+</para>
+
+<para>
+To get DCP-o-matic's decryption certificate, open the Preferences
+dialogue (see <xref linkend="ch-preferences"/>) and go to the
+<guilabel>Keys</guilabel> tab. Click the <guilabel>Export DCP
+decryption certificate...</guilabel> button at the bottom of this tab
+and save the certificate. Send this certificate to the DCP creators
+and they can create a KDM to allow DCP-o-matic to decrypt their DCP.
+</para>
+
+<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 the DCP
+will be decrypted and become available for preview.
+</para>
+
+</section>
+
+
+<section>
+<title>Making a DCP from a DCP</title>
+
+<para>
+In many ways, using DCPs as <emphasis>content</emphasis> in
+DCP-o-matic is the same as using any other content. There are a few
+things to note, though.
+</para>
+
+
+<section>
+<title>Re-use of existing data</title>
+
+<para>
+Where possible DCP-o-matic will re-use existing JPEG2000-compressed
+data from DCP content without modification. This has the advantage
+that creation of the new DCP will be quick, as the time-consuming
+JPEG2000 encoding is not necessary.
+</para>
+
+<para>
+DCP-o-matic can do this if you <emphasis>avoid</emphasis> changes to
+the following content settings:
+</para>
+
+<itemizedlist>
+<listitem>Crop</listitem>
+<listitem>Scaling</listitem>
+<listitem>Subtitle burn-in</listitem>
+<listitem>Fades</listitem>
+<listitem>Colour conversion</listitem>
+</itemizedlist>
+
+<para>
+DCP-o-matic will be forced to decode and re-encode your JPEG2000 data
+if you change any of these settings on a piece of DCP content.
+</para>
+
+</section>
+
+
+<section xml:id="sec-overlay">
+<title>Making overlay files</title>
+
+<para>
+With its default settings, DCP-o-matic will take any data from DCP
+content and copy it into the DCP that it creates. See <xref linkend="fig-dcp-copy"/>.
+</para>
+
+<figure id="fig-dcp-copy">
+<title>Creating a new DCP by copying an existing one</title>
+<mediaobject><imageobject><imagedata scale="100" fileref="diagrams/dcp-copy&dia;"/></imageobject></mediaobject>
+</figure>
+
+<para>
+This can be inefficient in some cases. Consider, for example, a film
+which has ten different translations for which the subtitles are
+different but video and audio are the same. If the video and audio
+content takes up, say, 100Gb this means that the set of DCPs for every
+translation would be about 1Tb with a lot of duplicated data.
+</para>
+
+<para>
+The DCP format has a solution to this problem. One DCP can refer to
+the ‘assets’ (picture, sound or subtitle) of another DCP.
+For our translation example this means that we could have a
+‘base’ DCP (often called the OV or Original Version)
+containing video, audio and one set of subtitles and then any number
+of overlay DCPs (often called VF or Version Files) which refer to the
+base version and replace the original subtitles with their own. <xref
+linkend="fig-dcp-refer"/> shows this principle for one of our
+translations. The DCP that we make refers to the original content
+DCP's video and audio rather than containing a copy.
+</para>
+
+<figure id="fig-dcp-refer">
+<title>Creating a new DCP by referring to an existing one</title>
+<mediaobject><imageobject><imagedata scale="100" fileref="diagrams/dcp-refer&dia;"/></imageobject></mediaobject>
+</figure>
+
+<para>
+To play back the subtitled DCP the projectionist ingests both the base
+(OV) DCP and the overlay (VF) DCP, then plays the VF one.
+</para>
+
+<para>
+To make a DCP like this:
+</para>
+
+<itemizedlist>
+<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>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>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>
+
+</section>
+
+</section>
+
+
+
+</chapter>
+<!-- ============================================================== -->
+
+
+<!-- ============================================================== -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<title>Content settings</title>
<para>
The previous chapters showed DCP generation using the default
settings. DCP-o-matic offers a range of features to adjust the
-content that goes into your DCP, and this chapter describes those features in
-detail.
+content that goes into your DCP, and this chapter describes those
+features in detail.
</para>
<section>
<itemizedlist>
<listitem>Movie — a file containing some video, probably some
-audio and possibly some subtitles; for example, a MOV, MP4 or VOB.
+audio and possibly some embedded subtitles; for example, a MOV, MP4 or VOB.
</listitem>
<listitem>Sound — a file containing one or more channels of
<listitem>Moving image — a directory containing many still
images which should be treated as the frames of a video.
</listitem>
+
+<listitem>Subtitle — a file containing subtitles which will be
+superimposed on the image of the DCP. These can be
+<guilabel>.srt</guilabel>, <guilabel>.ssa</guilabel>, <guilabel>.ass</guilabel> or <guilabel>.xml</guilabel>
+files. Subtitle files can also be used to make closed captions.</listitem>
+
+<listitem>DCP — an existing DCP.</listitem>
+
+<listitem>ATMOS MXFs — if you have Dolby ATMOS content in MXF format (created using Dolby's tools) you can add it to a DCP just like any other content.</listitem>
</itemizedlist>
<para>
-To add one or more movie, sound or still-image files, select
+To add one or more movie, sound, still-image or subtitle files, select
<guilabel>Add file(s)...</guilabel> and choose them from the selector.
-To add a directory of images, choose <guilabel>Add
-directory...</guilabel> and do similar.
+</para>
+
+<para>
+DCP-o-matic will automatically map a set of audio files to the correct channels if you include appropriate ‘tags’ in your filenames, as shown in <xref linkend="tab-audio-file-naming"/>.
+</para>
+
+<table id="tab-audio-file-naming">
+ <title>Audio file naming</title>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <thead>
+ <row>
+ <entry>Tag</entry>
+ <entry>Examples</entry>
+ <entry>Channel</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><code>L</code> surrounded by <code>.</code> <code>_</code> or <code>-</code></entry>
+ <entry>film-L.wav my_movie_L_final.wav</entry>
+ <entry>Left</entry>
+ </row>
+ <row>
+ <entry><code>R</code> surrounded by <code>.</code> <code>_</code> or <code>-</code></entry>
+ <entry>film-R.wav my_movie_R_final.wav</entry>
+ <entry>Right</entry>
+ </row>
+ <row>
+ <entry><code>C</code> surrounded by <code>.</code> <code>_</code> or <code>-</code></entry>
+ <entry>film-C.wav my_movie_C_final.wav</entry>
+ <entry>Centre</entry>
+ </row>
+ <row>
+ <entry><code>Lfe</code> surrounded by <code>.</code> <code>_</code> or <code>-</code></entry>
+ <entry>film-Lfe.wav my_movie_Lfe_final.wav</entry>
+ <entry>LFE (sub)</entry>
+ </row>
+ <row>
+ <entry><code>Ls</code> surrounded by <code>.</code> <code>_</code> or <code>-</code></entry>
+ <entry>film-Ls.wav my_movie_Ls_final.wav</entry>
+ <entry>Left surround</entry>
+ </row>
+ <row>
+ <entry><code>Rs</code> surrounded by <code>.</code> <code>_</code> or <code>-</code></entry>
+ <entry>film-Rs.wav my_movie_Rs_final.wav</entry>
+ <entry>Right surround</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
+<para>
+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>
</para>
</section>
+
+<!-- ============================================================== -->
+<section>
+<title>Adding existing DCPs</title>
+
+<para>Adding existing DCPs to a DCP-o-matic film is a little different
+to adding other types of content. Most content has to be converted to
+JPEG2000, the compression scheme used by DCPs, which is a very
+time-consuming process. Existing DCPs are already in JPEG2000 format
+so do not require conversion. This means that, provided no settings
+such as crop are used on the DCP content, picture and sound data will
+be passed from existing to new DCP unaltered.
+</para>
+
+<para>Encrypted DCPs that are added as content will require a KDM
+targeted at DCP-o-matic so that DCP-o-matic can decrypt them. You
+should ask the creator of the imported DCP to provide a KDM for
+DCP-o-matic's decryption certificate, which can be obtained by
+clicking <guilabel>Export DCP decryption certificate...</guilabel>
+from the <guilabel>Keys</guilabel> tab of the
+<guilabel>Preferences</guilabel> dialog (see <xref
+linkend="sec-prefs-keys"/>).
+</para>
+
+</section>
+
+<!-- ============================================================== -->
<section>
-<title>Content Properties</title>
+<title>Content properties</title>
<para>
Below the content list are the controls to set content properties. To
for that piece of content.
</para>
+<para>
+If you want to change the properties for multiple pieces of content at
+the same time, select the content in the list by clicking the first
+piece then clicking the other pieces with <keycap>shift</keycap> key
+held down. Note that not all settings can be changed in this way.
+</para>
+
<para>
The content properties are split up into four sections:
<guilabel>Video</guilabel>, <guilabel>Audio</guilabel>,
-<guilabel>Subtitles</guilabel> and <guilabel>Timing</guilabel>. Not
+<guilabel>Timed text</guilabel> and <guilabel>Timing</guilabel>. Not
all of these sections will be active for all content types. The controls
in each section are described below.
</para>
</section>
+
+<!-- ============================================================== -->
<section>
<title>Video</title>
The <guilabel>Video</guilabel> tab controls properties of the image, as shown in <xref linkend="fig-video-tab"/>.
</para>
-<figure id="fig-video-tab">
+<figure id="fig-video-tab">
<title>Video settings tab</title>
<mediaobject>
- <imageobject>
+ <imageobject>
<imagedata fileref="screenshots/video-tab&scs;"/>
- </imageobject>
+ </imageobject>
</mediaobject>
</figure>
+
+<!-- ============================================================== -->
+<section>
+<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 make a VF DCP, using the video content from the
+existing DCP by referencing it (rather than copying). See <xref
+linkend="sec-overlay"/>.
+</para>
+
+</section>
+
+<!-- ============================================================== -->
<section>
<title>Image type</title>
<para>
-The first option on this tab is the ‘type’ of the video.
+The next option on this tab is the ‘type’ of the video.
This specifies how DCP-o-matic should interpret the video's image.
<guilabel>2D</guilabel> is the default; this just takes the video
image as a standard 2D frame. The <guilabel>3D
left-right pair, as shown in <xref linkend="fig-3d-left-right"/>.
</para>
-<figure id="fig-3d-left-right">
+<figure id="fig-3d-left-right">
<title>3D left/right image type</title>
<mediaobject>
- <imageobject>
+ <imageobject>
<imagedata scale="100" fileref="diagrams/3d-left-right&dia;"/>
- </imageobject>
+ </imageobject>
</mediaobject>
</figure>
linkend="fig-3d-top-bottom"/>.
</para>
-<figure id="fig-3d-top-bottom">
+<figure id="fig-3d-top-bottom">
<title>3D top/bottom image type</title>
<mediaobject>
- <imageobject>
+ <imageobject>
<imagedata scale="100" fileref="diagrams/3d-top-bottom&dia;"/>
- </imageobject>
+ </imageobject>
</mediaobject>
</figure>
+<para>
+Another option is <guilabel>3D alternate</guilabel> which takes the
+first frame of the content as for the left eye, the second for the
+right eye, the third for the left, and so on. Finally, you can
+specify <guilabel>3D left only</guilabel> or <guilabel>3D right
+only</guilabel> if this content contains only the the left or right
+eye images. This is useful when you have the left and right eye image
+sets in different files; you can specify one content as <guilabel>3D
+left only</guilabel> and another as <guilabel>3D right only</guilabel>
+and DCP-o-matic will pick up the appropriate frames from each.
+</para>
+
</section>
<!-- ============================================================== -->
<section>
-<title>Filtering</title>
+<title>Colour conversion</title>
<para>
-The ‘filters’ settings allow you to apply various video
-filters to the image. These may be useful to try to improve
-poor-quality sources like DVDs. You can set up the filters by clicking the
-<guilabel>Edit</guilabel> button next to the filters entry in the
-setup area of the DCP-o-matic window; this opens the filters selector
-as shown in <xref linkend="fig-filters"/>.
+The <guilabel>Colour conversion</guilabel> setting specifies what
+colour transforms and gamma correction DCP-o-matic will use when
+converting the selected content into the XYZ colourspace for the DCP.
+</para>
+
+<para>
+The easiest way to select the required conversion is to choose one of
+DCP-o-matic's presets. DCP-o-matic knows how to convert from four
+common colourspaces: sRGB, Rec. 601, Rec. 709 and P3. If you do not
+know which preset you should use, refer to the suggestions in <xref
+linkend="tab-colour-conversion"/>.
+</para>
+
+<table id="tab-colour-conversion">
+<title>Suggested colour conversion settings</title>
+<tgroup cols='2' align='left' colsep='1' rowsep='1'>
+<colspec colwidth='1*'/>
+<colspec colwidth='5*'/>
+<tbody>
+<row>
+<entry>sRGB</entry><entry>Still images in RGB, e.g. photographs.</entry>
+</row>
+<row>
+<entry>Rec. 601</entry><entry>Standard-definition content (fewer than about 1000 pixels across) including DVD rips.</entry>
+</row>
+<row>
+<entry>Rec. 709</entry><entry>High-definition content including Blu-Ray rips.</entry>
+</row>
+<row>
+<entry>P3</entry><entry>Content explicitly graded to P3.</entry>
+</row>
+</tbody>
+</tgroup>
+</table>
+
+<para>
+For other required colour conversions, and if you know what you are
+doing, you can choose <guilabel>Custom</guilabel> which will open the full
+colour conversion editing dialogue box:
</para>
-<figure id="fig-filters">
- <title>Filters selector</title>
+<figure id="fig-colour-conversion">
+ <title>Dialogue box for custom colour conversion</title>
<mediaobject>
- <imageobject>
- <imagedata fileref="screenshots/filters&scs;"/>
- </imageobject>
+ <imageobject>
+ <imagedata fileref="screenshots/colour-conversion&scs;"/>
+ </imageobject>
</mediaobject>
</figure>
<para>
-After changing the filters setup, you will need to regenerate the DCP
-to see the effect on the cinema screen. The preview in DCP-o-matic
-will update itself whenever filters are changed, though of course this
-image is much smaller and of lower resolution than a projected image!
+Alternatively, choose <guilabel>None</guilabel> if your source files
+are already in the XYZ colour space and require no conversion.
</para>
-</section>
+<para>
+DCP-o-matic's colour conversion processes are discussed in much more
+detail in a separate document <ulink
+url="https://dcpomatic.com/manual/colour.pdf">colour.pdf</ulink>.
+</para>
+
+</section>
<!-- ============================================================== -->
<section>
<title>Other settings</title>
<para>
-The ‘crop’ settings can be used to crop your content,
-which can be used to remove black borders from round the edges of DVD
-images, for example. The specified number of pixels will be trimmed
-from each edge, and the content image in the right of the window will
-be updated to show the effect of the crop.
+The <guilabel>crop</guilabel> settings can be used to crop your
+content, which is often used to remove black borders from the edges of
+the image. The specified number of pixels will be trimmed from each
+edge, and the content image in the right of the window will be updated
+to show the effect of the crop.
+</para>
+
+<para>
+The <guilabel>fade in</guilabel> and <guilabel>fade out</guilabel>
+settings can be used to apply linear fades into and out of a piece of
+content. Specify the time for each, clicking <guilabel>Set</guilabel>
+after making any changes.
</para>
<para>
</para>
</section>
+
+<!-- ============================================================== -->
<section>
<title>Video description</title>
At the bottom of the video tab is a short description of what will
happen to your video with the current settings. In the example of
<xref linkend="fig-video-tab"/>, DCP-o-matic is telling you that the
-video file is 1920x1080 pixels (which is a ratio of 1.78:1). Since
-the controls specify ‘Flat’ for the ratio, DCP-o-matic
-scales the content image to 1998x1080, which is the DCI flat
-resolution at 2K.
+video file is 2048x872 pixels and it has square pixels (a pixel
+aspect ratio of 1.00) hence its display aspect ratio is 2.35:1. Since
+the controls specify ‘2.35’ for the ratio, DCP-o-matic
+does not scale the image but pads it to the DCP's container ratio of
+1.85:1. For a 2K DCP this is 1998x1080 pixels.
</para>
<para>
This description also gives the frame rate of the content and what
-will happen to it when it is played at the DCP's frame rate.
-<!-- XXX: link to more detailed discussion of this -->
+will happen to it when it is played at the DCP's frame rate. See
+<xref linkend="ch-frame-rates"/> for details of DCP-o-matic's
+frame-rate conversion.
</para>
</section>
</section>
+
+<!-- ============================================================== -->
<section>
<title>Audio</title>
<para>
-The <guilabel>Audio</guilabel> tab controls properties of the image, as shown in <xref linkend="fig-audio-tab"/>.
+The <guilabel>Audio</guilabel> tab controls properties of the sound, as shown in <xref linkend="fig-audio-tab"/>.
</para>
-<figure id="fig-audio-tab">
+<figure id="fig-audio-tab">
<title>Audio settings tab</title>
<mediaobject>
- <imageobject>
+ <imageobject>
<imagedata fileref="screenshots/audio-tab&scs;"/>
- </imageobject>
+ </imageobject>
</mediaobject>
</figure>
+<!-- ============================================================== -->
<section>
-<title>Show audio</title>
+<title>The audio map</title>
<para>
-The <guilabel>Show Audio</guilabel> button will instruct DCP-o-matic
-to examine the audio in your content and plot a graph of its level
-over time. This can be useful for getting a rough idea of how loud
-the sound will be in the cinema auditorium. A typical plot is shown
-in <xref linkend="fig-audio-plot"/>
+The section at the bottom of the audio tab is the ‘audio
+map’. This governs how sound from the content will be arranged
+in the DCP.
</para>
-<figure id="fig-audio-plot">
- <title>Audio plot</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="screenshots/audio-plot&scs;"/>
- </imageobject>
- </mediaobject>
-</figure>
-
<para>
-The plot gives the audio level (vertical axis, in dB) with time
-(horizontal axis). 0dB represents full scale, so if there is anything
-near this you are in danger of clipping the projector's audio outputs.
-</para>
-
-<para>
-There are two plot types: the peak level and the RMS, which can be
-shown or hidden using the check-boxes on the right hand side of the
-window.
-</para>
-
-<para>
-The channel check-boxes will show or hide the plot(s) for
-the corresponding channels in the DCP.
-</para>
-
-<para>
-The smoothing slider applies a variable degree of temporal smoothing
-to the plots, which can make them easier to read in some cases.
+Down the left-hand side of the map is the list of audio channels in
+the currently-selected piece of content. These are labelled with two
+numbers; the first is the stream index within the content and the
+second is the channel number within that stream. Some content will
+have different streams for different languages or audio mixes. Along
+the top is each channel in the DCP. A green box means that the
+corresponding content channel will be copied into the corresponding
+DCP channel.
</para>
<para>
-Obviously the audio plot is no substitute for listening in an
-auditorium, but it can be useful to get levels in the right rough area.
+When content channels are copied into DCP channels they can be done
+with variable gain. If, for example, you want to copy a channel
+as-is, you can set a gain of 0dB. Alternatively, if you want to mix
+two channels into one, you may want to use a gain of -6dB on each one
+to prevent clipping when the two channels are added.
</para>
-</section>
-
-<section>
-<title>The audio map</title>
-
<para>
-The section at the bottom of the audio tab is the ‘audio
-map’. This governs how sound from the content will be arranged
-in the DCP.
+The green boxes of the audio mapping view tell you (very roughly) how
+much gain is applied to each channel. A full-height box means 0dB
+(i.e. unity) gain. Any less height indicates lower gain.
</para>
<para>
-Down the left-hand side of the map is the list of audio channels in
-the currently-selected piece of content. Along the top is each
-channel in the DCP. A checked box means that the corresponding
-content channel will be copied into the corresponding DCP channel.
+To map one channel to another with 0dB gain, click in the empty box
+and it will turn green to reflect the mapping. A second click will
+turn the mapping back off. To set some other gain, right-click on the
+box to open the gain menu. This allows you to set
+<guilabel>Off</guilabel> (no mapping or negative infinity gain),
+<guilabel>Full</guilabel> (0dB gain), -6dB gain or
+<guilabel>Edit</guilabel> which allows you to set the required gain
+precisely.
</para>
<para>
<figure id="fig-audio-map-eg1">
<title>Audio map example 1</title>
<mediaobject>
- <imageobject>
+ <imageobject>
<imagedata fileref="screenshots/audio-map-eg1&scs;"/>
- </imageobject>
+ </imageobject>
</mediaobject>
</figure>
<para>
Here, we have two channels in the source which are mapped to left and
-right, respectively, in the DCP. If we modify that as in <xref
-linkend="fig-audio-map-eg2"/>
+right, respectively, in the DCP. The full green boxes show that the
+mapping is at unity gain (0dB) in each case. Imagine that we modify
+the settings to those shown in <xref linkend="fig-audio-map-eg2"/>
</para>
<figure id="fig-audio-map-eg2">
<title>Audio map example 2</title>
<mediaobject>
- <imageobject>
+ <imageobject>
<imagedata fileref="screenshots/audio-map-eg2&scs;"/>
- </imageobject>
+ </imageobject>
</mediaobject>
</figure>
<para>
-we now have the content's streams mapped to left and right and also
-mixed together and placed in the DCP's centre channel.
+We now have the content's streams mapped to left and right and also
+mixed together and placed in the DCP's centre channel. The smaller
+green boxes on the centre mappings show that those channels are added
+with some non-unity gain; you can see by hovering the mouse pointer
+over those boxes that the gain for content channels 1 and 2 is -6dB
+when being sent to the centre channel and 0dB when being sent to left
+and right.
</para>
<figure id="fig-audio-map-eg3">
<title>Audio map example 3</title>
<mediaobject>
- <imageobject>
+ <imageobject>
<imagedata fileref="screenshots/audio-map-eg3&scs;"/>
- </imageobject>
+ </imageobject>
</mediaobject>
</figure>
</section>
+
+<!-- ============================================================== -->
<section>
-<title>Other controls</title>
+ <title>Other controls</title>
+
+<para>
+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>
+<guilabel>Show graphs of audio levels</guilabel> will analyse the
+audio of the selected content and plot it on a graph. See <xref
+linkend="sec-show-audio"/> for more details.
+</para>
<para>
‘Audio Gain’ is used to alter the volume of the
linkend="fig-calculate-audio-gain"/> will open.
</para>
-<figure id="fig-calculate-audio-gain">
+<figure id="fig-calculate-audio-gain">
<title>Calculating audio gain</title>
<mediaobject>
- <imageobject>
+ <imageobject>
<imagedata fileref="screenshots/calculate-audio-gain&scs;"/>
- </imageobject>
+ </imageobject>
</mediaobject>
</figure>
with respect to the video, and a negative delay will move it earlier.
</para>
-<para>
-The <guilabel>Audio Stream</guilabel> option allows you to select the
-audio stream to use, if the content contains more than one. There
-might be different soundtrack languages, for example.
-</para>
-
</section>
</section>
+<!-- ============================================================== -->
<section>
-<title>Subtitles</title>
+<title>Timed text (subtitles and closed captions)</title>
+
+<para>
+The timed text tab contains settings related to subtitles and closed captions in your
+content, as shown in <xref linkend="fig-timed-text-tab"/>.
+</para>
+
+<figure id="fig-timed-text-tab">
+ <title>Timed text settings tab</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/timed-text-tab&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+Depending on where timed text comes from it can sometimes be used as
+either an open subtitle (to be overlaid onto the cinema screen and
+seen by everybody) or as a closed caption (to be displayed to
+individual viewers using a special system such as the Doremi
+CaptiView™)
+</para>
+
+<para>
+DCP-o-matic can either:
+</para>
+
+<itemizedlist>
+ <listitem>Extract timed text that is embedded in video files, or</listitem>
+ <listitem>Use timed text from SubRip (<code>.srt</code>), SubStation
+ 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>
+</itemizedlist>
+
+<para>
+Embedded timed text is usually represented using a set of bitmaps,
+especially on files that have come from DVD or BluRay. Such text can
+be used as a subtitle, but not a closed caption (since the closed
+captioning system requires the text to be delivered as
+character codes rather than an image).
+</para>
+
+<para>In contrast, SubRip, SubStation Alpha or DCP text can be used as either a subtitle or a closed caption.</para>
<para>
-The subtitles tab contains settings related to subtitles in your
-content, as shown in <xref linkend="fig-subtitles-tab"/>.
+With subtitles you have the further choice of whether to burn the
+subtitles into the image or include them as a separate subtitle
+‘asset’ within your DCP (in which case the projector
+overlays them onto the image on playback). The difference between
+burn-in and overlay is illustrated by <xref linkend="fig-burn-in"/>
+and <xref linkend="fig-discrete"/>.
</para>
-<figure id="fig-subtitles-tab">
- <title>Subtitle settings tab</title>
+<figure id="fig-burn-in">
+ <title>Burnt-in subtitles</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="100" fileref="diagrams/burn-in&dia;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<figure id="fig-discrete">
+ <title>Separate subtitles</title>
<mediaobject>
- <imageobject>
- <imagedata fileref="screenshots/subtitles-tab&scs;"/>
- </imageobject>
+ <imageobject>
+ <imagedata scale="100" fileref="diagrams/discrete&dia;"/>
+ </imageobject>
</mediaobject>
</figure>
<para>
-DCP-o-matic will extract subtitles from the content, if present, and
-they can be ‘burnt into’ the DCP (that is, they are
-included in the image and not overlaid by the projector). Note that
-DVD and Blu-Ray subtitles are stored as bitmaps, so it is not possible
-(automatically) to use non-burnt-in subtitles with these sources.
-Select the <guilabel>With Subtitles</guilabel> check-box to enable
-subtitles. The <guilabel>offset</guilabel> control moves the
-subtitles up and down the image, and the <guilabel>scale</guilabel>
-control changes their size.
+The advantage of separate subtitles is that the same video content can
+be used for DCPs in many different languages. This means that only a
+small text file needs to be changed for each target language, rather
+than a large video file. It also means that the time-consuming video
+encoding need only be done once for the project rather than once for
+every language.
+</para>
+
+<para>
+Select the <guilabel>Use as</guilabel> check-box to enable the timed
+text in the selected content, then choose what you want to use the
+text for: open subtitles or closed captions.
+</para>
+
+<para>
+Select the <guilabel>Burn subtitles into image</guilabel> check-box to
+burn subtitles into the image; if this is not ticked the
+subtitles will be included separately in the DCP to be rendered by the
+projector.
+</para>
+
+<para>
+The <guilabel>X Offset</guilabel> and <guilabel>Y Offset</guilabel>
+controls move subtitles around within the image. These controls have
+no effect for closed captions. The offsets are expressed as a
+percentage of the video frame size; 100% X offset is the entire width
+of the frame, and 100% Y offset is the entire height. Hence, to move
+the subtitles down by half the frame height you would use a Y offset
+of 50%.
+</para>
+
+<para>
+The <guilabel>X Scale</guilabel> and <guilabel>Y Scale</guilabel>
+controls scale subtitles. These controls have no effect for closed
+captions. Scale values of 1 make the subtitles the same size
+(relative to the size of the image) as they are on the original.
+Values lower than 1 make them smaller, and values higher make them
+larger. You can stretch the subtitles in either direction by
+specifying different values for X and Y scale. Subtitles from DVD and
+Blu Ray sources are frequently larger (relative to the video frame)
+than those typically used for DCP, so it is often useful to scale such
+subtitles down using these controls.
+</para>
+
+<para>
+The <guilabel>Line spacing</guilabel> control adjusts the line spacing
+of the subtitles. This only works for subtitles that did not come from bitmaps.
+</para>
+
+<para>
+The <guilabel>Stream</guilabel> control changes the subtitle stream
+that is used when the content has more than one.
+</para>
+
+<para>
+If you are using non-image (text) subtitles or closed captions you can see the
+subtitle text and timings by clicking the <guilabel>View...</guilabel>
+button, or specify the fonts that should be used by clicking <guilabel>Fonts...</guilabel>.
</para>
<para>
-All being well, future versions of DCP-o-matic will include the option to
-use text subtitles (as is the norm with most professionally-mastered
-DCPs).
+With any subtitles you can click <guilabel>Appearance...</guilabel> to
+change how the subtitles look. Some of the controls in the
+<guilabel>Appearance</guilabel> only apply to burnt-in subtitles, as
+only limited control is available for subtitles rendered by the
+projection system.
</para>
</section>
+
+<!-- ============================================================== -->
<section>
<title>Timing</title>
content, as shown in <xref linkend="fig-timing-tab-detail"/>.
</para>
-<figure id="fig-timing-tab-detail">
+<figure id="fig-timing-tab-detail">
<title>Timing settings tab</title>
<mediaobject>
- <imageobject>
+ <imageobject>
<imagedata fileref="screenshots/timing-tab&scs;"/>
- </imageobject>
+ </imageobject>
</mediaobject>
</figure>
linkend="fig-timecode"/>.
</para>
-<figure id="fig-timecode">
+<figure id="fig-timecode">
<title>Timecode</title>
<mediaobject>
- <imageobject>
- <imagedata fileref="diagrams/timecode&dia;"/>
- </imageobject>
+ <imageobject>
+ <imagedata scale="100" fileref="diagrams/timecode&dia;"/>
+ </imageobject>
</mediaobject>
</figure>
</para>
<para>
-<guilabel>Trim from start</guilabel> specifies the amount that should be trimmed from the start of the content.
+<guilabel>Trim from start</guilabel> specifies the amount that should
+be trimmed from the start of the content. You can set this amount to
+trim up to the current preview position by clicking <guilabel>Trim up
+to current position</guilabel>.
</para>
<para>
-<guilabel>Trim from end</guilabel> specifies the amount that should be trimmed from the end of the content.
+<guilabel>Trim from end</guilabel> specifies the amount that should be
+trimmed from the end of the content. You can set this amount to trim
+after the current preview position by clicking <guilabel>Trim after to
+current position</guilabel>.
</para>
<para>
</para>
<para>
-<guilabel>Video frame rate</guilabel> specifies the frame rate for still-image content.
+<guilabel>Video frame rate</guilabel> specifies the frame rate for
+still-image content. It can also be used to override the detected
+frame rate of other content if DCP-o-matic has got it wrong.
</para>
<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>
+ <title>Timeline</title>
+
+ <para>
+ The timeline window gives an overview of all the pieces of content
+ in your film, and how they are arranged. You can open the
+ timeline by clicking the <guilabel>Timeline...</guilabel> button
+ next to the content list. This will open a window like the one in <xref linkend="fig-timeline1"/>.
+ </para>
+
+ <figure id="fig-timeline1">
+ <title>Timeline</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/timeline1&scs;"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>
+ The horizontal axis represents time, and you can see the time codes (in
+ hours:minutes:seconds) along the bottom of the window. Pieces of
+ content are represented with rectangles in the main part of the
+ window. Content containing different types of data (e.g. a MP4
+ file with video, audio and subtitles) have a rectangle for each
+ type.
+ </para>
+
+ <para>
+ Within the timeline you can select content by clicking, and drag
+ it to change its position. Right-clicking a piece of content will
+ open the content menu.
+ </para>
+
+ <para>
+ The toolbar at the top of the window offers the following tools:
+ </para>
+
+ <itemizedlist>
+ <listitem>Select — to select and move content.</listitem>
+ <listitem>Zoom in — to drag out an area that you want to see more closely.</listitem>
+ <listitem>Zoom out — to zoom out so that the window shows the whole film.</listitem>
+ <listitem>Snap — when enabled, content will snap to other content when you drag it close.</listitem>
+ <listitem>Sequence — when enabled, content will be kept in sequence, without gaps, even if some content is removed.</listitem>
+ </itemizedlist>
+</section>
+
+<!-- ============================================================== -->
+<section>
+<title>Video processing pipeline</title>
<para>
-This chapter describes the settings that apply to the whole DCP. The
-controls for these settings are in the <guilabel>DCP</guilabel> tab of
-the main window, as shown in <xref linkend="fig-dcp-tab"/>.
+This section gives a little more detail about how DCP-o-matic process
+video as it takes it from a source and puts it into a DCP.
</para>
-<figure id="fig-dcp-tab">
- <title>DCP settings tab</title>
+<para>
+Consider, as a somewhat over-the-top example, that we have a 720 x 576
+image which is letterboxed with 36 black pixels each at the top and
+bottom, and the video content within the letterbox should be presented
+in the DCP at ratio of 2.39:1 within a 1.85:1 frame (such as might
+happen with a trailer). The source image is shown in <xref
+linkend="fig-pipeline1"/>.
+</para>
+
+<figure id="fig-pipeline1">
+ <title>Example image to demonstrate video processing</title>
<mediaobject>
- <imageobject>
- <imagedata fileref="screenshots/dcp-tab&scs;"/>
- </imageobject>
+ <imageobject>
+ <imagedata scale="100" fileref="diagrams/pipeline1&dia;"/>
+ </imageobject>
</mediaobject>
</figure>
<para>
-The first thing here is the name. This is generally set to the title
-of the film that is being encoded. If <guilabel>Use ISDCF
-name</guilabel> is not ticked, the name that you specify will be used
-as-is for the name of the DCP. If <guilabel>Use ISDCF name</guilabel>
-is ticked, the name that you enter will be used as part of a
-ISDCF-compliant name.
+DCP-o-matic runs through the following steps when preparing an image for a DCP:
</para>
-<para>
-Underneath the name field is a preview of the name that the DCP will
-get. To use a ISDCF-compliant name, tick the <guilabel>Use ISDCF
-name</guilabel> check-box. The ISDCF name will be composed using details
-of your content's soundtrack, the current date and other things that
-can be specified in the ISDCF name details dialogue box, which you can
-open by clicking on the <guilabel>Details</guilabel> button.
-</para>
+<itemizedlist>
+<listitem>Crop</listitem>
+<listitem>Scale</listitem>
+<listitem>Place in container</listitem>
+</itemizedlist>
<para>
-If the DCP name is long, it may not all be visible. You can see the
-full name by hovering the mouse pointer over the partial name.
+First, some amount of the image can be cropped. This is almost always
+used to remove black borders (letterboxing and/or pillarboxing) around
+images.
</para>
<para>
-The <guilabel>Container</guilabel> option sets the ratio of the image
-in the DCP. If this ratio is different to the ratio used for any
-content, DCP-o-matic will pad the content with black. In simple cases
-this should be set to the same ratio as that for the the primary piece
-of video content. Alternatively, you might want to pillarbox a small
-format into a Flat container: in this case, select the small format
-for the content's ratio and ‘Flat’ for the DCP.
+In our example image, we would use 36 pixels of crop from the top and
+bottom. This would give the new image shown in <xref
+linkend="fig-pipeline2"/>.
</para>
-<para>
-Next up is the content type. This can be
-‘feature’, ‘trailer’ or whatever; select the
-required type from the drop-down list.
-</para>
+<figure id="fig-pipeline2">
+ <title>Example image after cropping</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="100" fileref="diagrams/pipeline2&dia;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
<para>
-The <guilabel>Frame Rate</guilabel> control sets the frame rate of
-your DCP. This can be a little tricky to get right. Ideally, you
-want it to be the same as the video content that you are using. If it
-is not the same, DCP-o-matic must resort to some tricks to alter your
-content to fit the specified frame rate. Frame rates are discussed in
-more detail in <xref linkend="ch-frame-rates"/>.
+The next step is to scale the image. Since this content should be
+presented in a 2.39:1 (scope) aspect ratio inside a 1.85:1 (flat) DCP we would select
+<guilabel>Scope</guilabel> from the <guilabel>Scale to</guilabel>
+option in the <guilabel>Video</guilabel> tab and
+<guilabel>Flat</guilabel> from the <guilabel>Container</guilabel>
+option in the <guilabel>DCP</guilabel> tab.
</para>
-<para>
-The <guilabel>Signed</guilabel> check-box sets whether or not the DCP
-is signed. This is rarely important; if in doubt, tick it.
+<para>The <guilabel>Scale to</guilabel> option should always be set to
+the aspect ratio at which the content should be seen. The
+<guilabel>Container</guilabel> option should be set to the preset that
+you want to use on the projector. Of course, these two settings will
+often be the same.
</para>
<para>
-The <guilabel>Encrypted</guilabel> check-box will set whether the DCP
-should be encrypted or not. If this is ticked, the DCP will require a
-KDM to play back. Encryption is discussed in <xref
-linkend="ch-encryption"/>.
+Given the scaling and container information, DCP-o-matic will look at
+the DCP's container size, and then scale the source image up until one
+or both of its dimensions (width, height or both) fits the size of the
+container, all the while preserving the desired aspect ratio.
</para>
<para>
-The <guilabel>Use best</guilabel> button sets the DCP video frame rate
-to what DCP-o-matic thinks is the best given the content that you have
-added.
+In our example here, the DCP's container is specified as 1.85:1 (so
+that the DCP will play back correctly using the projector's
+‘Flat’ preset). At 2K, 1.85:1 is 1998 pixels by 1080.
+Scaling the source up whilst preserving its 1.85:1 aspect ratio will
+result in the image hitting the sides of the container first, at a
+size of 1998 x 836. This gives us a new version of the image as shown
+in <xref linkend="fig-pipeline3"/>.
</para>
-<para>
-The <guilabel>Audio Channels</guilabel> control sets the number of
-audio channels that the DCP will have. If the DCP has any channels
-for which there is no content audio they will be replaced by silence.
-</para>
+<figure id="fig-pipeline3">
+ <title>Example image after cropping and scaling</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="100" fileref="diagrams/pipeline3&dia;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
<para>
-The <guilabel>3D</guilabel> button will set your DCP to 3D mode if it
-is checked. A 3D DCP will then be created, and any 2D content will be
-made 3D compatible by repeating the same frame for both left and right
-eyes. A 3D DCP can be played back on many 3D systems (e.g. Dolby 3D,
-Real-D etc.) but not on a 2D system.
+The final step is to place the image into the DCP. In this case,
+since we have a 2.39:1 image that should be presented as a 1.85:1 DCP,
+we have set the <guilabel>container</guilabel> in the
+<guilabel>DCP</guilabel> tab to be Scope. Since the content has been
+scaled to 1998 x 836, and a Flat container is 1998 x 1080, there will
+be some black bars at the top and bottom of the image. DCP-o-matic
+shares out this black equally, as shown in <xref
+linkend="fig-pipeline3"/>.
</para>
-<para>
-The <guilabel>Resolution</guilabel> tab allows you to choose the
-resolution for your DCP. Use 2K unless you have content that is of
-high enough resolution to be worth presenting in 4K.
-</para>
+<figure id="fig-pipeline4">
+ <title>Example image in the DCP</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="100" fileref="diagrams/pipeline4&dia;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
-<para>
-The <guilabel>JPEG2000 bandwidth</guilabel>; setting changes how big the final
-image files used within the DCP will be. Larger numbers will give
-better quality, but correspondingly larger DCPs. The bandwidth can be
-between 50 and 250 megabits per second (Mbit/s).
-</para>
+</section>
-<para>
-The <guilabel>Standard</guilabel> option specifies which of the two
-DCP standards DCP-o-matic should use. If in doubt, use SMPTE (the
-more modern of the two).
-</para>
+
+<section>
+ <title>Copy and paste settings</title>
<para>
-Finally, the <guilabel>Scaler</guilabel> is the method that will be used to scale up
-your content to the required size for the DCP, if required. Bicubic is a fine choice in
-most situations.
+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>
-</chapter>
+</section>
-<chapter xml:id="ch-encryption" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
-<title>Encryption</title>
+
+<section>
+<title>Advanced content settings</title>
<para>
-It is not required that DCPs be encrypted, but they can be. This
-chapter discusses the basic principles of DCP encryption, and how
-DCP-o-matic can create encrypted DCPs and KDMs for them.
+There are a few more content settings that you can change by right-clicking a piece of content in the list and choosing <guilabel>Advanced settings...</guilabel>
+This opens the dialogue box shown in <xref linkend="fig-advanced-content"/>.
</para>
+<figure id="fig-advanced-content">
+ <title>Advanced content dialogue</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/advanced-content&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+
+<!-- ============================================================== -->
<section>
-<title>Basics</title>
+<title>Video filters</title>
<para>
-DCPs can be encrypted. This means that the picture and sound data are
-encoded in such a way that only cinemas ‘approved’ by the
-DCP's creators can read them. In particular, this means copies of the
-DCP can be distributed by insecure means: if an ne'er-do-well called
-Mallory obtains a hard drive containing an encrypted DCP, there is no
-way that he can play it. Only those cinemas who receive a correct key
-delivery message (KDM) can play the DCP.
+The <guilabel>Video filters</guilabel> setting allows you to apply various
+filters to the image. These may be useful to try to improve
+poor-quality sources like DVDs. You can set up the filters by clicking the
+<guilabel>Edit</guilabel> button next to the filters entry; this opens the filters selector
+as shown in <xref linkend="fig-filters"/>.
</para>
+<figure id="fig-filters">
+ <title>Filters selector</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/filters&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+</section>
+
+
<section>
-<title>How it works (in a nutshell)</title>
+<title>Override frame rate</title>
<para>
-This section attempts to summarise how DCP encryption works. You can
-skip it if you like. You may need some knowledge of encryption
-methods to understand it.
+The <guilabel>Override detected video frame rate</guilabel> setting has some different effects depending on the type of content
+you use it on.
</para>
<para>
-We suppose that we are trying to distribute a DCP to
-Alice's cinema, without a troublemaker called Mallory being able to
-watch it himself.
+For video content, it sets the frame rate that DCP-o-matic will run the video at. This is useful if DCP-o-matic has mis-detected
+the video frame rate. For example, if DCP-o-matic says your content is 24fps when you know for a fact it's 25fps, you can set the
+override value to 25 to force DCP-o-matic to do the right thing.
</para>
<para>
-There are two main families of encryption techniques. The first,
-symmetric-key encryption, allows us to encode some data using some
-numeric key. After encoding, no-one can decode the data unless they
-know the key.
+On audio, subtitle and caption content this setting behaves slightly differently. It sets the video frame rate that the content
+in question was intended to work with. As an example, consider a project with a 23.976fps video source and some separate audio files.
+Perhaps those audio files have been mastered alongside a 24fps version of your video. By default, DCP-o-matic will see the 23.976fps
+video file and decide to run it slightly fast at 24fps to fit the DCP standard. It will then also run the audio slightly fast so that
+it stays in sync with the video.
</para>
<para>
-The first step in a DCP encryption is to encode its data with some key
-using symmetric-key encryption. The encrypted DCP can then be sent
-anywhere, safe in the knowledge that even if Mallory got hold of a
-copy, he could not decrypt it.
+In this case, though, that is not what you want, since the audio is already ‘fixed’ to work alongside 24fps video. If you
+override the video frame rate of the <emphasis>audio</emphasis> content to 24fps this will stop DCP-o-matic altering it.
</para>
<para>
-Alice, however, needs to know the key so she can play the DCP in her
-cinema. A simple approach might be for us to send Alice the key.
-However, if Mallory can intercept the DCP, he might also be able to
-intercept our communication of the key to Alice. Furthermore, if Alice
-happened to know Mallory, she could just send him a copy of the key.
+A similar situation can occur if you have video at one rate and a subtitle file that was prepared with its timing at a different rate.
+In that case, you should override the video frame rate of the <emphasis>subtitle</emphasis> content to the one that it was prepared for.
+This will mean that DCP-o-matic can get the relative timing right.
</para>
<para>
-The clever bit in DCP encryption requires the use of public-key
-encryption. With this technique we can encrypt a block of data using
-some ‘public’ key. That data can then only be decrypted
-using a <emphasis>different</emphasis> ‘private’ key. The
-private and public keys are related mathematically, but it is
-extremely hard (or rather, virtually impossible) to derive the private
-key from the public key.
+Do <emphasis>not</emphasis> use this setting to change the DCP frame rate. Doing so will result in strange effects and sync problems.
</para>
+</section>
-<para>
-Public-key encryption allows us to distribute the DCP's key to Alice
-securely. The manufacturer of Alice's projector generates a public
-and private key. They hide the private key deep inside the bowels of
-the projector (inside an integrated circuit) where no-one can read it.
-They then make the public key available to anyone who is interested.
-</para>
+<section>
+<title>Video has burnt-in subtitles</title>
<para>
-We take our DCP's symmetric key and encrypt it using the public key of
-Alice's projector. We send the result to Alice over email (using a
-format called a Key Delivery Message, or KDM). Her projector then
-decrypts our message using its private key, yielding the magic
-symmetric key which can decrypt the DCP.
+Details about subtitle language are stored in various places within the DCP metadata. If a piece of video content already has subtitles
+burnt into the image you can tell DCP-o-matic the language that they are in by clicking the <guilabel>Edit...</guilabel> button.
</para>
+</section>
+
+<section>
+<title>Ignore this content's video</title>
<para>
-If is fine if Mallory intercepts our email to Alice, since the only
-key which can decrypt the message is the private key buried inside
-Alice's projector. The projector manufacturer is very careful that
-no-one ever finds out what this key is. Our DCP is secure: only Alice
-can play it back, since only her projector knows the key (even Alice
-does not).
+Tick this if you have some content which includes video along with other things (such as audio or subtitles) and you do
+<emphasis>not</emphasis> want the video to appear in the DCP.
</para>
-
</section>
+
+
+</section>
+
+</chapter>
+
+
+<!-- ============================================================== -->
+<chapter xml:id="ch-dcp" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<title>DCP settings</title>
+
+<para>
+This chapter describes the settings that apply to the whole DCP. The
+controls for these settings are in the <guilabel>DCP</guilabel> tab of
+the main window, as shown in <xref linkend="fig-dcp-tab"/>.
+</para>
+
+<figure id="fig-dcp-tab">
+ <title>DCP settings tab</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/dcp-tab&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+The first thing here is the name. This is generally set to the title
+of the film that is being encoded. If <guilabel>Use ISDCF
+name</guilabel> is not ticked, the name that you specify will be used
+as-is for the name of the DCP. If <guilabel>Use ISDCF name</guilabel>
+is ticked, the name that you enter will be used as part of a
+ISDCF-compliant name.
+</para>
+
+<para>
+Underneath the name field is a preview of the name that the DCP will
+get. To use a ISDCF-compliant name, tick the <guilabel>Use ISDCF
+name</guilabel> check-box. The ISDCF name will be composed using details
+of your content's soundtrack, the current date and other things that
+can be specified in the ISDCF name details dialogue box, which you can
+open by clicking on the <guilabel>Details</guilabel> button.
+</para>
+
+<para>
+If you want to take the ISDCF-compliant name that DCP-o-matic
+generates and modify it, click <guilabel>Copy as name</guilabel> and
+the ISDCF name will be copied into the <guilabel>Name</guilabel> box.
+You can then edit it as you wish. The DCP name should not matter (in
+that it should not affect how the DCP ingests or plays) but
+projectionists will appreciate it if you use the standard naming
+scheme as it makes it easier to identify details of the content.
+</para>
+
+<para>
+The <guilabel>Content Type</guilabel> option can be
+‘feature’, ‘trailer’ or whatever; select the
+required type from the drop-down list. On some projection systems
+this will affect where your content appears in the projector's server
+user interface, so take care to select an appropriate type.
+</para>
+
+<para>
+The <guilabel>Signed</guilabel> check-box sets whether or not the DCP
+is signed. This is rarely important; if in doubt, tick it.
+</para>
+
+<para>
+The <guilabel>Encrypted</guilabel> check-box will set whether the DCP
+should be encrypted or not. If this is ticked, the DCP will require a
+KDM to play back. Encryption is discussed in <xref
+linkend="ch-encryption"/>.
+</para>
+
+<para>
+If you use encryption DCP-o-matic will generate a random encryption
+key for you. To specify your own key, click the
+<guilabel>Edit..</guilabel> button next to the key.
+</para>
+
+<para>
+The <guilabel>Reels</guilabel> and <guilabel>Reel length</guilabel>
+controls specify how the DCP will be split up into
+‘reels’. See <xref linkend="sec-reels"/>.
+</para>
+
+<para>
+The <guilabel>Standard</guilabel> option specifies which of the two
+DCP standards DCP-o-matic should use. If in doubt, use SMPTE (the
+more modern of the two).
+</para>
+
+<para>
+Ticking the <guilabel>Upload DCP to TMS after it is made</guilabel>
+will ask DCP-o-matic to copy the finished DCP to your configured TMS (see <xref linkend="sec-prefs-tms"/>).
+</para>
+
+<para>
+At the bottom of the DCP tab are a further two tabs, one each to
+contain the settings for the DCP's video and audio parts.
+</para>
+
+<para>
+The <guilabel>Container</guilabel> option sets the ratio of the image
+in the DCP. If this ratio is different to the ratio used for any
+content, DCP-o-matic will pad the content with black. In simple cases
+this should be set to the same ratio as that for the the primary piece
+of video content. Alternatively, you might want to pillarbox a small
+format into a Flat container: in this case, select the small format
+for the content's ratio and ‘Flat’ for the DCP.
+</para>
+
+<para>
+The <guilabel>Frame Rate</guilabel> control sets the frame rate of
+your DCP. This can be a little tricky to get right. Ideally, you
+want it to be the same as the video content that you are using. If it
+is not the same, DCP-o-matic must resort to some tricks to alter your
+content to fit the specified frame rate. Frame rates are discussed in
+more detail in <xref linkend="ch-frame-rates"/>.
+</para>
+
+<para>
+The <guilabel>Use best</guilabel> button sets the DCP video frame rate
+to what DCP-o-matic thinks is the best given the content that you have
+added.
+</para>
+
+<para>
+The <guilabel>3D</guilabel> button will set your DCP to 3D mode if it
+is checked. A 3D DCP will then be created, and any 2D content will be
+made 3D compatible by repeating the same frame for both left and right
+eyes. A 3D DCP can be played back on many 3D systems (e.g. Dolby 3D,
+Real-D etc.) but not on a 2D system.
+</para>
+
+<para>
+The <guilabel>Resolution</guilabel> tab allows you to choose the
+resolution for your DCP. Use 2K unless you have content that is of
+high enough resolution to be worth presenting in 4K.
+</para>
+
+<para>
+The <guilabel>JPEG2000 bandwidth</guilabel>; setting changes how big
+the final image files used within the DCP will be. Larger numbers
+will give better quality, but correspondingly larger DCPs. The
+bandwidth can be between 50 and 250 megabits per second (Mbit/s).
+Most commercial DCPs use bit rates between 75 and 125 Mbit/s.
+</para>
+
+<para>
+<guilabel>Re-encode JPEG2000 data from input</guilabel> governs
+whether or not JPEG2000-encoded data from a piece of content (usually
+a DCP) will be re-used in the output data as-is or whether it will be
+decoded and re-encoded by DCP-o-matic. If the option is enabled
+DCP-o-matic will decompress any JPEG2000 data it finds and re-encode
+it. This is useful if you want to reduce the bitrate of a DCP.
+Usually you will achieve better quality and quicker results by leaving
+this option switched off.
+</para>
+
+<para>
+The <guilabel>Audio Channels</guilabel> control sets the number of
+audio channels that the DCP will have. If the DCP has any channels
+for which there is no content audio they will be replaced by silence.
+You can only set an even number of channels here, since that is
+required by the DCI standard. If you want an odd number of channels,
+set the DCP channel count to one greater than you need and the
+unused channel will be filled with silence.
+</para>
+
+<para>
+The <guilabel>Processor</guilabel> control allows you to select a
+process to apply to the audio before it goes into the DCP. One process is currently provided:
+</para>
+
+<itemizedlist>
+<listitem>Mid-side decode — this will take a L/R
+stereo input and extract the common part (corresponding to the
+‘Mid’ in a mid-side signal) into the DCP's centre channel.
+The remaining L/R parts will be kept in the L/R channels of the DCP.
+This may be useful to make near-field L/R mixes more compatible with
+cinema audio systems.</listitem>
+</itemizedlist>
+
+<!-- ============================================================== -->
+<section xml:id="sec-reels">
+<title>Reels</title>
+
+<para>
+A ‘reel’ in a DCP is a subsection of the DCP, in the same
+way as a 35mm reel is a section of a film. A DCP can be split up into
+any number of reels and the joins (the equivalent to 35mm splices or changeovers)
+between the reels are seamless.
+</para>
+
+<para>
+There is no reason why you can't just use a single reel for the whole
+of your DCP, as there is no limit to their length. Many people choose
+to do this.
+</para>
+
+<para>
+There are, however, some possible advantages of splitting things up
+into reels:
+</para>
+
+<itemizedlist>
+<listitem>
+The picture, sound and subtitle data of the DCP will be
+split up into more smaller files on disk, rather than fewer larger
+files. This can be useful if the DCP is to be transferred on storage
+that have file size limits. The FAT32 filesystem, for example, can
+only hold files smaller than 4Gb. A 6Gb DCP with a single reel could
+not be transferred using a FAT32-formatted disk. If that DCP were
+split up into two 3Gb reels it could be transferred.
+</listitem>
+<listitem>
+It is easier to re-use DCP components if they are in reels. Consider,
+for example, a film company who wants to put a 5 second ident onto the
+beginning of DCPs that they distribute. If they receive a feature
+film DCP they can modify it to add their ident as a separate reel.
+This is easier than attaching the picture data to the feature's existing data.
+</listitem>
+</itemizedlist>
+
+<para>
+DCP-o-matic offers three options for setting up the reels in your DCP:
+<guilabel>single reel</guilabel>, <guilabel>split by video content</guilabel> or <guilabel>custom</guilabel>.
+</para>
+
+<para>
+<guilabel>Single reel</guilabel>, as its name suggests, keeps the whole DCP as one reel.
+This is a perfectly good option if you have no particular reason to
+need reels.
+</para>
+
+<para>
+<guilabel>Split by video content</guilabel> puts each piece of source
+video content in its own reel, as shown in <xref linkend="fig-reels-by-video"/>.
+</para>
+
+<figure id="fig-reels-by-video">
+<title>Making reels using split by video content</title>
+<mediaobject><imageobject><imagedata scale="100" fileref="diagrams/reels-by-video&dia;"/></imageobject></mediaobject>
+</figure>
+
+<para>
+Here we have three video files (<code>ident.mp4</code>,
+<code>feature.ts</code> and <code>cred.mov</code>). With
+<guilabel>split by video content</guilabel> DCP-o-matic makes a new
+reel to hold each video file.
+</para>
+
+<para>
+<guilabel>Custom</guilabel> splits reels by the size of the files that
+will make up their video content. With <guilabel>Custom</guilabel>
+you must specify a reel length in Gb. Then no file in the DCP will be larger than this reel length.
+</para>
+
+</section>
+
+
+<!-- ============================================================== -->
+<section xml:id="sec-show-audio">
+<title>Show audio</title>
+
+<para>
+The <guilabel>Show Audio</guilabel> button will instruct DCP-o-matic
+to examine the audio in your content and plot a graph of its level
+over time. This can be useful for getting a rough idea of how loud
+the sound will be in the cinema auditorium. A typical plot is shown
+in <xref linkend="fig-audio-plot"/>
+</para>
+
+<figure id="fig-audio-plot">
+ <title>Audio plot</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/audio-plot&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+The plot gives the audio level (vertical axis, in dB) with time
+(horizontal axis). 0dB represents full scale, so if there is anything
+near this you are in danger of clipping the projector's audio outputs.
+</para>
+
+<para>
+There are two plot types: the peak level and the RMS, which can be
+shown or hidden using the check-boxes on the right hand side of the
+window.
+</para>
+
+<para>
+The channel check-boxes will show or hide the plot(s) for
+the corresponding channels in the DCP.
+</para>
+
+<para>
+The smoothing slider applies a variable degree of temporal smoothing
+to the plots, which can make them easier to read in some cases.
+</para>
+
+<para>
+Obviously the audio plot is no substitute for listening in an
+auditorium, but it can be useful to get levels in the right rough area.
+</para>
+
+</section>
+
+</chapter>
+
+
+<!-- ============================================================== -->
+<chapter xml:id="ch-templates" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<title>Templates</title>
+
+<para>
+If you frequently make DCPs with similar settings you may find it
+useful to use templates.
+</para>
+
+<para>
+Say, for example, you often make 4K feature DCPs from video files in
+’scope at 25fps. You can speed up this process by following
+these steps:
+</para>
+
+<itemizedlist>
+ <listitem>Create a film with any content and set it up how you like;
+ in our example, set the content to scale to DCP, the DCP resolution
+ to 4K, and so on.</listitem>
+ <listitem>Choose <guilabel>Save as template...</guilabel> from the <guilabel>File</guilabel> menu.</listitem>
+ <listitem>Enter a name for your template.</listitem>
+</itemizedlist>
+
+<para>
+Then in the future you can create a new film, tick the
+<guilabel>Template</guilabel> box and choose your previously-saved
+template. The basic film's settings will come from your template, and
+when you add some content it will take on the settings of the
+first similarly-typed piece of content in your template.
+</para>
+
+<para>
+For example, if the template has a piece of video content and some
+subtitles, any video that you add to the new film will take on the
+settings of the video in the template. Similarly, any subtitles that
+you add will take on the settings of the subtitles from the template.
+</para>
+
+<para>
+The following settings from the <guilabel>DCP</guilabel> tab are saved
+in templates:
+</para>
+
+<itemizedlist>
+ <listitem>“Use ISDCF name” checkbox</listitem>
+ <listitem>Content type (FTR, TLR etc.)</listitem>
+ <listitem>Container</listitem>
+ <listitem>Resolution</listitem>
+ <listitem>JPEG200 bandwidth</listitem>
+ <listitem>Video frame rate</listitem>
+ <listitem>Signed and encrypted checkboxes</listitem>
+ <listitem>Audio channels</listitem>
+ <listitem>Standard (Interop / SMPTE)</listitem>
+ <listitem>Audio processor</listitem>
+ <listitem>Reel type and length</listitem>
+ <listitem>Upload after make DCP checkbox</listitem>
+</itemizedlist>
+
+<para>
+In addition to this, the settings (but not the filenames) of any
+content in the template are stored, as discussed above. The status of
+the <guilabel>Keep video and subtitles in sequence</guilabel> checkbox
+from the timeline is also preserved.
+</para>
+
+</chapter>
+
+
+<!-- ============================================================== -->
+<chapter xml:id="ch-export" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+ <title>Export</title>
+
+ <para>
+ As well as creating DCPs from the content you specify, DCP-o-matic
+ can also export projects to ProRes and MP4 files. This is most
+ often useful to convert DCPs to a file that is smaller and easier to play back.
+ </para>
+
+ <para>
+ To convert a DCP to ProRes or MP4, the first step is start a new
+ project and import the DCP (see <xref
+ linkend="ch-manipulating-existing-dcps"/>). Then, choose
+ <guilabel>Export...</guilabel> from the <guilabel>Jobs</guilabel>
+ menu to open the export dialogue, as shown in <xref linkend="fig-export"/>.
+ </para>
+
+ <figure id="fig-export">
+ <title>Export dialogue</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/export&scs;"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>
+ From this dialogue you can select the required output format,
+ output file and, in the case of MP4, the quality of the output
+ file (by setting the <ulink url="https://trac.ffmpeg.org/wiki/Encode/H.264#crf">CRF value</ulink>).
+ </para>
+
+ <para>
+ The useful range of CRF values is from 17 (high quality but large file size) to 28 (smaller file size and still reasonable quality).
+ </para>
+
+ <para>
+ The time needed to export, and the resulting size, depend partly on the DCP resolution set in the project. To change that, see chapter <xref linkend="ch-dcp"/>.
+ </para>
+
+ <para>
+ You can also choose whether to mix down multichannel sources to stereo and whether you want to write separate reels to separate files.
+ </para>
+</chapter>
+
+<!-- ============================================================== -->
+<chapter xml:id="ch-encryption" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<title>Encryption</title>
+
+<para>
+DCP's do not have to be encrypted, but they can be. This
+chapter discusses the basic principles of DCP encryption, and how
+DCP-o-matic can create encrypted DCPs and KDMs for them.
+</para>
+
+
+<!-- ============================================================== -->
+<section>
+<title>Basics</title>
+
+<para>
+DCPs can be encrypted. This means that the picture and sound data are
+encoded in such a way that only cinemas ‘approved’ by the
+DCP's creators can read them. In particular, this means copies of the
+DCP can be distributed by insecure means: if a bad person called
+Mallory obtains a hard drive containing an encrypted DCP, there is no
+way that he can play it. Only those cinemas who receive a correct key
+delivery message (KDM) can play the DCP.
+</para>
+
+
+<!-- ============================================================== -->
+<section>
+<title>How it works</title>
+
+<para>
+This section attempts to summarise how DCP encryption works. You can
+skip it if you like. You may need some knowledge of encryption
+methods to understand it.
+</para>
+
+<para>
+We suppose that we are trying to send a DCP to
+Alice's cinema without a third party called Mallory being able to
+watch it himself.
+</para>
+
+<para>
+There are two main families of encryption techniques. The first,
+symmetric-key encryption, allows us to encode some data using some
+numeric key. After encoding, no-one can decode the data unless they
+know the key.
+</para>
+
+<para>
+The first step in a DCP encryption is to encode its data with a random key
+using symmetric-key encryption. The encrypted DCP can then be sent
+anywhere, safe in the knowledge that even if Mallory got hold of a
+copy, he could not decrypt it.
+</para>
+
+<para>
+Alice, however, needs to know the key so she can play the DCP in her
+cinema. A simple approach might be for us to send Alice the key.
+However, if Mallory can intercept the DCP, he might also be able to
+intercept our communication of the key to Alice. Furthermore, if Alice
+happened to know Mallory, she could just send him a copy of the key.
+</para>
+
+<para>
+The clever bit in the process requires the use of public-key
+encryption. With this technique we can encrypt a block of data using
+some ‘public’ key. That data can then only be decrypted
+using a corresponding private key which is
+<emphasis>different</emphasis> to the public key. The private and
+public keys form a pair which are related mathematically, but it is
+extremely hard (or rather, virtually impossible) to derive the private
+key from the public key.
+</para>
+
+<para>
+Public-key encryption allows us to distribute the DCP's key to Alice
+securely. The manufacturer of Alice's projector generates a public
+and private key. They hide the private key inside the projector where
+no-one can read it. They then make the public key available to anyone
+who is interested.
+</para>
+
+<para>
+DCP-o-matic has a similar arrangement except that it stores its
+private keys in the user's configuration file. See <xref
+linkend="sec-decrypting"/> for details of how to share DCP-o-matic's
+certificate so that others can make encrypted DCPs for DCP-o-matic.
+</para>
+
+<para>
+We take our DCP's symmetric key and encrypt it using the public key of
+Alice's projector. We send the result to Alice over email (using a
+format called a Key Delivery Message, or KDM). Her projector then
+decrypts our message using its private key, giving the
+symmetric key which can decrypt the DCP.
+</para>
+
+<para>
+If is fine if Mallory intercepts our email to Alice, since the only
+key which can decrypt the message is the private key buried inside
+Alice's projector. The projector manufacturer is very careful that
+no-one ever finds out what this key is. Our DCP is secure: only Alice
+can play it back, since only her projector knows the key (even Alice
+does not).
+</para>
+
+</section>
+</section>
+
+
+<!-- ============================================================== -->
+<section>
+<title>Encryption using DCP-o-matic</title>
+
+<para>
+There are two steps to distributing an encrypted DCP. First, the
+DCP's data must be encrypted, and secondly KDMs must be generated for
+those cinemas that are allowed to play the DCP.
+</para>
+
+<para>
+The first part is simple: ticking the <guilabel>Encrypted</guilabel>
+box in the <guilabel>DCP</guilabel> tab will instruct DCP-o-matic to
+encrypt the DCP that it makes using a random key that DCP-o-matic
+generates. The key will be written to the film's metadata file, which
+should be kept secure.
+</para>
+
+<para>
+A DCP that is generated with the <guilabel>Encrypted</guilabel> box
+ticked will not play on any projector as-is (it will be marked as
+‘locked’, or whatever the projector manufacturer's term
+is).
+</para>
+
+<para>
+The second part of distributions is to generate KDMs for the cinemas
+that you wish to allow to play your DCP. There are two approaches to
+this within DCP-o-matic: using the project, or using a DKDM. These
+approaches are now described in turn.
+</para>
+
+<section>
+<title>Creating KDMs from a DCP-o-matic project</title>
+
+<para>
+You can create KDMs from inside a DCP-o-matic project using the
+<guilabel>Make KDMs</guilabel> option on the <guilabel>Jobs</guilabel>
+menu. This will open the KDM dialogue box, as shown in <xref
+linkend="fig-kdm"/>.
+</para>
+
+<figure id="fig-kdm">
+ <title>KDM dialog</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="35" fileref="screenshots/kdm&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+In order to generate KDMs for a particular projector, you need to know
+its <emphasis>certificate</emphasis>. These are usually made
+available by the projector manufacturers as text files with a
+<code>.pem</code> extension.
+</para>
+
+<para>
+DCP-o-matic can store these certificates along with details of their
+cinemas and screens within those cinemas. Each screen has a
+certificate for its projector (and optionally certificates for other
+trusted devices, such as the sound processor). DCP-o-matic can
+generate KDMs for any screens that it knows about.
+</para>
+
+<para>
+To add a cinema, click <guilabel>Add Cinema...</guilabel>. This opens
+a dialogue box into which you can enter the cinema's name, and
+optionally an email address. This email address can be used to
+get DCP-o-matic to deliver KDMs via email.
+</para>
+
+<para>
+Once you have added a cinema, select it by clicking on its name, then
+click <guilabel>Add Screen...</guilabel>. The resulting dialogue
+allows you to enter a name for the screen and load in its certificate
+from a file. The certificate should be in SHA256 PEM format.
+</para>
+
+<para>
+Alternatively, certificates for projection systems made by some
+manufacturers can be downloaded from databases provided by the
+manufacturer. Currently this is supported for Doremi, Dolby, Barco,
+Christie and GDC equipment (through downloading Barco, Christie or GDC
+certificates requires you to have an appropriate account set up in
+DCP-o-matic's preferences). If you are targeting a screen with
+equipment by one of these manufacturers you can click
+<guilabel>Download</guilabel> then enter the serial number of the
+server in the screen and click <guilabel>Download</guilabel> again
+and, all being well, the certificate will be fetched. Most cinema
+projection or technical departments will know these serial numbers.
+</para>
+
+<para>
+Note that the reliability of the manufacturers' certificate databases
+cannot be guaranteed. It is vital that KDMs are tested by the
+destination cinema will in advance of show time to identify any
+problems.
+</para>
+
+<para>
+Once you have set up all the screens that you need KDMs for, select
+the CPL that you want to create the KDM for. You can use the
+drop-down list to select the CPLs in the current film project, or load
+a CPL from somewhere else. Select the cinemas and/or screens that you
+want KDMs for and fill in the start and end dates and times.
+</para>
+
+<para>
+You must also select the type of KDM that you want to generate. If in
+doubt, use <guilabel>Modified Transitional 1</guilabel>.
+</para>
+
+<note>
+The differences between the three KDM types are fairly subtle.
+<guilabel>DCI Specific</guilabel> and <guilabel>DCI Any</guilabel> add
+a <code><ContentAuthenticator></code> tag to the KDM which
+allows the exhibitor to check that the DCP and KDM have come from a
+bona-fide source. In addition, <guilabel>DCI Specific</guilabel> adds
+information on trusted devices to the KDM. This allows the KDM
+creator to specify devices (such as sound processors) that are allowed
+to use keys delivered by the KDM. At present it is not clear how
+widely the <guilabel>DCI Specific</guilabel> and <guilabel>DCI
+Any</guilabel> features are supported (or even tolerated) by servers
+so you are advised to use <guilabel>Modified Transitional
+1</guilabel>.
+</note>
+
+<para>
+Finally, choose what you want to do with the KDMs. They can be
+written to disk, to a location that you can specify by clicking
+<guilabel>Browse</guilabel>. Alternatively, if you choose
+<guilabel>Send by email</guilabel> the KDMs will be zipped up and
+emailed to the appropriate cinema email addresses. Click
+<guilabel>Make KDMs</guilabel> to generate the KDMs.
+</para>
+
</section>
<section>
-<title>Encryption using DCP-o-matic</title>
+<title>Creating KDMs using a DKDM</title>
+</section>
<para>
-There are two steps to distributing an encrypted DCP. First, the
-DCP's data must be encrypted, and secondly KDMs must be generated for
-those cinemas that are allowed to play the DCP.
+It can be inconvenient to need a whole DCP-o-matic project just to
+create KDMs for its film. Perhaps you want to archive the project to
+save space, or create KDMs on a different machine. In such situations
+it is easier to use a DKDM. This is a normal KDM, but instead of
+being targeted at a projection system (to allow it to decrypt the
+content) it is targeted at a particular user's certificate. This
+means that the certificate owner can create new KDMs for other users.
+The DKDM holds everything that is required to create further KDMs.
</para>
<para>
-The first part is simple: ticking the <guilabel>Encrypted</guilabel>
-box in the <guilabel>DCP</guilabel> tab of DCP-o-matic will encrypt
-the DCP using a random key that DCP-o-matic generates. The key will
-be written to the film's metadata file, which should be kept
-secure.
+Sometimes it is useful to create DKDMs that can be used by
+DCP-o-matic. If you create such a DKDM you can keep it and then, at
+any point in the future, use DCP-o-matic's standalone KDM creator to
+make KDMs for the DKDM's film for any cinema.
</para>
<para>
-A DCP that is generated with the <guilabel>Encrypted</guilabel> box
-ticked will not play on any projector as-is (it will be marked as
-‘locked’, or whatever the projector manufacturer's term
-is).
+In other cases a DKDM is sent to a 3rd party so that they can create
+KDMs for your films. This can be useful if, for example, you have a
+distributor who provides 24-hour KDM support to cinemas and can create
+KDMs for anybody that requires them at short notice.
+</para>
+
+<para>
+To create a DKDM for DCP-o-matic, open your encrypted project and
+select <guilabel>Make DKDM for DCP-o-matic...</guilabel> from the
+<guilabel>Jobs</guilabel> menu. Select the CPL that you want to make
+the DKDM for and click <guilabel>OK</guilabel>. This DKDM will then
+be available in the KDM creator. This is a separate program which you
+can start from the same place that you start the ‘normal’
+DCP-o-matic. Its window is shown in <xref linkend="fig-kdm-creator"/>.
+</para>
+
+<figure id="fig-kdm-creator">
+ <title>The KDM creator</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="30" fileref="screenshots/kdm-creator&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+To create KDMs, select the cinema(s) and/or screens that you want KDMs
+to be created for, the date range, the DCP that the KDMs are for and
+the destination for the KDMs and click <guilabel>Create
+KDMs</guilabel>.
+</para>
+
+<para>
+By default the <guilabel>DKDM</guilabel> list will list any DCPs for
+which you have clicked <guilabel>Make DKDM for
+DCP-o-matic</guilabel> in the main DCP-o-matic program. If you have
+other DKDMs you can add them by clicking <guilabel>Add...</guilabel> and
+specifying the file containing the DKDM.
+</para>
+
+<para>
+If another organisation wants to send you a DKDM they will ask you for
+a target certificate. You can get DCP-o-matic's target certificate by
+opening <guilabel>Preferences</guilabel> and clicking <guilabel>Export
+DCP decryption certificate...</guilabel> in the <guilabel>Keys</guilabel>
+tab.
+
+</para>
+
+</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>Should I encrypt?</title>
+
+ <para>
+ The question of whether encryption is appropriate for a given
+ project is a tricky one.
+ </para>
+
+ <para>
+ On the one hand, if you distribute an unencrypted DCP it is easy for
+ anybody to take it and do whatever they want with its contents.
+ They could use DCP-o-matic to convert it to a MP4, show it in
+ their cinema, or even edit and redistribute it in ways that you
+ do not like.
+ </para>
+
+ <para>
+ Encryption prevents this, but brings its own problems. It will be
+ impossible for a cinema to screen your DCP unless they have the
+ correct KDM. This is easy enough if things work as they should,
+ but problems can occur. For example, cinemas may substitute
+ broken playout servers with new ones without telling you: then the
+ KDM that you sent them will be invalid, and a new one required.
+ If the cinema can't get in touch with you, or somebody else who
+ can create a new KDM, they can't screen your DCP. Often these
+ problems are only discovered very close to showtime, with little
+ time for fixes.
+ </para>
+
+ <para>
+ If you are distributing encrypted DCPs widely it is worth thinking
+ about who will make the KDMs, and who will provide quick-response
+ technical support. It may be a good idea to engage a company who can
+ provide such services.
+ </para>
+
+</section>
+
+
+<section>
+<title>Encryption overview</title>
+
+<figure id="fig-encryption-overview">
+ <title>Overview of encryption</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="diagrams/crypt&dia;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+</section>
+</chapter>
+
+
+
+<!-- ============================================================== -->
+<chapter xml:id="ch-preferences" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<title>Preferences</title>
+
+<para>
+DCP-o-matic provides preferences which can be used to modify its
+behaviour. They are described in this chapter.
+</para>
+
+<para>
+Preferences can be edited by choosing
+<guilabel>Preferences...</guilabel> from the <guilabel>Edit</guilabel>
+menu. This opens a dialogue which is split into eleven tabs.
+</para>
+
+<!-- ============================================================== -->
+<section>
+<title>General</title>
+
+<para>
+The general tab is shown in <xref linkend="fig-prefs-general"/>.
+</para>
+
+<figure id="fig-prefs-general">
+ <title>General preferences</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/prefs-general&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+
+<!-- ============================================================== -->
+<section>
+<title>Language</title>
+
+<para>
+If you tick the <guilabel>Set Language</guilabel> checkbox and choose
+a language from the list, that language will be used for DCP-o-matic.
+You will need to restart DCP-o-matic to see the new language.
+</para>
+
+<para>
+The translations for DCP-o-matic have been contributed by helpful
+users. If your language is not on the last, head to <ulink
+url="https://dcpomatic.com/i18n.php">the DCP-o-matic website</ulink> to
+find out how to contribute a translation.
+</para>
+</section>
+
+
+<!-- ============================================================== -->
+<section>
+ <title>Interface complexity</title>
+
+ <para>
+ Choose <guilabel>Simple</guilabel> to see a cut-down, simplified
+ interface or <guilabel>Full</guilabel> to see DCP-o-matic's full
+ interface.
+ </para>
+</section>
+
+
+<!-- ============================================================== -->
+<section>
+<title>Number of threads DCP-o-matic should use</title>
+
+<para>
+When DCP-o-matic is encoding DCPs it can use multiple parallel threads
+to speed things up. Set this value to the number of threads
+DCP-o-matic should use. This should normally be the number of
+processors (or processor cores) in your machine. DCP-o-matic will try
+to set this up correctly when you run it for the first time.
+</para>
+
+</section>
+
+
+<!-- ============================================================== -->
+<section>
+<title>Number of threads DCP-o-matic encode server should use</title>
+
+<para>
+This is the number of threads that the encode server should use when
+it is running and helping another copy of DCP-o-matic to speed up its
+encode.
+</para>
+
+</section>
+
+
+<!-- ============================================================== -->
+<section>
+<title>Configuration file</title>
+
+<para>
+This is the location of DCP-o-matic's configuration file on disk. You
+can use this to share configuration between several copies of
+DCP-o-matic, across a network share, for instance.
+</para>
+</section>
+
+<!-- ============================================================== -->
+<section>
+<title>Cinema and screen database file</title>
+
+<para>
+This option allows you to change the file that DCP-o-matic uses to
+store details of the cinemas and screens used to make KDMs.
+</para>
+</section>
+
+
+<!-- ============================================================== -->
+<section>
+<title>Play sound via</title>
+
+<para>
+The checkbox to the left of <guilabel>Play sound</guilabel> enables or
+disables DCP-o-matic use of sound. On some machines there will be
+multiple options in the drop-down menu to decide how the sound should
+be played.
+</para>
+</section>
+
+<!-- ============================================================== -->
+<section>
+<title>Integrated loudness</title>
+
+<para>
+If <guilabel>Find integrated loudness, true peak and loudness range
+when analysing audio</guilabel> is ticked, DCP-o-matic will do extra
+work when analysing audio. Leave this ticked if the extra parameters
+are useful to you. If not, untick it and audio analysis will be
+faster.
+</para>
+
+</section>
+
+<!-- ============================================================== -->
+<section>
+<title>Automatically analyse content audio</title>
+
+<para>
+If this checkbox is ticked an audio analysis will be run whenever content is added that contains sound.
+</para>
+</section>
+
+<!-- ============================================================== -->
+<section>
+<title>Updates</title>
+
+<para>
+The <guilabel>Check for updates on startup</guilabel> option, if
+enabled, will tell DCP-o-matic to check on <ulink
+url="https://dcpomatic.com/">dcpomatic.com</ulink> to see if there any
+newer versions of DCP-o-matic then the one you are running. If so, a
+dialogue box will open with a link to download the new version.
+</para>
+
+<para>
+The <guilabel>Check for testing updates as well as stable
+ones</guilabel> option will also check for test updates as well as
+those that are formally ‘released’. This is useful if you
+like to live on the bleeding edge!
+</para>
+</section>
+
+<!-- ============================================================== -->
+<section>
+<title>Issuer and creator</title>
+
+<para>
+With these controls you can set the issuer and creator strings that
+will be put into the DCPs which you create. The issuer is typically your name
+(or your organisation's name) and the creator is typically the name of the tool
+used to make the DCP (e.g. DCP-o-matic).
+</para>
+</section>
+
+</section>
+
+<!-- ============================================================== -->
+<section>
+<title>Defaults</title>
+
+<para>
+The defaults tab is shown in <xref linkend="fig-prefs-defaults"/>.
+</para>
+
+<figure id="fig-prefs-defaults">
+ <title>Defaults preferences</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/prefs-defaults&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+The options in this tab simply allow you to set up default values for
+various properties of new films.
+</para>
+
+</section>
+
+<!-- ============================================================== -->
+<section>
+<title>Servers</title>
+
+<para>
+The servers tab is shown in <xref linkend="fig-prefs-servers"/>.
+</para>
+
+<figure id="fig-prefs-servers">
+ <title>Servers preferences</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/prefs-servers&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+If <guilabel>Use all servers</guilabel> is ticked DCP-o-matic will
+locate encoding servers automatically (see <xref
+linkend="ch-servers"/>).
</para>
<para>
-The second part is to generate KDMs for the cinemas that you wish to
-allow to play your DCP. This is done using the <guilabel>Make
-KDMs</guilabel> option on the <guilabel>Jobs</guilabel> menu. This
-will open the KDM dialogue box, as shown in <xref linkend="fig-kdm"/>.
+Instead of this (or in addition) servers can be specified explicitly.
+To add a server, click <guilabel>Add...</guilabel> and enter the host
+name or IP address of the server to use.
+</para>
+
+</section>
+
+
+<!-- ============================================================== -->
+<section xml:id="sec-prefs-keys">
+<title>Keys</title>
+
+<para>
+The Keys tab (shown in <xref linkend="fig-prefs-keys"/>) has controls
+related to the keys and certificates used in some parts of DCP
+creation.
</para>
-<figure id="fig-kdm">
- <title>KDM dialog</title>
+<figure id="fig-prefs-keys">
+ <title>Keys preferences</title>
<mediaobject>
- <imageobject>
- <imagedata fileref="screenshots/kdm&scs;"/>
- </imageobject>
+ <imageobject>
+ <imagedata fileref="screenshots/prefs-keys&scs;"/>
+ </imageobject>
</mediaobject>
</figure>
<para>
-In order to generate KDMs for a particular projector, you need to know
-its <emphasis>certificate</emphasis>. These are usually made
-available by the projector manufacturers as text files with a
-<code>.pem</code> extension.
+<guilabel>Export KDM decryption certificate...</guilabel> allows you
+to save the certificate that DCP-o-matic uses when decrypting KDMs
+that you give it. Use this option if somebody wants to make a KDM for
+you and asks for your certificate.
</para>
<para>
-DCP-o-matic can store these certificates to make life easier. It
-stores details of cinemas and screens within those cinemas. Each
-screen has a certificate for its projector. DCP-o-matic can generate
-KDMs for any screens that it knows about.
+<guilabel>Export all KDM decryption settings...</guilabel> exports a
+file which contains all the DCP-o-matic settings related to the use of
+KDMs supplied by other people. Use this button and <guilabel>Import
+all KDM decryption settings...</guilabel> to transfer settings between
+different copies of DCP-o-matic so that they can both use the same
+KDMs.
</para>
<para>
-To add a cinema, click <guilabel>Add Cinema...</guilabel>. This opens
-a dialogue box into which you can enter the cinema's name, and
-optionally an email address. This email address can be used to
-get DCP-o-matic to deliver KDMs via email, but it is optional.
+The two <guilabel>Advanced...</guilabel> buttons open advanced
+dialogue boxes for detailed manipulation of DCP-o-matic's certificate
+chains.
</para>
+</section>
+
+<section>
+<title>Advanced keys settings</title>
+
<para>
-Once you have added a cinema, select it by clicking on its name, then
-click <guilabel>Add Screen...</guilabel>. The resulting dialogue
-allows you to enter a name for the screen and load in its certificate
-from a file. The certificate should be in SHA256 PEM format.
+At the top of the <guilabel>Advanced</guilabel> dialogue for signing
+DCPs and KDMs is the chain of certificates that will be used to sign
+DCPs and KDMs. DCP-o-matic creates a random chain when you first run
+it and if you are happy to use this chain you can ignore the
+preferences. Otherwise, you can add or remove certificates from the
+chain using the <guilabel>Add...</guilabel> and
+<guilabel>Remove</guilabel> buttons.
</para>
<para>
-Once you have set up all the screens that you need KDMs for,
-DCP-o-matic can generate KDMs for the last DCP that you generated for
-the currently-loaded film. Select the cinemas and/or screens that you
-want KDMs for and fill in the start and end dates and times.
+If you want DCP-o-matic to re-create the certificate chain (using new,
+random certificates) click <guilabel>Re-make
+certificates and key...</guilabel> and specify your organisation and common
+names in the dialogue box that opens.
</para>
<para>
-Finally, choose what you want to do with the KDMs. They can be
-written to disk, to a location that you can specify by clicking
-<guilabel>Browse</guilabel>. Alternatively, if you choose
-<guilabel>Send by email</guilabel> the KDMs will be zipped up and
-emailed to the appropriate cinema email addresses. Click OK to
-generate the KDMs.
+Underneath the certificate chain is the private key that corresponds
+to the leaf certificate in the chain. You can specify your own
+private key by clicking <guilabel>Import...</guilabel>. You must do
+this if you change the leaf certificate, so that the leaf private key
+corresponds to the public key held in the leaf certificate.
</para>
-</section>
-
-</chapter>
-
-
-<chapter xml:id="ch-preferences" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
-<title>Preferences</title>
-
<para>
-DCP-o-matic provides a few preferences which can be used to modify its
-behaviour. This chapter explains those options.
+At the top of the <guilabel>Advanced</guilabel> dialogue for decrypting DCPs is the chain and key which is used by
+DCP-o-matic when you import an encrypted DCP as a piece of content.
+The leaf certificate of this chain contains the public key that should
+be used when targeting a KDM at DCP-o-matic.
</para>
-<section>
-<title>The preferences dialogue</title>
-
<para>
-The preferences dialogue is opened by choosing
-<guilabel>Preferences...</guilabel> from the <guilabel>Edit</guilabel>
-menu. The dialogue is split into five tabs.
+Clicking <guilabel>Export chain...</guilabel> will
+export the whole certificate chain.
</para>
-<section>
-<title>Miscellaneous</title>
+</section>
+
+<!-- ============================================================== -->
+<section xml:id="sec-prefs-tms">
+<title>TMS</title>
+<titleabbrev xml:id="sec-prefs-tms-short">TMS preferences</titleabbrev>
<para>
-The miscellaneous tab is shown in <xref linkend="fig-prefs-misc"/>.
+The TMS tab (shown in <xref linkend="fig-prefs-tms"/>) gives some
+options for specifying details about your theatre management system
+(TMS). If you do this, and your TMS accepts SSH or FTP connections,
+you can upload DCPs directly from DCP-o-matic to the TMS using the
+<guilabel>Send DCP to TMS</guilabel> option in the
+<guilabel>Jobs</guilabel> menu.
</para>
-<figure id="fig-prefs-misc">
- <title>Miscellaneous preferences</title>
+<figure id="fig-prefs-tms">
+ <title>TMS preferences</title>
<mediaobject>
- <imageobject>
- <imagedata fileref="screenshots/prefs-misc&scs;"/>
- </imageobject>
+ <imageobject>
+ <imagedata fileref="screenshots/prefs-tms&scs;"/>
+ </imageobject>
</mediaobject>
</figure>
-<section>
-<title>Language</title>
+<para>
+<guilabel>Protocol</guilabel> should be set to SCP or FTP as
+appropriate for your TMS. We know that the Arts Alliance Media (AAM)
+and the Doremi ranges uses SCP connections, and that Dolby's TMSs use
+FTP. Do let us know if you use any other type of TMS with the
+<guilabel>Send DCP to TMS</guilabel> feature.
+</para>
<para>
-If you tick the <guilabel>Set Language</guilabel> checkbox and choose
-a language from the list, that language will be used for DCP-o-matic.
-You will need to restart DCP-o-matic to see the new language.
+<guilabel>TMS IP address</guilabel> should be set to the IP address of
+your TMS, <guilabel>TMS target path</guilabel> to the place that DCPs
+should be uploaded to (which will be relative to the home directory of
+the SSH or FTP user). Finally, the user name and password are the
+credentials required to log into the TMS via SSH or FTP.
</para>
<para>
-The translations for DCP-o-matic have been contributed by helpful
-users. If your language is not on the last, head to <ulink
-url="http://dcpomatic.com/i18n.php">the DCP-o-matic website</ulink> to
-read about how to contribute a translation.
+Note that for this to work on Doremi servers you will need to set the
+<code>PasswordAuthentication</code> option in your server's
+<code>sshd_config</code> to <code>yes</code>.
</para>
+
</section>
+
+<!-- ============================================================== -->
<section>
-<title>Threads</title>
+<title>Email</title>
<para>
-When DCP-o-matic is encoding DCPs it can use multiple parallel threads
-to speed things up. Set this value to the number of threads
-DCP-o-matic should use. This should normally be the number of
-processors (or processor cores) in your machine. DCP-o-matic will try
-to set this up correctly when you run it for the first time.
+The Email tab is shown in <xref linkend="fig-prefs-email"/>.
</para>
-</section>
+<figure id="fig-prefs-email">
+ <title>Email preferences</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/prefs-email&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
-<section>
-<title>KDM emails</title>
+<para>
+These settings are used when DCP-o-matic sends emails.
+</para>
<para>
-DCP-o-matic can send KDMs (see <xref linkend="ch-encryption"/>) to
-cinemas (or anywhere else) via email. To make this work, enter a
-suitable outgoing mail (SMTP) server and ‘from’ address
-for these emails.
+ <guilabel>Outgoing mail server</guilabel> should be the host name of a mail (SMTP) server that DCP-o-matic can use. You can also specify the port that DCP-o-matic should use. <guilabel>User name</guilabel> and <guilabel>Password</guilabel> are the credentials that are required to send email through the server you have specified.
</para>
</section>
+<!-- ============================================================== -->
<section>
-<title>Defaults</title>
+<title>KDM email</title>
<para>
-The next few options allow you to set up default values for several
-properties of new films that you create.
+The KDM email tab is shown in <xref linkend="fig-prefs-kdm-email"/>.
+</para>
+
+<figure id="fig-prefs-kdm-email">
+ <title>KDM email preferences</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/prefs-kdm-email&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+This is a template for the email that is used to send KDMs out to
+cinemas. You can change it to say whatever you like. A few
+‘magic’ strings will be replaced by information from the
+KDM that is being sent; these strings are shown in <xref linkend="tab-kdm-magic"/>.
+</para>
+
+<table id="tab-kdm-magic">
+<title>‘Magic’ KDM strings</title>
+<tgroup cols='2' align='left' colsep='1' rowsep='1'>
+<tbody>
+<row>
+<entry><code>$CPL_NAME</code></entry><entry>DCP title</entry>
+</row>
+<row>
+<entry><code>$CINEMA_NAME</code></entry><entry>Cinema name</entry>
+</row>
+<row>
+<entry><code>$SCREENS</code></entry><entry>Name of screen or screens that KDMs are being generated for</entry>
+</row>
+<row>
+<entry><code>$START_TIME</code></entry><entry>The time from which the KDMs are valid</entry>
+</row>
+<row>
+<entry><code>$END_TIME</code></entry><entry>The time until which the KDMs are valid</entry>
+</row>
+</tbody>
+</tgroup>
+</table>
+
+<para>
+The <guilabel>Reset to default text</guilabel> will replace the current KDM email with DCP-o-matic's default.
</para>
-</section>
</section>
+<!-- ============================================================== -->
<section>
-<title>Colour conversions</title>
+<title>Notifications</title>
<para>
-The colour conversions tab is shown in <xref linkend="fig-prefs-colour-conversions"/>.
+The Notifications tab is shown in <xref linkend="fig-prefs-notifications"/>.
</para>
-<figure id="fig-prefs-colour-conversions">
- <title>Colour conversions preferences</title>
+<figure id="fig-prefs-notifications">
+ <title>Notifications preferences</title>
<mediaobject>
- <imageobject>
- <imagedata fileref="screenshots/prefs-colour-conversions&scs;"/>
- </imageobject>
+ <imageobject>
+ <imagedata fileref="screenshots/prefs-notifications&scs;"/>
+ </imageobject>
</mediaobject>
</figure>
<para>
-As part of the encoding process, DCP-o-matic has to convert the colour
-space of the source files that you use into XYZ, the colour space used
-by the DCI standard.
-</para>
-
-<para>
-Colour conversion is discussed in more detail in a separate document
-<ulink url="http://dcpomatic.com/manual/colour.pdf">colour.pdf</ulink>.
+DCP-o-matic can notify the user when jobs have completed. These
+notifications can be either or both of a message box on-screen (if
+<guilabel>Message box</guilabel> is ticked) and email (if
+<guilabel>Email</guilabel> is ticked). If you enable email
+notifications you can fill in the details of the emails you want to
+send.
</para>
<para>
-These preferences control a list of presets which are suitable for
-converting from common input colour spaces to XYZ.
+The bottom box in the tab is the contents of the email that should
+be sent. DCP-o-matic will replace the ‘magic’ strings
+<code>$JOB_NAME</code> and <code>$JOB_STATUS</code> in the with the
+details of the job that has completed.
</para>
</section>
+
+<!-- ============================================================== -->
<section>
-<title>Metadata</title>
+<title>Cover sheet</title>
<para>
-The metadata tab is shown in <xref linkend="fig-prefs-metadata"/>.
+The DCP cover sheet configuration is shown in <xref linkend="fig-prefs-cover-sheet"/>.
</para>
-<figure id="fig-prefs-metadata">
- <title>Metadata preferences</title>
+<figure id="fig-prefs-cover-sheet">
+ <title>DCP cover sheet preferences</title>
<mediaobject>
- <imageobject>
- <imagedata fileref="screenshots/prefs-metadata&scs;"/>
- </imageobject>
+ <imageobject>
+ <imagedata fileref="screenshots/prefs-cover-sheet&scs;"/>
+ </imageobject>
</mediaobject>
</figure>
<para>
-This allows you to set up a couple of identifiers that are written
-into the DCP. The default values should cause no problems.
+This is a template for the cover sheet that is written next to every DCP that DCP-o-matic creates. You can change it to say whatever you like. A few
+‘magic’ strings will be replaced by information from the
+DCP that has been made:
+</para>
+
+<table>
+<title>‘Magic’ cover sheet strings</title>
+<tgroup cols='2' align='left' colsep='1' rowsep='1'>
+<tbody>
+<row>
+<entry><code>$CPL_NAME</code></entry><entry>DCP title</entry>
+</row>
+<row>
+<entry><code>$TYPE</code></entry><entry>DCP content type (e.g. feature, trailer...)</entry>
+</row>
+<row>
+<entry><code>$CONTAINER</code></entry><entry>The container ratio (e.g. flat, scope...)</entry>
+</row>
+<row>
+<entry><code>$AUDIO</code></entry><entry>Details of the audio channels</entry>
+</row>
+<row>
+<entry><code>$AUDIO_LANGUAGE</code></entry><entry>Audio language</entry>
+</row>
+<row>
+<entry><code>$SUBTITLE_LANGUAGE</code></entry><entry>Subtitle language</entry>
+</row>
+<row>
+<entry><code>$LENGTH</code></entry><entry>DCP length in hours, minutes and seconds</entry>
+</row>
+<row>
+<entry><code>$SIZE</code></entry><entry>DCP size in gigabytes</entry>
+</row>
+</tbody>
+</tgroup>
+</table>
+
+<para>
+The <guilabel>Reset to default text</guilabel> will replace the current cover sheet with DCP-o-matic's default.
</para>
</section>
-<section xml:id="sec-prefs-tms">
-<title>TMS</title>
+
+<!-- ============================================================== -->
+<section xml:id="sec-prefs-advanced">
+<title>Advanced</title>
+<titleabbrev xml:id="sec-prefs-advanced-short">Advanced preferences</titleabbrev>
<para>
-The TMS tab (shown in <xref linkend="fig-prefs-tms"/>) gives some
-options for specifying details about your theatre management system
-(TMS). If you do this, and your TMS accepts SSH connections, you can
-upload DCPs directly from DCP-o-matic to the TMS using the
-<guilabel>Send DCP to TMS</guilabel> option in the
-<guilabel>Jobs</guilabel> menu.
+The advanced preferences are shown in <xref linkend="fig-prefs-advanced"/>.
</para>
-<figure id="fig-prefs-tms">
- <title>TMS preferences</title>
+<figure id="fig-prefs-advanced">
+ <title>Advanced preferences</title>
<mediaobject>
- <imageobject>
- <imagedata fileref="screenshots/prefs-tms&scs;"/>
- </imageobject>
+ <imageobject>
+ <imagedata fileref="screenshots/prefs-advanced&scs;"/>
+ </imageobject>
</mediaobject>
</figure>
<para>
-<guilabel>TMS IP address</guilabel> should be set to the IP address of
-your TMS, <guilabel>TMS target path</guilabel> to the place that DCPs
-should be uploaded to (which will be relative to the home directory of
-the SSH user). Finally, the user name and password are the
-credentials required to log into the TMS via SSH.
+<guilabel>Maximum JPEG2000 bandwidth</guilabel> specifies the maximum
+bit-rate of JPEG2000 that DCP-o-matic will allow you to create. You
+are advised to leave this at 250Mbit/s in normal use for maximum DCP
+compatibility.
</para>
-</section>
-<section>
-<title>KDM email</title>
+<para>
+<guilabel>Allow any DCP frame rate</guilabel> removes the limits on
+the DCP video frame rates that DCP-o-matic will create. This may be
+useful for experimentation. Again, you are strongly advised to leave
+this unticked for normal use.
+</para>
<para>
-The KDM email is shown in <xref linkend="fig-prefs-kdm-email"/>.
+<guilabel>Only servers encode</guilabel> makes DCP-o-matic encode
+JPEG2000 data only on encoding servers and not on the host. We
+suggest you leave this unticked unless you have a good reason to do otherwise.
</para>
-<figure id="fig-prefs-kdm-email">
- <title>KDM email preferences</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="screenshots/prefs-kdm-email&scs;"/>
- </imageobject>
- </mediaobject>
-</figure>
+<para>
+With the filename format fields you can adjust the filenames that are
+used for metadata (CPL and PKL files) and assets (MXF and subtitle
+files). Below each field there is a list of the ‘magic’
+values that you can use in the format and an example of a filename
+that you might see with your current settings.
+</para>
<para>
-This is a template for the email that is used to send KDMs out to
-cinemas. You can change it to say whatever you like. The
-‘magic’ string <code>$CPL_NAME</code> will be replaced by
-DCP's title.
+The four checkboxes labelled <guilabel>Log</guilabel> control what
+sort of messages DCP-o-matic writes to its log file when creating a
+DCP. It is useful to leave <guilabel>General</guilabel>,
+<guilabel>Warnings</guilabel> and <guilabel>Errors</guilabel> ticked
+as this makes the log files useful for tracking down bugs.
</para>
-</section>
-</section>
+<para>
+The <guilabel>Timing</guilabel> checkbox will enable extra log entries
+to allow developers to investigate and optimise the speed of
+DCP-o-matic. It will significantly increase the size of the log files
+that are generated, so in normal use it is best to leave this
+unticked.
+</para>
+</section>
</chapter>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en" xml:id="ch-frame-rates">
however, always possible.
</para>
+
+<!-- ============================================================== -->
<section>
-<title>DCP rate limitations</title>
+<title>DCP frame rate limitations</title>
<para>
-There are some limitations to video and audio rates in DCPs. This is
+There are some limitations to video and audio frame rates in DCPs. This is
complicated by the fact that not all projectors will play DCPs at the
-same rates. It is possible to create a DCP which one projector will
-play fine, but another (of a different type) will refuse to play, or
-even refuse to ingest.
+same frame rates. It is possible to create a DCP which one projector will
+play fine, but another (of a different type) will refuse to play.
</para>
+
+<!-- ============================================================== -->
<section>
<title>Guaranteed rates</title>
<para>
-The only rates that are (pretty much) guaranteed to work on all DCI
-projectors is 24 frames per second (fps) for video and 48kHz or 96kHz
-for audio. If you are sending your DCPs to unknown places it wise to
-consider using these rates if at all possible.
+The only rates that are guaranteed to work on all DCI projectors are
+24 frames per second (fps) for video and 48kHz for audio. If you are
+sending DCPs to unknown places it is wise to consider using these
+rates if at all possible.
</para>
</section>
+
+<!-- ============================================================== -->
<section>
<title>Other often-supported rates</title>
<para>
Many projectors now in the wild support additional video frame rates:
-25, 30 and 48 fps.
+25, 30, 48, 50 and 60 fps.
</para>
</section>
+
+<!-- ============================================================== -->
<section>
<title>Adapting content to fit the DCP rate</title>
</section>
</section>
+
+<!-- ============================================================== -->
<section>
<title>Setting up</title>
The <guilabel>Frame Rate</guilabel> control in the
<guilabel>DCP</guilabel> tab sets the video frame rate that the DCP
will use. Clicking <guilabel>Use best</guilabel> sets the rate to
-what DVD-o-matic thinks is the best for your content. With this
-button, DCP-o-matic assumes that the whole range of frame rates (24,
-25, 30 and 48fps) are allowable.
+what DCP-o-matic thinks is the best for your content. With this
+button, DCP-o-matic assumes that the most commonly-working frame rates (24,
+25 and 30fps) are allowed.
</para>
<para>
content.
</para>
+<para>
+If you want to experiment with other non-standard frame rates, you can
+do so by ticking the <guilabel>Allow any DCP frame rate</guilabel> in
+the <guilabel>Advanced</guilabel> tab of the preferences dialogue (see the
+<xref linkend="sec-prefs-advanced" endterm="sec-prefs-advanced-short"/>). You are strongly advised to
+use this only on your own equipment, and only for experimentation
+purposes.
+</para>
+
</section>
</chapter>
+<!-- ============================================================== -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en" xml:id="ch-servers">
<title>Encoding servers</title>
can mix Windows PCs, Macs and Linux machines as you wish.
</para>
+
+<!-- ============================================================== -->
<section>
<title>Running the servers</title>
</para>
<programlisting>
-dcpomatic_server_cli
+dcpomatic2_server_cli
</programlisting>
<para>
</para>
<programlisting>
-dcpomatic_server_cli -t 4
+dcpomatic2_server_cli -t 4
</programlisting>
<para>
<para>If you would rather not bother installing DCP-o-matic on your
server computers, the other option is to use the live-CD
image that you can download from the <ulink
-url="http://dcpomatic.com/">DCP-o-matic web site.</ulink></para>
+url="https://dcpomatic.com/">DCP-o-matic web site.</ulink></para>
<para>Either burn the image to CD, or write it to a USB stick (using
something like <ulink
</para>
</section>
+
+<!-- ============================================================== -->
<section>
<title>Setting up DCP-o-matic</title>
</para>
</section>
+
+<!-- ============================================================== -->
<section>
<title>Some notes about encode servers</title>
after you have created a DCP for a film called ‘DCP Test’.
</para>
-<figure id="fig-file-structure">
- <title>Creating a new film</title>
+<figure id="fig-file-structure">
+ <title>Creating a new film</title>
<mediaobject>
- <imageobject>
- <imagedata fileref="diagrams/file-structure&dia;"/>
- </imageobject>
+ <imageobject>
+ <imagedata scale="100" fileref="diagrams/file-structure&dia;"/>
+ </imageobject>
</mediaobject>
</figure>
Following this is the DCP itself:
<code>DCP-TEST_EN-XX_UK-U_51_2K_CSY_20130218_CSY_OV</code>. This
contains some small XML files, which describe the DCP, and two large
-MXF files, which contain the DCP's audio and video data. This folder
+MXF files, which contain the DCP's audio and video data. It may also
+contain subtitles in either XML or MXF format. This folder
(<code>DCP-TEST_EN-XX_...</code>) is what you should ingest, or pass
to the cinema which is showing your DCP.
</para>
</chapter>
+
+<chapter>
+ <title>Command-line tools</title>
+
+ <para>
+ 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.
+ </para>
+
+ <para>
+ 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. 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
+ do the encode. This allows, for example, setup on a relatively
+ low-powered machine before running the encode on a higher-powered
+ headless server.
+ </para>
+
+ <section>
+ <title><code>dcpomatic2_create</code></title>
+
+ <para>
+ The syntax for <code>dcpomatic2_create</code> is:
+ </para>
+
+ <para>
+ <code>dcpomatic2_create [OPTION] <CONTENT> [[OPTION] <CONTENT> ...]</code>
+ </para>
+
+ <para>
+ <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>
+
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dcpomatic_create.xml"/>
+
+ <para>
+ For example, to setup a film using a MP4 file you might do:
+ </para>
+
+ <para>
+ <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>
+
+ <para>
+ <code>dcpomatic2_create</code> will use any default settings that you have configured in the main DCP-o-matic preferences.
+ </para>
+ </section>
+
+ <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>
+
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dcpomatic_cli.xml"/>
+
+ <para>
+ For example, to encode a film called <code>my_film</code> you might do:
+ </para>
+
+ <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>
+
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dcpomatic_kdm_cli.xml"/>
+
+ </section>
+</chapter>
+
+
+
+<!-- ============================================================== -->
<chapter>
<title>Loose ends</title>
This chapter collects a few notes on bits of DCP-o-matic that do not fit elsewhere in the manual.
</para>
+
+<!-- ============================================================== -->
<section>
<title>Resuming encodes</title>
</chapter>
+<!-- ============================================================== -->
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<title>Common tasks</title>
+
+<para>
+This chapter describes how to carry out some commonly-required tasks
+with DCP-o-matic. The full details are elsewhere in the manual: here
+we just discuss different approaches to these tasks and how to carry
+them out.
+</para>
+
+<section>
+<title>Adding subtitles to an existing DCP</title>
+
+<para>
+You have three options:
+</para>
+
+<itemizedlist>
+<listitem>Make a “Version File” (VF) DCP.</listitem>
+<listitem>Make a complete DCP with projector-added subtitles.</listitem>
+<listitem>Make a complete DCP with burnt-in subtitles.</listitem>
+</itemizedlist>
+
+<para>
+Making a VF DCP is usually the best option. This will be a very small
+DCP which contains only the subtitles: it refers to your existing DCP
+for the picture and sound. The projectionist will ingest both the
+existing and VF DCPs and play back the VF. The advantages of this
+approach are that the VF is very quick to generate, and small in size,
+making it easy to distribute. This is especially useful if you have
+to make VF DCPs in many different languages.
+</para>
+
+<para>
+Making a complete DCP with projector-added subtitles gives you a new,
+single DCP which the projectionist can ingest and play. It will be
+the same size as your existing DCP, and fairly quick to create. This
+approach relies on the projector (or server) to create the subtitles
+and overlay them on the image, which mostly works well but is not
+100% reliable.
+</para>
+
+<para>
+Making a complete DCP with burnt-in subtitles gives you a new, single DCP
+but with the subtitles rendered by DCP-o-matic and copied into your
+image. This is slower to create than a DCP with projector-added
+subtitles as every video frame with a subtitle must be re-encoded.
+The advantage of this approach is that it is less likely to go wrong,
+especially if you are using unusual subtitle positioning or character
+sets.
+</para>
+
+<section>
+<title>Making a VF DCP</title>
+
+<itemizedlist>
+<listitem>Start a new DCP-o-matic film.</listitem>
+<listitem>Click <guilabel>Add DCP...</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>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
+DCP.</listitem>
+<listitem>Choose <guilabel>Make DCP</guilabel> from the menu.</listitem>
+</itemizedlist>
+
+</section>
+
+<section>
+<title>Making a complete DCP with projector-added subtitles</title>
+
+<itemizedlist>
+<listitem>Start a new DCP-o-matic film.</listitem>
+<listitem>Click <guilabel>Add DCP...</guilabel> and specify your existing DCP's folder.</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
+DCP. Adjust the appearance using controls in the
+<guilabel>Subtitle</guilabel> tab if required.</listitem>
+<listitem>Choose <guilabel>Make DCP</guilabel> from the menu.</listitem>
+</itemizedlist>
+
+</section>
+
+<section>
+<title>Making a complete DCP with burnt-in subtitles</title>
+
+<itemizedlist>
+<listitem>Start a new DCP-o-matic film.</listitem>
+<listitem>Click <guilabel>Add DCP...</guilabel> and specify your existing DCP's folder.</listitem>
+<listitem>Add your subtitles to the film in whatever format you have.</listitem>
+<listitem>Go to the <guilabel>Subtitle</guilabel> tab and tick the <guilabel>Burn subtitles into image</guilabel> checkbox.</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
+DCP. Adjust the appearance using controls in the
+<guilabel>Subtitle</guilabel> tab if required.</listitem>
+<listitem>Choose <guilabel>Make DCP</guilabel> from the menu.</listitem>
+</itemizedlist>
+
+</section>
+</section>
+
+<section>
+<title>Adding soundtracks or subtitles in different languages</title>
+
+<para>
+If you have a film that is to be dubbed or subtitled in several
+languages, the best approach with DCP-o-matic is as follows:
+</para>
+
+<itemizedlist>
+<listitem>Make a DCP with the common elements (perhaps just the video, or maybe the video and sound); this is known as the Original Version (OV).</listitem>
+<listitem>For each language, make a new Version File (VF) DCP which refers to the OV.</listitem>
+</itemizedlist>
+
+<para>
+Once you have done this, you send the OV DCP to every cinema and then
+the appropriate VF to each cinema depending on what language they want
+to play the film in. The projectionist ingests both DCPs and then plays the VF.
+</para>
+
+<para>
+The advantage of this approach is that the VF DCPs are much smaller
+than the OV since they only have the language-specific parts. If you
+are just changing the subtitles you can often ship the OV by normal
+transport means (e.g. a hard drive or high-speed download) and send
+the VF by email.
+</para>
+
+<para>
+The full details of OV and VF files are discussed in <xref linkend="sec-overlay"/>. The steps can be summarised as follows:
+</para>
+
+<itemizedlist>
+<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>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>
+
+</section>
+
+</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-verifier" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+ <title>Verifying DCPs</title>
+
+ <para>
+ The player also offers a DCP verifier. To check a DCP,
+ open it and then select <guilabel>Verify DCP</guilabel> from the
+ <guilabel>Tools</guilabel> menu.
+ </para>
+
+ <para>
+ The verifier will report three kinds of problems:
+ </para>
+
+ <itemizedlist>
+ <listitem><emphasis>Errors</emphasis> — serious problems with the DCP that are likely to cause problems on playback.</listitem>
+ <listitem><emphasis>Bv2.1 errors</emphasis> — errors described by the <ulink url="https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=9161348">SMPTE Bv2.1 standard</ulink>.</listitem>
+ <listitem><emphasis>Warnings</emphasis> — small problems that may not matter.</listitem>
+ </itemizedlist>
+
+ <para>
+ The following sections list what the verifier checks for in each category.
+ </para>
+
+ <section>
+ <title>Errors</title>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="verify_errors.xml"/>
+ </section>
+
+ <section>
+ <title>Bv2.1 errors</title>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="verify_bv21_errors.xml"/>
+ </section>
+
+ <section>
+ <title>Warnings</title>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="verify_warnings.xml"/>
+ </section>
+
+</chapter>
+
+
+<!-- ============================================================== -->
+<chapter>
+<title>Keyboard shortcuts</title>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="shortcuts.xml"/>
+</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>
+
+<!-- LocalWords: dbcent DCP matic Hetherington DCPs KDMs GPL XP sid
+-->
+<!-- LocalWords: matic's jessie Tahr Xenial Xerus Centos Mageia GTK
+-->
+<!-- LocalWords: Karner FFmpeg libsndfile libsamplerate OpenSSL waf
+-->
+<!-- LocalWords: libopenjpeg libssh wxWidgets libxml xmlsec libzip
+-->
+<!-- LocalWords: asdcplib libdcp libsub libcxml sstream sudo Sintel
+-->
+<!-- LocalWords: dcpomatic TMS SCP timecode DCP's unencrypted OV Gb
+-->
+<!-- LocalWords: Decrypting KDM decrypt decrypted MOV VOB WAV AIFF
+-->
+<!-- LocalWords: PNG srt ssa xml wav Lfe XYZ colourspace sRGB RGB
+-->
+<!-- LocalWords: colourspaces pdf fader CP Doremi CaptiView SubRip
+-->
+<!-- LocalWords: SubStation BluRay
+-->
projects / dcpomatic.git / blobdiff