<title>Windows</title>
<para>
-To install DCP-o-matic on Windows, simply download the installer from
+To install DCP-o-matic on Windows, download the installer from
<ulink url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>
and double-click it. Click through the installer wizard, and
DCP-o-matic will be installed onto your machine.
<para>
You can install DCP-o-matic on Ubuntu 12.04 (‘Precise
-Pangolin’), 12.10 (‘Quantal Quetzal’) or 13.04
-(‘Raring Ringtail’) using <code>.deb</code> packages:
-
download the appropriate package from <ulink
+Pangolin’), 12.10 (‘Quantal Quetzal’), 13.10 (‘Saucy
+Salamander’) or 14.04 (‘Trusty Tahr’) using <code>.deb</code> packages: download the
+appropriate package from <ulink
url="http://dcpomatic.com/">http://dcpomatic.com/</ulink> and
double-click it. Ubuntu will install the necessary bits and pieces
and set DCP-o-matic up for you.
</section>
+<section>
+<title>Debian Linux</title>
+<para>
+Packages are available for Debian 7 (squeeze) from <ulink
+url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>.
+</para>
+</section>
+
+<section>
+<title>Centos Linux</title>
+<para>
+Packages are available for Centos 6.5 from <ulink
+url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>.
+</para>
+</section>
+
+<section>
+<title>Arch Linux</title>
+<para>
+Packages for Arch Linux are available from <ulink
+url="https://aur.archlinux.org/packages/dcpomatic/">https://aur.archlinux.org/packages/dcpomatic/</ulink>,
+thanks to Stefan Karner.
+</para>
+</section>
+
<section>
<title>Other Linux distributions</title>
<listitem><ulink url="http://www.imagemagick.org/script/index.php">ImageMagick</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</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://freecode.com/projects/libquickmail">libquickmail</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/software/libdcp/">libdcp</ulink></listitem>
<listitem><ulink url="http://carlh.net/software/libcxml/">libcxml</ulink></listitem>
</itemizedlist>
<para>
Alternatively, if you have a projector or TMS that is accessible via
SCP across your network, you can upload the content directly from
-DCP-o-matic. See the preferences in <xref linkend="sec-prefs-tms"/>.
+DCP-o-matic. See the <xref linkend="sec-prefs-tms" endterm="sec-prefs-tms-short"/>.
</para>
</section>
The first option on this tab is the ‘type’ 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 other option <guilabel>3D
-left/right</guilabel> tells DCP-o-matic to interpret the frame as a
+image as a standard 2D frame. The <guilabel>3D
+left/right</guilabel> option tells DCP-o-matic to interpret the frame as a
left-right pair, as shown in <xref linkend="fig-3d-left-right"/>.
</para>
</figure>
<para>
-This option can be used to generate a 3D DCP. Other means of creating
-3D will be added in the future.
+Alternatively the <guilabel>3D top/bottom</guilabel> option tells
+DCP-o-matic to see the frame as a top-bottom pair, as shown in <xref
+linkend="fig-3d-top-bottom"/>.
</para>
+<figure id="fig-3d-top-bottom">
+ <title>3D top/bottom image type</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="100" fileref="diagrams/3d-top-bottom&dia;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
</section>
</section>
-<!-- XXX: timing tab -->
+<section>
+<title>Timing</title>
+
+<para>
+The timing tab contains settings related to the timing of your
+content, as shown in <xref linkend="fig-timing-tab-detail"/>.
+</para>
+
+<figure id="fig-timing-tab-detail">
+ <title>Timing settings tab</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/timing-tab&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+Most of the timing tab's entries are <emphasis>time-codes</emphasis>.
+These are expressed as four numbers, as shown in <xref
+linkend="fig-timecode"/>.
+</para>
+
+<figure id="fig-timecode">
+ <title>Timecode</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="diagrams/timecode&dia;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+<guilabel>Position</guilabel> is the time at which this piece of
+content should start within the DCP. In most cases, this will be
+<code>0:0:0:0</code> to make the content start at the beginning of the
+DCP.
+</para>
+
+<para>
+<guilabel>Full length</guilabel> is the length of the piece of
+content. This can only be set for still-image content: for video or
+sound content, it is fixed by the nature of the content file. If
+still-image content is being used you can set the length for which it
+should be displayed using this control.
+</para>
+
+<para>
+<guilabel>Trim from start</guilabel> specifies the amount that should be trimmed from the start of the content.
+</para>
+
+<para>
+<guilabel>Trim from end</guilabel> specifies the amount that should be trimmed from the end of the content.
+</para>
+
+<para>
+<guilabel>Play length</guilabel> indicates how long this piece of
+content will be once the trims have been applied. This will be equal
+to the full length minus <guilabel>trim-from-start</guilabel> and minus <guilabel>trim-from-end</guilabel>.
+</para>
+
+<para>
+<guilabel>Video frame rate</guilabel> specifies the frame rate for still-image content.
+</para>
+
+<para>
+Each timecode control has a <guilabel>Set</guilabel> which you should
+click when you have entered a new value for a timecode. The
+<guilabel>Set</guilabel> button will make DCP-o-matic take account of
+any changes to the corresponding timecode.
+</para>
+
+</section>
+
+<section>
+<title>Video processing pipeline</title>
+
+<para>
+This section gives a little more detail about how DCP-o-matic process
+video as it takes it from a source and puts it into a DCP.
+</para>
+
+<para>
+Consider, as a somewhat over-the-top example, that we have a 720 x 576
+image which is letterboxed with 36 black pixels each at the top and
+bottom, and the video content within the letterbox should be presented
+in the DCP at ratio of 2.39:1 within a 1.85:1 frame (such as might
+happen with a trailer). The source image is shown in <xref
+linkend="fig-pipeline1"/>.
+</para>
+
+<figure id="fig-pipeline1">
+ <title>Example image to demonstrate video processing</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="100" fileref="diagrams/pipeline1&dia;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+DCP-o-matic runs through the following steps when preparing an image for a DCP:
+</para>
+
+<itemizedlist>
+<listitem>Crop</listitem>
+<listitem>Scale</listitem>
+<listitem>Place in container</listitem>
+</itemizedlist>
+
+<para>
+First, some amount of the image can be cropped. This is almost always
+used to remove black borders (letterboxing and/or pillarboxing) around
+images.
+</para>
+
+<para>
+In our example image, we would use 36 pixels of crop from the top and
+bottom. This would give the new image shown in <xref
+linkend="fig-pipeline2"/>.
+</para>
+
+<figure id="fig-pipeline2">
+ <title>Example image after cropping</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="100" fileref="diagrams/pipeline2&dia;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+The next step is to scale the image. Since this content should be
+presented in a 2.39:1 aspect ratio inside a 1.85:1 DCP we would select
+<guilabel>Scope</guilabel> from the <guilabel>Scale to</guilabel>
+option in the <guilabel>Video</guilabel> tab and
+<guilabel>Flat</guilabel> from the <guilabel>Container</guilabel>
+option in the <guilabel>DCP</guilabel> tab.
+</para>
+
+<para>The <guilabel>Scale to</guilabel> option should always be set to
+the aspect ratio at which the content should be seen. The
+<guilabel>Container</guilabel> option should be set to the preset that
+you want to use on the projector. Of course, these two settings will
+often be the same.
+</para>
+
+<para>
+Given the scaling and container information, DCP-o-matic will look at
+the DCP's container size, and then scale the source image up until one
+or both of its dimensions (width, height or both) fits the size of the
+container, all the while preserving the desired aspect ratio.
+</para>
+
+<para>
+In our example here, the DCP's container is specified as 1.85:1 (so
+that the DCP will play back correctly using the projector's
+‘Flat’ preset). At 2K, 1.85:1 is 1998 pixels by 1080.
+Scaling the source up whilst preserving its 1.85:1 aspect ratio will
+result in the image hitting the sides of the container first, at a
+size of 1998 x 836. This gives us a new version of the image as shown
+in <xref linkend="fig-pipeline3"/>.
+</para>
+
+<figure id="fig-pipeline3">
+ <title>Example image after cropping and scaling</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="100" fileref="diagrams/pipeline3&dia;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+The final step is to place the image into the DCP. In this case,
+since we have a 2.39:1 image that should be presented as a 1.85:1 DCP,
+we have set the <guilabel>container</guilabel> in the
+<guilabel>DCP</guilabel> tab to be Scope. Since the content has been
+scaled to 1998 x 836, and a Flat container is 1998 x 1080, there will
+be some black bars at the top and bottom of the image. DCP-o-matic
+shares out this black equally, as shown in <xref
+linkend="fig-pipeline3"/>.
+</para>
+
+<figure id="fig-pipeline4">
+ <title>Example image in the DCP</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="100" fileref="diagrams/pipeline4&dia;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+</section>
</chapter>
<para>
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
+of the film that is being encoded. If <guilabel>Use ISDCF
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>
+as-is for the name of the DCP. If <guilabel>Use ISDCF name</guilabel>
is ticked, the name that you enter will be used as part of a
-DCI-compliant name.
+ISDCF-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> check-box. The DCI name will be composed using details
+get. To use a ISDCF-compliant name, tick the <guilabel>Use ISDCF
+name</guilabel> check-box. The ISDCF 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
+can be specified in the ISDCF name details dialogue box, which you can
open by clicking on the <guilabel>Details</guilabel> button.
</para>
more detail in <xref linkend="ch-frame-rates"/>.
</para>
+<para>
+The <guilabel>Signed</guilabel> check-box sets whether or not the DCP
+is signed. This is rarely important; if in doubt, tick it.
+</para>
+
<para>
The <guilabel>Encrypted</guilabel> check-box will set whether the DCP
should be encrypted or not. If this is ticked, the DCP will require a
The <guilabel>JPEG2000 bandwidth</guilabel>; 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).
+between 50 and 250 megabits per second (Mbit/s).
</para>
<para>
</para>
<para>
-Finally, the <guilabel>scaler</guilabel> is the method that will be used to scale up
+Finally, the <guilabel>Scaler</guilabel> is the method that will be used to scale up
your content to the required size for the DCP, if required. Bicubic is a fine choice in
most situations.
</para>
DCP's creators can read them. In particular, this means copies of the
DCP can be distributed by insecure means: if an ne'er-do-well called
Mallory obtains a hard drive containing an encrypted DCP, there is no
-way that he can play it. Only those cinemas who receive a key
+way that he can play it. Only those cinemas who receive a correct key
delivery message (KDM) can play the DCP.
</para>
The first part is simple: ticking the <guilabel>Encrypted</guilabel>
box in the <guilabel>DCP</guilabel> tab of DCP-o-matic will encrypt
the DCP using a random key that DCP-o-matic generates. The key will
-be written to the film's metadata file, so that should be kept
+be written to the film's metadata file, which should be kept
secure.
</para>
<section xml:id="sec-prefs-tms">
<title>TMS</title>
+<titleabbrev xml:id="sec-prefs-tms-short">TMS preferences</titleabbrev>
<para>
The TMS tab (shown in <xref linkend="fig-prefs-tms"/>) gives some
</para>
</section>
-</section>
+<section xml:id="sec-prefs-advanced">
+<title>Advanced</title>
+<titleabbrev xml:id="sec-prefs-advanced-short">Advanced preferences</titleabbrev>
+
+<para>
+The advanced preferences are shown in <xref linkend="fig-prefs-advanced"/>.
+</para>
+
+<figure id="fig-prefs-advanced">
+ <title>Advanced preferences</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/prefs-advanced&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+<guilabel>Maximum JPEG2000 bandwidth</guilabel> specifies the maximum
+bit-rate of JPEG2000 that DCP-o-matic will allow you to create. You
+are advised to leave this at 250Mbit/s in normal use for maximum DCP
+compatibility.
+</para>
+
+<para>
+<guilabel>Allow any DCP frame rate</guilabel> removes the limits on
+the DCP video frame rates that DCP-o-matic will create. This may be
+useful for experimentation. Again, you are strongly advised to leave
+this unticked for normal use.
+</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
+DCP. It is useful to leave <guilabel>General</guilabel>,
+<guilabel>Warnings</guilabel> and <guilabel>Errors</guilabel> ticked
+as this makes the log files useful for tracking down bugs.
+</para>
+
+<para>
+The <guilabel>Timing</guilabel> checkbox will enable extra log entries
+to allow developers to investigate and optimize the speed of
+DCP-o-matic. It will significantly increase the size of the log files
+that are generated, so in normal use it is best to leave this
+unticked.
+</para>
+
+</section>
+</section>
</chapter>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en" xml:id="ch-frame-rates">
</para>
<section>
-<title>DCP rate limitations</title>
+<title>DCP frame rate limitations</title>
<para>
-There are some limitations to video and audio rates in DCPs. This is
+There are some limitations to video and audio frame rates in DCPs. This is
complicated by the fact that not all projectors will play DCPs at the
-same rates. It is possible to create a DCP which one projector will
+same frame rates. It is possible to create a DCP which one projector will
play fine, but another (of a different type) will refuse to play, or
even refuse to ingest.
</para>
audio would be running at the original speed with the video running
slowly. Hence the audio would drift slowly out of sync. To avoid
this, DCP-o-matic also resamples the audio such that the projector
-will play it too fast by the same amount. Hence it will sound
+will play it too slow by the same amount. Hence it will sound
slightly different but will remain in sync with the video.
</para>
content.
</para>
+<para>
+If you want to experiment with other non-standard frame rates, you can
+do so by ticking the <guilabel>Allow any DCP frame rate</guilabel> in
+the <guilabel>Advanced</guilabel> tab of the preferences dialogue (see the
+<xref linkend="sec-prefs-advanced" endterm="sec-prefs-advanced-short"/>). You are strongly advised to
+use this only on your own equipment, and only for experimentation
+purposes.
+</para>
+
</section>
</chapter>
</chapter>
-<chapter xml:id="ch-colour-conversions" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
-<title>Colour conversions</title>
-
-<para>
-As part of the encoding process, DCP-o-matic has to convert the colour
-space of the source files that you use into XYZ, the colour space used
-by the DCI standard.
-</para>
-
-<para>
-In order to do this, source colour is converted in three steps:
-</para>
-
-<itemizedlist>
-<listitem>Input gamma correction.</listitem>
-<listitem>Multiplication by a conversion matrix.</listitem>
-<listitem>Output gamma correction.</listitem>
-</itemizedlist>
-
-</chapter>
-
<chapter xml:id="ch-files" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<title>Generated files</title>
projects / dcpomatic.git / blobdiff