Merge branch 'master' of ssh://git.carlh.net/home/carl/git/dcpomatic
[dcpomatic.git] / doc / manual / dcpomatic.xml
index a790d10cf13f36c633ad51ab97e85891c1aa86ac..18b2eafa3776d9f388baa6b183ce5b6d270c8c02 100644 (file)
@@ -26,13 +26,16 @@ Hello, and welcome to DCP-o-matic!
 <section>
 <title>What is DCP-o-matic?</title>
 
-<para>
-DCP-o-matic is a program to generate <ulink
-url="http://en.wikipedia.org/wiki/Digital_Cinema_Package">Digital
-Cinema Packages</ulink> (DCPs) from almost any video, audio and/or
-subtitle source files.  The resulting DCPs will play on modern digital
-cinema projectors.
-</para>
+<para>DCP-o-matic is a set of programs to perform the following tasks:</para>
+
+<itemizedlist>
+  <listitem>Creation 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>
+</itemizedlist>
 
 </section>
 
@@ -116,24 +119,22 @@ Windows version.
 
 <para>
 DCP-o-matic will run on Mac OS X version 10.6 (Snow Leopard) and
-higher.  To install it, download the <code>.dmg</code> from <ulink
-url="http://dcpomatic.com/">http://dcpomatic.com/</ulink> and double
-click to open it.  Then drag the DCP-o-matics icon to your
-<guilabel>Applications</guilabel> folder or wherever else you would
-like to install it.
+higher.  DCP-o-matic is split into four 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>
-You do not have to install all the applications, but you must always
-install <code>DCP-o-matic 2.app</code> as the other applications
-depend on it.
+If you are not sure which parts of DCP-o-matic to install, start
+with the first (main) part.
 </para>
 
 </section>
 
 <!-- ============================================================== -->
 <section>
-<title>Debian or Ubuntu Linux</title>
+<title>Debian, Ubuntu or Mint Linux</title>
 
 <para>
   You can install DCP-o-matic on:
@@ -143,9 +144,11 @@ depend on it.
   <listitem>Debian 7 (&lsquo;wheezy&rsquo;)</listitem>
   <listitem>Debian 8 (&lsquo;jessie&rsquo;)</listitem>
   <listitem>Debian unstable (&lsquo;sid&rsquo;)</listitem>
-  <listitem>Ubuntu 12.04 (&lsquo;Precise Pangolin&rsquo;)</listitem>
   <listitem>Ubuntu 14.04 (&lsquo;Trusty Tahr&rsquo;)</listitem>
   <listitem>Ubuntu 16.04 (&lsquo;Xenial Xerus&rsquo;)</listitem>
+  <listitem>Ubuntu 17.10 (&lsquo;Artful Aardvark&rsquo;)</listitem>
+  <listitem>Mint 17</listitem>
+  <listitem>Mint 18</listitem>
 </itemizedlist>
 
 <para>
@@ -160,25 +163,14 @@ pieces and set DCP-o-matic up for you.
 
 <!-- ============================================================== -->
 <section>
-  <title>Fedora Linux</title>
-
-  <para>There are <code>.rpm</code> packages for Fedora 22 and 23 on
-  <ulink url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>
-  </para>
-</section>
-<!-- ============================================================== -->
-
+  <title>Fedora, Centos and Mageia Linux</title>
 
-<!-- ============================================================== -->
-<section>
-  <title>Centos Linux</title>
-  <para>There are <code>.rpm</code> packages for Centos 5, 6.5 and 7 on
+  <para>There are <code>.rpm</code> packages for Fedora 25, 26 and 27, Centos 6 and 7 and Mageia 6 on
   <ulink url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>
   </para>
 </section>
 <!-- ============================================================== -->
 
-
 <!-- ============================================================== -->
 <section>
 <title>Arch Linux</title>
@@ -272,7 +264,7 @@ DCP-o-matic.  We will gloss over the details and look at the basics.
 Let's make a very simple DCP to see how DCP-o-matic works.  First, we
 need some content.  Download the low-resolution trailer for the open
 movie <ulink url="http://sintel.org/">Sintel</ulink> from <ulink
