Manual updates.

[dcpomatic.git] / doc / manual / dcpomatic.xml

diff --git a/doc/manual/dcpomatic.xml b/doc/manual/dcpomatic.xml
index 1a71bb6d1680050a852ace7811f48c9306d4680a..1bd1516b077fd42458885d497c492d16ef610dac 100644 (file)
--- a/doc/manual/dcpomatic.xml
+++ b/doc/manual/dcpomatic.xml
@@ -58,6 +58,20 @@ GPL</ulink>.
 This manual uses icons from the <ulink url="http://tango.freedesktop.org/">Tango Desktop Project</ulink>, with thanks.
 </para>
 
 This manual uses icons from the <ulink url="http://tango.freedesktop.org/">Tango Desktop Project</ulink>, with thanks.
 </para>
 

+</section>
+
+<!-- ============================================================== -->
+<section>
+<title>This manual</title>
+
+<para>
+This manual presents bits of DCP-o-matic's user interface (such as menu items or buttons) <guilabel>like this</guilabel>.
+</para>
+
+<note>
+Notes of an advanced nature are presented like this.  Ignore them unless you want to know the gory details.
+</note>
+

 </section>
 </chapter>
 
 </section>
 </chapter>
 


@@ -87,6 +101,12 @@ many parallel encoding threads (more than 4) on the 32-bit
 version.
 </para>
 
 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 &lsquo;normal&rsquo;
+Windows version.
+</para>
+

 </section>
 
 
 </section>
 
 


@@ -125,7 +145,7 @@ depend on it.
   <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>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 15.10 (&lsquo;Wily Werewolf&rsquo;)</listitem>
+  <listitem>Ubuntu 16.04 (&lsquo;Xenial Xerus&rsquo;)</listitem>

 </itemizedlist>
 
 <para>
 </itemizedlist>
 
 <para>


@@ -152,7 +172,7 @@ pieces and set DCP-o-matic up for you.
 <!-- ============================================================== -->
 <section>
   <title>Centos Linux</title>
 <!-- ============================================================== -->
 <section>
   <title>Centos Linux</title>

-  <para>There are <code>.rpm</code> packages for Centos 6.5 and 7 on
+  <para>There are <code>.rpm</code> packages for Centos 5, 6.5 and 7 on

   <ulink url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>
   </para>
 </section>
   <ulink url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>
   </para>
 </section>


@@ -516,6 +536,19 @@ playback will be very slow as decoding of DCPs is almost as
 computationally intensive as encoding them.
 </para>
 
 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:
+</para>
+
+<itemizedlist>
+<listitem>Use <guilabel>Add folder...</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>
+<listitem>Choose the folder that contains the OV DCP.  The VF will now be playable as normal.</listitem>
+</itemizedlist>
+

 </section>
 
 
 </section>
 
 


@@ -595,7 +628,7 @@ DCP-o-matic will decode and then re-encode the JPEG2000 data.
 </section>
 
 
 </section>
 
 

-<section>
+<section xml:id="sec-overlay">

 <title>Making overlay files</title>
 
 <para>
 <title>Making overlay files</title>
 
 <para>


@@ -702,7 +735,7 @@ images which should be treated as the frames of a video.
 
 <listitem>Subtitle &mdash; a file containing subtitle which will be
 superimposed on the image of the DCP.  These can be
 
 <listitem>Subtitle &mdash; a file containing subtitle which will be
 superimposed on the image of the DCP.  These can be

-<guilabel>.srt</guilabel>, <guilabel>.ssa</guilabel> or <guilabel>.xml</guilabel>
+<guilabel>.srt</guilabel>, <guilabel>.ssa</guilabel>, <guilabel>.ass</guilabel> or <guilabel>.xml</guilabel>

 files.</listitem>
 
 <listitem>DCP &mdash; an existing DCP.</listitem>
 files.</listitem>
 
 <listitem>DCP &mdash; an existing DCP.</listitem>


@@ -800,12 +833,25 @@ The <guilabel>Video</guilabel> tab controls properties of the image, as shown in
 </figure>
 
 
 </figure>
 
 

+<!-- ============================================================== -->
+<section>
+<title>Refer to existing DCP</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
+linkend="sec-overlay"/>.
+</para>
+
+</section>
+

 <!-- ============================================================== -->
 <section>
 <title>Image type</title>
 
 <para>
 <!-- ============================================================== -->
 <section>
 <title>Image type</title>
 
 <para>

