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 gory details.
+</note>
+
</section>
</chapter>
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
+click to open it. Then drag the DCP-o-matics icon to your
<guilabel>Applications</guilabel> folder or wherever else you would
like to install it.
</para>
+<para>
+You do not have to install all the applications, but you must always
+install <code>DCP-o-matic 2.app</code> as the other applications
+depend on it.
+</para>
+
</section>
<!-- ============================================================== -->
<listitem>Debian unstable (‘sid’)</listitem>
<listitem>Ubuntu 12.04 (‘Precise Pangolin’)</listitem>
<listitem>Ubuntu 14.04 (‘Trusty Tahr’)</listitem>
- <listitem>Ubuntu 15.04 (‘Vivid Vervet’)</listitem>
<listitem>Ubuntu 15.10 (‘Wily Werewolf’)</listitem>
+ <listitem>Ubuntu 16.04 (‘Xenial Xerus’)</listitem>
</itemizedlist>
<para>
<!-- ============================================================== -->
<section>
<title>Centos Linux</title>
- <para>There are <code>.rpm</code> packages for Centos 6.5 and 7 on
+ <para>There are <code>.rpm</code> packages for Centos 5, 6.5 and 7 on
<ulink url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>
</para>
</section>
<para>
Installation on other Linux systems (for which no packages are
-available) is quite hard; you will have to compile it from source. If
-you are using distribution for which no packages are available, do let
-me know by <ulink url="mailto:carl@dcpomatic.com">email</ulink> and I
-will look into providing packages on the website.
+available) is quite hard as it must be compiled from source. If you
+can't download packages for your distribution, do let me know by
+<ulink url="mailto:carl@dcpomatic.com">email</ulink> and I will look
+into providing packages on the website.
</para>
<para>
<!-- ============================================================== -->
<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>
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
+website</ulink>. Generally one would want to use the
highest-resolution material available, but for this test we will use
the low-resolution version to save everyone's bandwidth bills.
</para>
</para>
<para>
-Alternatively, if you have a projector or Theatre Management System
-(TMS) that is accessible via SCP across your network, you can upload
+Alternatively, if you have a projector or Theatre Management System
+(TMS) that is accessible via SCP or FTP across your network, you can upload
the content directly from DCP-o-matic. See the <xref
linkend="sec-prefs-tms" endterm="sec-prefs-tms-short"/> in <xref linkend="sec-prefs-tms"/>.
</para>
<!-- ============================================================== -->
<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"/>.
</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>Play 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>Play length</guilabel> setting, as shown in <xref
linkend="fig-timing-tab"/>.
</para>
<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>
<para>
Frequently DCP-o-matic is used to take content in formats such as MP4
-and convert it to JPEG2000 for a DCP. Alternatively, it can be used
+and convert it to JPEG2000 for a DCP. It can also be used
to take existing DCPs and modify them in various ways.
</para>
computationally intensive as encoding them.
</para>
+<para>
+If your DCP is a Version File (VF), in other words it refers to
+another DCP's assets, you should import it as follows:
+</para>
+
+<itemizedlist>
+<listitem>Use <guilabel>Add folder...</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>
</para>
<para>
-DCP-o-matic can do this if you avoid changes to the following content
-settings:
+DCP-o-matic can do this if you <emphasis>avoid</emphasis> changes to
+the following content settings:
</para>
<itemizedlist>
(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>Refer to existing DCP</guilabel> checkbox
+in the tabs for the parts of the DCP that you want to refer to in your
+new DCP. For example, to refer to the Content DCP's video and audio you would select the <guilabel>Video</guilabel> tab, click <guilabel>Refer to existing DCP</guilabel> then select the <guilabel>Audio</guilabel> tab and do the same.</listitem>
+<listitem>Do <guilabel>Make DCP</guilabel> as usual and your VF DCP will be created.</listitem>
+</itemizedlist>
+
</section>
</section>
<listitem>Subtitle — a file containing subtitle which will be
superimposed on the image of the DCP. These can be
-<guilabel>.srt</guilabel> or <guilabel>.xml</guilabel>
+<guilabel>.srt</guilabel>, <guilabel>.ssa</guilabel> or <guilabel>.xml</guilabel>
files.</listitem>
<listitem>DCP — an existing DCP.</listitem>
</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) or included
-as a separate subtitle ‘asset’ within your DCP (in which
-case the projector overlays them onto the image on playback). The
-difference between these two arrangements is illustrated by <xref
-linkend="fig-burn-in"/> and <xref linkend="fig-discrete"/>
+DCP-o-matic can either:
+</para>
+
+<itemizedlist>
+ <listitem>Extract subtitles that are embedded in video files, or</listitem>
+ <listitem>Use subtitles from SubRip (<code>.srt</code>), SubStation
+ Alpha (<code>.ssa</code>) or DCP XML files. You may find the great
+ free program <ulink
+ url="http://www.nikse.dk/subtitleedit/">Subtitle Edit</ulink> useful
+ for creating such files.</listitem>
+</itemizedlist>
+
+<para>
+Embedded subtitles are usually represented using a set of bitmaps,
+especially on files that have come from DVD or BluRay. Such subtitles
+can (currently) only be ‘burnt’ into the DCP (that is,
+they are included in the image and not overlaid by the projector).
+</para>
+
+<para>
+With SubRip, SubStation Alpha or DCP subtitles you have the choice to
+either burn-in or include the subtitles as 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-burn-in">
every language.
</para>
-<para>
-Note that subtitles come in two types: text and bitmap. Text
-subtitles are expressed as plain text and can be either burnt into the
-image or included as a separate subtitle asset within the DCP. Bitmap
-subtitles, on the other hand, are expressed as pre-rendered bitmaps.
-They cannot (yet) be added to the DCP as a separate asset and must be
-burnt into the image.
-</para>
-
<para>
Select the <guilabel>Use Subtitles</guilabel> check-box to enable
-these subtitles.
+the subtitles in the selected content.
</para>
<para>
Select the <guilabel>Burn subtitles into image</guilabel> check-box to
burn these subtitles into the image; if this is not ticked the
subtitles will be included separately in the DCP to be rendered by the
-projector.
+projector. This check-box will always be ticked if you are using
+embedded ‘image’ subtitles.
</para>
<para>
that is used when the content has more than one.
</para>
+<para>
+If you are using non-embedded (text) subtitles 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>
+With any subtitles you can click <guilabel>Appearance...</guilabel> to
+change how the subtitles look.
+</para>
+
</section>
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>
The <guilabel>Processor</guilabel> control allows you to select a
-process to apply to the audio before it goes into the DCP. Two processes are currently provided:
+process to apply to the audio before it goes into the DCP. Three processes are currently provided:
</para>
<itemizedlist>
<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.
+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>
</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"/>.
+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">
</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.
+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>
manufacturers can be downloaded from databases provided by the
manufacturer. Currently this is supported for Doremi and Dolby
equipment. If you are targeting a screen with equipment by one of
-these manufacturers you can select Doremi or Dolby from the
-<guilabel>Server manufacturer</guilabel> selection and then click
-<guilabel>Download</guilabel>. In the next dialogue box, enter
-details of the screen and click <guilabel>Download</guilabel> and, all
-being well, the certificate will be fetched.
+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.
</para>
<para>
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 OK to
-generate the KDMs.
+emailed to the appropriate cinema email addresses. Click
+<guilabel>Make KDMs</guilabel> to generate the KDMs.
+</para>
+
+</section>
+
+<section>
+<title>Creating KDMs using a DKDM</title>
+</section>
+
+<para>
+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 users'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>
+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>
+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 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 overview</title>
+
+<figure id="fig-encryption-overview">
+ <title>Overview of encryption</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="diagrams/crypt&dia;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+</section>
</chapter>
</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>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>Updates</title>
If you want to import an encrypted DCP you will need to give the
decryption certificate to the distributor of the DCP so that they can
generate a DKDM for you. You can save this certificate to disk by
-clicking <guilabel>Export DCP decryption certificate</guilabel>. As
+clicking <guilabel>Export DCP decryption certificate...</guilabel>. As
with the signing chain, DCP-o-matic will create a certificate chain
and private key for you. You can also choose to load your own
certificates and key or re-make the chain and key with new, random
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>