-url="http://ftp.nluug.nl/ftp/graphics/blender/apricot/trailer/Sintel_Trailer1.480p.DivX_Plus_HD.mkv">their
+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.
@@ -378,15 +370,7 @@ the right of the window, as shown in <xref linkend="fig-examine-content"/>.
 
 <para>
 Dragging the slider will move through your video.  You can also click
-the <guilabel>Play</guilabel> button to play the content back.  <emphasis>Note
-that there will be no sound</emphasis>, and playback might not be entirely
-accurate (it may be slightly slower or faster than it should be, for
-example).  This player is really only intended for brief inspection of
-content; if you need to check it more thoroughly, use another player
-such as <ulink
-url="http://projects.gnome.org/totem/index.html">Totem</ulink>, <ulink
-url="http://www.mplayerhq.hu/design7/news.html">mplayer</ulink> or
-<ulink url="http://www.videolan.org/vlc/index.html">VLC</ulink>.
+the <guilabel>Play</guilabel> button to play the content back.
 </para>
 
 </section>
@@ -529,7 +513,7 @@ to take existing DCPs and modify them in various ways.
 
 <para>
 If you want to do something to an existing DCP the first step is to
-import it.  Click <guilabel>Add folder...</guilabel> and select your
+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
@@ -537,12 +521,12 @@ computationally intensive as encoding them.
 </para>
 
 <para>