-The first option on this tab is the &lsquo;type&rsquo; of the video.
+The next option on this tab is the &lsquo;type&rsquo; of the video.

 This specifies how DCP-o-matic should interpret the video's image.
 <guilabel>2D</guilabel> is the default; this just takes the video
 image as a standard 2D frame.  The <guilabel>3D
 This specifies how DCP-o-matic should interpret the video's image.
 <guilabel>2D</guilabel> is the default; this just takes the video
 image as a standard 2D frame.  The <guilabel>3D


@@ -1023,7 +1069,6 @@ The <guilabel>Audio</guilabel> tab controls properties of the image, as shown in
   </mediaobject>
 </figure>
 
   </mediaobject>
 </figure>
 

-

 <!-- ============================================================== -->
 <section>
 <title>The audio map</title>
 <!-- ============================================================== -->
 <section>
 <title>The audio map</title>


@@ -1128,7 +1173,20 @@ shows the mapping of a 5.1 source into a 5.1 DCP.
 
 <!-- ============================================================== -->
 <section>
 
 <!-- ============================================================== -->
 <section>

-<title>Other controls</title>
+  <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"/>.
+</para>
+
+<para>
+<guilabel>Show graphs of audio levels</guilabel> will analyse the
+audio of the selected content and plot it on a graph.  See <xref
+linkend="sec-show-audio"/> for more details.
+</para>

 
 <para>
 &lsquo;Audio Gain&rsquo; is used to alter the volume of the
 
 <para>
 &lsquo;Audio Gain&rsquo; is used to alter the volume of the


@@ -1289,6 +1347,11 @@ frame) than those typically used for DCP, so it is often useful to
 scale such subtitles down using these controls.
 </para>
 
 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.
+</para>
+

 <para>
 The <guilabel>Stream</guilabel> control changes the subtitle stream
 that is used when the content has more than one.
 <para>
 The <guilabel>Stream</guilabel> control changes the subtitle stream
 that is used when the content has more than one.


@@ -1357,11 +1420,17 @@ should be displayed using this control.
 </para>
 
 <para>
 </para>
 
 <para>

-<guilabel>Trim from start</guilabel> specifies the amount that should be trimmed from the start of the content.
+<guilabel>Trim from start</guilabel> specifies the amount that should
+be trimmed from the start of the content.  You can set this amount to
+trim up to the current preview position by clicking <guilabel>Trim up
+to current position</guilabel>.

 </para>
 
 <para>
 </para>
 
 <para>

-<guilabel>Trim from end</guilabel> specifies the amount that should be trimmed from the end of the content.
+<guilabel>Trim from end</guilabel> specifies the amount that should be
+trimmed from the end of the content.  You can set this amount to trim
+after the current preview position by clicking <guilabel>Trim after to
+current position</guilabel>.

 </para>
 
 <para>
 </para>
 
 <para>


@@ -1776,7 +1845,7 @@ you must specify a reel length in Gb.  Then no file in the DCP will be larger th
 
 
 <!-- ============================================================== -->
 
 
 <!-- ============================================================== -->

-<section>
+<section xml:id="sec-show-audio">

 <title>Show audio</title>
 
 <para>
 <title>Show audio</title>
 
 <para>


@@ -1976,7 +2045,7 @@ linkend="fig-kdm"/>.
   <title>KDM dialog</title>
   <mediaobject>
     <imageobject>
   <title>KDM dialog</title>
   <mediaobject>
     <imageobject>

-      <imagedata fileref="screenshots/kdm&scs;"/>
+      <imagedata scale="40" fileref="screenshots/kdm&scs;"/>

     </imageobject>
   </mediaobject>
 </figure>
     </imageobject>
   </mediaobject>
 </figure>


@@ -2047,13 +2116,28 @@ You must also select the type of KDM that you want to generate.  If in
 doubt, use <guilabel>Modified Transitional 1</guilabel>.
 </para>
 
 doubt, use <guilabel>Modified Transitional 1</guilabel>.
 </para>
 

+<note>
+The differences between the three KDM types are fairly subtle.
+<guilabel>DCI Specific</guilabel> and <guilabel>DCI Any</guilabel> add
+a <code>&lt;ContentAuthenticator&gt;</code> tag to the KDM which
+allows the exhibitor to check that the DCP and KDM have come from a
+bona-fide source.  In addition, <guilabel>DCI Specific</guilabel> adds
+information on trusted devices to the KDM.  This allows the KDM
+creator to specify devices (such as sound processors) that are allowed
+to use keys delivered by the KDM.  At present it is not clear how
+widely the <guilabel>DCI Specific</guilabel> and <guilabel>DCI
+Any</guilabel> features are supported (or even tolerated) by servers
+so you are advised to use <guilabel>Modified Transitional
+1</guilabel>.
+</note>
+

 <para>
 Finally, choose what you want to do with the KDMs.  They can be
 written to disk, to a location that you can specify by clicking
 <guilabel>Browse</guilabel>.  Alternatively, if you choose
 <guilabel>Send by email</guilabel> the KDMs will be zipped up and
 <para>
 Finally, choose what you want to do with the KDMs.  They can be
 written to disk, to a location that you can specify by clicking
 <guilabel>Browse</guilabel>.  Alternatively, if you choose
 <guilabel>Send by email</guilabel> the KDMs will be zipped up and

