-->
<bookinfo>
-<title>DCP-o-matic</title>
+<title>DCP-o-matic users' manual</title>
<author><firstname>Carl</firstname><surname>Hetherington</surname></author>
</bookinfo>
cinema projectors.
</para>
-<para>
-You might find it useful to make DVDs easier to present, to encode
-independently-shot feature films, or to generate local advertising for
-your cinema.
-</para>
-
</section>
<title>Licence</title>
<para>
-DCP-o-matic is licensed under the <ulink url="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GNU GPL</ulink>.
+DCP-o-matic is free and open-source and is licensed under the <ulink
+url="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GNU
+GPL</ulink>.
</para>
</section>
</section>
</chapter>
+
+<!-- ============================================================== -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<title>Installation</title>
<para>
You can install DCP-o-matic on Ubuntu 12.04 (‘Precise
-Pangolin’) or 14.04 (‘Trusty Tahr’) using <code>.deb</code> packages: download the
-appropriate package from <ulink
+Pangolin’), 14.04 (‘Trusty Tahr’) or 15.04
+(‘Vivid Vervet’) 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>
<title>Debian Linux</title>
<para>
-Packages are available for Debian 7 (squeeze) and unstable (sid) from <ulink
+Packages are available for Debian 7 (squeeze)
, 8 (jessie) and unstable (sid) from <ulink
url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>.
</para>
</section>
<title>Other Linux distributions</title>
<para>
-Installation on non-Ubuntu Linux is currently a little involved, as
-there are no packages available (yet); you will have to compile it
-from source. If you are using a non-Ubuntu distribution, do let me
-know by <ulink url="mailto:carl@dcpomatic.com">email</ulink> and I will see about building some packages.
+Installation on other Linux systems (for which no packages are
+available) is quite hard; you will have to compile it from source. If
+you are using distribution for which no packages are available, do let
+me know by <ulink url="mailto:carl@dcpomatic.com">email</ulink> and I
+will look into providing packages on the website.
</para>
<para>
<listitem><ulink url="http://www.libssh.org/">libssh</ulink></listitem>
<listitem><ulink url="http://www.gtk.org/">GTK (on Linux)</ulink></listitem>
<listitem><ulink url="http://www.wxwidgets.org/">wxWidgets</ulink></listitem>
-<listitem><ulink url="http://freecode.com/projects/libquickmail">libquickmail</ulink></listitem>
<listitem><ulink url="http://libxmlplusplus.sourceforge.net/">libxml++</ulink></listitem>
<listitem><ulink url="http://www.aleksey.com/xmlsec/">xmlsec</ulink></listitem>
<listitem><ulink url="http://curl.haxx.se/">curl</ulink></listitem>
</para>
<programlisting>
-dcpomatic
+dcpomatic2
</programlisting>
<para>
</para>
<para>
-Alternatively, if you have a projector or TMS that is accessible via
-SCP across your network, you can upload the content directly from
-DCP-o-matic. See the <xref linkend="sec-prefs-tms" endterm="sec-prefs-tms-short"/>.
+Alternatively, if you have a projector or Theatre Management System
+(TMS) that is accessible via SCP across your network, you can upload
+the content directly from DCP-o-matic. See the <xref
+linkend="sec-prefs-tms" endterm="sec-prefs-tms-short"/> in <xref linkend="sec-prefs-tms"/>.
</para>
</section>
<itemizedlist>
<listitem>Movie — a file containing some video, probably some
-audio and possibly some subtitles; for example, a MOV, MP4 or VOB.
+audio and possibly some embedded subtitles; for example, a MOV, MP4 or VOB.
</listitem>
<listitem>Sound — a file containing one or more channels of
<listitem>Moving image — a directory containing many still
images which should be treated as the frames of a video.
</listitem>
+
+<listitem>Subtitle — a file containing subtitle which will be
+superimposed on the image of the DCP. These can be
+<guilabel>.srt</guilabel> or <guilabel>.xml</guilabel>
+files.</listitem>
</itemizedlist>
<para>
-To add one or more movie, sound or still-image files, select
+To add one or more movie, sound, still-image or subtitle files, select
<guilabel>Add file(s)...</guilabel> and choose them from the selector.
-To add a directory of images, choose <guilabel>Add
-directory...</guilabel> and do similar.
+</para>
+
+<para>
+To add a directory (folder) of images, choose <guilabel>Add
+folder...</guilabel> and choose the directory from the selector.
+DCP-o-matic will open a small dialogue box where you can enter the
+frame rate that your image sequence should be run at.
</para>
<para>
for that piece of content.
</para>
+<para>
+If you want to change the properties for multiple pieces of content at
+the same time, select the content in the list by clicking the first
+piece then clicking the other pieces with <keycap>shift</keycap> key
+held down. Note that not all settings can be changed in this way.
+</para>
+
<para>
The content properties are split up into four sections:
<guilabel>Video</guilabel>, <guilabel>Audio</guilabel>,
</para>
<para>
-Clicking <guilabel>Edit...</guilabel> will open the colour conversion
-dialogue box, as shown in <xref linkend="fig-colour-conversion"/>.
+The easiest way to select the required conversion is to choose one of
+DCP-o-matic's presets. DCP-o-matic knows how to convert from four
+common colourspaces: sRGB, Rec. 601, Rec. 709 and P3. If you do not
+know which preset you should use, refer to the suggestions in <xref
+linkend="tab-colour-conversion"/>.
+</para>
+
+<table id="tab-colour-conversion">
+<title>Suggested colour conversion settings</title>
+<tgroup cols='2' align='left' colsep='1' rowsep='1'>
+<colspec colwidth='1*'/>
+<colspec colwidth='5*'/>
+<tbody>
+<row>
+<entry>sRGB</entry><entry>Still images in RGB, e.g. photographs</entry>.
+</row>
+<row>
+<entry>Rec. 601</entry><entry>Standard-definition content (lower than about 1000 pixels across) including DVD rips.</entry>
+</row>
+<row>
+<entry>Rec. 709</entry><entry>High-definition content including Blu-Ray rips.</entry>
+</row>
+<row>
+<entry>P3</entry><entry>Content explicitly graded to P3.</entry>
+</row>
+</tbody>
+</tgroup>
+</table>
+
+<para>
+For other required colour conversions, and if you know what you are
+doing, you can choose <guilabel>Custom</guilabel> which will open the full
+colour conversion editing dialogue box:
</para>
<figure id="fig-colour-conversion">
- <title>Dialogue box for setting colour conversion</title>
+ <title>Dialogue box for custom colour conversion</title>
<mediaobject>
<imageobject>
<imagedata fileref="screenshots/colour-conversion&scs;"/>
</figure>
<para>
-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.
+Alternatively, choose <guilabel>None</guilabel> if your source files
+are already in the XYZ colour space and require no conversion.
</para>
<para>
-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>
-Colour conversion is discussed in more detail in a separate document
-<ulink url="http://dcpomatic.com/manual/colour.pdf">colour.pdf</ulink>.
+DCP-o-matic's colour conversion processes are discussed in much more
+detail in a separate document <ulink
+url="http://dcpomatic.com/manual/colour.pdf">colour.pdf</ulink>.
</para>
</section>
<title>Other settings</title>
<para>
-The ‘crop’ settings can be used to crop your content,
+The <guilabel>crop</guilabel> 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>
+The <guilabel>fade in</guilabel> and <guilabel>fade out</guilabel>
+settings can be used to apply linear fades into and out of a piece of
+content. Specify the time for each, clicking <guilabel>Set</guilabel>
+after making any changes.
+</para>
+
<para>
The <guilabel>Scale to</guilabel> option governs the shape that
DCP-o-matic will scale the content's image into. Select the aspect
At the bottom of the video tab is a short description of what will
happen to your video with the current settings. In the example of
<xref linkend="fig-video-tab"/>, DCP-o-matic is telling you that the
-video file is 1920x1080 pixels (which is a ratio of 1.78:1). Since
-the controls specify ‘Flat’ for the ratio, DCP-o-matic
-scales the content image to 1998x1080, which is the DCI flat
-resolution at 2K.
+video file is 1920x1080 pixels and it has square pixels (a pixel
+aspect ratio of 1.00) hence its display aspect ratio is 1.78:1. Since
+the controls specify ‘16.9’ for the ratio, DCP-o-matic
+does not scale the image but pads it to the DCP's container ratio of
+1.85:1. For a 2K DCP this is 1998x1080 pixels.
</para>
<para>
</figure>
-<!-- ============================================================== -->
-<section>
-<title>Show audio</title>
-
-<para>
-The <guilabel>Show Audio</guilabel> button will instruct DCP-o-matic
-to examine the audio in your content and plot a graph of its level
-over time. This can be useful for getting a rough idea of how loud
-the sound will be in the cinema auditorium. A typical plot is shown
-in <xref linkend="fig-audio-plot"/>
-</para>
-
-<figure id="fig-audio-plot">
- <title>Audio plot</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="screenshots/audio-plot&scs;"/>
- </imageobject>
- </mediaobject>
-</figure>
-
-<para>
-The plot gives the audio level (vertical axis, in dB) with time
-(horizontal axis). 0dB represents full scale, so if there is anything
-near this you are in danger of clipping the projector's audio outputs.
-</para>
-
-<para>
-There are two plot types: the peak level and the RMS, which can be
-shown or hidden using the check-boxes on the right hand side of the
-window.
-</para>
-
-<para>
-The channel check-boxes will show or hide the plot(s) for
-the corresponding channels in the DCP.
-</para>
-
-<para>
-The smoothing slider applies a variable degree of temporal smoothing
-to the plots, which can make them easier to read in some cases.
-</para>
-
-<para>
-Obviously the audio plot is no substitute for listening in an
-auditorium, but it can be useful to get levels in the right rough area.
-</para>
-
-</section>
-
-
<!-- ============================================================== -->
<section>
<title>The audio map</title>
<para>
DCP-o-matic will extract subtitles from the content, if present, and
they can be ‘burnt into’ the DCP (that is, they are
-included in the image and not overlaid by the projector). Note that
-DVD and Blu-Ray subtitles are stored as bitmaps, so it is not possible
-(automatically) to use non-burnt-in subtitles with these sources.
+included in the image and not overlaid by the projector).
+</para>
+
+<para>
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.
+subtitles.
</para>
<para>
-All being well, future versions of DCP-o-matic will include the option to
-use text subtitles (as is the norm with most professionally-mastered
-DCPs).
+The <guilabel>X Offset</guilabel> and <guilabel>Y Offset</guilabel>
+controls move the subtitles around within the image. The offsets are
+expressed as a percentage of the video frame size; 100% X offset is
+the entire width of the frame, and 100% Y offset is the entire height.
+Hence, to move the subtitles down by half the frame height you would
+use a Y offset of 50%.
+</para>
+
+<para>
+The <guilabel>X Scale</guilabel> and <guilabel>Y Scale</guilabel>
+controls scale the subtitles. Scale values of 1 make the subtitles
+the same size (relative to the size of the image) as they are on the
+original. Values lower than 1 make them smaller, and values higher
+make them larger. You can stretch the subtitles in either direction
+by specifying different values for X and Y scale. Subtitles from DVD
+and Blu Ray sources are frequently larger (relative to the video
+frame) than those typically used for DCP, so it is often useful to
+scale such subtitles down using these controls.
+</para>
+
+<para>
+The <guilabel>Stream</guilabel> control changes the subtitle stream
+that is used when the content has more than one.
</para>
</section>
open by clicking on the <guilabel>Details</guilabel> button.
</para>
+<para>
+If you want to take the ISDCF-compliant name that DCP-o-matic
+generates and modify it, click <guilabel>Copy as name</guilabel> and
+the ISDCF name will be copied into the <guilabel>Name</guilabel> box.
+You can then edit it as you wish. The DCP name should not matter (in
+that it should not affect how the DCP ingests or plays) but
+projectionists will appreciate it if you use the standard naming
+scheme as it makes it easier to identify details of the content.
+</para>
+
<para>
If the DCP name is long, it may not all be visible. You can see the
full name by hovering the mouse pointer over the partial name.
more detail in <xref linkend="ch-frame-rates"/>.
</para>
+<para>
+The <guilabel>Use best</guilabel> button sets the DCP video frame rate
+to what DCP-o-matic thinks is the best given the content that you have
+added.
+</para>
+
<para>
The <guilabel>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>Use best</guilabel> button sets the DCP video frame rate
-to what DCP-o-matic thinks is the best given the content that you have
-added.
+If you use encryption DCP-o-matic will generate a random encryption
+key for you. To specify your own key, click the
+<guilabel>Edit..</guilabel> button next to the key.
</para>
<para>
The <guilabel>Audio Channels</guilabel> control sets the number of
audio channels that the DCP will have. If the DCP has any channels
for which there is no content audio they will be replaced by silence.
+You can only set an even number of channels here, since that is
+required by the DCI standard. If you want an odd number of channels,
+set the DCP channel count to one greater than you need and the
+unused channel will be filled with silence.
</para>
<para>
</para>
<para>
-The <guilabel>JPEG2000 bandwidth</guilabel>; setting changes how big the final
-image files used within the DCP will be. Larger numbers will give
-better quality, but correspondingly larger DCPs. The bandwidth can be
-between 50 and 250 megabits per second (Mbit/s).
+The <guilabel>JPEG2000 bandwidth</guilabel>; setting changes how big
+the final image files used within the DCP will be. Larger numbers
+will give better quality, but correspondingly larger DCPs. The
+bandwidth can be between 50 and 250 megabits per second (Mbit/s).
+Most commercial DCPs use bit rates between 75 and 125 MBit/s.
</para>
<para>
most situations.
</para>
+<!-- ============================================================== -->
+<section>
+<title>Show audio</title>
+
+<para>
+The <guilabel>Show Audio</guilabel> button will instruct DCP-o-matic
+to examine the audio in your content and plot a graph of its level
+over time. This can be useful for getting a rough idea of how loud
+the sound will be in the cinema auditorium. A typical plot is shown
+in <xref linkend="fig-audio-plot"/>
+</para>
+
+<figure id="fig-audio-plot">
+ <title>Audio plot</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/audio-plot&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+The plot gives the audio level (vertical axis, in dB) with time
+(horizontal axis). 0dB represents full scale, so if there is anything
+near this you are in danger of clipping the projector's audio outputs.
+</para>
+
+<para>
+There are two plot types: the peak level and the RMS, which can be
+shown or hidden using the check-boxes on the right hand side of the
+window.
+</para>
+
+<para>
+The channel check-boxes will show or hide the plot(s) for
+the corresponding channels in the DCP.
+</para>
+
+<para>
+The smoothing slider applies a variable degree of temporal smoothing
+to the plots, which can make them easier to read in some cases.
+</para>
+
+<para>
+Obviously the audio plot is no substitute for listening in an
+auditorium, but it can be useful to get levels in the right rough area.
+</para>
+
+</section>
+
</chapter>
<chapter xml:id="ch-encryption" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
</para>
<para>
-We suppose that we are trying to distribute a DCP to
+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>
<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.
+Alternatively, certificates for projection systems made by some
+manufacturers can be downloaded from databases provided by the
+manufacturer. Currently this is supported for Doremi and Dolby
+equipment. If you are targeting a screen with equipment by one of
+these manufacturers you can select Doremi or Dolby from the
+<guilabel>Server manufacturer</guilabel> selection and then click
+<guilabel>Download</guilabel>. In the next dialogue box, enter
+details of the screen and click <guilabel>Download</guilabel> and, all
+being well, the certificate will be fetched.
+</para>
+
+<para>
+Using the download system you will need to know the serial number of
+the media server in use in the screen. Most cinema projection or
+technical departments will know these serial numbers.
+</para>
+
+<para>
+Note that the reliability of the manufacturers' certificate databases
+cannot be guaranteed. It is vital that KDMs are tested by the
+destination cinema will in advance of show time to identify any
+problems.
+</para>
+
+<para>
+Once you have set up all the screens that you need KDMs for, select
+the CPL that you want to create the KDM for. You can use the
+drop-down list to select the CPLs in the current film project, or load
+a CPL from somewhere else. Select the cinemas and/or screens that you
+want KDMs for and fill in the start and end dates and times.
+</para>
+
+<para>
+You must also select the type of KDM that you want to generate. If in
+doubt, use <guilabel>Modified Transitional 1</guilabel>.
</para>
<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
+those that are formally ‘released’. This is useful if you
like to live on the bleeding edge!
</para>
</section>
</section>
-<!-- XXX: servers -->
+<!-- ============================================================== -->
+<section>
+<title>Servers</title>
+
+<para>
+The servers tab is shown in <xref linkend="fig-prefs-servers"/>.
+</para>
+
+<figure id="fig-prefs-servers">
+ <title>Servers preferences</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/prefs-servers&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+If <guilabel>Use all servers</guilabel> is ticked DCP-o-matic will
+locate encoding servers automatically (see <xref
+linkend="ch-servers"/>).
+</para>
+
+<para>
+Instead of this (or in addition) servers can be specified explicitly.
+To add a server, click <guilabel>Add...</guilabel> and enter the host
+name or IP address of the server to use.
+</para>
+
+</section>
<!-- ============================================================== -->
<section xml:id="sec-prefs-colour">
</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>
<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
+projectors are 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>
The <guilabel>Frame Rate</guilabel> control in the
<guilabel>DCP</guilabel> tab sets the video frame rate that the DCP
will use. Clicking <guilabel>Use best</guilabel> sets the rate to
-what DVD-o-matic thinks is the best for your content. With this
+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>
<programlisting>
-dcpomatic_server_cli
+dcpomatic2_server_cli
</programlisting>
<para>
</para>
<programlisting>
-dcpomatic_server_cli -t 4
+dcpomatic2_server_cli -t 4
</programlisting>
<para>
projects / dcpomatic.git / blobdiff