Update subtitles -> timed text in manual.
[dcpomatic.git] / doc / manual / dcpomatic.xml
index 1519562fdc4aedc20dae6ae65085e3f6185c2169..cc19d9ebf9a6e1b3230c2542954006875bf1d757 100644 (file)
@@ -32,7 +32,7 @@ Hello, and welcome to DCP-o-matic!
   <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>
+  subtitle and closed caption files.</listitem>
   <listitem>Playback and verification of DCPs on a PC/Mac.</listitem>
   <listitem>Creation of KDMs for DCPs.</listitem>
 </itemizedlist>
@@ -107,7 +107,8 @@ version.
 <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.
+Windows version.  Be aware, though, that support for Windows XP will
+not last forever and you should plan to upgrade if at all possible.
 </para>
 
 </section>
@@ -119,7 +120,7 @@ Windows version.
 
 <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
+higher.  DCP-o-matic is split into five 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.
@@ -142,7 +143,7 @@ with the first (main) part.
 
 <itemizedlist>
   <listitem>Debian 7 (&lsquo;wheezy&rsquo;), 8 (&lsquo;jessie&rsquo;), 9 (&lsquo;squeeze&rsquo;) and unstable (&lsquo;sid&rsquo;)</listitem>
-  <listitem>Ubuntu 14.04 (&lsquo;Trusty Tahr&rsquo;), 16.04 (&lsquo;Xenial Xerus&rsquo;) and 18.04 (&lsquo;Bionic Beaver&rsquo;)</listitem>
+  <listitem>Ubuntu 14.04 (&lsquo;Trusty Tahr&rsquo;), 16.04 (&lsquo;Xenial Xerus&rsquo;), 18.04 (&lsquo;Bionic Beaver&rsquo;) and 18.10 (&lsquo;Cosmic Cuttlefish&rsquo;)</listitem>
   <listitem>Mint 17, 18 and 19</listitem>
 </itemizedlist>
 
@@ -224,7 +225,7 @@ directory:
 </para>
 
 <programlisting>
-./waf configure
+./waf configure --disable-tests
 ./waf build
 sudo ./waf install
 </programlisting>
@@ -240,11 +241,40 @@ dcpomatic2
 <para>
 in a shell.
 </para>
+</section>
+
+<!-- ============================================================== -->
+<section>
+<title>&lsquo;Simple&rsquo; and &lsquo;Full&rsquo; modes</title>
+
+<para>When you start DCP-o-matic for the first time it will ask you if
+you want to use &lsquo;simple&rsquo; or &lsquo;full&rsquo; mode.
+</para>
+
+<para>The difference between these two is that some of DCP-o-matic's
+more complex or less-used controls are hidden from view in
+&lsquo;Simple&rsquo; mode.  This makes the interface simpler to
+navigate.  You may wish to choose this mode if you do not have much
+experience with video processing.
+</para>
+
+<para>Even if you choose &lsquo;Simple&rsquo; mode you can always go
+back to &lsquo;Full&rsquo; mode by changing the <guilabel>Interface
+complexity</guilabel> setting in the <guilabel>General</guilabel> tab
+of <guilabel>Preferences</guilabel>.
+</para>
+
+<para>
+All the screenshots in this manual are from a copy of DCP-o-matic in &lsquo;Full&rsquo; mode.
+</para>
 
 </section>
+
 </chapter>
 
 
+
+
 <!-- ============================================================== -->
 <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
 <title>Creating a DCP from a video</title>
@@ -281,7 +311,7 @@ shown in <xref linkend="fig-file-new"/>.
   <title>Creating a new film</title>
   <mediaobject>
     <imageobject>
-      <imagedata fileref="screenshots/file-new&scs;"/>
+      <imagedata scale="250" fileref="screenshots/file-new&scs;"/>
     </imageobject>
   </mediaobject>
 </figure>
@@ -397,7 +427,7 @@ linkend="fig-making-dcp"/>.
   <title>Making the DCP</title>
   <mediaobject>
     <imageobject>
-      <imagedata scale="50" fileref="screenshots/making-dcp&scs;"/>
+      <imagedata scale="250" fileref="screenshots/making-dcp&scs;"/>
     </imageobject>
   </mediaobject>
 </figure>