-emailed to the appropriate cinema email addresses.  Click OK to
-generate the KDMs.
+emailed to the appropriate cinema email addresses.  Click
+<guilabel>Make KDMs</guilabel> to generate the KDMs.

 </para>
 
 </section>
 </para>
 
 </section>


@@ -2093,7 +2177,7 @@ select <guilabel>Make DKDM for DCP-o-matic...</guilabel> from the
 <guilabel>Jobs</guilabel> menu.  Select the CPL that you want to make
 the DKDM for and click <guilabel>OK</guilabel>.  This DKDM will then
 be available in the KDM creator.  This is a separate program which you
 <guilabel>Jobs</guilabel> menu.  Select the CPL that you want to make
 the DKDM for and click <guilabel>OK</guilabel>.  This DKDM will then
 be available in the KDM creator.  This is a separate program which you

-can start from the same place that you start the &lsquo;Normal&rsquo;
+can start from the same place that you start the &lsquo;normal&rsquo;

 DCP-o-matic.  Its window is shown in <xref linkend="fig-kdm-creator"/>.
 </para>
 
 DCP-o-matic.  Its window is shown in <xref linkend="fig-kdm-creator"/>.
 </para>
 


@@ -2101,7 +2185,7 @@ DCP-o-matic.  Its window is shown in <xref linkend="fig-kdm-creator"/>.
   <title>The KDM creator</title>
   <mediaobject>
     <imageobject>
   <title>The KDM creator</title>
   <mediaobject>
     <imageobject>

-      <imagedata fileref="screenshots/kdm-creator&scs;"/>
+      <imagedata scale="35" fileref="screenshots/kdm-creator&scs;"/>

     </imageobject>
   </mediaobject>
 </figure>
     </imageobject>
   </mediaobject>
 </figure>


@@ -2388,13 +2472,19 @@ be used when targeting a KDM at DCP-o-matic.
 If you want to import an encrypted DCP you will need to give the
 decryption certificate to the distributor of the DCP so that they can
 generate a DKDM for you.  You can save this certificate to disk by
 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
+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>
 
 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.
+</para>
+

 </section>
 
 <!-- ============================================================== -->
 </section>
 
 <!-- ============================================================== -->


@@ -2537,6 +2627,14 @@ JPEG2000 data only on encoding servers and not on the host.  We
 suggest you leave this un-ticked unless you have a good reason to do otherwise.
 </para>
 
 suggest you leave this un-ticked unless you have a good reason to do otherwise.
 </para>
 

+<para>
+With the filename format fields you can adjust the filenames that are
+used for metadata (CPL and PKL files) and assets (MXF and subtitle
+files).  Below each field there is a list of the &lsquo;magic&rsquo;
+values that you can use in the format and an example of a filename
+that you might see with your current settings.
+</para>
+

 <para>
 The four checkboxes labelled <guilabel>Log</guilabel> control what
 sort of messages DCP-o-matic writes to its log file when creating a
 <para>
 The four checkboxes labelled <guilabel>Log</guilabel> control what
 sort of messages DCP-o-matic writes to its log file when creating a


@@ -2838,7 +2936,8 @@ operation is interrupted and DCP-o-matic must resume it.</listitem>
 Following this is the DCP itself:
 <code>DCP-TEST_EN-XX_UK-U_51_2K_CSY_20130218_CSY_OV</code>.  This
 contains some small XML files, which describe the DCP, and two large
 Following this is the DCP itself:
 <code>DCP-TEST_EN-XX_UK-U_51_2K_CSY_20130218_CSY_OV</code>.  This
 contains some small XML files, which describe the DCP, and two large

-MXF files, which contain the DCP's audio and video data.  This folder
+MXF files, which contain the DCP's audio and video data.  It may also
+contain subtitles 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>
 (<code>DCP-TEST_EN-XX_...</code>) is what you should ingest, or pass
 to the cinema which is showing your DCP.
 </para>