<section>
<title>What is DCP-o-matic?</title>
-<para>DCP-o-matic is a set of programs to perform the following tasks:</para>
+<para>DCP-o-matic is a set of tools to allow you to:</para>
<itemizedlist>
- <listitem>Creat
ion of <ulink
- url="http://en.wikipedia.org/wiki/Digital_Cinema_Package">Digital
- Cinema Packages</ulink> (DCPs) from video, audio and/or
- subtitle files.</listitem>
- <listitem>Playback of DCPs on a PC.</listitem>
- <listitem>Creation of KDMs for DCPs.</listitem>
+ <listitem>Creat
e <ulink
+ url="https://en.wikipedia.org/wiki/Digital_Cinema_Package">Digital
+ Cinema Packages</ulink> (DCPs) from video, audio, subtitle and closed-caption files.</listitem>
+ <listitem>Play and verify DCPs (see <xref linkend="ch-player"/> and <xref linkend="ch-verifier"/>).</listitem>
+ <listitem>Create KDMs for DCPs (see <xref linkend="ch-encryption"/>).</listitem>
+ <listitem>Write cinema-format drives containing DCPs (see <xref linkend="ch-writer"/>).</listitem>
</itemizedlist>
</section>
<para>
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
+url="https://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GNU
GPL</ulink>.
</para>
</para>
<note>
-Notes of an advanced nature are presented like this. Ignore them unless you want to know the gory details.
+Notes of an advanced nature are presented like this. Ignore them unless you want to know the details.
</note>
</section>
<para>
To install DCP-o-matic on Windows, download the installer from
-<ulink url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>
+<ulink url="https://dcpomatic.com/">https://dcpomatic.com/</ulink>
and double-click it. Click through the installer wizard, and
DCP-o-matic will be installed onto your machine.
</para>
<para>
-If you are using a 32-bit version of Windows, you will need the 32-bit
-installer. For 64-bit Windows, either installer will work, but I
-suggest you used the 64-bit version as it will allow DCP-o-matic to
-use more memory. You may find that DCP-o-matic crashes if you run
-many parallel encoding threads (more than 4) on the 32-bit
-version.
-</para>
-
-<para>
-If you are still using Windows XP, download the specific XP version as
-it should be more stable on your machine than the ‘normal’
-Windows version.
+Use the 64-bit installer unless you are using a 32-bit version of Windows.
+You may find that DCP-o-matic crashes if run the 32-bit version on a CPU with more than 4 cores.
</para>
</section>
<!-- ============================================================== -->
<section>
-<title>Mac OS X</title>
+<title>macOS</title>
<para>
-DCP-o-matic will run on Mac OS X version 10.6 (Snow Leopard) and
-higher. DCP-o-matic is split into four separate applications, each of
+DCP-o-matic versions 2.16.0 and higher will run on macOS version 10.8 (Mountain Lion) and
+higher. DCP-o-matic is split into eight separate applications, each of
which can be installed by downloading the <code>.dmg</code>,
double-clicking to open and then dragging the icon to your
<guilabel>Applications</guilabel> folder.
</para>
<para>
-If you are not sure which parts of DCP-o-matic to install, start
+If you don't know which parts of DCP-o-matic to install, start
with the first (main) part.
</para>
+<para>
+If you are using macOS 10.7 (Lion) or older you will need to install the latest 2.14.x version of DCP-o-matic.
+</para>
+
</section>
<!-- ============================================================== -->
<section>
-<title>Debian, Ubuntu or Mint Linux</title>
-
-<para>
- You can install DCP-o-matic on:
-</para>
-
-<itemizedlist>
- <listitem>Debian 7 (‘wheezy’)</listitem>
- <listitem>Debian 8 (‘jessie’)</listitem>
- <listitem>Debian 9 (‘squeeze’)</listitem>
- <listitem>Debian unstable (‘sid’)</listitem>
- <listitem>Ubuntu 14.04 (‘Trusty Tahr’)</listitem>
- <listitem>Ubuntu 16.04 (‘Xenial Xerus’)</listitem>
- <listitem>Ubuntu 18.04 (‘Bionic Beaver’)</listitem>
- <listitem>Mint 17</listitem>
- <listitem>Mint 18</listitem>
- <listitem>Mint 19</listitem>
-</itemizedlist>
+<title>Debian, Ubuntu and Mint Linux</title>
-<para>
-using <code>.deb</code> packages: download the appropriate package
-from <ulink url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>
-and double-click it. Debian or Ubuntu will install the necessary bits and
-pieces and set DCP-o-matic up for you.
+<para>There are <code>.deb</code> packages for Debian, Ubuntu and Mint on
+ <ulink url="https://dcpomatic.com/">https://dcpomatic.com/</ulink>
</para>
</section>
<!-- ============================================================== -->
<section>
<title>Fedora, Centos and Mageia Linux</title>
- <para>There are <code>.rpm</code> packages for Fedora 27 and 28, Centos 6 and 7 and Mageia 6 on
- <ulink url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>
+ <para>There are <code>.rpm</code> packages for Fedora, Centos and Mageia on
+ <ulink url="https://dcpomatic.com/">https://dcpomatic.com/</ulink>
</para>
</section>
<!-- ============================================================== -->
</para>
</section>
-
-<!-- ============================================================== -->
<section>
-<title>Other Linux distributions</title>
-
-<para>
-Installation on other Linux systems (for which no packages are
-available) is quite hard as it must be compiled from source. If you
-can't download packages for your distribution, do let me know by
-<ulink url="mailto:carl@dcpomatic.com">email</ulink> and I will look
-into providing packages on the website.
-</para>
-
-<para>
-The following dependencies are required:
-<itemizedlist>
-<listitem><ulink url="http://ffmpeg.org/">FFmpeg</ulink></listitem>
-<listitem><ulink url="http://www.mega-nerd.com/libsndfile/">libsndfile</ulink></listitem>
-<listitem><ulink url="http://www.mega-nerd.com/SRC/">libsamplerate</ulink></listitem>
-<listitem><ulink url="http://www.openssl.org/">OpenSSL</ulink></listitem>
-<listitem><ulink url="http://www.openjpeg.org/">libopenjpeg</ulink></listitem>
-<listitem><ulink url="http://www.imagemagick.org/script/index.php">ImageMagick</ulink></listitem>
-<listitem><ulink url="http://www.boost.org/">Boost</ulink></listitem>
-<listitem><ulink url="http://www.libssh.org/">libssh</ulink></listitem>
-<listitem><ulink url="http://www.gtk.org/">GTK (on Linux)</ulink></listitem>
-<listitem><ulink url="http://www.wxwidgets.org/">wxWidgets</ulink></listitem>
-<listitem><ulink url="http://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/asdcplib">asdcplib with some patches</ulink></listitem>
-<listitem><ulink url="http://carlh.net/libdcp">libdcp</ulink></listitem>
-<listitem><ulink url="http://carlh.net/libsub">libsub</ulink></listitem>
-<listitem><ulink url="http://carlh.net/libcxml">libcxml</ulink></listitem>
-<listitem><ulink url="https://carlh.net/locked_sstream">locked_sstream</ulink></listitem>
-<listitem><ulink url="https://www.music.mcgill.ca/~gary/rtaudio/">rtaudio</ulink></listitem>
-<listitem><ulink url="http://site.icu-project.org">libicu</ulink></listitem>
-</itemizedlist>
-</para>
-
-<para>
-Once you have installed the development packages for the dependencies,
-download the source code from <ulink
-url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>,
-unpack it and run the following commands from inside the source
-directory:
-</para>
-
-<programlisting>
-./waf configure
-./waf build
-sudo ./waf install
-</programlisting>
-
-<para>
-With any luck, this will build and install DCP-o-matic on your system. To run it, enter:
-</para>
-
-<programlisting>
-dcpomatic2
-</programlisting>
-
+<title>Building from source</title>
<para>
-in a shell.
+Since DCP-o-matic is open-source you can also build it yourself,
+though this can be quite a difficult process (especially on Windows and macOS).
+There are instructions for how to do it on <ulink url="https://dcpomatic.com/building">https://dcpomatic.com/building</ulink>
</para>
-
</section>
</chapter>
+
+
<!-- ============================================================== -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<title>Creating a DCP from a video</title>
url="https://download.blender.org/durian/trailer/Sintel_Trailer.480p.DivX_Plus_HD.mkv">their
website</ulink>. Generally one would want to use the
highest-resolution material available, but for this test we will use
-the low-resolution version to save everyone's bandwidth bills.
+the low-resolution version to save on download time.
</para>
<para>
Now, start DCP-o-matic and its window will open. First, we will
create a new ‘film’. A ‘film’ is how DCP-o-matic refers to
some pieces of content, along with some settings, which we will make into
-a DCP. DCP-o-matic stores its data in a folder on your disk while it
-creates the DCP. You can create a new film by selecting
+a DCP. DCP-o-matic stores its ‘film’ data in a folder on your disk while it
+creates the DCP.
+</para>
+
+<para>
+You can create a new film by selecting
<guilabel>New</guilabel> from the <guilabel>File</guilabel> menu, as
shown in <xref linkend="fig-file-new"/>.
</para>
<title>Dialogue box for creating a new film</title>
<mediaobject>
<imageobject>
- <imagedata fileref="screenshots/video-new-film&scs;"/>
+ <imagedata fileref="screenshots/new-film&scs;"/>
</imageobject>
</mediaobject>
</figure>
<para>
In this dialogue box you can choose a name for the film. This will be
used to name the folder to store its data in, and also as the initial
-name for the DCP itself. You can also choose whereabouts you want to create
+name for the DCP itself. You can also choose where you want to create
the film. In the example from the figure, DCP-o-matic will create a
-folder called ‘DCP Test’ inside my home folder (carl) into which it
+folder called ‘DCP Test’ inside my existing folder <code>DCP</code> into which it
will write its working files.
</para>
+<para>
+DCPs can be very large (more than 100Gb for a feature-length DCP) so
+it's important to choose a folder on a disk with plenty of free space.
+</para>
+
</section>
<para>
The next step is to add the content that you want to use. DCP-o-matic
-can make DCPs from multiple pieces of content, but in this simple
-example we will just use a single piece. Click the <guilabel>Add
+can make DCPs from multiple pieces of content, but in this example we
+will use a single piece. Click the <guilabel>Add
file(s)...</guilabel> button, as shown in <xref
linkend="fig-add-file"/>, and a file chooser will open for you to
select the content file to use, as shown in <xref
<para>
Choose <guilabel>Make DCP</guilabel> from the
-<guilabel>Jobs</guilabel> menu. DCP-o-matic will encode your DCP.
+<guilabel>Jobs</guilabel> menu. Before encoding your DCP, DCP-o-matic
+will run a series of checks on your film to look for various conditions
+that might cause problems when playing back the DCP. If any potential
+problems are found, DCP-o-matic will show you a list of hints.
+Each hint describes the condition that was found and gives
+advice on how to resolve it. If hints are found and reported, you can
+either <guilabel>Make DCP</guilabel> anyway (without adjusting any
+settings), or <guilabel>Go back</guilabel> in order to make
+adjustments before encoding the DCP.
+</para>
+
+<para>
+If no hints were found (or you pressed <guilabel>Make DCP</guilabel>
+after hints were displayed), DCP-o-matic will encode your DCP.
This may take some time (many hours in some cases). While the job is
in progress, DCP-o-matic will update you on how it is getting on with
the progress bar in the bottom of its window, as shown in <xref
<title>Making the DCP</title>
<mediaobject>
<imageobject>
- <imagedata scale="50" fileref="screenshots/making-dcp&scs;"/>
+ <imagedata fileref="screenshots/making-dcp&scs;"/>
</imageobject>
</mediaobject>
</figure>
<para>
-When it has finished, the DCP will end up on your disk inside the
-film's folder. You can then copy this to a projector via a USB
-stick, hard-drive or network connection. See <xref
+When it has finished, the DCP will be written into its own folder inside the film's folder.
+You can copy this to a projector via a USB stick, hard-drive or network connection. See <xref
linkend="ch-files"/> for details about the files that DCP-o-matic creates.
</para>
<para>
-Alternatively, if you have a projector or Theatre Management System
-(TMS) that is accessible via SCP or FTP across your network, you can upload
-the content directly from DCP-o-matic. See the <xref
-linkend="sec-prefs-tms" endterm="sec-prefs-tms-short"/> in <xref linkend="sec-prefs-tms"/>.
+Alternatively, DCP-o-matic can upload your DCP directly to a projector
+or Theatre Management System (TMS) that is accessible via SCP or FTP
+across your network. See <xref linkend="sec-prefs-tms"/>.
</para>
</section>
<title>Dialogue box for creating a new film</title>
<mediaobject>
<imageobject>
- <imagedata fileref="screenshots/still-new-film&scs;"/>
+ <imagedata fileref="screenshots/new-film&scs;"/>
</imageobject>
</mediaobject>
</figure>
Most of the default settings will be fine for a simple test. The one
thing that you might wish to change is the length of the still.
Select the <guilabel>Timing</guilabel> tab and you will see a
-<guilabel>Play length</guilabel> setting, as shown in <xref
+<guilabel>Full length</guilabel> setting, as shown in <xref
linkend="fig-timing-tab"/>.
</para>
<!-- ============================================================== -->
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en" id="ch-manipulating-existing-dcps">
<title>Manipulating existing DCPs</title>
<para>
-Frequently DCP-o-matic is used to take content in formats such as MP4
-and convert it to JPEG2000 for a DCP. It can also be used
-to take existing DCPs and modify them in various ways.
+DCP-o-matic is often used to take content in formats such as MP4 and
+make it into a DCP. It can also be used to take existing DCPs and
+modify them in various ways.
</para>
<section>
<title>Importing a DCP into DCP-o-matic</title>
<para>
-If you want to do something to an existing DCP the first step is to
-import it. Click <guilabel>Add DCP...</guilabel> and select your
-DCP's folder. It will be added to the DCP-o-matic project. If the
-DCP is unencrypted you can preview it in the normal way, though
-playback will be very slow as decoding of DCPs is almost as
-computationally intensive as encoding them.
+The first step in manipulating an existing DCP is to import it. Click
+<guilabel>Add DCP...</guilabel> and select your DCP's folder. It will
+be added to the DCP-o-matic project. If the DCP is unencrypted you
+can preview it in the normal way, though playback may be slow as
+decoding of DCPs is almost as computationally intensive as encoding
+them.
</para>
<para>
</para>
<para>
-KDMs must be prepared by the organisation which created the DCP. They
+KDMs must be prepared by whoever created the DCP. They
contain the keys to decrypt the DCP wrapped up in such a way that only
the intended recipient can read them. You will need to provide the
-organisation with a certificate which identifies your copy of
+KDM creator with a certificate which identifies your copy of
DCP-o-matic and allows them to create a KDM for you.
</para>
<para>
To get DCP-o-matic's decryption certificate, open the Preferences
dialogue (see <xref linkend="ch-preferences"/>) and go to the
-<guilabel>Keys</guilabel> tab. Click the <guilabel>Export DCP
-decryption certificate...</guilabel> button at the bottom of this tab
-and save the certificate. Send this certificate to the DCP creators
-and they can create a KDM to allow DCP-o-matic to decrypt their DCP.
+<guilabel>Keys</guilabel> tab. Click the <guilabel>Export KDM
+decryption leaf certificate...</guilabel> button at the top of this tab
+and save the certificate. Send this certificate to the KDM creators
+and they can make a KDM to allow DCP-o-matic to decrypt the DCP.
</para>
<para>
-Once you have your KDM, right-click the DCP's name in DCP-o-matic and
-choose <guilabel>Add KDM...</guilabel>. Specify your KDM and the DCP
+Once you have your KDM, right-click the DCP's name in the DCP-o-matic content list and
+choose <guilabel>Add KDM...</guilabel>. Select your KDM and the DCP
will be decrypted and become available for preview.
</para>
</itemizedlist>
<para>
-If you do change any of these settings on a piece of DCP content
-DCP-o-matic will decode and then re-encode the JPEG2000 data.
+DCP-o-matic will be forced to decode and re-encode your JPEG2000 data
+if you change any of these settings on a piece of DCP content.
</para>
</section>
which has ten different translations for which the subtitles are
different but video and audio are the same. If the video and audio
content takes up, say, 100Gb this means that the set of DCPs for every
-translation would be about 1Tb with a lot of duplicated data.
+translation would be about 1Tb, with a lot of duplicated data.
</para>
<para>
images which should be treated as the frames of a video.
</listitem>
-<listitem>Subtitle — a file containing subtitle which will be
+<listitem>Subtitle — a file containing subtitles which will be
superimposed on the image of the DCP. These can be
<guilabel>.srt</guilabel>, <guilabel>.ssa</guilabel>, <guilabel>.ass</guilabel> or <guilabel>.xml</guilabel>
-files.</listitem>
+files. Subtitle files can also be used to make closed captions.</listitem>
<listitem>DCP — an existing DCP.</listitem>
+
+<listitem>ATMOS MXFs — if you have Dolby ATMOS content in MXF format (created using Dolby's tools) you can add it to a DCP just like any other content.</listitem>
</itemizedlist>
<para>
<guilabel>Add file(s)...</guilabel> and choose them from the selector.
</para>
+<para>
+DCP-o-matic will automatically map a set of audio files to the correct channels if you include appropriate ‘tags’ in your filenames, as shown in <xref linkend="tab-audio-file-naming"/>.
+</para>
+
+<table id="tab-audio-file-naming">
+ <title>Audio file naming</title>
+ <tgroup cols='3' align='left' colsep='1' rowsep='1'>
+ <thead>
+ <row>
+ <entry>Tag</entry>
+ <entry>Examples</entry>
+ <entry>Channel</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><code>L</code> surrounded by <code>.</code> <code>_</code> or <code>-</code></entry>
+ <entry>film-L.wav my_movie_L_final.wav</entry>
+ <entry>Left</entry>
+ </row>
+ <row>
+ <entry><code>R</code> surrounded by <code>.</code> <code>_</code> or <code>-</code></entry>
+ <entry>film-R.wav my_movie_R_final.wav</entry>
+ <entry>Right</entry>
+ </row>
+ <row>
+ <entry><code>C</code> surrounded by <code>.</code> <code>_</code> or <code>-</code></entry>
+ <entry>film-C.wav my_movie_C_final.wav</entry>
+ <entry>Centre</entry>
+ </row>
+ <row>
+ <entry><code>Lfe</code> surrounded by <code>.</code> <code>_</code> or <code>-</code></entry>
+ <entry>film-Lfe.wav my_movie_Lfe_final.wav</entry>
+ <entry>LFE (sub)</entry>
+ </row>
+ <row>
+ <entry><code>Ls</code> surrounded by <code>.</code> <code>_</code> or <code>-</code></entry>
+ <entry>film-Ls.wav my_movie_Ls_final.wav</entry>
+ <entry>Left surround</entry>
+ </row>
+ <row>
+ <entry><code>Rs</code> surrounded by <code>.</code> <code>_</code> or <code>-</code></entry>
+ <entry>film-Rs.wav my_movie_Rs_final.wav</entry>
+ <entry>Right surround</entry>
+ </row>
+ </tbody>
+ </tgroup>
+</table>
+
<para>
To add a directory (folder) of images, choose <guilabel>Add
folder...</guilabel> and choose the directory from the selector.
<para>Adding existing DCPs to a DCP-o-matic film is a little different
to adding other types of content. Most content has to be converted to
-JPEG2000, the compression scheme used by DCPs, which is a very
+JPEG2000 (the compression scheme used by DCPs) which is a very
time-consuming process. Existing DCPs are already in JPEG2000 format
so do not require conversion. This means that, provided no settings
such as crop are used on the DCP content, picture and sound data will
<!-- ============================================================== -->
<section>
-<title>Content Properties</title>
+<title>Content properties</title>
<para>
Below the content list are the controls to set content properties. To
<para>
The content properties are split up into four sections:
<guilabel>Video</guilabel>, <guilabel>Audio</guilabel>,
-<guilabel>Subtitles</guilabel> and <guilabel>Timing</guilabel>. Not
+<guilabel>Timed text</guilabel> and <guilabel>Timing</guilabel>. Not
all of these sections will be active for all content types. The controls
in each section are described below.
</para>
<title>Use this DCP's video as OV and make VF</title>
<para>
-This option is only applicable if the selected content is an existing
+This option is only available if the selected content is an existing
DCP. It allows you make a VF DCP, using the video content from the
existing DCP by referencing it (rather than copying). See <xref
linkend="sec-overlay"/>.
</section>
-<!-- ============================================================== -->
-<section>
-<title>Filtering</title>
-
-<para>
-The ‘filters’ settings allow you to apply various video
-filters to the image. These may be useful to try to improve
-poor-quality sources like DVDs. You can set up the filters by clicking the
-<guilabel>Edit</guilabel> button next to the filters entry in the
-setup area of the DCP-o-matic window; this opens the filters selector
-as shown in <xref linkend="fig-filters"/>.
-</para>
-
-<figure id="fig-filters">
- <title>Filters selector</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="screenshots/filters&scs;"/>
- </imageobject>
- </mediaobject>
-</figure>
-
-<para>
-After changing the filters setup, you will need to regenerate the DCP
-to see the effect on the cinema screen. The preview in DCP-o-matic
-will update itself whenever filters are changed, though of course this
-image is much smaller and of lower resolution than a projected image!
-</para>
-</section>
-
-
-
<!-- ============================================================== -->
<section>
<title>Colour conversion</title>
converting the selected content into the XYZ colourspace for the DCP.
</para>
+<para>
+In particular, the setting you choose here should be the colour space <emphasis>that the content
+has been created or graded for</emphasis>. DCP-o-matic will take care of converting your content's
+colourspace into the correct one for the DCP.
+</para>
+
<para>
The easiest way to select the required conversion is to choose one of
-DCP-o-matic's presets. DCP-o-matic knows how to convert from four
-common colourspaces: sRGB, Rec. 601, Rec. 709 and P3. If you do not
+DCP-o-matic's presets. DCP-o-matic knows how to convert from seven
+common colourspaces: sRGB, Rec. 601, Rec. 709, Rec. 1886, Rec. 2020, S-Gamut3 and P3. If you do not
know which preset you should use, refer to the suggestions in <xref
linkend="tab-colour-conversion"/>.
</para>
<colspec colwidth='5*'/>
<tbody>
<row>
-<entry>sRGB</entry><entry>Still images in RGB, e.g. photographs</entry>.
+<entry>sRGB</entry><entry>Still images in RGB, e.g. photographs.</entry>
</row>
<row>
<entry>Rec. 601</entry><entry>Standard-definition content (fewer than about 1000 pixels across) including DVD rips.</entry>
<para>
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>.
+url="https://dcpomatic.com/manual/colour.pdf">colour.pdf</ulink>.
</para>
</section>
<title>Other settings</title>
<para>
-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.
+The <guilabel>crop</guilabel> settings can be used to crop your
+content, which is often used to remove black borders from the edges of
+the image. The specified number of pixels will be trimmed from each
+edge, and the content image in the right of the window will be updated
+to show the effect of the crop.
</para>
<para>
</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.
+The <guilabel>Scale</guilabel> option governs the shape that
+DCP-o-matic will scale the content's image into. In most cases <guilabel>to fit DCP</guilabel> will do the right thing; if not, choose <guilabel>custom</guilabel>
+and you can specify exactly how the image should be scaled.
</para>
</section>
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 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.
+video file is 720x576 pixels and has rectangular pixels (a pixel
+aspect ratio of 1.42:1) and so its display aspect ratio is 1.78:1. Since
+the controls specify <guilabel>to fit DCP</guilabel> DCP-o-matic scales the image
+to 1918x1080 and pads it to the DCP's container ratio of 1.85:1 (called ‘DCI Flat’). For a 2K DCP this is 1998x1080 pixels.
</para>
<para>
<title>Audio</title>
<para>
-The <guilabel>Audio</guilabel> tab controls properties of the image, as shown in <xref linkend="fig-audio-tab"/>.
+The <guilabel>Audio</guilabel> tab controls properties of the sound, as shown in <xref linkend="fig-audio-tab"/>.
</para>
<figure id="fig-audio-tab">
</para>
<para>
-When content channels are copied into DCP channels they can be done
+When content channels are copied into DCP channels the copy 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
</para>
<para>
-‘Audio Gain’ is used to alter the volume of the
+<guilabel>Audio Gain</guilabel> is used to alter the volume of the
soundtrack. The specified gain (in dB) will be applied to each sound
channel of your content before it is written to the DCP.
</para>
your sound-rack fader.
</para>
-<para>
-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>
-
<para>
<guilabel>Audio Delay</guilabel> is used to adjust the synchronisation
between audio and video. A positive delay will move the audio later
<!-- ============================================================== -->
<section>
-<title>Subtitles</title>
+<title>Timed text (subtitles and closed captions)</title>
<para>
-The subtitles tab contains settings related to subtitles in your
-content, as shown in <xref linkend="fig-subtitles-tab"/>.
+The timed text tab contains settings related to subtitles and closed captions in your
+content, as shown in <xref linkend="fig-timed-text-tab"/>.
</para>
-<figure id="fig-subtitles-tab">
- <title>Subtitle settings tab</title>
+<figure id="fig-timed-text-tab">
+ <title>Timed text settings tab</title>
<mediaobject>
<imageobject>
- <imagedata fileref="screenshots/subtitles-tab&scs;"/>
+ <imagedata fileref="screenshots/timed-text-tab&scs;"/>
</imageobject>
</mediaobject>
</figure>
+<para>
+Depending on where timed text comes from it can sometimes be used as
+either an open subtitle (to be overlaid onto the cinema screen and
+seen by everybody) or as a closed caption (to be displayed to
+individual viewers using a special system such as the Doremi
+CaptiView™)
+</para>
+
<para>
DCP-o-matic can either:
</para>
<itemizedlist>
- <listitem>Extract subtitles that are embedded in video files, or</listitem>
- <listitem>Use subtitles from SubRip (<code>.srt</code>), SubStation
- Alpha (<code>.ssa</code> or <code>.ass</code>) or DCP XML files. You may find the great
+ <listitem>Extract timed text that is embedded in video files, or</listitem>
+ <listitem>Use timed text from SubRip (<code>.srt</code>), SubStation
+ Alpha (<code>.ssa</code> or <code>.ass</code>) or DCP XML files. You may find the
free program <ulink
url="http://www.nikse.dk/subtitleedit/">Subtitle Edit</ulink> useful
for creating such files.</listitem>
</itemizedlist>
<para>
-Embedded subtitles are usually represented using a set of bitmaps,
-especially on files that have come from DVD or BluRay. Such subtitles
-can (currently) only be ‘burnt’ into the DCP (that is,
-they are included in the image and not overlaid by the projector).
+Embedded timed text is usually represented using a set of bitmaps,
+especially on files that have come from DVD or BluRay. Such text can
+be used as a subtitle, but not a closed caption (since the closed
+captioning system requires the text to be delivered as
+character codes rather than as an image).
</para>
+<para>In contrast, SubRip, SubStation Alpha or DCP text can be used as either a subtitle or a closed caption.</para>
+
<para>
-With SubRip, SubStation Alpha or DCP subtitles you have the choice to
-either burn-in or include the subtitles as separate subtitle
+With subtitles you have the further choice of whether to burn the
+subtitles into the image or include them as a separate subtitle
‘asset’ within your DCP (in which case the projector
overlays them onto the image on playback). The difference between
burn-in and overlay is illustrated by <xref linkend="fig-burn-in"/>
</para>
<para>
-Select the <guilabel>Use Subtitles</guilabel> check-box to enable
-the subtitles in the selected content.
+Select the <guilabel>Use as</guilabel> check-box to enable the timed
+text in the selected content, then choose what you want to use the
+text for: open subtitles or closed captions.
</para>
<para>
Select the <guilabel>Burn subtitles into image</guilabel> check-box to
-burn these subtitles into the image; if this is not ticked the
+burn subtitles into the image; if this is not ticked the
subtitles will be included separately in the DCP to be rendered by the
-projector. This check-box will always be ticked if you are using
-embedded ‘image’ subtitles.
+projector.
</para>
<para>
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%.
+controls move subtitles around within the image. These controls have
+no effect for closed captions. The offsets are expressed as a
+percentage of the video frame size; 100% X offset is the entire width
+of the frame, and 100% Y offset is the entire height. Hence, to move
+the subtitles down by half the frame height you would use a Y offset
+of 50%.
</para>
<para>
The <guilabel>X Scale</guilabel> and <guilabel>Y Scale</guilabel>
-controls scale 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.
+controls scale subtitles. These controls have no effect for closed
+captions. Scale values of 1 make the subtitles the same size
+(relative to the size of the image) as they are on the original.
+Values lower than 1 make them smaller, and values higher make them
+larger. You can stretch the subtitles in either direction by
+specifying different values for X and Y scale. Subtitles from DVD and
+Blu Ray sources are frequently larger (relative to the video frame)
+than those typically used for DCP, so it is often useful to scale such
+subtitles down using these controls.
</para>
<para>
The <guilabel>Line spacing</guilabel> control adjusts the line spacing
-of the subtitles. This only works for non-embedded (text) subtitles.
+of the subtitles. This only works for subtitles that did not come from bitmaps.
</para>
<para>
</para>
<para>
-If you are using non-embedded (text) subtitles you can see the
+If you are using non-image (text) subtitles or closed captions you can see the
subtitle text and timings by clicking the <guilabel>View...</guilabel>
button, or specify the fonts that should be used by clicking <guilabel>Fonts...</guilabel>.
</para>
<para>
With any subtitles you can click <guilabel>Appearance...</guilabel> to
-change how the subtitles look.
+change how the subtitles look. Some of the controls in the
+<guilabel>Appearance</guilabel> only apply to burnt-in subtitles, as
+only limited control is available for subtitles rendered by the
+projection system.
</para>
</section>
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. It can also be used to override the detected
-frame rate of other content if DCP-o-matic has got it wrong.
-</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
</section>
+<!-- ============================================================== -->
+<section>
+ <title>Timeline</title>
+
+ <para>
+ The timeline window gives an overview of all the pieces of content
+ in your film, and how they are arranged. You can open the
+ timeline by clicking the <guilabel>Timeline...</guilabel> button
+ next to the content list. This will open a window like the one in <xref linkend="fig-timeline1"/>.
+ </para>
+
+ <figure id="fig-timeline1">
+ <title>Timeline</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/timeline1&scs;"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>
+ The horizontal axis represents time, and you can see the time codes (in
+ hours:minutes:seconds) along the bottom of the window. Pieces of
+ content are represented with rectangles in the main part of the
+ window. Content containing different types of data (e.g. a MP4
+ file with video, audio and subtitles) have a rectangle for each
+ type.
+ </para>
+
+ <para>
+ Within the timeline you can select content by clicking, and drag
+ it to change its position. Right-clicking a piece of content will
+ open the content menu.
+ </para>
+
+ <para>
+ The toolbar at the top of the window offers the following tools:
+ </para>
+
+ <itemizedlist>
+ <listitem>Select — to select and move content.</listitem>
+ <listitem>Zoom in — to drag out an area that you want to see more closely.</listitem>
+ <listitem>Zoom out — to zoom out so that the window shows the whole film.</listitem>
+ <listitem>Snap — when enabled, content will snap to other content when you drag it close.</listitem>
+ <listitem>Sequence — when enabled, content will be kept in sequence, without gaps, even if some content is removed.</listitem>
+ </itemizedlist>
+</section>
+
<!-- ============================================================== -->
<section>
<title>Video processing pipeline</title>
</para>
<para>
-Consider, as a somewhat over-the-top example, that we have a 720 x 576
+Consider, as a rather contrived 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
<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.
+presented in a 2.39:1 (scope) aspect ratio inside a 1.85:1 (flat) DCP we would select
+<guilabel>custom</guilabel> from the <guilabel>Scale</guilabel>
+option in the <guilabel>Video</guilabel> tab, then choose a ratio (<guilabel>Set ratio and
+fit to DCP container</guilabel>) of 2.39:1.
</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>Next, we would choose
+<guilabel>Flat</guilabel> from the <guilabel>Container</guilabel>
+option in the <guilabel>DCP</guilabel> tab.
</para>
<para>
‘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
+size of 1998x836. This gives us a new version of the image as shown
in <xref linkend="fig-pipeline3"/>.
</para>
</section>
+<section>
+<title>Advanced content settings</title>
+
+<para>
+There are a few more content settings that you can change by right-clicking a piece of content in the list and choosing <guilabel>Advanced settings...</guilabel>
+This opens the dialogue box shown in <xref linkend="fig-advanced-content"/>.
+</para>
+
+<figure id="fig-advanced-content">
+ <title>Advanced content dialogue</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/advanced-content&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+
+<!-- ============================================================== -->
+<section>
+<title>Video filters</title>
+
+<para>
+The <guilabel>Video filters</guilabel> setting allows you to apply various
+filters to the image. These may be useful to try to improve
+poor-quality sources like DVDs. You can set up the filters by clicking the
+<guilabel>Edit</guilabel> button next to the filters entry; this opens the filters selector
+as shown in <xref linkend="fig-filters"/>.
+</para>
+
+<figure id="fig-filters">
+ <title>Filters selector</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/filters&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+</section>
+
+
+<section>
+<title>Override frame rate</title>
+
+<para>
+The <guilabel>Override detected video frame rate</guilabel> setting has some different effects depending on the type of content
+you use it on.
+</para>
+
+<para>
+For video content, it sets the frame rate that DCP-o-matic will run the video at. This is useful if DCP-o-matic has mis-detected
+the video frame rate. For example, if DCP-o-matic says your content is 24fps when you know for a fact it's 25fps, you can set the
+override value to 25 to force DCP-o-matic to do the right thing.
+</para>
+
+<para>
+On audio, subtitle and caption content this setting behaves slightly differently. It sets the video frame rate that the content
+in question was intended to work with. As an example, consider a project with a 23.976fps video source and some separate audio files.
+Perhaps those audio files have been mastered alongside a 24fps version of your video. By default, DCP-o-matic will see the 23.976fps
+video file and decide to run it slightly fast at 24fps to fit the DCP standard. It will then also run the audio slightly fast so that
+it stays in sync with the video.
+</para>
+
+<para>
+In this case, though, that is not what you want, since the audio is already ‘fixed’ to work alongside 24fps video. If you
+override the video frame rate of the <emphasis>audio</emphasis> content to 24fps this will stop DCP-o-matic altering it.
+</para>
+
+<para>
+A similar situation can occur if you have video at one rate and a subtitle file that was prepared with its timing at a different rate.
+In that case, you should override the video frame rate of the <emphasis>subtitle</emphasis> content to the one that it was prepared for.
+This will mean that DCP-o-matic can get the relative timing right.
+</para>
+
+<para>
+Do <emphasis>not</emphasis> use this setting to change the DCP frame rate. Doing so will result in strange effects and sync problems.
+</para>
+</section>
+
+
+<section>
+<title>Video has burnt-in subtitles</title>
+<para>
+Details about subtitle language are stored in various places within the DCP metadata. If a piece of video content already has subtitles
+burnt into the image you can tell DCP-o-matic the language that they are in by clicking the <guilabel>Edit...</guilabel> button.
+</para>
+</section>
+
+
+<section>
+<title>Ignore this content's video</title>
+<para>
+Tick this if you have some content which includes video along with other things (such as audio or subtitles) and you do
+<emphasis>not</emphasis> want the video to appear in the DCP.
+</para>
+</section>
+
+
+</section>
+
</chapter>
</para>
<para>
-Underneath the name field is a preview of the name that the DCP will
-get. To use a ISDCF-compliant name, tick the <guilabel>Use ISDCF
-name</guilabel> check-box. The ISDCF name will be composed using details
+Underneath the <guilabel>Use ISDCF name</guilabel> checkbox is a preview of the name that the DCP will
+get. The ISDCF name will be composed using details
of your content's soundtrack, the current date and other things that
-can be specified in the ISDCF name details dialogue box, which you can
-open by clicking on the <guilabel>Details</guilabel> button.
+can be specified in the <guilabel>Metadata</guilabel> dialogue box, which you can
+open by clicking on the <guilabel>Metadata</guilabel> button.
</para>
<para>
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.
+projectionists will appreciate it if you use the
+<ulink url="https://registry-page.isdcf.com/illustratedguide/">standard naming scheme</ulink>
+as it makes it easier to identify details of the content.
+</para>
+
+<para>
+If there is spoken language in your project's audio you can tick the
+<guilabel>Audio Language</guilabel> checkbox and then specify the language
+of that audio. This information will be used for the ISDCF name, written into
+the DCP cover sheet, and added as metadata to the audio MXF files in the DCP.
</para>
<para>
user interface, so take care to select an appropriate type.
</para>
-<para>
-The <guilabel>Signed</guilabel> check-box sets whether or not the DCP
-is signed. This is rarely important; if in doubt, tick it.
-</para>
-
<para>
The <guilabel>Encrypted</guilabel> check-box will set whether the DCP
should be encrypted or not. If this is ticked, the DCP will require a
<para>
The <guilabel>Reels</guilabel> and <guilabel>Reel length</guilabel>
controls specify how the DCP will be split up into
-‘reels’. See <xref linkend="sec-reels"/> below.
+‘reels’. See <xref linkend="sec-reels"/>.
</para>
<para>
</para>
<para>
-Ticking the <guilabel>Upload DCP to TMS after it is made</guilabel>
-will ask DCP-o-matic to copy the finished DCP to your configured TMS (see <xref linkend="sec-prefs-tms"/>).
+The <guilabel>Markers</guilabel> button opens the Markers dialogue,
+as shown in <xref linkend="fig-markers"/>.
+</para>
+
+<figure id="fig-markers">
+ <title>Markers dialogue</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/markers&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+This dialogue allows you to specify times for when certain things happen
+within your DCP. These times may be read by projection systems to automate
+actions such as setting house light levels.
+</para>
+
+<para>
+The <guilabel>Metadata</guilabel> button opens the Metadata dialogue,
+which allows you to specify various information about the DCP that you are
+making. Some of these data will be included in the DCP's files, and others
+used to make up the ISDCF name for the DCP (if that option is being used).
</para>
<para>
for the content's ratio and ‘Flat’ for the DCP.
</para>
+<para>
+The <guilabel>Resolution</guilabel> control allows you to choose the
+resolution for your DCP. Use 2K unless you have content that is of
+high enough resolution to be worth presenting in 4K.
+</para>
+
<para>
The <guilabel>Frame Rate</guilabel> control sets the frame rate of
your DCP. This can be a little tricky to get right. Ideally, you
more detail in <xref linkend="ch-frame-rates"/>.
</para>
-<para>
-The <guilabel>Use best</guilabel> button sets the DCP video frame rate
-to what DCP-o-matic thinks is the best given the content that you have
-added.
-</para>
-
<para>
The <guilabel>3D</guilabel> button will set your DCP to 3D mode if it
is checked. A 3D DCP will then be created, and any 2D content will be
</para>
<para>
-The <guilabel>Resolution</guilabel> tab allows you to choose the
-resolution for your DCP. Use 2K unless you have content that is of
-high enough resolution to be worth presenting in 4K.
-</para>
-
-<para>
-The <guilabel>JPEG2000 bandwidth</guilabel>; setting changes how big
+The <guilabel>JPEG2000 bandwidth for newly-encoded data</guilabel>; setting changes how big
the final image files used within the DCP will be. Larger numbers
will give better quality, but correspondingly larger DCPs. The
bandwidth can be between 50 and 250 megabits per second (Mbit/s).
</para>
<para>
-The <guilabel>Audio Channels</guilabel> control sets the number of
+<guilabel>Re-encode JPEG2000 data from input</guilabel> governs
+whether or not JPEG2000-encoded data from a piece of content (usually
+a DCP) will be re-used in the output data as-is or whether it will be
+decoded and re-encoded by DCP-o-matic. If the option is enabled
+DCP-o-matic will decompress any JPEG2000 data it finds and re-encode
+it. This is useful if you want to reduce the bitrate of a DCP.
+Usually you will achieve better quality and quicker results by leaving
+this option switched off.
+</para>
+
+<para>
+The <guilabel>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
<para>
The <guilabel>Processor</guilabel> control allows you to select a
-process to apply to the audio before it goes into the DCP. Three processes are currently provided:
+process to apply to the audio before it goes into the DCP. One process is currently provided:
</para>
<itemizedlist>
-<listitem>Mid-side decode — this will take a L/R
+<listitem>Mid-side decoder — this will take a L/R
stereo input and extract the common part (corresponding to the
‘Mid’ in a mid-side signal) into the DCP's centre channel.
The remaining L/R parts will be kept in the L/R channels of the DCP.
This may be useful to make near-field L/R mixes more compatible with
cinema audio systems.</listitem>
-<listitem>Stereo to 5.1 up-mixer A — this will take a stereo input and up-mix it to ‘fake’ 5.1. The input L/R are treated as follows:
-<itemizedlist>
-<listitem>DCP L is input L bandpass-filtered between 1.9kHz and 4.8kHz.</listitem>
-<listitem>DCP R is input R bandpass-filtered between 1.9kHz and 4.8kHz.</listitem>
-<listitem>DCP C is input L mixed with input R, taken down by 3dB and then bandpass-filtered between 150Hz and 1.9kHz.</listitem>
-<listitem>DCP Lfe is input L mixed with input R, taken down by 3dB and then bandpass-filtered between 20Hz and 150Hz.</listitem>
-<listitem>DCP Ls is input L bandpass-filtered between 4.8kHz and 20kHz.</listitem>
-<listitem>DCP Rs is input R bandpass-filtered between 4.8kHz and 20kHz.</listitem>
-</itemizedlist>
-<para>
-This upmixing algorithm is due to Gérald Maruccia.
-</para>
-</listitem>
-<listitem>Stereo to 5.1 up-mixer B — this uses a different approach:
-<itemizedlist>
- <listitem>DCP L is input L.</listitem>
- <listitem>DCP R is input R.</listitem>
- <listitem>DCP C is input L + input R taken down by 3dB.</listitem>
- <listitem>DCP Lfe is DCP C bandpass filtered between 20Hz and 150Hz.</listitem>
- <listitem>DCP Ls and Rs are input L - input R with a 20ms delay.</listitem>
-</itemizedlist>
-</listitem>
</itemizedlist>
<!-- ============================================================== -->
<para>
A ‘reel’ in a DCP is a subsection of the DCP, in the same
way as a 35mm reel is a section of a film. A DCP can be split up into
-any number of reels and the joins (the equivalent to 35mm splices)
+any number of reels and the joins (the equivalent to 35mm splices or changeovers)
between the reels are seamless.
</para>
<para>
There is no reason why you can't just use a single reel for the whole
-of your DCP, as there is no limit on their length. Many people choose
+of your DCP, as there is no limit to their length. Many people choose
to do this.
</para>
The picture, sound and subtitle data of the DCP will be
split up into more smaller files on disk, rather than fewer larger
files. This can be useful if the DCP is to be transferred on storage
-that have file size limits. The FAT32 filesystem, for example, can
+that has a file size limit. The FAT32 filesystem, for example, can
only hold files smaller than 4Gb. A 6Gb DCP with a single reel could
not be transferred using a FAT32-formatted disk. If that DCP were
split up into two 3Gb reels it could be transferred.
for example, a film company who wants to put a 5 second ident onto the
beginning of DCPs that they distribute. If they receive a feature
film DCP they can modify it to add their ident as a separate reel.
-This is easier than attaching the picture data in the DCP.
+This is easier than attaching the picture data to the feature's existing data.
</listitem>
</itemizedlist>
<para>
DCP-o-matic offers three options for setting up the reels in your DCP:
-single reel, split by video content or custom.
+<guilabel>single reel</guilabel>, <guilabel>split by video content</guilabel> or <guilabel>custom</guilabel>.
</para>
<para>
to the plots, which can make them easier to read in some cases.
</para>
+<para>Underneath the plot are shown some precise numbers for peaks and other measurements. A peak value displayed in red means that it is greater than -3dB.</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.
+The audio plot is no substitute for listening in an
+cinema, but it can be useful to get levels in roughly the right area.
</para>
</section>
</para>
<para>
-For example if the template has a piece of video content and some
+For example, if the template has a piece of video content and some
subtitles, any video that you add to the new film will take on the
settings of the video in the template. Similarly, any subtitles that
you add will take on the settings of the subtitles from the template.
<listitem>Resolution</listitem>
<listitem>JPEG200 bandwidth</listitem>
<listitem>Video frame rate</listitem>
- <listitem>Signed and encrypted checkboxes</listitem>
+ <listitem>Encrypted checkbox</listitem>
<listitem>Audio channels</listitem>
<listitem>Standard (Interop / SMPTE)</listitem>
<listitem>Audio processor</listitem>
<listitem>Reel type and length</listitem>
- <listitem>Upload after make DCP checkbox</listitem>
</itemizedlist>
<para>
-In addition to this, the settings (but not the filenames) of any
+In addition, the settings (but not the filenames) of any
content in the template are stored, as discussed above. The status of
the <guilabel>Keep video and subtitles in sequence</guilabel> checkbox
from the timeline is also preserved.
</chapter>
+<!-- ============================================================== -->
+<chapter xml:id="ch-export" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+ <title>Export</title>
+
+ <para>
+ As well as creating DCPs from the content you specify, DCP-o-matic
+ can also export projects to ProRes and MP4 files. This is most
+ often useful to convert DCPs to a file that is smaller and easier to play back.
+ </para>
+
+ <para>
+ To convert a DCP to ProRes or MP4, the first step is start a new
+ project and import the DCP (see <xref
+ linkend="ch-manipulating-existing-dcps"/>). Then, choose
+ <guilabel>Export...</guilabel> from the <guilabel>Jobs</guilabel>
+ menu to open the export dialogue, as shown in <xref linkend="fig-export"/>.
+ </para>
+
+ <figure id="fig-export">
+ <title>Export dialogue</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/export&scs;"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>
+ From this dialogue you can select the required output format,
+ output file and, in the case of MP4, the quality of the output
+ file (by setting the <ulink url="https://trac.ffmpeg.org/wiki/Encode/H.264#crf">CRF value</ulink>).
+ </para>
+
+ <para>
+ The useful range of CRF values is from 17 (high quality but large file size) to 28 (smaller file size and still reasonable quality).
+ </para>
+
+ <para>
+ The time needed to export, and the resulting size, depend partly on the DCP resolution set in the project. To change that, see <xref linkend="ch-dcp"/>.
+ </para>
+
+ <para>
+ You can also choose whether to mix down multichannel sources to stereo and whether you want to write separate reels to separate files.
+ </para>
+</chapter>
<!-- ============================================================== -->
<chapter xml:id="ch-encryption" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<title>Encryption</title>
<para>
-It is not required that DCPs be encrypted, but they can be. This
+DCP's do not have to be encrypted, but they can be. This
chapter discusses the basic principles of DCP encryption, and how
DCP-o-matic can create encrypted DCPs and KDMs for them.
</para>
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
+DCP can be distributed by insecure means: if a bad person called
Mallory obtains a hard drive containing an encrypted DCP, there is no
way that he can play it. Only those cinemas who receive a correct key
delivery message (KDM) can play the DCP.
<para>
We suppose that we are trying to send a DCP to
-Alice's cinema without a troublemaker called Mallory being able to
+Alice's cinema without a third party called Mallory being able to
watch it himself.
</para>
</para>
<para>
-The first step in a DCP encryption is to encode its data with some key
+The first step in encrypting a DCP is to encode its data with a random key
using symmetric-key encryption. The encrypted DCP can then be sent
anywhere, safe in the knowledge that even if Mallory got hold of a
copy, he could not decrypt it.
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.
+happened to know Mallory, he could just send her a copy of the key.
</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
+decrypts our message using its private key, giving the
symmetric key which can decrypt the DCP.
</para>
</para>
<para>
-The second part of distributions is to generate KDMs for the cinemas
+The second stage of distribution is to generate KDMs for the cinemas
that you wish to allow to play your DCP. There are two approaches to
this within DCP-o-matic: using the project, or using a DKDM. These
approaches are now described in turn.
<title>KDM dialog</title>
<mediaobject>
<imageobject>
- <imagedata scale="40" fileref="screenshots/kdm&scs;"/>
+ <imagedata scale="35" fileref="screenshots/kdm&scs;"/>
</imageobject>
</mediaobject>
</figure>
<para>
Alternatively, certificates for projection systems made by some
manufacturers can be downloaded from databases provided by the
-manufacturer. Currently this is supported for Doremi and Dolby
-equipment. If you are targeting a screen with equipment by one of
-these manufacturers you can click <guilabel>Download</guilabel> then
-enter the serial number of the server in the screen and click
-<guilabel>Download</guilabel> again and, all being well, the certificate
-will be fetched.
-</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.
+manufacturer. Currently this is supported for Doremi, Dolby, Barco,
+Christie and GDC equipment (through downloading Barco, Christie or GDC
+certificates requires you to have an appropriate account set up in
+DCP-o-matic's preferences). If you are targeting a screen with
+equipment by one of these manufacturers you can click
+<guilabel>Download</guilabel> then enter the serial number of the
+server in the screen and click <guilabel>Download</guilabel> again
+and, all being well, the certificate will be fetched. Most cinema
+projection or technical departments will know these serial numbers.
</para>
<para>
problems.
</para>
+<!-- XXX: this is a sudden introduction of CPL as a concept -->
<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
<section>
<title>Creating KDMs using a DKDM</title>
-</section>
<para>
It can be inconvenient to need a whole DCP-o-matic project just to
</para>
<para>
-In other cases a DKDM is sent to a 3rd party so that they can create
+In other cases a DKDM is sent to a third party so that they can create
KDMs for your films. This can be useful if, for example, you have a
distributor who provides 24-hour KDM support to cinemas and can create
KDMs for anybody that requires them at short notice.
<title>The KDM creator</title>
<mediaobject>
<imageobject>
- <imagedata scale="35" fileref="screenshots/kdm-creator&scs;"/>
+ <imagedata scale="30" fileref="screenshots/kdm-creator&scs;"/>
</imageobject>
</mediaobject>
</figure>
<para>
By default the <guilabel>DKDM</guilabel> list will list any DCPs for
which you have clicked <guilabel>Make DKDM for
-DCP-o-matic</guilabel>in the main DCP-o-matic program. If you have
+DCP-o-matic</guilabel> in the main DCP-o-matic program. If you have
other DKDMs you can add them by clicking <guilabel>Add...</guilabel> and
specifying the file containing the DKDM.
</para>
opening <guilabel>Preferences</guilabel> and clicking <guilabel>Export
DCP decryption certificate...</guilabel> in the <guilabel>Keys</guilabel>
tab.
-
</para>
</section>
<section>
-<title>Encryption keys</title>
+<title>Creating KDMs for a distributor</title>
<para>
- You must be careful when using encryption not to lose important keys.
+Sometimes you have an encrypted DCP and you want to allow somebody else
+(for example, a distributor) to make KDMs for the DCP on your behalf.
</para>
<para>
-If you are making KDMs from a DCP-o-matic film you
-<emphasis>must</emphasis> ensure that you have a backup of the
-<code>metadata.xml</code> file from the project, as well as the DCP
-itself.
+The normal way to do this is to send the distributor a KDM which they
+can use with their own KDM creation system. Such a KDM is often called
+a DKDM (the ‘D’ stands for <emphasis>Distribution</emphasis>).
+It is the same as a normal KDM except that it is made to work with another
+computer, rather than with a projection system.
</para>
<para>
-If you are using a DKDM you <emphasis>must</emphasis> ensure that you
+To make a DKDM for a distributor you will first need to ask them to send you
+a decryption certificate. This should be a small file, usually with the extension
+<code>.pem</code>.
+</para>
+
+<para>
+Once you have the certificate, you will need to add a ‘fake’ cinema
+and screen to the list in DCP-o-matic. This is because making a KDM for another
+computer uses the same process internally as making one for a projection system,
+it's just that DCP-o-matic does not have a nice way to present that.
+</para>
+
+<para>
+In either the KDM window in the main DCP-o-matic, or the KDM creator, first add
+a new cinema by clicking <guilabel>Add Cinema...</guilabel>, giving it a name
+(perhaps the name of the distributor).
+</para>
+
+<para>
+Then select this new cinema and click <guilabel>Add Screen...</guilabel> to open
+the screen dialog box, as shown in <xref linkend="fig-add-screen"/>.
+</para>
+
+<figure id="fig-add-screen">
+ <title>Adding a screen</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="30" fileref="screenshots/add-screen&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+Here you can give any name (perhaps just ‘DKDM’). Then click <guilabel>Get from file...</guilabel>
+and choose the certificate file that the distributor gave you. Finally, click <guilabel>OK</guilabel>.
+</para>
+
+<para>
+Now you can create a KDM for this screen, and send it to the distributor. Using that KDM the distributor
+can then make KDMs for your DCP for anybody (and also, of course, decrypt the DCP if they wanted to).
+</para>
+
+</section>
+
+</section>
+
+<section>
+<title>Encryption keys</title>
+
+<para>
+ You should be careful when using encryption not to lose important keys.
+</para>
+
+<para>
+If you are making KDMs from a DCP-o-matic film you
+<emphasis>must</emphasis> ensure that you have a backup of the
+<code>metadata.xml</code> file from the project, as well as the DCP
+itself.
+</para>
+
+<para>
+If you are using a DKDM you <emphasis>must</emphasis> ensure that you
have a backup of DCP-o-matic's <code>config.xml</code> file, since it
contains the only key which can decrypt the DKDM. The
<code>config.xml</code> file location depends on your operating
-system; possible locations are listed in <xref linkend="ch-config"/>
+system; possible locations are listed in <xref linkend="ch-config"/>.
</para>
</section>
+<section>
+ <title>Should I encrypt?</title>
+
+ <para>
+ The question of whether encryption is appropriate for a given
+ project is a tricky one.
+ </para>
+
+ <para>
+ On the one hand, if you distribute an unencrypted DCP it is easy for
+ anybody to take it and do whatever they want with its contents.
+ They could use DCP-o-matic to convert it to a MP4, show it in
+ their cinema, or even edit and redistribute it in ways that you
+ do not like.
+ </para>
+
+ <para>
+ Encryption prevents this, but brings its own problems. It will be
+ impossible for a cinema to screen your DCP unless they have the
+ correct KDM. This is easy enough if things work as they should,
+ but problems can occur. For example, cinemas may substitute
+ broken playout servers with new ones without telling you: then the
+ KDM that you sent them will be invalid, and a new one required.
+ If the cinema can't get in touch with you, or somebody else who
+ can create a new KDM, they can't screen your DCP. Often these
+ problems are only discovered very close to showtime, with little
+ time for fixes.
+ </para>
+
+ <para>
+ If you are distributing encrypted DCPs widely it is worth thinking
+ about who will make the KDMs, and who will provide quick-response
+ technical support. It may be a good idea to engage a company who can
+ provide such services.
+ </para>
+
+</section>
+
+
<section>
<title>Encryption overview</title>
<title>Preferences</title>
<para>
-DCP-o-matic provides a few preferences which can be used to modify its
-behaviour. This chapter explains those options.
+DCP-o-matic provides preferences which can be used to modify its
+behaviour. They are described in this chapter.
</para>
<para>
Preferences can be edited by choosing
<guilabel>Preferences...</guilabel> from the <guilabel>Edit</guilabel>
-menu. This opens a dialogue which is split into seven tabs.
+menu. This opens a dialogue which is split into tabs.
</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.
+users. If your language is not on the last,
visit <ulink
+url="https://dcpomatic.com/i18n.php">the DCP-o-matic website</ulink> to
+find out how to contribute a translation.
</para>
</section>
<para>
This is the location of DCP-o-matic's configuration file on disk. You
can use this to share configuration between several copies of
-DCP-o-matic, across a network share, for instance.
+DCP-o-matic: across a network share, for instance.
</para>
</section>
<para>
The checkbox to the left of <guilabel>Play sound</guilabel> enables or
-disables DCP-o-matic use of sound. On some machines there will be
+disables DCP-o-matic's use of sound. On some machines there will be
multiple options in the drop-down menu to decide how the sound should
be played.
</para>
If <guilabel>Find integrated loudness, true peak and loudness range
when analysing audio</guilabel> is ticked, DCP-o-matic will do extra
work when analysing audio. Leave this ticked if the extra parameters
-are useful to you. If not, untick it and audio analysis will be
-faster.
+are useful to you. If not, untick it to make audio analysis faster.
</para>
</section>
<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
+url="https://dcpomatic.com/">dcpomatic.com</ulink> to see if there are 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>
-<title>Issuer and creator</title>
-
-<para>
-With these controls you can set the issuer and creator strings that
-will be put into the DCPs which you create.
+those that are formally ‘released’.
</para>
</section>
you and asks for your certificate.
</para>
-<para>
-<guilabel>Export KDM decryption chain...</guilabel> exports the whole
-KDM decryption chain rather than just its certificate. This may also
-be requested by KDM creators.
-</para>
-
<para>
<guilabel>Export all KDM decryption settings...</guilabel> exports a
file which contains all the DCP-o-matic settings related to the use of
<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
+certificates and key...</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
+private key by clicking <guilabel>Import...</guilabel>. You must do
this if you change the leaf certificate, so that the leaf private key
corresponds to the public key held in the leaf certificate.
</para>
be used when targeting a KDM at DCP-o-matic.
</para>
-
<para>
-If you want to import an encrypted DCP you will need to give the
-decryption certificate to the distributor of the DCP so that they can
-generate a DKDM for you. You can save this certificate to disk by
-clicking <guilabel>Export DCP decryption certificate...</guilabel>.
-As with the signing chain, DCP-o-matic will create a certificate chain
-and private key for you. You can also choose to load your own
-certificates and key or re-make the chain and key with new, random
-values.
-</para>
-
-<para>
-Clicking <guilabel>Export DCP decryption chain...</guilabel> will
-export the whole certificate chain, rather than just the leaf
-certificate.
+Clicking <guilabel>Export chain...</guilabel> will
+export the whole certificate chain.
</para>
</section>
<para>
<guilabel>Protocol</guilabel> should be set to SCP or FTP as
appropriate for your TMS. We know that the Arts Alliance Media (AAM)
-and the Doremi ranges uses SCP connections, and that Dolby's TMSs use
+and the Doremi ranges uses SCP connections, and that Dolby's TMS uses
FTP. Do let us know if you use any other type of TMS with the
<guilabel>Send DCP to TMS</guilabel> feature.
</para>
</section>
+<!-- ============================================================== -->
+<section>
+<title>Email</title>
+
+<para>
+The Email tab is shown in <xref linkend="fig-prefs-email"/>.
+</para>
+
+<figure id="fig-prefs-email">
+ <title>Email preferences</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/prefs-email&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+These settings are used when DCP-o-matic sends emails.
+</para>
+
+<para>
+ <guilabel>Outgoing mail server</guilabel> should be the host name of a mail (SMTP) server that DCP-o-matic can use. You can also specify the port that DCP-o-matic should use. <guilabel>User name</guilabel> and <guilabel>Password</guilabel> are the credentials that are required to send email through the server you have specified.
+</para>
+
+</section>
+
<!-- ============================================================== -->
<section>
<title>KDM email</title>
<para>
-The KDM email is shown in <xref linkend="fig-prefs-kdm-email"/>.
+The KDM email tab is shown in <xref linkend="fig-prefs-kdm-email"/>.
</para>
<figure id="fig-prefs-kdm-email">
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:
+KDM that is being sent; these strings are shown in <xref linkend="tab-kdm-magic"/>.
</para>
-<table>
+<table id="tab-kdm-magic">
<title>‘Magic’ KDM strings</title>
<tgroup cols='2' align='left' colsep='1' rowsep='1'>
<tbody>
<entry><code>$CPL_NAME</code></entry><entry>DCP title</entry>
</row>
<row>
+<entry><code>$CPL_FILENAME</code></entry><entry>Filename of the CPL</entry>
+</row>
+<row>
<entry><code>$CINEMA_NAME</code></entry><entry>Cinema name</entry>
</row>
<row>
+<entry><code>$CINEMA_SHORT_NAME</code></entry><entry>First 14 characters of the 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>
</section>
+<!-- ============================================================== -->
+<section>
+<title>Notifications</title>
+
+<para>
+The Notifications tab is shown in <xref linkend="fig-prefs-notifications"/>.
+</para>
+
+<figure id="fig-prefs-notifications">
+ <title>Notifications preferences</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/prefs-notifications&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+DCP-o-matic can notify the user when jobs have completed. These
+notifications can be either or both of a message box on-screen (if
+<guilabel>Message box</guilabel> is ticked) and email (if
+<guilabel>Email</guilabel> is ticked). If you enable email
+notifications you can fill in the details of the emails you want to
+send.
+</para>
+
+<para>
+The bottom box in the tab is the content of the email that should
+be sent. DCP-o-matic will replace the ‘magic’ strings
+<code>$JOB_NAME</code> and <code>$JOB_STATUS</code> in the with the
+details of the job that has completed.
+</para>
+
+</section>
+
<!-- ============================================================== -->
<section>
</para>
<table>
-<title>‘Magic’ Cover sheet strings</title>
+<title>‘Magic’ cover sheet strings</title>
<tgroup cols='2' align='left' colsep='1' rowsep='1'>
<tbody>
<row>
</para>
<para>
-The four checkboxes labelled <guilabel>Log</guilabel> control what
+The 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
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.
+play fine, but another (of a different type, or even just with a different software version) will refuse to play.
</para>
<title>Guaranteed rates</title>
<para>
-The only rates that are (pretty much) guaranteed to work on all DCI
-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.
+The only rates that are guaranteed to work on all DCI projectors are
+24 frames per second (fps) for video and 48kHz for audio. If you are
+sending DCPs to unknown places it is wise to consider using these
+rates if at all possible.
</para>
</section>
<title>Other often-supported rates</title>
<para>
Many projectors now in the wild support additional video frame rates:
-25, 30 and 48 fps.
+25, 30, 48, 50 and 60 fps.
</para>
</section>
</para>
<para>
-Video rate conversion is harder. DCP-o-matic's basic strategy to deal
+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>
<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.
+button, DCP-o-matic assumes that the most commonly-working frame rates (24,
+25 and 30fps) are allowed.
</para>
<para>
</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
+You can experiment with other non-standard frame rates
+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
</para>
<para>
-The master and server machines do not need to be the same type, so you
+The master and server machines do not need to be running the same operating system, so you
can mix Windows PCs, Macs and Linux machines as you wish.
</para>
<title>Running the servers</title>
<para>
-There are two options for the encoding server;
+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
+the GUI version works best on Windows and macOS where it will put an icon in the
system tray.
</para>
<para>If you would rather not bother installing DCP-o-matic on your
server computers, the other option is to use the live-CD
image that you can download from the <ulink
-url="http://dcpomatic.com/">DCP-o-matic web site.</ulink></para>
+url="https://dcpomatic.com/">DCP-o-matic web site.</ulink></para>
<para>Either burn the image to CD, or write it to a USB stick (using
something like <ulink
<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. It may also
-contain subtitles in either XML or MXF format. This folder
+contain subtitles or closed captions in either XML or MXF format. This folder
(<code>DCP-TEST_EN-XX_...</code>) is what you should ingest, or pass
to the cinema which is showing your DCP.
</para>
</para>
<para>
- <code>dcpomatic2_create [OPTION] [CONTENT] [<CONTENT> ...]</code>
+ <code>dcpomatic2_create [OPTION] <CONTENT> [[OPTION] <CONTENT> ...]</code>
</para>
<para>
The options are:
</para>
- <itemizedlist>
- <listitem><code>-v</code>, <code>--version</code> — show DCP-o-matic version</listitem>
- <listitem><code>-h</code>, <code>--help</code> — show this help</listitem>
- <listitem><code>-n</code>, <code>--name</code> — <name> film name</listitem>
- <listitem><code>-t, --template <name></code> — template name</listitem>
- <listitem><code>-c, --dcp-content-type <type></code> — FTR, SHR, TLR, TST, XSN, RTG, TSR, POL, PSA or ADV</listitem>
- <listitem><code>--container-ratio <ratio></code> — 119, 133, 137, 138, 166, 178, 185 or 239</listitem>
- <listitem><code>--content-ratio <ratio></code> — 119, 133, 137, 138, 166, 178, 185 or 239</listitem>
- <listitem><code>-s, --still-length <n></code> — number of seconds that still content should last</listitem>
- <listitem><code>--standard <standard></code> — SMPTE or interop (default SMPTE)</listitem>
- <listitem><code>--no-use-isdcf-name></code> — do not use an ISDCF name; use the specified name unmodified</listitem>
- <listitem><code>--no-sign</code>— do not sign the DCP</listitem>
- <listitem><code>-o</code>, <code>--output <dir></code> — output directory</listitem>
- </itemizedlist>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dcpomatic_create.xml"/>
<para>
For example, to setup a film using a MP4 file you might do:
<code>dcpomatic2_cli [OPTION] [FILM]</code>
</para>
- <para>
- <itemizedlist>
- <listitem><code>-v</code>, <code>--version</code> — show DCP-o-matic version</listitem>
- <listitem><code>-h</code>, <code>--help</code> — show this help</listitem>
- <listitem><code>-f</code>, <code>--flags</code> — show flags passed to C++ compiler on build</listitem>
- <listitem><code>-n</code>, <code>--no-progress</code> — do not print progress to stdout</listitem>
- <listitem><code>-r</code>, <code>--no-remote</code> — do not use any remote servers</listitem>
- <listitem><code>-t</code>, <code>--threads</code> — specify number of local encoding threads (overriding configuration)</listitem>
- <listitem><code>-j</code>, <code>--json</code> <port> — run a JSON server on the specified port</listitem>
- <listitem><code>-k</code>, <code>--keep-going</code> — keep running even when the job is complete</listitem>
- <listitem><code>-s</code>, <code>--servers</code> — just display a list of encoding servers that DCP-o-matic is configured to use; don't encode</listitem>
- <listitem><code>-d</code>, <code>--dcp-path</code> — echo DCP's path to stdout on successful completion (implies -n)</listitem>
- <listitem><code>--dump</code> — just dump a summary of the film's settings; don't encode</listitem>
- </itemizedlist>
- </para>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dcpomatic_cli.xml"/>
<para>
For example, to encode a film called <code>my_film</code> you might do:
<code>dcpomatic2_kdm_cli [OPTION] <FILM|CPL-ID></code>
</para>
- <para>
- <itemizedlist>
- <listitem><code>-o</code>, <code>--output</code> — output file or directory</listitem>
- <listitem><code>-f</code>, <code>--valid-from</code> — valid from time (in local time zone of the cinema) (e.g. "2013-09-28 01:41:51") or "now"</listitem>
- <listitem><code>-t</code>, <code>--valid-to</code> — valid to time (in local time zone of the cinema) (e.g. "2014-09-28 01:41:51")</listitem>
- <listitem><code>-d</code>, <code>--valid-duration</code> — valid duration (e.g. "1 day", "4 hours", "2 weeks")</listitem>
- <listitem><code>--formulation</code> — modified-transitional-1, dci-any or dci-specific [default modified-transitional-1]</listitem>
- <listitem><code>-z</code>, <code>--zip</code> — ZIP each cinema's KDMs into its own file</listitem>
- <listitem><code>-v</code>, <code>--verbose</code> — be verbose</listitem>
- <listitem><code>-c</code>, <code>--cinema</code> — specify a cinema, either by name or email address</listitem>
- <listitem><code>--certificate</code> — file containing projector certificate</listitem>
- <listitem><code>--cinemas</code> — list known cinemas from the DCP-o-matic settings</listitem>
- <listitem><code>--dkdm-cpls</code> — list CPLs for which DCP-o-matic has DKDMs</listitem>
- </itemizedlist>
- </para>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dcpomatic_kdm_cli.xml"/>
</section>
</chapter>
<itemizedlist>
<listitem>Start a new DCP-o-matic film.</listitem>
-<listitem>Click <guilabel>Add folder...</guilabel> and specify your existing DCP's folder.</listitem>
+<listitem>Click <guilabel>Add DCP...</guilabel> and specify your existing DCP's folder.</listitem>
<listitem>Go to the <guilabel>DCP</guilabel> tab and choose <guilabel>Split by video content</guilabel> for <guilabel>Reel type</guilabel>.</listitem>
-<listitem>Go to the <guilabel>Video</guilabel> and
-<guilabel>Audio</guilabel> tabs in turn and tick the <guilabel>Use this DCP's audio as OV and make VF</guilabel> checkboxes.</listitem>
+<listitem>Go to the <guilabel>Video</guilabel> tab and tick the <guilabel>Use this DCP's video as OV and make VF</guilabel> checkbox.</listitem>
+<listitem>Go to the <guilabel>Audio</guilabel> tab and tick the <guilabel>Use this DCP's audio as OV and make VF</guilabel> checkbox.</listitem>
<listitem>Add your subtitles to the film in whatever format you have.</listitem>
<listitem>Check the subtitle appearance in the preview; it will be
slow to respond as it is having to decompress images from the existing
<itemizedlist>
<listitem>Start a new DCP-o-matic film.</listitem>
-<listitem>Click <guilabel>Add folder...</guilabel> and specify your existing DCP's folder.</listitem>
+<listitem>Click <guilabel>Add DCP...</guilabel> and specify your existing DCP's folder.</listitem>
<listitem>Add your subtitles to the film in whatever format you have.</listitem>
<listitem>Check the subtitle appearance in the preview; it will be
slow to respond as it is having to decompress images from the existing
DCP. Adjust the appearance using controls in the
-<guilabel>Subtitle</guilabel> tab if required.</listitem>
+<guilabel>Timed Text</guilabel> or <guilabel>Closed Captions</guilabel> tabs if required.</listitem>
<listitem>Choose <guilabel>Make DCP</guilabel> from the menu.</listitem>
</itemizedlist>
<itemizedlist>
<listitem>Start a new DCP-o-matic film.</listitem>
-<listitem>Click <guilabel>Add folder...</guilabel> and specify your existing DCP's folder.</listitem>
+<listitem>Click <guilabel>Add DCP...</guilabel> and specify your existing DCP's folder.</listitem>
<listitem>Add your subtitles to the film in whatever format you have.</listitem>
<listitem>Go to the <guilabel>Subtitle</guilabel> tab and tick the <guilabel>Burn subtitles into image</guilabel> checkbox.</listitem>
<listitem>Check the subtitle appearance in the preview; it will be
slow to respond as it is having to decompress images from the existing
DCP. Adjust the appearance using controls in the
-<guilabel>Subtitle</guilabel> tab if required.</listitem>
+<guilabel>Timed Text</guilabel> or <guilabel>Closed Captions</guilabel> tabs if required.</listitem>
<listitem>Choose <guilabel>Make DCP</guilabel> from the menu.</listitem>
</itemizedlist>
resolution.
</para>
+ <para>Another way to improve performance is to set the <guilabel>Video display mode</guilabel>
+ in <guilabel>Preferences</guilabel> to <guilabel>OpenGL (faster)</guilabel>. This should provide
+ a significant speed-up on most systems, although this mode has not been so widely tested so may
+ have problems.
+ </para>
+
+
+<section>
+<title>Advanced playback mode</title>
+
+<para>
+By default, the DCP-o-matic player is set up to load and play back single DCPs, mostly for checking purposes.
+There is also a second, more experimental mode, which is more suited to using DCP-o-matic for ‘presentation’
+applications, such as playing back DCPs via a projector. In this mode you can set up basic playlists, in a similar
+way to how most commercial playback servers work.
+</para>
+
+<para>
+<emphasis>Using DCP-o-matic for theatrical exhibition is not widely tested, and I would not advise depending
+on it without plenty of testing in your particular environment.</emphasis>
+</para>
+
+<para>
+The ‘advanced’ playback mode uses two windows (instead of the usual one):
+<itemizedlist>
+ <listitem>Full-screen playback window.</listitem>
+ <listitem>Control window.</listitem>
+</itemizedlist>
+The idea is that these windows are spread over two monitors (or one monitor and one projector).
+</para>
+
+<para>
+To enable ‘advanced’ mode, load the player and go to the preferences and open the <guilabel>General</guilabel>
+tab of preferences, then choose <guilabel>full screen with separate advanced controls</guilabel> from the
+<guilabel>Start player as</guilabel> drop-down list. Then close and re-start the player.
+</para>
+</section>
+
+<para>
+On loading the player in ‘advanced’ mode you will see a control window like the one in <xref linkend="fig-advanced-player"/>.
+</para>
+
+<figure id="fig-advanced-player">
+ <title>Player in advanced mode</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="30" fileref="screenshots/advanced-player&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+The important parts are the list of playlists, in the top left, and the current playlist, on the right. Double-click a playlist to load it,
+and then press the <guilabel>Play</guilabel> button to start playback.
+</para>
+
+<para>
+Creating playlists must be done using the separate DCP-o-matic Playlist Editor. As with the other tools, this is included
+with the normal installer on Windows and most Linux distributions, but must be downloaded separately on macOS or if you are using AppImage.
+</para>
+
+<para>
+The first important step after loading the playlist editor for the first time is to set the location of your playlists, the content (i.e. DCPs)
+that they will use, and a folder containing any KDMs that the content needs. This can be done in the Playlist Editor preferences window,
+as shown in <xref linkend="fig-playlist-editor-prefs"/>.
+</para>
+
+<figure id="fig-playlist-editor-prefs">
+ <title>Playlist editor preferences</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/playlist-editor-prefs&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+Once you have done this you can start creating playlists in the main editor window. Each playlist you create will be shown in the player and
+so be available for playback. The playlist editor is shown in <xref linkend="fig-playlist-editor"/>.
+</para>
+
+<figure id="fig-playlist-editor">
+ <title>Playlist editor</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/playlist-editor&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+The top half of the window shows the current list of playlists. Create a new one by clicking the <guilabel>New</guilabel> button. You can
+then edit its name and add remove, or reorder content in the bottom half of the window. Playlists are saved automatically each time they
+are changed.
+</para>
+
+</chapter>
+
+
+<chapter xml:id="ch-verifier" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+ <title>Verifying DCPs</title>
+
+ <para>
+ The DCP-o-matic Player (see <xref linkend="ch-player"/>) also offers a DCP verifier. To check a DCP,
+ open it and then select <guilabel>Verify DCP</guilabel> from the
+ <guilabel>Tools</guilabel> menu.
+ </para>
+
+ <para>
+ The verifier will report three kinds of problems:
+ </para>
+
+ <itemizedlist>
+ <listitem><emphasis>Errors</emphasis> — serious problems with the DCP that are likely to cause problems on playback.</listitem>
+ <listitem><emphasis>Bv2.1 errors</emphasis> — errors described by the <ulink url="https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=9161348">SMPTE Bv2.1 standard</ulink>.</listitem>
+ <listitem><emphasis>Warnings</emphasis> — small problems that may not matter.</listitem>
+ </itemizedlist>
+
+ <para>
+ The following sections list what the verifier checks for in each category.
+ </para>
+
+ <section>
+ <title>Errors</title>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="verify_errors.xml"/>
+ </section>
+
+ <section>
+ <title>Bv2.1 errors</title>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="verify_bv21_errors.xml"/>
+ </section>
+
+ <section>
+ <title>Warnings</title>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="verify_warnings.xml"/>
+ </section>
+
</chapter>
+
+<!-- ============================================================== -->
+<chapter xml:id="ch-writer">
+<title>Writing DCPs to disks</title>
+
+<para>
+Once you have your DCP, you need to get it to the cinema or theater who
+will play it. Sometimes this is possible via the internet, using a
+service such as Filemail. If that's an option: go for it! Network
+transfers avoid a lot of the difficulties that other methods have.
+</para>
+
+<para>
+However, your DCP may be too large to make that practical. In that case,
+the usual approach is to copy the DCP onto a USB hard drive or stick and
+physically take it or send it to the cinema.
+</para>
+
+<section>
+<title>Hard drive formatting</title>
+
+<para>
+In theory, this should be as simple as dragging and dropping the DCP's
+files onto a USB-connected drive. Sadly, though, things are not always
+that simple. This is because not all hard drives are formatted in the
+same way. The most common formats for hard drives are:
+</para>
+
+<itemizedlist>
+<listitem>APFS — used by macOS 10.13 and later for solid state drives (SSDs).</listitem>
+<listitem>HFS+ (Mac OS Extended) — used by macOS on 10.12 and earlier, and on all macOS systems for spinning disks.</listitem>
+<listitem>NTFS — modern format used by Windows.</listitem>
+<listitem>ExFAT — another modern, but less common (and buggier) format used by Windows.</listitem>
+<listitem>FAT32 — old format used by Windows.</listitem>
+<listitem>ext2, ext3, ext4 — often used by Linux.</listitem>
+</itemizedlist>
+
+<para>
+You can format a drive however you want, but a drive set up on macOS will usually use APFS, just as one set up on Windows will probably use NTFS or ExFAT.
+</para>
+
+<para>
+The problem you have as a DCP maker is: the only format that is
+guaranteed to work in all cinemas is ext2. This format is not easy to
+use directly from Windows or macOS: both operating systems need extra
+software to write ext2 drives.
+</para>
+
+<para>
+The “DCP-o-matic Disk Writer” provides a possible
+solution to this problem. It allows you to format and copy DCPs onto ext2-formatted disks from Windows, macOS or Linux.
+</para>
+
+</section>
+
+
+<section>
+<title>Caution</title>
+
+<para>
+DCP-o-matic is made by one developer in his spare time. As a project,
+we do not have any quality assurance department, testing team or
+anything like that. Though we try our best to ensure quality using
+automated testing, and by the great efforts of our users to find and report problems,
+bugs do get into the code and things do go wrong.
+</para>
+
+<para>
+Though very undesirable, bugs in most parts of DCP-o-matic are usually
+not disastrous; they most often result in an error message, or some
+problem with a DCP. The Disk Writer tool, however, is a bit different. It obtains
+permission from your operating system to write directly to disks connected to the
+computer. Though we have done as much as we can to prevent problems, there is a chance
+that a bug in the Disk Writer could cause irretrievable data loss (for example, if
+the writer wrote to the wrong drive by mistake).
+</para>
+
+<para>
+No such problems have been reported, nor found by us during testing, but I would
+like to warn you that they are possible. As always, make sure that you have backups
+(somewhere that is not directly connected to your computer) of anything that you do not want
+to lose.
+</para>
+
+</section>
+
+
+<section>
+<title>Writing a DCP to a disk</title>
+
+<para>
+Starting up the Disk Writer will give open a confirmation window to make sure that you understand the risks involved, as shown in <xref linkend="fig-disk-writer-notice"/>.
+</para>
+
+<figure id="fig-disk-writer-notice">
+ <title>Starting the Disk Writer</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/disk-writer-notice&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+If you are sure you want to continue, type <code>I am sure</code> into the text box and click <guilabel>OK</guilabel>. This will open the window shown in <xref linkend="fig-disk-writer"/>.
+</para>
+
+<figure id="fig-disk-writer">
+ <title>The Disk Writer</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/disk-writer&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>Next, click <guilabel>Open...</guilabel> and choose the DCP that you want to write.</para>
+
+<para>
+Now we need to choose the drive that the DCP will be written to from the drop-down menu.
+<emphasis>Whichever drive you choose will be irretrievably wiped!</emphasis>
+If the drive you want is not listed, click <guilabel>Refresh</guilabel> to search the system for drives.
+</para>
+
+<para>
+Finally, click <guilabel>Copy DCP</guilabel>. After a confirmation window, the drive will be formatted,
+and the DCP copied and then read back to check that it was written correctly.
+</para>
+
+</section>
+
+</chapter>
+
+
+<!-- ============================================================== -->
+<chapter>
+<title>Keyboard shortcuts</title>
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="shortcuts.xml"/>
+</chapter>
+
+
<!-- ============================================================== -->
<chapter xml:id="ch-config" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<title>Configuration files</title>
</chapter>
</book>
+
+<!-- LocalWords: dbcent DCP matic Hetherington DCPs KDMs GPL XP sid
+-->
+<!-- LocalWords: matic's jessie Tahr Xenial Xerus Centos Mageia GTK
+-->
+<!-- LocalWords: Karner FFmpeg libsndfile libsamplerate OpenSSL waf
+-->
+<!-- LocalWords: libopenjpeg libssh wxWidgets libxml xmlsec libzip
+-->
+<!-- LocalWords: asdcplib libdcp libsub libcxml sstream sudo Sintel
+-->
+<!-- LocalWords: dcpomatic TMS SCP timecode DCP's unencrypted OV Gb
+-->
+<!-- LocalWords: Decrypting KDM decrypt decrypted MOV VOB WAV AIFF
+-->
+<!-- LocalWords: PNG srt ssa xml wav Lfe XYZ colourspace sRGB RGB
+-->
+<!-- LocalWords: colourspaces pdf fader CP Doremi CaptiView SubRip
+-->
+<!-- LocalWords: SubStation BluRay
+-->
projects / dcpomatic.git / blobdiff