Add config options for some of the DCP XML metadata (#122).
[dcpomatic.git] / doc / manual / dvdomatic.xml
index 3143772c7e743c1f211b4bc0e3cc818b3729c117..58315eca6ccb53cb28c7aa17df87819267599890 100644 (file)
@@ -48,8 +48,8 @@ your cinema.
 DVD-o-matic is licensed under the <ulink url="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GNU GPL</ulink>.
 </para>
 
-
 </section>
+
 </chapter>
 
 <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
@@ -65,14 +65,41 @@ and double-click it.  Click through the installer wizard, and
 DVD-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 DVD-o-matic to
+use more memory.  You may find that DVD-o-matic crashes if you run
+many parallel encoding threads (more than 4) on the 32-bit
+version.
+</para>
+
+</section>
+
+<section>
+<title>Ubuntu Linux</title>
+
+<para>
+You can install DVD-o-matic on Ubuntu 12.04 (&lsquo;Precise
+Pangolin&rsquo;) or 12.10 (&lsquo;Quantal Quetzal&rsquo;) using
+<code>.deb</code> packages: download the appropriate package from
+<ulink
+url="http://carlh.net/software/dvdomatic">http://carlh.net</ulink> and
+double-click it.  Ubuntu will install the necessary bits and pieces
+and set DVD-o-matic up for you.
+</para>
+
 </section>
 
 <section>
-<title>Linux</title>
+<title>Other Linux distributions</title>
 
 <para>
-Installation on Linux is currently a little involved, as there are no
-packages available (yet); you will have to compile it from source.
+Installation on non-Ubuntu Linux is currently a little involved, as
+there are no packages available (yet); you will have to compile it
+from source.  If you are using a non-Ubuntu distribution, do let me
+know via the <ulink url="mailto:dvdomatic@carlh.net">mailing
+list</ulink> and I will see about building some packages.
 </para>
 
 <para>
@@ -117,87 +144,6 @@ dvdomatic
 in a shell.
 </para>
 
-<section>
-<title>Obtaining dependencies on Ubuntu 12.04</title>
-
-<para>
-Ubuntu 12.04 packages most of DVD-o-matic's dependencies, but some are missing.  This section
-describes how to obtain all of the dependencies.
-</para>
-
-<section>
-<title>Packaged dependencies</title>
-
-<para>
-Most of the dependencies can be obtained from Ubuntu's packages using:
-</para>
-
-<programlisting>
-sudo apt-get install libwxgtk2.8-dev libsndfile1-dev libssl-dev libssh-dev
-sudo apt-get install libmagickcore-dev libboost-filesystem-dev libboost-thread-dev
-</programlisting>
-
-</section>
-
-<section>
-<title>Unpackaged dependencies</title>
-</section>
-
-<section>
-<title>FFmpeg</title>
-
-<para>
-Ubuntu does not package FFmpeg, so you will need to build it from source.  The
-following commands should work:
-</para>
-
-<programlisting>
-git clone git://source.ffmpeg.org/ffmpeg.git ffmpeg
-cd ffmpeg
-./configure --enable-shared --enable-postproc --enable-gpl
-make
-sudo make install
-</programlisting>
-
-</section>
-
-<section>
-<title>libdcp</title>
-
-<para>
-You can build libdcp using:
-</para>
-
-<programlisting>
-wget http://carlh.net/software/libdcp-0.20.tar.bz2
-tar xjf libdcp-0.20.tar.bz2
-cd libdcp-0.20
-./waf configure
-./waf build
-sudo ./waf install
-</programlisting>
-
-</section>
-
-<section>
-<title>libopenjpeg</title>
-
-<para>
-Ubuntu does package libopenjpeg, but it is a rather old version.  To build
-the current release:
-</para>
-
-<programlisting>
-wget http://code.google.com/p/openjpeg/downloads/detail?name=openjpeg-1.5.1.tar.gz
-tar xzf openjpeg-1.5.1.tar.gz
-cd openjepg-1.5.1.tar.gz
-./configure
-make
-sudo make install
-</programlisting>
-
-</section>
-</section>
 </section>
 </chapter>
 
@@ -259,12 +205,19 @@ linkend="fig-video-new-film"/>.
 <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 set whereabouts you want to create
+name for the DCP itself.  You can also choose whereabouts you want to create
 the film.  In the example from the figure, DVD-o-matic will create a
 folder called &lsquo;DCP Test&rsquo; inside my home folder (carl) into which it
 will write its working files.
 </para>
 
+<para>
+If you always create your DCPs in a particular folder, you can use
+DVD-o-matic's <guilabel>Preferences</guilabel> to make life a little
+easier by setting the default folder that DVD-o-matic will offer in this dialogue.
+See <xref linkend="ch-preferences"/>.
+</para>
+
 </section>
 
 <section>
@@ -273,7 +226,7 @@ will write its working files.
 <para>
 The next step is to set the content that you want to use.  Click the
 content selector, as shown in <xref
-linkend="fig-click-content-selector"/> and the a file chooser will
+linkend="fig-click-content-selector"/>, and a file chooser will
 open for you to select the content file to use, as shown in <xref
 linkend="fig-video-select-content-file"/>.
 </para>
@@ -298,13 +251,13 @@ linkend="fig-video-select-content-file"/>.
 
 <para>
 Select your content file and click <guilabel>Open</guilabel>.  In this
-case, we are using the Sintel trailer that we downloaded earlier.
+case we are using the Sintel trailer that we downloaded earlier.
 </para>
 
 <para>
 When you do this, DVD-o-matic will take a look at your file.  After a
-short while (when the progress bars at the bottom right of the window
-have finished), you can look through your content using the slider to
+short while (when the progress bar at the bottom right of the window
+has finished), you can look through your content using the slider to
 the right of the window, as shown in <xref linkend="fig-examine-thumbs"/>.
 </para>
 
@@ -318,7 +271,13 @@ the right of the window, as shown in <xref linkend="fig-examine-thumbs"/>.
 </figure>
 
 <para>
-Dragging the slider will move through your video.
+Dragging the slider will move through your video.  You can also click
+the <guilabel>Play</guilabel> button to play the content back.  Note
+that there will be no sound, 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>.
 </para>
 
 </section>
@@ -328,43 +287,103 @@ Dragging the slider will move through your video.
 
 <para>
 Now there are a few things to set up to describe how the DCP should be
-created, as shown in <xref linkend="fig-video-setup"/>.
+created.  The settings are divided into four tabs: film, video, audio and subtitles.
 </para>
 
-<figure id="fig-video-setup"> 
-  <title>Setting up to make a video DCP</title>
+<section>
+<title>Film tab</title>
+
+<para>
+The &lsquo;film&rsquo; tab contains settings that pertain to the whole film, as shown in <xref linkend="fig-film-tab"/>.
+</para>
+
+<figure id="fig-film-tab"> 
+  <title>Film settings tab</title>
   <mediaobject>
     <imageobject> 
-      <imagedata fileref="screenshots/video-setup&scs;"/>
+      <imagedata fileref="screenshots/film-tab&scs;"/>
     </imageobject> 
   </mediaobject>
 </figure>
 
 <para>
-The first thing is the content type.  This can be
+The first thing here is the name.  This is generally set to the title
+of the film that is being encoded.  If <guilabel>Use DCI
+name</guilabel> is not ticked, the name that you specify will be used
+as-is for the name of the DCP.  If <guilabel>Use DCI name</guilabel>
+is ticked, the name that you enter will be used as part of a
+DCI-compliant name.
+</para>
+
+<para>
+Underneath the name field is a preview of the name that the DCP will
+get.  To use a DCI-compliant name, tick the <guilabel>Use DCI
+name</guilabel> checkbox.  The DCI name will be composed using details
+of your content's soundtrack, the current date and other things that
+can be specified in the DCI name details dialogue box, which you can
+open by clicking on the <guilabel>Details</guilabel> button.
+</para>
+
+<para>
+If the DCP name is long, it may not all be visible.  You can see the
+full name by hovering the mouse pointer over the partial name.
+</para>
+
+<para>
+The <guilabel>Trust content's header</guilabel> button starts off
+checked, and this means that DVD-o-matic will use the content's header
+information to determine its length.  If, for some reason, this header
+length is wrong, uncheck the <guilabel>Trust content's
+header</guilabel> button and DVD-o-matic will run through the content
+to find its exact length.  This may take a while for large pieces of content.
+</para>
+
+<para>
+Next up is the content type.  This can be
 &lsquo;feature&rsquo;, &lsquo;trailer&rsquo; or whatever; select the
 required type from the drop-down list.
 </para>
 
 <para>
-Next is the format.  This will govern the shape that DVD-o-matic will
-make your image into.  Select the aspect ratio that your content
-should be presented in.  The &lsquo;4:3 within Flat&rsquo; and
-&lsquo;16:9 within Flat&rsquo; settings will put the image at the
-specified ratio within a Flat (1.85:1) frame, so that you can project
-the DCP using your projector's Flat preset.
+The <guilabel>trim frames</guilabel> settings allow you to trim frames
+from the beginning and end of the content; any trimmed frames will not
+be included in the DCP.
+</para>
+
+</section>
+
+<section>
+<title>Video tab</title>
+
+<para>
+This tab contains settings related to the picture in your DCP, as shown in <xref linkend="fig-video-tab"/>.
+</para>
+
+<figure id="fig-video-tab"> 
+  <title>Video settings tab</title>
+  <mediaobject>
+    <imageobject> 
+      <imagedata fileref="screenshots/video-tab&scs;"/>
+    </imageobject> 
+  </mediaobject>
+</figure>
+
+<para>
+The first option on this tab is the format.  This will govern the
+shape that DVD-o-matic will make your image into.  Select the aspect
+ratio that your content should be presented in.  The &lsquo;4:3 within
+Flat&rsquo; and &lsquo;16:9 within Flat&rsquo; settings will put the
+image at the specified ratio within a Flat (1.85:1) frame, so that you
+can project the DCP using your projector's Flat preset.
 </para>
 
 <para>
 The remaining options can often be left alone, but may sometimes be
 useful.  The &lsquo;crop&rsquo; 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 <guilabel>L</guilabel>,
-<guilabel>R</guilabel>, <guilabel>T</guilabel> and
-<guilabel>B</guilabel> settings correspond to the left, right, top and
-bottom of the image respectively.  The specified number of pixels will
-be trimmed from each edge, and your content image in the right of the
-window will be updated to show the cropping in action.
+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.
 </para>
 
 <para>
@@ -382,6 +401,38 @@ most situations.
 <!-- XXX: link -->
 </para>
 
+<para>
+The &lsquo;colour look-up table&rsquo; specifies the colour space that
+your input content will be expected to be in.  If in doubt, leave it
+set to &lsquo;sRGB&rsquo;.
+</para>
+
+<para>
+Finally, the &lsquo;JPEG2000 bandwidth&rsquo; 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 (MBps).
+</para>
+
+</section>
+
+<section>
+<title>Audio tab</title>
+
+<para>
+This tab contains settings related to the sound in your DCP, as shown in <xref linkend="fig-audio-tab"/>.
+</para>
+
+<figure id="fig-audio-tab"> 
+  <title>Audio settings tab</title>
+  <mediaobject>
+    <imageobject> 
+      <imagedata fileref="screenshots/audio-tab&scs;"/>
+    </imageobject> 
+  </mediaobject>
+</figure>
+
+
 <para>
 &lsquo;Audio Gain&rsquo; is used to alter the volume of the
 soundtrack.  The specified gain (in dB) will be applied to each sound
@@ -430,10 +481,61 @@ with respect to the video, and a negative delay will move it earlier.
 </para>
 
 <para>
-The <guilabel>Range</guilabel> controls allow you to specify a part of
-your content to encode.  We will discuss this later.
+By default the <guilabel>Use content&lsquo;s audio</guilabel> button
+will be selected.  This means that the DCP will use one of the
+soundtracks from your content file; you can select the soundtrack that
+you wish to use from the drop-down box.
+</para>
+
+<para>
+Note that if your content's audio is mono, DVD-o-matic will place it
+in the centre channel in the DCP.
+</para>
+
+<para>
+Alternatively, you can supply different sound files by clicking the
+<guilabel>Use external audio</guilabel> button and choosing a WAV file
+for any channels that you want to appear in the DCP.  These files can
+be any bit depth and sampling rate, and will be re-sampled and
+bit-depth converted if required.
 </para>
 
+</section>
+<section>
+<title>Subtitles tab</title>
+
+<para>
+This tab contains settings related to subtitles in your DCP, as shown in <xref linkend="fig-subtitles-tab"/>.
+</para>
+
+<figure id="fig-subtitles-tab"> 
+  <title>Subtitle settings tab</title>
+  <mediaobject>
+    <imageobject> 
+      <imagedata fileref="screenshots/subtitles-tab&scs;"/>
+    </imageobject> 
+  </mediaobject>
+</figure>
+
+<para>
+DVD-o-matic will extract subtitles from the content, if present, and
+they can be &lsquo;burnt into&rsquo; the DCP (that is, they are
+included in the image and not overlaid by the projector).  Note that
+DVD and Blu-Ray subtitles are stored as bitmaps, so it is not possible
+(automatically) to use non-burnt-in subtitles with these sources.
+Select the <guilabel>With Subtitles</guilabel> checkbox to enable
+subtitles.  The <guilabel>offset</guilabel> control moves the
+subtitles up and down the image, and the <guilabel>scale</guilabel>
+control changes their size.
+</para>
+
+<para>
+Future versions of DVD-o-matic will hopefully include the option to
+use text subtitles (as is the norm with most professionally-mastered
+DCPs).
+</para>
+
+</section>
 </section>
 
 <section>
@@ -444,8 +546,7 @@ Now that we have set everything up, choose <guilabel>Make
 DCP</guilabel> from the <guilabel>Jobs</guilabel> menu.  DVD-o-matic
 will encode your DCP.  This may take some time (many hours in some
 cases).  While the job is in progress, DVD-o-matic will update you on
-how it is getting on with the progress bar in the bottom right hand
-corner of its window, as shown in <xref linkend="fig-making-dcp"/>.
+how it is getting on with the progress bar in the bottom of its window, as shown in <xref linkend="fig-making-dcp"/>.
 </para>
 
 <figure id="fig-making-dcp">
@@ -463,6 +564,12 @@ film's directory.  You can then copy this to a projector via a USB
 stick, hard-drive or network connection.
 </para>
 
+<para>
+Alternatively, if you have a projector or TMS that is accessible via
+SCP across your network, you can upload the content directly from
+DVD-o-matic.  See <xref linkend="sec-tms-upload"/>.
+</para>
+
 </section>
 </chapter>
 
@@ -510,24 +617,25 @@ linkend="fig-still-select-content-file"/>.
 
 <para>
 Setting up for a still image DCP is somewhat simpler than for a video;
-the options are shown in <xref linkend="fig-still-setup"/>.
+the tabs are all the same, but many options are removed and a few are added.
 </para>
 
-<figure id="fig-still-setup"> 
-  <title>Setting up to make a still DCP</title>
-  <mediaobject>
-    <imageobject> 
-      <imagedata fileref="screenshots/still-setup&scs;"/>
-    </imageobject> 
-  </mediaobject>
-</figure>
-
 <para>
 As with video, you can select a content type and the format (ratio)
-that your image should be presented in.  It will be scaled to fit the
-selected ratio.  You can also crop your image, if you so choose, and
-then set a duration (in seconds) that the image should appear on
-screen.
+that your image should be presented in.  It will be scaled and padded
+to fit the selected ratio, but in such a way that the pixel aspect
+ratio is preserved.  In other words, the image will not be stretched,
+merely scaled; if you want to stretch your image, you will need to do
+so in a separate program before importing it into DVD-o-matic.  You
+can also crop your image, if you so choose, and then set a duration
+(in seconds) that the image should appear on screen.
+</para>
+
+<para>
+Still-image DCPs can include sound; this can be added from the
+<guilabel>Audio</guilabel> tab.  If your specified duration is shorter
+than the audio, the audio will be cut off at the duration; if it is
+longer, silence will be added after your audio.
 </para>
 
 <para>
@@ -598,11 +706,10 @@ processors (or processor cores) in your machine.
 </section>
 
 <section>
-<title>Colour look-up table</title>
+<title>Default directory for new films</title>
 
 <para>
-This specifies the colour space that your input content will be
-expected to be in.  If in doubt, leave it set to &lsquo;sRGB&rsquo;.
+This is the directory which DVD-o-matic will suggest initially as a place to put new films.
 </para>
 
 </section>
@@ -664,20 +771,11 @@ as shown in <xref linkend="fig-filters"/>.
   </mediaobject>
 </figure>
 
-<para>
-As it stands, these filters are somewhat disorganised!  Work is
-ongoing to test them with various content and choose a selection which
-work well for cinema applications.
-</para>
-
-<para>
-If you want to examine them yourself, you may find the A/B option (see
-<xref linkend="sec-ab"/>) useful.
-</para>
-
 <para>
 After changing the filters setup, you will need to regenerate the DCP
-to see the effect on-screen.
+to see the effect on the cinema screen.  The preview in DVD-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>
@@ -695,13 +793,13 @@ best all-round option, but tests are ongoing.
 
 </section>
 
-<section xml:id="tms-upload">
+<section xml:id="sec-tms-upload">
 <title>TMS upload</title>
 
 <para>
 If you have configured details of a TMS in the preferences dialogue
 (<xref linkend="ch-preferences"/>) you can upload a completed DCP
-straight to your TMS but choosing <guilabel>Send DCP to TMS</guilabel>
+straight to your TMS buy choosing <guilabel>Send DCP to TMS</guilabel>
 from the <guilabel>Jobs</guilabel> menu.
 </para>
 
@@ -731,43 +829,6 @@ half will use the filters and scaler specified in the film setup.
 
 </section>
 
-
-<section>
-<title>Encode range</title>
-
-<para>
-If you want to encode only a portion of your input content, you can do
-so by clicking the <guilabel>Edit</guilabel> button next to the
-<guilabel>Range</guilabel> entry in the film setup area.  This will
-open the dialogue shown in <xref linkend="fig-range"/>.
-</para>
-
-<figure id="fig-range"> 
-  <title>Range selector</title> 
-  <mediaobject>
-    <imageobject> 
-      <imagedata fileref="screenshots/range&scs;"/>
-    </imageobject> 
-  </mediaobject>
-</figure>
-
-<para>
-Here you can choose to encode the whole film, or just the first
-so-many frames of it.  This can be useful to check the quality of an
-encode before comitting to encoding the whole film &mdash; perhaps
-just encode the first ten minutes, look at it on screen, and check
-that it is ok.
-</para>
-
-<para>
-If you choose to encode only a part of the film, you can set
-DVD-o-matic to black out the rest.  This can be useful to chop a small
-part off the end of a piece of content while letting the audio play
-out.
-</para>
-
-</section>
-
 <section xml:id="sec-servers">
 <title>Encoding servers</title>