<!-- ============================================================== -->
<section>
-<title>Debian, Ubuntu or Mint Linux</title>
+<title>Debian, Ubuntu and Mint Linux</title>
-<para>
- You can install DCP-o-matic on:
-</para>
-
-<itemizedlist>
- <listitem>Debian 9 (‘squeeze’), 10 (‘buster’) and unstable (‘sid’)</listitem>
- <listitem>Ubuntu 16.04, 18.04, 20.04 and 20.10</listitem>
- <listitem>Mint 18 and 19</listitem>
-</itemizedlist>
-
-<para>
-using <code>.deb</code> packages: download the appropriate package
-from <ulink url="https://dcpomatic.com/">https://dcpomatic.com/</ulink>
-and double-click it. Debian, Ubuntu or Mint 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 31, 32 and 33, Centos 7 and 8 and Mageia 7 on
+ <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.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="https://dcpomatic.com/">https://dcpomatic.com/</ulink>,
-unpack it and run the following commands from inside the source
-directory:
-</para>
-
-<programlisting>
-./waf configure --disable-tests
-./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>
-
-<para>
-in a shell.
+ <title>
+ Building from source
+ </title>
+ <para>
+ 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/development">
+ https://dcpomatic.com/
+ </ulink>
</para>
</section>
-
</chapter>
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>
<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 existing folder <code>DCP</code> into which it
will write its working files.
</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>
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 will be slow as
+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>
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>
</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 may be smaller and of lower resolution than a projected image!
-</para>
-</section>
-
-
-
<!-- ============================================================== -->
<section>
<title>Colour conversion</title>
</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>
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 an attacker called Mallory being able to
watch it himself.
</para>
</chapter>
<chapter xml:id="ch-player" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
- <title>Playing and verifying DCPs</title>
+ <title>Playing DCPs</title>
<para>DCP-o-matic includes a DCP player, and although it requires a
very high-speed CPU to play DCPs in full resolution, it can also
resolution.
</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 player also offers a simple DCP validator. To check a DCP,
+ The player also offers a DCP validator. To check a DCP,
open it and then select <guilabel>Verify DCP</guilabel> from the
- <guilabel>Tools</guilabel> menu. This will run some basic checks to see if the DCP meets the required standards.
+ <guilabel>Tools</guilabel> menu. This will run various checks on the DCP.
+ </para>
+
+ <para>
+ The validator will report three kinds of problems:
</para>
+ <itemizedlist>
+ <listitem>Errors — serious problems with the DCP that are likely to cause problems on playback.</listitem>
+ <listitem>Bv2.1 errors — errors described by the <ulink url="https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=9161348">SMPTE Bv2.1 standard</ulink>.</listitem>
+ <listitem>Warnings — small problems that may not matter.</listitem>
+ </itemizedlist>
+
+ <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>
+<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>