<!ENTITY % extensions SYSTEM "extensions.ent">
%extensions;
]>
-<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<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
<title>Windows</title>
<para>
-To install DCP-o-matic on Windows, simply download the installer from
+To install DCP-o-matic on Windows, download the installer from
<ulink url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>
and double-click it. Click through the installer wizard, and
DCP-o-matic will be installed onto your machine.
<para>
You can install DCP-o-matic on Ubuntu 12.04 (‘Precise
-Pangolin’), 12.10 (‘Quantal Quetzal’) or 13.04
-(‘Raring Ringtail’) using <code>.deb</code> packages:
-
download the appropriate package from <ulink
+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.
</section>
+<section>
+<title>Debian Linux</title>
+<para>
+Packages are available for Debian 7 (squeeze) from <ulink
+url="http://dcpomatic.com/">http://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>
+</section>
+
+<section>
+<title>Arch Linux</title>
+<para>
+Packages for Arch Linux are available from <ulink
+url="https://aur.archlinux.org/packages/dcpomatic/">https://aur.archlinux.org/packages/dcpomatic/</ulink>,
+thanks to Stefan Karner.
+</para>
+</section>
+
<section>
<title>Other Linux distributions</title>
<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</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>
The first 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 other option <guilabel>3D
-left/right</guilabel> tells DCP-o-matic to interpret the frame as a
+image as a standard 2D frame. The <guilabel>3D
+left/right</guilabel> option tells DCP-o-matic to interpret the frame as a
left-right pair, as shown in <xref linkend="fig-3d-left-right"/>.
</para>
</figure>
<para>
-This option can be used to generate a 3D DCP. Other means of creating
-3D will be added in the future.
+Alternatively the <guilabel>3D top/bottom</guilabel> option tells
+DCP-o-matic to see the frame as a top-bottom pair, as shown in <xref
+linkend="fig-3d-top-bottom"/>.
</para>
+<figure id="fig-3d-top-bottom">
+ <title>3D top/bottom image type</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="100" fileref="diagrams/3d-top-bottom&dia;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
</section>
</para>
<para>
-Current versions of DCP-o-matic only know about the Dolby CP750. If
-you use a different sound processor, and know the gain curve of its
-volume control, <ulink url="mailto:cth@carlh.net">get in
+Current versions of DCP-o-matic only know about the Dolby CP650 and
+CP750. If you use a different sound processor, and know the gain
+curve of its volume control, <ulink url="mailto:carl@dcpomatic.com">get in
touch</ulink>.
</para>
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> checkbox to enable
+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.
</section>
-<!-- XXX: timing tab -->
+<section>
+<title>Timing</title>
+
+<para>
+The timing tab contains settings related to the timing of your
+content, as shown in <xref linkend="fig-timing-tab-detail"/>.
+</para>
+
+<figure id="fig-timing-tab-detail">
+ <title>Timing settings tab</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/timing-tab&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+Most of the timing tab's entries are <emphasis>time-codes</emphasis>.
+These are expressed as four numbers, as shown in <xref
+linkend="fig-timecode"/>.
+</para>
+
+<figure id="fig-timecode">
+ <title>Timecode</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="diagrams/timecode&dia;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+<guilabel>Position</guilabel> is the time at which this piece of
+content should start within the DCP. In most cases, this will be
+<code>0:0:0:0</code> to make the content start at the beginning of the
+DCP.
+</para>
+
+<para>
+<guilabel>Full length</guilabel> is the length of the piece of
+content. This can only be set for still-image content: for video or
+sound content, it is fixed by the nature of the content file. If
+still-image content is being used you can set the length for which it
+should be displayed using this control.
+</para>
+
+<para>
+<guilabel>Trim from start</guilabel> specifies the amount that should be trimmed from the start of the content.
+</para>
+
+<para>
+<guilabel>Trim from end</guilabel> specifies the amount that should be trimmed from the end of the content.
+</para>
+
+<para>
+<guilabel>Play length</guilabel> indicates how long this piece of
+content will be once the trims have been applied. This will be equal
+to the full length minus <guilabel>trim-from-start</guilabel> and minus <guilabel>trim-from-end</guilabel>.
+</para>
+
+<para>
+<guilabel>Video frame rate</guilabel> specifies the frame rate for still-image content.
+</para>
+
+<para>
+Each timecode control has a <guilabel>Set</guilabel> which you should
+click when you have entered a new value for a timecode. The
+<guilabel>Set</guilabel> button will make DCP-o-matic take account of
+any changes to the corresponding timecode.
+</para>
+
+</section>
</chapter>
<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 DCI
+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 DCI name</guilabel>
+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
-DCI-compliant name.
+ISDCF-compliant name.
</para>
<para>
Underneath the name field is a preview of the name that the DCP will
-get. To use a DCI-compliant name, tick the <guilabel>Use DCI
-name</guilabel> checkbox. The DCI name will be composed using details
+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 DCI name details dialogue box, which you can
+can be specified in the ISDCF name details dialogue box, which you can
open by clicking on the <guilabel>Details</guilabel> button.
</para>
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 later.
-<!--- XXX: link -->
+content to fit the specified frame rate. Frame rates are discussed in
+more detail in <xref linkend="ch-frame-rates"/>.
+</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>
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,
+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>
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 (MBps).
+between 50 and 250 megabits per second (Mbit/s).
+</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>
</chapter>
+<chapter xml:id="ch-encryption" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<title>Encryption</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.
+</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 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 key
+delivery message (KDM) can play the DCP.
+</para>
+
+<section>
+<title>How it works (in a nutshell)</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 distribute a DCP to
+Alice's cinema, without a troublemaker 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 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.
+</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 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.
+</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 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>
+
+<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.
+</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 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, so that 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 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"/>.
+</para>
+
+<figure id="fig-kdm">
+ <title>KDM dialog</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata 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 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.
+</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.
+</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>
+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.
+</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.
+</para>
+
+</section>
+
+</chapter>
+
<chapter xml:id="ch-preferences" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<title>Preferences</title>
<para>
The preferences dialogue is opened by choosing
<guilabel>Preferences...</guilabel> from the <guilabel>Edit</guilabel>
-menu. The dialogue is split into four tabs.
+menu. The dialogue is split into five tabs.
</para>
<section>
<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 would typically be set to the number of
-processors (or processor cores) in your machine.
+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>KDM emails</title>
+
+<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.
</para>
</section>
</section>
<section>
-<title>Encoding servers</title>
+<title>Colour conversions</title>
<para>
-The encoding servers tab is shown in <xref linkend="fig-prefs-servers"/>.
+The colour conversions tab is shown in <xref linkend="fig-prefs-colour-conversions"/>.
</para>
-<figure id="fig-prefs-servers">
- <title>Encoding servers preferences</title>
+<figure id="fig-prefs-colour-conversions">
+ <title>Colour conversions preferences</title>
<mediaobject>
<imageobject>
- <imagedata fileref="screenshots/prefs-servers&scs;"/>
+ <imagedata fileref="screenshots/prefs-colour-conversions&scs;"/>
</imageobject>
</mediaobject>
</figure>
<para>
-If you have spare machines sitting around on your network not doing
-much, they can be pressed into service to speed up DCP encodes. This
-is done by running a small server program on the machine, which will
-encode video sent to it by the ‘master’ DCP-o-matic. This
-option is described in more detail in <xref linkend="sec-servers"/>.
-Use these preferences to specify the encoding servers that should be
-used.
+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>.
+</para>
+
+<para>
+These preferences control a list of presets which are suitable for
+converting from common input colour spaces to XYZ.
</para>
</section>
</section>
-<section xml:id="prefs-tms">
+<section xml:id="sec-prefs-tms">
<title>TMS</title>
<para>
</para>
</section>
+<section>
+<title>KDM email</title>
+<para>
+The KDM email 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. The
+‘magic’ string <code>$CPL_NAME</code> will be replaced by
+DCP's title.
+</para>
+
+</section>
</section>
+
</chapter>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en" xml:id="ch-frame-rates">
<title>Frame rates</title>
<para>
</chapter>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en" xml:id="ch-servers">
<title>Encoding servers</title>
<para>
offload some of the time-consuming JPEG2000 encoding to any number of
other machines on a network. To do this, one ‘master’
machine runs DCP-o-matic, and the ‘server’ machines run
-a small program called ‘dcpomatic_server’.
+a small program called <code>dcpomatic_server</code>.
+</para>
+
+<para>
+The master and server machines do not need to be the same type, so you
+can mix Windows PCs, Macs and Linux machines as you wish.
</para>
<section>
server or open a window to show its status.
</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>
+
+<para>Either burn the image to CD, or write it to a USB stick (using
+something like <ulink
+url="http://unetbootin.sourceforge.net/">unetbootin</ulink>). Boot a
+PC from the CD or USB stick and it becomes a DCP-o-matic server
+without touching your standard operating system install.
+</para>
+
</section>
<section>
<title>Setting up DCP-o-matic</title>
<para>
-Once your servers are running, you need to tell your master
-DCP-o-matic instance about them. Start DCP-o-matic and open the
-<guilabel>Preferences</guilabel> dialog from the
-<guilabel>Edit</guilabel> menu. At the bottom of this dialog is a
-section where you can add, edit and remove encoding servers. For each
-encoding server you need only specify its IP address and the number of
-threads that it is running, so that DCP-o-matic knows how many
-parallel encode jobs to send to the server.
-</para>
-
-<para>
-Once this is done, any encodes that you start will split the workload
-up between the master machine and the servers.
+DCP-o-matic periodically looks on the local network for servers. Any
+that it finds are given work to do during encodes. Selecting
+<guilabel>Encoding Servers</guilabel> from the
+<guilabel>Tools</guilabel> menu brings up a window which shows that
+servers that DCP-o-matic has found.
</para>
</section>
provide a significant speed-up compared to a 100Mb/s network.
</para>
-<para>
-Making changes to the server configuration in the master DCP-o-matic
-will have no effect while an encode is running; the changes will only
-be noticed when a new encode is started.
-</para>
-
</section>
</chapter>
</chapter>
+<chapter>
+<title>Loose ends</title>
+
+<para>
+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>
+
+<para>
+If you cancel a DCP encoding run half-way through, or your computer
+crashes... fear not. DCP-o-matic takes care to ensure that, in most
+cases, it can resume encoding from where it left off. When you
+re-start a DCP creation, using the same settings are a previous run,
+DCP-o-matic will first check that the existing picture frames are
+correct, and then resume from where it left off. The checking of
+existing frames does take some time, but it is much faster than
+running a full re-encode.
+</para>
+
+<para>
+This resumption is achieved by writing a digest (hash) to disk for
+every image frame that is written. On resumption, the existing MXF
+file for image data is read and its contents checked against the
+hashes.
+</para>
+
+</section>
+
+</chapter>
</book>
projects / dcpomatic.git / blobdiff