-If your DCP is a Version File (VF), in other words it refers to
-another DCP's assets, you should import it as follows:
+If your DCP is a Version File (VF) (i.e.\ it refers to
+another DCP's assets) you should import it as follows:
 </para>
 
 <itemizedlist>
-<listitem>Use <guilabel>Add folder...</guilabel> to import the VF DCP.
+<listitem>Use <guilabel>Add DCP...</guilabel> to import the VF DCP.
 The VF DCP will be added to the content list and marked &ldquo;NEEDS
 OV&rdquo;.</listitem>
 <listitem>Right-click on the VF DCP in the content list and choose <guilabel>Add OV...</guilabel> from the menu.</listitem>
@@ -580,8 +564,8 @@ and they can create a KDM to allow DCP-o-matic to decrypt their DCP.
 
 <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 (all
-being well) the DCP will be decrypted and become available for preview.
+choose <guilabel>Add KDM...</guilabel>.  Specify your KDM and the DCP
+will be decrypted and become available for preview.
 </para>
 
 </section>
@@ -680,9 +664,9 @@ To make a DCP like this:
 <listitem>Import your &lsquo;Content DCP&rsquo; to a DCP-o-matic project.</listitem>
 <listitem>Add whatever replacement you want in your new DCP (replacement subtitles or audio files, for example).</listitem>
 <listitem>Select the DCP in the content list</listitem>
-<listitem>Tick the <guilabel>Refer to existing DCP</guilabel> checkbox
+<listitem>Tick the <guilabel>Use's this DCP's ... as OV and make VF</guilabel> checkbox
 in the tabs for the parts of the DCP that you want to refer to in your
-new DCP.  For example, to refer to the Content DCP's video and audio you would select the <guilabel>Video</guilabel> tab, click <guilabel>Refer to existing DCP</guilabel> then select the <guilabel>Audio</guilabel> tab and do the same.</listitem>
+new DCP.  For example, to refer to the Content DCP's video and audio you would select the <guilabel>Video</guilabel> tab, click <guilabel>Use this DCP's video as OV and make VF</guilabel> then select the <guilabel>Audio</guilabel> tab and click <guilabel>Use this DCP's audio as OV and make VF</guilabel>.</listitem>
 <listitem>Do <guilabel>Make DCP</guilabel> as usual and your VF DCP will be created.</listitem>
 </itemizedlist>
 
@@ -747,11 +731,15 @@ To add one or more movie, sound, still-image or subtitle files, select
 </para>
 
 <para>
-To add a directory (folder) of images or a DCP, choose <guilabel>Add
-folder...</guilabel> and choose the directory from the selector.  If
-you select a folder of images DCP-o-matic will open a small dialogue
-box where you can enter the frame rate that the image sequence should
-be run at.
+To add a directory (folder) of images, choose <guilabel>Add
+folder...</guilabel> and choose the directory from the selector.
+DCP-o-matic will open a small dialogue box where you can enter the
+frame rate that the image sequence should be run at.
+</para>
+
+<para>
+To add a DCP, choose <guilabel>Add DCP...</guilabel> and choose the
+DCP's directory from the selector.
 </para>
 
 <para>
@@ -835,12 +823,12 @@ The <guilabel>Video</guilabel> tab controls properties of the image, as shown in
 
 <!-- ============================================================== -->
 <section>
-<title>Refer to existing DCP</title>
+<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
-DCP.  It allows you to get the video content from the existing DCP by
-referencing it (rather than copying).  See <xref
+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"/>.
 </para>
 
@@ -1176,10 +1164,11 @@ shows the mapping of a 5.1 source into a 5.1 DCP.
   <title>Other controls</title>
 
 <para>
-The <guilabel>Refer to existing DCP</guilabel> checkbox isonly
-applicable if the selected content is an existing DCP.  It allows you
-to get the audio content from the existing DCP by referencing it
-(rather than copying).  See <xref linkend="sec-overlay"/>.
+The <guilabel>Use this DCP's audio as OV and make VF</guilabel>
+checkbox is only applicable if the selected content is an existing
+DCP.  It allows you to make a VF DCP, using the audio content from the
+existing DCP by referencing it (rather than copying).  See <xref
+linkend="sec-overlay"/>.
 </para>
 
 <para>
@@ -1264,7 +1253,7 @@ DCP-o-matic can either:
 <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 DCP XML files.  You may find the great
+  Alpha (<code>.ssa</code> or <code>.ass</code>) or DCP XML files.  You may find the great
   free program <ulink
   url="http://www.nikse.dk/subtitleedit/">Subtitle Edit</ulink> useful
   for creating such files.</listitem>
@@ -1577,8 +1566,27 @@ linkend="fig-pipeline3"/>.
 
 </section>
 
+
+<section>
+  <title>Copy and paste settings</title>
+
+<para>
+Once you have set up a piece of content it is possible to copy the
+settings you have applied to another piece of content.  To do this,
+select the content to copy from and choose <guilabel>Copy</guilabel>
+from the <guilabel>Edit</guilabel> menu.  Then select the content to
+copy to and choose <guilabel>Paste</guilabel>.  A dialogue box will
+open to allow you to choose which settings you want to copy.  Clicking
+<guilabel>OK</guilabel> will apply the copied settings.
+</para>
+
+</section>
+
+
 </chapter>
 
+
+<!-- ============================================================== -->
 <chapter xml:id="ch-dcp" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
 <title>DCP settings</title>
 
@@ -1928,6 +1936,40 @@ when you add some content it will take on the settings of the
 first similarly-typed piece of content in your template.
 </para>
 
+<para>
+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.
+</para>
+
+<para>
+The following settings from the <guilabel>DCP</guilabel> tab are saved
+in templates:
+</para>
+
+<itemizedlist>
+  <listitem>&ldquo;Use ISDCF name&rdquo; checkbox</listitem>
+  <listitem>Content type (FTR, TLR etc.)</listitem>
+  <listitem>Container</listitem>
+  <listitem>Resolution</listitem>
+  <listitem>JPEG200 bandwidth</listitem>
+  <listitem>Video frame rate</listitem>
+  <listitem>Signed and encrypted checkboxes</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
+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.
+</para>
+
 </chapter>
 
 
@@ -2253,6 +2295,30 @@ tab.
 
 </section>
 
+<section>
+<title>Encryption keys</title>
+
+<para>
+  You must 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"/>
+</para>
+
+</section>
+
 <section>
 <title>Encryption overview</title>
 
@@ -2810,6 +2876,7 @@ purposes.
 </chapter>
 
 
+<!-- ============================================================== -->
 <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en" xml:id="ch-servers">
 <title>Encoding servers</title>
 
@@ -2975,6 +3042,160 @@ to the cinema which is showing your DCP.
 
 </chapter>
 
+
+<chapter>
+  <title>Command-line tools</title>
+
+  <para>
+    DCP-o-matic includes some tools which allow DCP creation from the
+    command line or from scripting languages.  This chapter covers the
+    use of those tools.
+  </para>
+
+  <para>
+    There are three command-line tools in DCP-o-matic.
+    <code>dcpomatic2_create</code> creates film directories, with the
+    associated metadata, from a list of content files.  Then
+    <code>dcpomatic2_cli</code> runs the transcode process on these
+    film directories.  Finally, <code>dcpomatic2_kdm_cli</code> can be
+    used to create KDMs.
+  </para>
+
+  <para>
+    Some applications will benefit from setting up the films using the
+    main DCP-o-matic GUI and then using <code>dcpomatic2_cli</code> to
+    do the encode.  This allows, for example, setup on a relatively
+    low-powered machine before running the encode on a higher-powered
+    headless server.
+  </para>
+
+  <section>
+    <title><code>dcpomatic2_create</code></title>
+
+    <para>
+      The syntax for <code>dcpomatic2_create</code> is:
+    </para>
+
+    <para>
+      <code>dcpomatic2_create [OPTION] [CONTENT] [&lt;CONTENT&gt; ...]</code>
+    </para>
+
+    <para>
+      <code>[CONTENT]</code> are the files or folders that you want to use in the
+      DCP. They can be:
+      <itemizedlist>
+       <listitem>&lsquo;Movie&rsquo; files in almost any common format (e.g. MP4, MOV, MKV, etc.)</listitem>
+       <listitem>A folder containing and image sequence in almost any common format (e.g. TIFF, DPX etc.)</listitem>
+       <listitem>Sound files (e.g. WAV, MP3, AIFF)</listitem>
+       <listitem>Subtitles files (e.g. <code>.srt</code>, DCP XML, <code>.ssa</code> etc.)</listitem>
+      </itemizedlist>
+    </para>
+
+    <para>
+      The options are:
+    </para>
+
+    <itemizedlist>
+      <listitem><code>-v</code>, <code>--version</code> &#8212; show DCP-o-matic version</listitem>
+      <listitem><code>-h</code>, <code>--help</code> &#8212; show this help</listitem>
+      <listitem><code>-n</code>, <code>--name</code> &#8212; &lt;name&gt; film name</listitem>
+      <listitem><code>-t, --template &lt;name&gt;</code> &#8212; template name</listitem>
+      <listitem><code>-c, --dcp-content-type &lt;type&gt;</code> &#8212; FTR, SHR, TLR, TST, XSN, RTG, TSR, POL, PSA or ADV</listitem>
+      <listitem><code>--container-ratio &lt;ratio&gt;</code> &#8212; 119, 133, 137, 138, 166, 178, 185 or 239</listitem>
+      <listitem><code>--content-ratio &lt;ratio&gt;</code> &#8212; 119, 133, 137, 138, 166, 178, 185 or 239</listitem>
+      <listitem><code>-s, --still-length &lt;n&gt;</code> &#8212; number of seconds that still content should last</listitem>
+      <listitem><code>--standard &lt;standard&gt;</code> &#8212; SMPTE or interop (default SMPTE)</listitem>
+      <listitem><code>--no-use-isdcf-name&gt;</code> &#8212; do not use an ISDCF name; use the specified name unmodified</listitem>
+      <listitem><code>--no-sign</code>&#8212; do not sign the DCP</listitem>
+      <listitem><code>-o</code>, <code>--output &lt;dir&gt;</code> &#8212; output directory</listitem>
+    </itemizedlist>
+
+    <para>
+      For example, to setup a film using a MP4 file you might do:
+    </para>
+
+    <para>
+      <code>dcpomatic2_create -o my_film --container-ratio 185 --content-ratio 185 -c FTR -n "My Film" Stuff.mp4</code>
+    </para>
+
+    <para>
+      This will create a folder called <code>my_film</code> which is ready for a DCP to be made by <code>dcpomatic2_cli</code>.
+    </para>
+
+    <para>
+      <code>dcpomatic2_create</code> will use any default settings that you have configured in the main DCP-o-matic preferences.
+    </para>
+  </section>
+
+  <section>
+    <title><code>dcpomatic2_cli</code></title>
+
+    <para>
+      The syntax for <code>dcpomatic2_cli</code> is:
+    </para>
+
+    <para>
+      <code>dcpomatic2_cli [OPTION] [FILM]</code>
+    </para>
+
+    <para>
+      <itemizedlist>
+       <listitem><code>-v</code>, <code>--version</code> &#8212; show DCP-o-matic version</listitem>
+       <listitem><code>-h</code>, <code>--help</code> &#8212; show this help</listitem>
+       <listitem><code>-f</code>, <code>--flags</code> &#8212; show flags passed to C++ compiler on build</listitem>
+       <listitem><code>-n</code>, <code>--no-progress</code> &#8212; do not print progress to stdout</listitem>
+       <listitem><code>-r</code>, <code>--no-remote</code> &#8212; do not use any remote servers</listitem>
+       <listitem><code>-t</code>, <code>--threads</code> &#8212; specify number of local encoding threads (overriding configuration)</listitem>
+       <listitem><code>-j</code>, <code>--json</code> &lt;port&gt; &#8212; run a JSON server on the specified port</listitem>
+       <listitem><code>-k</code>, <code>--keep-going</code> &#8212; keep running even when the job is complete</listitem>
+       <listitem><code>-s</code>, <code>--servers</code> &#8212; 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> &#8212; echo DCP's path to stdout on successful completion (implies -n)</listitem>
+       <listitem><code>--dump</code> &#8212; just dump a summary of the film's settings; don't encode</listitem>
+      </itemizedlist>
+    </para>
+
+    <para>
+      For example, to encode a film called <code>my_film</code> you might do:
+    </para>
+
+    <para>
+      <code>dcpomatic2_cli my_film</code>
+    </para>
+  </section>
+
+  <section>
+    <title><code>dcpomatic2_kdm_cli</code></title>
+
+    <para>
+      The syntax for <code>dcpomatic2_kdm_cli</code> is:
+    </para>
+
+    <para>
+      <code>dcpomatic2_kdm_cli [OPTION] &lt;FILM|CPL-ID&gt;</code>
+    </para>
+
+    <para>
+      <itemizedlist>
+       <listitem><code>-o</code>, <code>--output</code> &#8212; output file or directory</listitem>
+       <listitem><code>-f</code>, <code>--valid-from</code> &#8212; 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> &#8212; 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> &#8212; valid duration (e.g. "1 day", "4 hours", "2 weeks")</listitem>
+       <listitem><code>--formulation</code> &#8212; modified-transitional-1, dci-any or dci-specific [default modified-transitional-1]</listitem>
+       <listitem><code>-z</code>, <code>--zip</code> &#8212; ZIP each cinema's KDMs into its own file</listitem>
+       <listitem><code>-v</code>, <code>--verbose</code> &#8212; be verbose</listitem>
+       <listitem><code>-c</code>, <code>--cinema</code> &#8212; specify a cinema, either by name or email address</listitem>
+       <listitem><code>--certificate</code> &#8212; file containing projector certificate</listitem>
+       <listitem><code>--cinemas</code> &#8212; list known cinemas from the DCP-o-matic settings</listitem>
+       <listitem><code>--dkdm-cpls</code> &#8212; list CPLs for which DCP-o-matic has DKDMs</listitem>
+      </itemizedlist>
+    </para>
+
+  </section>
+</chapter>
+
+
+
+<!-- ============================================================== -->
 <chapter>
 <title>Loose ends</title>
 
@@ -3009,6 +3230,7 @@ hashes.
 
 </chapter>
 
+<!-- ============================================================== -->
 <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
 <title>Common tasks</title>
 
@@ -3061,8 +3283,6 @@ especially if you are using unusual subtitle positioning or character
 sets.
 </para>
 
-</section>
-
 <section>
 <title>Making a VF DCP</title>
 
@@ -3071,7 +3291,7 @@ sets.
 <listitem>Click <guilabel>Add folder...</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>Refer to existing DCP</guilabel> checkboxes.</listitem>
+<guilabel>Audio</guilabel> tabs in turn and tick the <guilabel>Use this DCP's audio as OV and make VF</guilabel> checkboxes.</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
@@ -3113,6 +3333,96 @@ DCP.  Adjust the appearance using controls in the
 </itemizedlist>
 
 </section>
+</section>
+
+<section>
+<title>Adding soundtracks or subtitles in different languages</title>
+
+<para>
+If you have a film that is to be dubbed or subtitled in several
+languages, the best approach with DCP-o-matic is as follows:
+</para>
+
+<itemizedlist>
+<listitem>Make a DCP with the common elements (perhaps just the video, or maybe the video and sound); this is known as the Original Version (OV).</listitem>
+<listitem>For each language, make a new Version File (VF) DCP which refers to the OV.</listitem>
+</itemizedlist>
+
+<para>
+Once you have done this, you send the OV DCP to every cinema and then
+the appropriate VF to each cinema depending on what language they want
+to play the film in.  The projectionist ingests both DCPs and then plays the VF.
+</para>
+
+<para>
+The advantage of this approach is that the VF DCPs are much smaller
+than the OV since they only have the language-specific parts.  If you
+are just changing the subtitles you can often ship the OV by normal
+transport means (e.g. a hard drive or high-speed download) and send
+the VF by email.
+</para>
+
+<para>
+The full details of OV and VF files are discussed in <xref linkend="sec-overlay"/>.  The steps can be summarised as follows:
+</para>
+
+<itemizedlist>
+<listitem>Create a new DCP-o-matic project for the OV, as normal, adding video and perhaps sound.  Make the DCP.</listitem>
+<listitem>Create a new DCP-o-matic project for the VF.</listitem>
+<listitem>Use <guilabel>Add folder...</guilabel> to add your OV DCP to the project.</listitem>
+<listitem>Select the video tab and tick <guilabel>Use this DCP's video as OV and make VF</guilabel> (you may need to select <guilabel>By video content</guilabel> for <guilabel>Reel type</guilabel> in the <guilabel>DCP</guilabel> tab).</listitem>
+<listitem>Do the same in the <guilabel>Audio</guilabel> tab if your OV has audio.</listitem>
+<listitem>Add your language-specific audio and/or subtitles and Make DCP.</listitem>
+</itemizedlist>
+
+</section>
+
+</chapter>
+
+<chapter xml:id="ch-player" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+  <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
+  play DCPs at reduced resolutions with slower CPUs.</para>
+
+  <para>To use the player, start <guilabel>DCP-o-matic
+  Player</guilabel>, and load a DCP using the
+  <guilabel>Open</guilabel> option on the <guilabel>File</guilabel>
+  menu.</para>
+
+  <para>If you load a VF and/or encrypted DCP you can add your OV
+  and/or KDM using the appropriate options on the
+  <guilabel>File</guilabel> menu.</para>
+
+  <para>During playback the <guilabel>Performance</guilabel> area at
+  the bottom right of the window will give details of how many frames
+  are being dropped; these are frames that were not decoded from the
+  DCP quickly enough.  If this number is high you can increase
+  performance at the cost of rendering quality by choosing an option
+  from the <guilabel>View</guilabel> menu.  If you set the player to
+  decode at less than full resolution the DCP's data will be decoded
+  at this lower resolution, which is quicker than decoding at full
+  resolution.
+  </para>
+
+</chapter>
+
+<!-- ============================================================== -->
+<chapter xml:id="ch-config" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<title>Configuration files</title>
+
+<para>Most of DCP-o-matic's configuration is stored in an XML file called <code>config.xml</code>.  This is stored in different places depending on your operating system:</para>
+
+<itemizedlist>
+  <listitem>Windows: <code>c:\Users\your_user_name\AppData\Local\dcpomatic</code></listitem>
+  <listitem>OS X: <code>/Users/your_user_Name/Library/Preferences/com.dcpomatic/2</code></listitem>
+  <listitem>Linux: <code>~/.config/dcpomatic2</code></listitem>
+</itemizedlist>
+
+<para>Possible XML tags are as follows:</para>
+
+<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="config.xml"/>
 
 </chapter>