<!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
+ Makefile.
+-->
<bookinfo>
<title>DCP-o-matic</title>
Hello, and welcome to DCP-o-matic!
</para>
+<!-- ============================================================== -->
<section>
<title>What is DCP-o-matic?</title>
</section>
+
+<!-- ============================================================== -->
<section>
<title>Licence</title>
</section>
+
+<!-- ============================================================== -->
<section>
<title>Acknowledgements</title>
<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, 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.
</section>
+
+<!-- ============================================================== -->
<section>
<title>Mac OS X</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
+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
<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’) 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) and unstable (sid) 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 and 7 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>
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:dcpomatic@carlh.net">mailing
-list</ulink> and I will see about building some packages.
+know by <ulink url="mailto:carl@dcpomatic.com">email</ulink> and I will see about building some packages.
</para>
<para>
<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>
</section>
</chapter>
+
+<!-- ============================================================== -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<title>Creating a video DCP</title>
</section>
+
+<!-- ============================================================== -->
<section>
<title>Adding content</title>
linkend="fig-video-select-content-file"/>.
</para>
-<figure id="fig-add-content">
- <title>Adding content</title>
+<figure id="fig-add-file">
+ <title>Adding content files</title>
<mediaobject>
<imageobject>
- <imagedata fileref="screenshots/add-content&scs;"/>
+ <imagedata fileref="screenshots/add-file&scs;"/>
</imageobject>
</mediaobject>
</figure>
+
+<!-- ============================================================== -->
<section>
<title>Making the DCP</title>
<title>Making the DCP</title>
<mediaobject>
<imageobject>
- <imagedata fileref="screenshots/making-dcp&scs;"/>
+ <imagedata scale="30" fileref="screenshots/making-dcp&scs;"/>
</imageobject>
</mediaobject>
</figure>
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
-linkend="ch-files"/> for details about the files that DVD-o-matic creates.
+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 <xref linkend="sec-tms-upload"/>.
+DCP-o-matic. See the <xref linkend="sec-prefs-tms" endterm="sec-prefs-tms-short"/>.
</para>
</section>
</chapter>
+
+<!-- ============================================================== -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<title>Creating a still-image DCP</title>
</chapter>
+
+<!-- ============================================================== -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
-<title>Handling content</title>
+<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 describes those features in
+content that goes into your DCP, and this chapter describes those features in
detail.
</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.
-</para>
+<!-- ============================================================== -->
<section>
-<title>The preferences dialogue</title>
+<title>Content Properties</title>
<para>
-The preferences dialogue is opened by choosing
-<guilabel>Preferences...</guilabel> from the <guilabel>Edit</guilabel>
-menu. The dialogue is shown in <xref linkend="fig-prefs"/>.
+Below the content list are the controls to set content properties. To
+adjust the properties for a piece of content, click its name in the
+content list. The content property controls will then become active
+for that piece of content.
</para>
-<figure id="fig-prefs">
- <title>Preferences</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="screenshots/prefs&scs;"/>
- </imageobject>
- </mediaobject>
-</figure>
-
-<section>
-<title>TMS setup</title>
-
<para>
-The first part of the dialogue gives some options for specifying
-details about your TMS. If you do this, and your TMS accepts SSH
-connections, you can upload DCPs directly from DCP-o-matic to the TMS.
-This is discussed in <xref linkend="sec-tms-upload"/>.
+The content properties are split up into four sections:
+<guilabel>Video</guilabel>, <guilabel>Audio</guilabel>,
+<guilabel>Subtitles</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>
-<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.
-</para>
</section>
+
+<!-- ============================================================== -->
<section>
-<title>Threads</title>
+<title>Video</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 would typically be set to the number of
-processors (or processor cores) in your machine.
+The <guilabel>Video</guilabel> tab controls properties of the image, as shown in <xref linkend="fig-video-tab"/>.
</para>
-</section>
+<figure id="fig-video-tab">
+ <title>Video settings tab</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/video-tab&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<!-- ============================================================== -->
<section>
-<title>Default directory for new films</title>
+<title>Image type</title>
<para>
-This is the directory (folder) which DCP-o-matic will suggest initially as a place to put new films.
+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 <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>
-</section>
-
-<section>
-<title>A/B options</title>
+<figure id="fig-3d-left-right">
+ <title>3D left/right image type</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="100" fileref="diagrams/3d-left-right&dia;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
<para>
-These options are for DCP-o-matic's special mode of making A/B
-comparison DCPs for checking the performance of video filters. Their
-use is described in <xref linkend="sec-ab"/>.
+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>
-</section>
-
-<section>
-<title>Encoding servers</title>
+<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>
<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.
+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>
-</chapter>
-
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
-<title>Advanced topics</title>
-
-<para>This chapter describes some parts of DCP-o-matic that are
-probably not essential, but which you might find useful in some
-circumstances.
-</para>
+<!-- ============================================================== -->
<section>
<title>Filtering</title>
<para>
-DCP-o-matic offers a variety of filters that can be applied to your
-video content. You can set up the filters by clicking the
+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"/>.
will update itself whenever filters are changed, though of course this
image is much smaller and of lower resolution than a projected image!
</para>
-
-</section>
-
-<section>
-<title>Scaling</title>
-
-<para>
-If your source material is not of the DCI-specified size, or if it
-uses non-square pixels, DCP-o-matic will need to scale it. The
-algorithm used to scale is set up by the <guilabel>Scaler</guilabel>
-entry in the film setup area. We think ‘Bicubic’ is the
-best all-round option, but tests are ongoing.
-</para>
-
</section>
-<section xml:id="sec-tms-upload">
-<title>TMS upload</title>
-
-<para>
-If you have configured details of a TMS in the preferences dialogue
-(<xref linkend="ch-preferences"/>) you can upload a completed DCP
-straight to your TMS buy choosing <guilabel>Send DCP to TMS</guilabel>
-from the <guilabel>Jobs</guilabel> menu.
-</para>
-
-</section>
-<section xml:id="sec-ab">
-<title>A/B comparison</title>
+<!-- ============================================================== -->
+<section>
+<title>Colour conversion</title>
<para>
-When evaluating the effects of different filters or scalers on the
-image quality, A/B mode might be useful. In this mode, DCP-o-matic
-will generate a DCP where the left half of the image uses some
-‘reference’ filtering and scaling, and the right half of
-the image uses a different set of filters and a different scaler.
-This DCP can then be played back on a projector and the image quality
-evaluated.
+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>
-To enable A/B mode, click the A/B checkbox in the setup area of the
-DCP-o-matic window. When you generate your DCP, the left half of the
-screen will use the filters and scaler specified in the <xref
-linkend="ch-preferences">preferences</xref> dialogue, and the right
-half will use the filters and scaler specified in the film setup.
+Clicking <guilabel>Edit...</guilabel> will open the colour conversion
+dialogue box, as shown in <xref linkend="fig-colour-conversion"/>.
</para>
-</section>
-
-<section xml:id="sec-servers">
-<title>Encoding servers</title>
+<figure id="fig-colour-conversion">
+ <title>Dialogue box for setting colour conversion</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/colour-conversion&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
<para>
-One way to increase the speed of DCP encoding is to use more
-than one machine at the same time. An instance of DCP-o-matic can
-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 ‘servomatic’.
+In most cases, it is only necessary to select one of DCP-o-matic's
+presets. DCP-o-matic knows how to convert from two common
+colourspaces: sRGB and Rec. 709, so if your content was graded using
+one of those you can select the appropriate preset.
</para>
-<section>
-<title>Running the servers</title>
-
<para>
-There are two options for the encoding server;
-<code>servomatic_cli</code>, which runs on the command line, and
-<code>servomatic_gui</code>, which has a simple GUI. The command line
-version is well-suited to headless servers, especially on Linux, and
-the GUI version works best on Windows where it will put an icon in the
-system tray.
+For other colour spaces you can edit the values in the lower half of
+the dialogue box as you wish. Alternatively, create a new colour
+conversion preset using the preferences dialog, as described in <xref
+linkend="sec-prefs-colour"/>.
</para>
<para>
-To run the command line version, simply enter:
+Colour conversion is discussed in more detail in a separate document
+<ulink url="http://dcpomatic.com/manual/colour.pdf">colour.pdf</ulink>.
</para>
-<programlisting>
-servomatic_cli
-</programlisting>
-
-<para>
-at a command prompt. If you are running the program on a machine with
-a multi-core processor, you can run multiple parallel encoding threads
-by doing something like:
-</para>
+</section>
-<programlisting>
-servomatic_cli -t 4
-</programlisting>
+<!-- ============================================================== -->
+<section>
+<title>Other settings</title>
<para>
-to run 4 threads in parallel.
+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.
</para>
<para>
-To run the GUI version on windows, run the ‘DCP-o-matic encode
-server’ from the start menu. An icon will appear in the system
-tray; right-click it to open a menu from whence you can quit the
-server or open a window to show its status.
+The <guilabel>Scale to</guilabel> option governs the shape that
+DCP-o-matic will scale the content's image into. Select the aspect
+ratio that your content should be presented in.
</para>
</section>
+
+<!-- ============================================================== -->
<section>
-<title>Setting up DCP-o-matic</title>
+<title>Video description</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.
+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.
</para>
<para>
-Once this is done, any encodes that you start will split the workload
-up between the master machine and the servers.
+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 -->
</para>
</section>
-<section>
-<title>Some notes about encode servers</title>
-<para>
-DCP-o-matic does not mind if servers come and go; if a server
-disappears, DCP-o-matic will stop sending work to it, and will check
-it every minute or so in case it has come back online.
-</para>
+</section>
-<para>
-You will probably find that using a 1Gb/s or faster network will
-provide a significant speed-up compared to a 100Mb/s network.
-</para>
+
+<!-- ============================================================== -->
+<section>
+<title>Audio</title>
<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.
+The <guilabel>Audio</guilabel> tab controls properties of the image, as shown in <xref linkend="fig-audio-tab"/>.
</para>
-</section>
-</section>
+<figure id="fig-audio-tab">
+ <title>Audio settings tab</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/audio-tab&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
-</chapter>
-<chapter xml:id="ch-files" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
-<title>Generated files</title>
+<!-- ============================================================== -->
+<section>
+<title>Show audio</title>
<para>
-DCP-o-matic generates a number of files as it makes a DCP. <xref
-linkend="fig-file-structure"/> shows the files that might be generated
-after you have created a DCP for a film called ‘DCP Test’.
+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-file-structure">
- <title>Creating a new film</title>
+<figure id="fig-audio-plot">
+ <title>Audio plot</title>
<mediaobject>
<imageobject>
- <imagedata fileref="diagrams/file-structure&dia;"/>
+ <imagedata fileref="screenshots/audio-plot&scs;"/>
</imageobject>
</mediaobject>
</figure>
<para>
-The <code>DCP Test</code> folder is the one that you specify when you
-select the <guilabel>New Film</guilabel> option from DCP-o-matic's
-menu. Everything is stored inside this folder.
+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>
-DCP-o-matic generates some working files as it goes along. These are as follows:
-<itemizedlist>
-
-<listitem><code>log</code> is a list of notes that DCP-o-matic makes as it goes
-along. This can be useful for debugging purposes if something goes
-wrong.</listitem>
-
-<listitem><code>metadata</code> stores the settings that you have made
-for this film: things like cropping, output format and so on.</listitem>
-
-<listitem><code>video</code> is where DCP-o-matic writes the DCP's
-video data as it encodes it.</listitem>
-
-<listitem><code>analysis</code> is used to keep the results of audio analysis runs.</listitem>
-
-<listitem><code>info</code> contains details of each video frame that
-DCP-o-matic has written so far. This is used when an encoding
-operation is interrupted and DCP-o-matic must resume it.</listitem>
-</itemizedlist>
+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>
-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
-(<code>DCP-TEST_EN-XX_...</code>) is what you should ingest, or pass
-to the cinema which is showing your DCP.
+The channel check-boxes will show or hide the plot(s) for
+the corresponding channels in the DCP.
</para>
-</chapter>
-
+<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>
-</book>
+<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>
-<!--
-OUTTAKES:
+<!-- ============================================================== -->
+<section>
+<title>The audio map</title>
<para>
-The folder that you choose should have plenty of free disc space
-available. As a very rough guide, you will need about 25Mb per second
-of your DCP. This works out at 1.5Gb per minute, or 90Gb per hour.
+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>
<para>
-If you always create your DCPs in a particular folder, you can use
-DCP-o-matic's <guilabel>Preferences</guilabel> to make life a little
-easier by setting the default folder that DCP-o-matic will offer in this dialogue.
-See <xref linkend="ch-preferences"/>.
+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 green box means that the corresponding
+content channel will be copied into the corresponding DCP channel.
</para>
-<section>
-<title>Setting up the content</title>
+<para>
+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>
<para>
-Now there are a few things to set up to describe how the content you just added should be used.
-created. The settings are divided into four tabs: video, audio, subtitles and timing.
+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>
-<section>
-<title>Video content tab</title>
+<para>
+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>
-This tab contains settings related to the video (i.e. the picture) of your content, as shown in <xref linkend="fig-video-tab"/>.
+Consider, for example, the case in <xref linkend="fig-audio-map-eg1"/>.
</para>
-<figure id="fig-video-tab">
- <title>Video settings tab</title>
+<figure id="fig-audio-map-eg1">
+ <title>Audio map example 1</title>
<mediaobject>
<imageobject>
- XXX: content video tab
+ <imagedata fileref="screenshots/audio-map-eg1&scs;"/>
</imageobject>
</mediaobject>
</figure>
-<para>The default values in this tab are fine for our example, but the
-options are described here anyway.</para>
-
<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 options allow the video to be
-interpreted as 3D; this is described later in the manual.
- XXX: link
+Here, we have two channels in the source which are mapped to left and
+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>
+ <imagedata fileref="screenshots/audio-map-eg2&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
<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.
+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>
-<para>
-The <guilabel>Scale to</guilabel> option governs the shape that
-DCP-o-matic will scale the content's image into. Select the aspect
-ratio that your content should be presented in.
-</para>
-
-<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. We will discuss filtering later in the manual.
- XXX: link
-</para>
-</section>
-
-<section>
-<title>Audio tab</title>
-
-<para>
-This tab contains settings related to the sound in your content, as shown in <xref linkend="fig-audio-tab"/>.
-</para>
-
-<figure id="fig-audio-tab">
- <title>Audio settings tab</title>
+<figure id="fig-audio-map-eg3">
+ <title>Audio map example 3</title>
<mediaobject>
<imageobject>
- XXX: content audio tab
+ <imagedata fileref="screenshots/audio-map-eg3&scs;"/>
</imageobject>
</mediaobject>
</figure>
<para>
-Once again, these settings can be left at their defaults for our Sintel example.
+As a final example, the map in <xref linkend="fig-audio-map-eg3"/>
+shows the mapping of a 5.1 source into a 5.1 DCP.
</para>
-<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. The audio graphic is
-discussed in more detail later in the manual.
- XXX: link
-</para>
+</section>
+
+
+<!-- ============================================================== -->
+<section>
+<title>Other controls</title>
<para>
‘Audio Gain’ is used to alter the volume of the
</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>
might be different soundtrack languages, for example.
</para>
-<para>
-The final section in the audio tab is the ‘audio map’.
-This governs how sound from the content will be arranged in the DCP.
-Our Sintel clip is in 5.1, so DCP-o-matic will default to assigning
-each channel from the content to the appropriate DCP channel. This
-audio mapping is described in more detail later in the manual.
- XXX: link
-</para>
-
</section>
+</section>
+
+<!-- ============================================================== -->
<section>
-<title>Subtitles tab</title>
+<title>Subtitles</title>
<para>
-This tab contains settings related to subtitles in your content, as shown in <xref linkend="fig-subtitles-tab"/>.
+The subtitles tab contains settings related to subtitles in your
+content, as shown in <xref linkend="fig-subtitles-tab"/>.
</para>
<figure id="fig-subtitles-tab">
<title>Subtitle settings tab</title>
<mediaobject>
<imageobject>
- XXX: subtitles tab
+ <imagedata fileref="screenshots/subtitles-tab&scs;"/>
</imageobject>
</mediaobject>
</figure>
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
-subtitles. The <guilabel>offset</guilabel> control moves the
-subtitles up and down the image, and the <guilabel>scale</guilabel>
-control changes their size.
+Select the <guilabel>With Subtitles</guilabel> check-box to enable
+subtitles. The <guilabel>X Offset</guilabel> and <guilabel>Y
+Offset</guilabel> controls move the subtitles around within the image,
+and the <guilabel>scale</guilabel> control changes their size. The
+<guilabel>Stream</guilabel> control changes the subtitle stream that
+is used when the content has more than one.
</para>
<para>
</para>
</section>
+
+
+<!-- ============================================================== -->
+<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>
+
+<!-- ============================================================== -->
<section>
-<title>Setting up the DCP</title>
+<title>Video processing pipeline</title>
+
+<para>
+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>
+
+<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 scale="100" fileref="diagrams/pipeline1&dia;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+DCP-o-matic runs through the following steps when preparing an image for a DCP:
+</para>
+
+<itemizedlist>
+<listitem>Crop</listitem>
+<listitem>Scale</listitem>
+<listitem>Place in container</listitem>
+</itemizedlist>
+
+<para>
+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>
+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>
+
+<figure id="fig-pipeline2">
+ <title>Example image after cropping</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="100" fileref="diagrams/pipeline2&dia;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+The next step is to scale the image. Since this content should be
+presented in a 2.39:1 aspect ratio inside a 1.85:1 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>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>
+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>
+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>
+
+<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 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>
+
+<figure id="fig-pipeline4">
+ <title>Example image in the DCP</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="100" fileref="diagrams/pipeline4&dia;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+</section>
+
+</chapter>
+
+<chapter xml:id="ch-dcp" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<title>DCP settings</title>
<para>
-Now that we have set up the content that will go into our DCP, we can
-set things up for the DCP itself. This is done from the
-<guilabel>DCP</guilabel> tab which can be found at the top of the
-DCP-o-matic window (next to the <guilabel>Content</guilabel> tab).
-The DCP tab is shown in foo.
+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>
- XXX: DCP tab
+<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 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. Set the name to something useful, like
-‘Sintel’.
+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>
<para>
The <guilabel>3D</guilabel> button will set your DCP to 3D mode if it
-is checked. This is discussed later.
- XXX: link
+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>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>
-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. We will
-discuss the options in more detail later; Bicubic is a fine choice in
+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>
+Finally, the <guilabel>Scaler</guilabel> is the method that will be used to scale up
+your content for the DCP, if required. Bicubic is a fine choice in
most situations.
- XXX: link
+</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 correct 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, 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 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>
+
+
+
+<!-- ============================================================== -->
+<!-- PREFERENCES -->
+<!-- ============================================================== -->
+
+<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.
+</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 eight tabs.
+</para>
--->
\ No newline at end of file
+<!-- ============================================================== -->
+<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="http://dcpomatic.com/i18n.php">the DCP-o-matic website</ulink> to
+read about how to contribute a translation.
+</para>
+</section>
+
+
+<!-- ============================================================== -->
+<section>
+<title>Threads</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>Updates</title>
+
+<para>
+The <guilabel>Check for updates on startup</guilabel> option, if
+enabled, will tell DCP-o-matic to check on <ulink
+url="http://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.
+available
+</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>
+
+<!-- ============================================================== -->
+<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>
+
+<!-- XXX: servers -->
+
+<!-- ============================================================== -->
+<section xml:id="sec-prefs-colour">
+<title>Colour conversions</title>
+
+<para>
+The colour conversions tab is shown in <xref linkend="fig-prefs-colour-conversions"/>.
+</para>
+
+<figure id="fig-prefs-colour-conversions">
+ <title>Colour conversions preferences</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/prefs-colour-conversions&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>.
+</para>
+
+<para>
+These preferences control a list of presets which are suitable for
+converting from common input colour spaces to XYZ.
+</para>
+
+</section>
+
+
+<!-- ============================================================== -->
+<section>
+<title>Keys</title>
+
+<para>
+The Keys tab (shown in <xref linkend="fig-prefs-keys"/>) holds options
+related to the keys and certificates used in some parts of DCP
+creation.
+</para>
+
+<figure id="fig-prefs-keys">
+ <title>Keys preferences</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/prefs-keys&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+At the top of the tab 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, so if you are happy to use a randomly-generated 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>
+If you want DCP-o-matic to re-create the certificate chain (using new,
+random certificates) click <guilabel>Re-make
+certificates...</guilabel> and specify your organisation and common
+names in the dialogue box that opens.
+</para>
+
+<para>
+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>Load...</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>
+
+<para>
+The bottom of the tab specifies the certificate and private key that
+is used to decrypt DCPs if they are imported as sources to
+DCP-o-matic. 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. As with the certificate chain,
+DCP-o-matic will create a certificate and private key for you. You
+can also choose to load your own certificate and key.
+</para>
+
+</section>
+
+<!-- ============================================================== -->
+<section xml:id="sec-prefs-tms">
+<title>TMS</title>
+<titleabbrev xml:id="sec-prefs-tms-short">TMS 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.
+</para>
+
+<figure id="fig-prefs-tms">
+ <title>TMS preferences</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/prefs-tms&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.
+</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. A few
+‘magic’ strings will be replaced by information from the
+KDM that is being sent:
+</para>
+
+<table>
+<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 xml:id="sec-prefs-advanced">
+<title>Advanced</title>
+<titleabbrev xml:id="sec-prefs-advanced-short">Advanced preferences</titleabbrev>
+
+<para>
+The advanced preferences are shown in <xref linkend="fig-prefs-advanced"/>.
+</para>
+
+<figure id="fig-prefs-advanced">
+ <title>Advanced preferences</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/prefs-advanced&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+<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>
+
+<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 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>
+
+<para>
+The <guilabel>Timing</guilabel> checkbox will enable extra log entries
+to allow developers to investigate and optimize 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>
+</section>
+</chapter>
+
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en" xml:id="ch-frame-rates">
+<title>Frame rates</title>
+
+<para>
+In an ideal world, a DCP would be created using content at the same
+video frame and audio sampling rates as the DCP. This is not,
+however, always possible.
+</para>
+
+
+<!-- ============================================================== -->
+<section>
+<title>DCP frame rate limitations</title>
+
+<para>
+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 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, or
+even refuse to ingest.
+</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.
+</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.
+</para>
+</section>
+
+
+<!-- ============================================================== -->
+<section>
+<title>Adapting content to fit the DCP rate</title>
+
+<para>
+DCP-o-matic has a few tricks to allow you to use content that is not
+in one of the ‘approved’ rates.
+</para>
+
+<para>
+Audio is easy: DCP-o-matic can resample to 48kHz from any source rate
+with minimal loss in quality.
+</para>
+
+<para>
+Video rate conversion is harder. DCP-o-matic's strategy to deal
+with a non-supported content rate is to run it at the wrong speed, and
+to adjust the audio to keep it in sync.
+</para>
+
+<para>Consider the example of a 25fps source for which you want
+to create a 24fps DCP. DCP-o-matic will put the frames from the
+source directly into the DCP without modification, but will tell the
+projector to play them back at 24fps. This means that the DCP's video
+will run slightly slower than the original.
+</para>
+
+<para>
+If DCP-o-matic did nothing else, the result of this would be that the
+audio would be running at the original speed with the video running
+slowly. Hence the audio would drift slowly out of sync. To avoid
+this, DCP-o-matic also resamples the audio such that the projector
+will play it too slow by the same amount. Hence it will sound
+slightly different but will remain in sync with the video.
+</para>
+
+<para>
+For very low or high frame rates, DCP-o-matic can also skip or duplicate frames.
+</para>
+
+</section>
+</section>
+
+
+<!-- ============================================================== -->
+<section>
+<title>Setting up</title>
+
+<para>
+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 DCP-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.
+</para>
+
+<para>
+After this, the <guilabel>Video</guilabel> tab for each piece of
+content will give a summary of what DCP-o-matic is doing with that
+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>
+
+<para>
+One way to increase the speed of DCP encoding is to use more
+than one machine at the same time. An instance of DCP-o-matic can
+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 <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>
+<title>Running the servers</title>
+
+<para>
+There are two options for the encoding server;
+<code>dcpomatic_server_cli</code>, which runs on the command line, and
+<code>dcpomatic_server</code>, which has a simple GUI. The command line
+version is well-suited to headless servers, especially on Linux, and
+the GUI version works best on Windows where it will put an icon in the
+system tray.
+</para>
+
+<para>
+To run the command line version, simply enter:
+</para>
+
+<programlisting>
+dcpomatic_server_cli
+</programlisting>
+
+<para>
+at a command prompt. If you are running the program on a machine with
+a multi-core processor, you can run multiple parallel encoding threads
+by doing something like:
+</para>
+
+<programlisting>
+dcpomatic_server_cli -t 4
+</programlisting>
+
+<para>
+to run 4 threads in parallel.
+</para>
+
+<para>
+To run the GUI version on windows, run the ‘DCP-o-matic encode
+server’ from the start menu. An icon will appear in the system
+tray; right-click it to open a menu from whence you can quit the
+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>
+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>
+
+<!-- ============================================================== -->
+<section>
+<title>Some notes about encode servers</title>
+
+<para>
+DCP-o-matic does not mind if servers come and go; if a server
+disappears, DCP-o-matic will stop sending work to it, and will check
+it every minute or so in case it has come back online.
+</para>
+
+<para>
+You will probably find that using a 1Gb/s or faster network will
+provide a significant speed-up compared to a 100Mb/s network.
+</para>
+
+</section>
+
+</chapter>
+
+<chapter xml:id="ch-files" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<title>Generated files</title>
+
+<para>
+DCP-o-matic generates a number of files as it makes a DCP. <xref
+linkend="fig-file-structure"/> shows the files that might be generated
+after you have created a DCP for a film called ‘DCP Test’.
+</para>
+
+<figure id="fig-file-structure">
+ <title>Creating a new film</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="diagrams/file-structure&dia;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+The <code>DCP Test</code> folder is the one that you specify when you
+select the <guilabel>New Film</guilabel> option from DCP-o-matic's
+menu. Everything is stored inside this folder.
+</para>
+
+<para>
+DCP-o-matic generates some working files as it goes along. These are as follows:
+<itemizedlist>
+
+<listitem><code>log</code> is a list of notes that DCP-o-matic makes as it goes
+along. This can be useful for debugging purposes if something goes
+wrong.</listitem>
+
+<listitem><code>metadata</code> stores the settings that you have made
+for this film: things like cropping, output format and so on.</listitem>
+
+<listitem><code>video</code> is where DCP-o-matic writes the DCP's
+video data as it encodes it.</listitem>
+
+<listitem><code>analysis</code> is used to keep the results of audio analysis runs.</listitem>
+
+<listitem><code>info</code> contains details of each video frame that
+DCP-o-matic has written so far. This is used when an encoding
+operation is interrupted and DCP-o-matic must resume it.</listitem>
+</itemizedlist>
+</para>
+
+<para>
+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
+(<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>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