@@ -500,21 +530,21 @@ to encode a single frame which it can then repeat.
 <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 will be slow as
+decoding of DCPs is almost as computationally intensive as encoding
+them.
 </para>
 
 <para>
@@ -602,8 +632,8 @@ the following content settings:
 </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>
@@ -989,7 +1019,7 @@ linkend="tab-colour-conversion"/>.
 <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>
@@ -1276,29 +1306,37 @@ with respect to the video, and a negative delay will move it earlier.
 
 <!-- ============================================================== -->
 <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 so
+seen by everybody) or as a closed caption (to be displayed to
+individual viewers using a special system such as the Doremi
+CaptiView&trade;)
+</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
+  <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 great
   free program <ulink
   url="http://www.nikse.dk/subtitleedit/">Subtitle Edit</ulink> useful
@@ -1306,15 +1344,18 @@ DCP-o-matic can either:
 </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 &lsquo;burnt&rsquo; 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 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
 &lsquo;asset&rsquo; 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"/>
@@ -1349,42 +1390,44 @@ every language.
 </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 &lsquo;image&rsquo; 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>
@@ -1393,14 +1436,17 @@ that is used when the content has more than one.
 </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>Apperance</guilabel> only apply to burnt-in subtitles, as
+only limited control is available for subtitles rendered by the
+projection system.
 </para>
 
 </section>
@@ -2177,7 +2223,7 @@ linkend="fig-kdm"/>.
   <title>KDM dialog</title>
   <mediaobject>
     <imageobject>
-      <imagedata scale="40" fileref="screenshots/kdm&scs;"/>
+      <imagedata scale="35" fileref="screenshots/kdm&scs;"/>
     </imageobject>
   </mediaobject>
 </figure>
@@ -2317,7 +2363,7 @@ DCP-o-matic.  Its window is shown in <xref linkend="fig-kdm-creator"/>.
   <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>
@@ -2767,12 +2813,39 @@ Note that for this to work on Doremi servers you will need to set the
 </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">
@@ -2821,6 +2894,68 @@ The <guilabel>Reset to default text</guilabel> will replace the current KDM emai
 </section>
 
 
+<!-- ============================================================== -->
+<section>
+<title>Accounts</title>
+
+<para>
+The Accounts tab is shown in <xref linkend="fig-prefs-accounts"/>.
+</para>
+
+<figure id="fig-prefs-accounts">
+  <title>Accounts preferences</title>
+  <mediaobject>
+    <imageobject>
+      <imagedata fileref="screenshots/prefs-accounts&scs;"/>
+    </imageobject>
+  </mediaobject>
+</figure>
+
+<para>
+DCP-o-matic can download projector certificates from the Barco and
+Christie websites if you have the appropriate credentials.  Enter your
+usernames and passwords.
+</para>
+
+</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 contents of the email that should
+be sent.  DCP-o-matic will replace the &lsquo;magic&rsquo; strings
+<code>$JOB_NAME</code> and <code>$JOB_STATUS</code> in the with the
+details of the job that has completed.
+</para>
+
+</section>
+
+
 <!-- ============================================================== -->
 <section>
 <title>Cover sheet</title>
@@ -3048,8 +3183,8 @@ The <guilabel>Frame Rate</guilabel> control in the
 <guilabel>DCP</guilabel> tab sets the video frame rate that the DCP
 will use.  Clicking <guilabel>Use best</guilabel> sets the rate to
 what 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>
@@ -3273,7 +3408,7 @@ to the cinema which is showing your DCP.
     </para>
 
     <para>
-      <code>dcpomatic2_create [OPTION] [CONTENT] [&lt;CONTENT&gt; ...]</code>
+      <code>dcpomatic2_create [OPTION] &lt;CONTENT&gt; [[OPTION] &lt;CONTENT&gt; ...]</code>
     </para>
 
     <para>
@@ -3291,20 +3426,7 @@ to the cinema which is showing your DCP.
       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>
+    <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:
@@ -3334,21 +3456,7 @@ to the cinema which is showing your DCP.
       <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>
+    <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:
@@ -3370,21 +3478,7 @@ to the cinema which is showing your DCP.
       <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>
+    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dcpomatic_kdm_cli.xml"/>
 
   </section>
 </chapter>