]>
<book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<!-- By good luck or good management, the scale parameter to imagedata
+ appears only to affect PDF output. HTML scaling is done in the
+ Makefile.
+-->
+
<bookinfo>
<title>DCP-o-matic</title>
<author><firstname>Carl</firstname><surname>Hetherington</surname></author>
</section>
+<section>
+<title>Acknowledgements</title>
+
+<para>
+This manual uses icons from the <ulink url="http://tango.freedesktop.org/">Tango Desktop Project</ulink>, with thanks.
+</para>
+
+</section>
</chapter>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<para>
To install DCP-o-matic on Windows, simply download the installer from
-<ulink url="http://carlh.net/software/dcpomatic">http://carlh.net</ulink>
+<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>
</section>
+<section>
+<title>Mac OS X</title>
+
+<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-matic icon to your
+<guilabel>Applications</guilabel> folder or wherever else you would
+like to install it.
+</para>
+
+</section>
+
<section>
<title>Ubuntu Linux</title>
<para>
You can install DCP-o-matic on Ubuntu 12.04 (‘Precise
-Pangolin’) or 12.10 (‘Quantal Quetzal’) using
-<code>.deb</code> packages: download the appropriate package from
-<ulink
-url="http://carlh.net/software/dcpomatic">http://carlh.net</ulink> and
+Pangolin’), 12.10 (‘Quantal Quetzal’) or 13.04
+(‘Raring Ringtail’) 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.
</para>
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:dcpomatic@carlh.net">mailing
+know via the <ulink url="mailto:carl@dcpomatic.com">mailing
list</ulink> and I will see about building some packages.
</para>
<para>
Once you have installed the development packages for the dependencies,
download the source code from <ulink
-url="http://carlh.net/software/dcpomatic">http://carlh.net</ulink>,
+url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>,
unpack it and run the following commands from inside the source
directory:
</para>
<para>
In this chapter we will see how to create a video DCP using
-DCP-o-matic. We will gloss over some of the finer details, which are
-explained in later chapters.
+DCP-o-matic. We will gloss over the details and look at the basics.
</para>
<section>
<para>
Now, start DCP-o-matic and its window will open. First, we will
create a new ‘film’. A ‘film’ is how DCP-o-matic refers to
-a piece of content, along with some settings, which we will make into
+some pieces of content, along with some settings, which we will make into
a DCP. DCP-o-matic stores its data in a folder on your disk while it
creates the DCP. You can create a new film by selecting
<guilabel>New</guilabel> from the <guilabel>File</guilabel> menu, as
shown in <xref linkend="fig-file-new"/>.
</para>
-<figure id="fig-file-new">
+<figure id="fig-file-new">
<title>Creating a new film</title>
<mediaobject>
<imageobject>
linkend="fig-video-new-film"/>.
</para>
-<figure id="fig-video-new-film">
+<figure id="fig-video-new-film">
<title>Dialogue box for creating a new film</title>
<mediaobject>
<imageobject>
will write its working files.
</para>
-<para>
-If you always create your DCPs in a particular folder, you can use
-DCP-o-matic's <guilabel>Preferences</guilabel> to make life a little
-easier by setting the default folder that DCP-o-matic will offer in this dialogue.
-See <xref linkend="ch-preferences"/>.
-</para>
-
</section>
<section>
-<title>Selecting content</title>
+<title>Adding content</title>
<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 a file chooser will
-open for you to select the content file to use, as shown in <xref
+The next step is to add the content that you want to use. DCP-o-matic
+can make DCPs from multiple pieces of content, but in this simple
+example we will just use a single piece. Click the <guilabel>Add
+file(s)...</guilabel> button, as shown in <xref
+linkend="fig-add-file"/>, 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>
-<figure id="fig-click-content-selector">
- <title>Opening the content selector</title>
+<figure id="fig-add-file">
+ <title>Adding content files</title>
<mediaobject>
<imageobject>
- <imagedata fileref="screenshots/click-content-selector&scs;"/>
+ <imagedata fileref="screenshots/add-file&scs;"/>
</imageobject>
</mediaobject>
</figure>
When you do this, DCP-o-matic will take a look at your file. After a
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"/>.
+the right of the window, as shown in <xref linkend="fig-examine-content"/>.
</para>
-<figure id="fig-examine-thumbs">
+<figure id="fig-examine-content">
<title>Examining the content</title>
<mediaobject>
<imageobject>
- <imagedata fileref="screenshots/examine-thumbs&scs;"/>
+ <imagedata fileref="screenshots/examine-content&scs;"/>
</imageobject>
</mediaobject>
</figure>
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>.
+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>
+
+
<section>
-<title>Setting up</title>
+<title>Making the DCP</title>
+
+<para>In most cases, some adjustments would be made to DCP-o-matic's
+settings once the content has been added. For our simple test,
+however, the default values will suffice, so we can go straight onto
+making the DCP.</para>
<para>
-Now there are a few things to set up to describe how the DCP should be
-created. The settings are divided into four tabs: film, video, audio and subtitles.
+Choose <guilabel>Make DCP</guilabel> from the
+<guilabel>Jobs</guilabel> menu. DCP-o-matic will encode your DCP.
+This may take some time (many hours in some cases). While the job is
+in progress, DCP-o-matic will update you on how it is getting on with
+the progress bar in the bottom of its window, as shown in <xref
+linkend="fig-making-dcp"/>.
</para>
-<section>
-<title>Film tab</title>
+<figure id="fig-making-dcp">
+ <title>Making the DCP</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="30" fileref="screenshots/making-dcp&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+When it has finished, the DCP will end up on your disk inside the
+film's folder. You can then copy this to a projector via a USB
+stick, hard-drive or network connection. See <xref
+linkend="ch-files"/> for details about the files that DCP-o-matic creates.
+</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
+DCP-o-matic. See the preferences in <xref linkend="sec-prefs-tms"/>.
+</para>
+
+</section>
+</chapter>
+
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<title>Creating a still-image DCP</title>
+
+<para>
+DCP-o-matic can also be used to create DCPs of one or more still images, perhaps
+for an advertisement or an on-screen announcement. This chapter shows you
+how to do it.
+</para>
+
+<para>
+As with video DCPs, the first step is to create a new
+‘Film’; select <guilabel>New</guilabel> from the
+<guilabel>File</guilabel> menu and the new film dialogue will open as
+shown in <xref linkend="fig-still-new-film"/>.
+</para>
+
+<figure id="fig-still-new-film">
+ <title>Dialogue box for creating a new film</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/still-new-film&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
<para>
-The ‘film’ tab contains settings that pertain to the whole film, as shown in <xref linkend="fig-film-tab"/>.
+Enter a name and click <guilabel>OK</guilabel>. Now we need to add
+the content. As before, click <guilabel>Add file(s)...</guilabel>.
+For our example, we will add a single image file, as shown in <xref
+linkend="fig-still-select-content-file"/>.
</para>
-<figure id="fig-film-tab">
- <title>Film settings tab</title>
+<figure id="fig-still-select-content-file">
+ <title>Selecting a still content file</title>
<mediaobject>
<imageobject>
- <imagedata fileref="screenshots/film-tab&scs;"/>
+ <imagedata fileref="screenshots/still-select-content-file&scs;"/>
</imageobject>
</mediaobject>
</figure>
<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
-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.
+As with video DCPs, most of the default settings will be fine for a
+simple test. The one thing that you might wish to change is the
+length of the still. Select the <guilabel>Timing</guilabel> tab and
+you will see a <guilabel>Length</guilabel> setting, as shown in <xref
+linkend="fig-timing-tab"/>.
</para>
+<figure id="fig-timing-tab">
+ <title>The timing tab</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/timing-tab&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
<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.
+This length is a ‘timecode’: it consists of four numbers.
+The first is hours, the second minutes, the third seconds, and the
+fourth frames. Enter the duration that you want and then click <guilabel>Set</guilabel>.
</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.
+Finally, as with video, you can choose <guilabel>Make DCP</guilabel>
+from the <guilabel>Jobs</guilabel> menu to create your DCP. This will
+be much quicker than creating a video DCP, as DCP-o-matic only needs
+to encode a single frame which it can then repeat.
</para>
+</chapter>
+
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<title>Content settings</title>
+
<para>
-The <guilabel>Trust content's header</guilabel> button starts off
-checked, and this means that DCP-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 DCP-o-matic will run through the content
-to find its exact length. This may take a while for large pieces of content.
+The previous chapters showed DCP generation using the default
+settings. DCP-o-matic offers a range of features to adjust the
+content that goes into your DCP, and this chapter describes those features in
+detail.
</para>
+<section>
+<title>Adding and removing content</title>
+
<para>
-Next up is the content type. This can be
-‘feature’, ‘trailer’ or whatever; select the
-required type from the drop-down list.
+At the top of the <guilabel>Content</guilabel> tab is a list of the
+content that will go into our DCP. There can be as many pieces of
+content as you like, and they can be of the following types:
+</para>
+
+<itemizedlist>
+<listitem>Movie — a file containing some video, probably some
+audio and possibly some subtitles; for example, a MOV, MP4 or VOB.
+</listitem>
+
+<listitem>Sound — a file containing one or more channels of
+audio; for example, a WAV or AIFF file.
+</listitem>
+
+<listitem>Still image — a file containing a single still image; for
+example, a JPEG, PNG or TIFF file.
+</listitem>
+
+<listitem>Moving image — a directory containing many still
+images which should be treated as the frames of a video.
+</listitem>
+</itemizedlist>
+
+<para>
+To add one or more movie, sound or still-image files, select
+<guilabel>Add file(s)...</guilabel> and choose them from the selector.
+To add a directory of images, choose <guilabel>Add
+directory...</guilabel> and do similar.
+</para>
+
+<para>
+You can remove a piece of content by clicking on its name and then
+clicking the <guilabel>Remove</guilabel> button.
+</para>
+
+</section>
+<section>
+<title>Content Properties</title>
+
+<para>
+Below the content list are the controls to set content properties. To
+adjust the properties for a piece of content, click its name in the
+content list. The content property controls will then become active
+for that piece of content.
</para>
<para>
-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.
+The content properties are split up into four sections:
+<guilabel>Video</guilabel>, <guilabel>Audio</guilabel>,
+<guilabel>Subtitles</guilabel> and <guilabel>Timing</guilabel>. Not
+all of these sections will be active for all content types. The controls
+in each section are described below.
</para>
</section>
<section>
-<title>Video tab</title>
+<title>Video</title>
<para>
-This tab contains settings related to the picture in your DCP, as shown in <xref linkend="fig-video-tab"/>.
+The <guilabel>Video</guilabel> tab controls properties of the image, 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;"/>
+ <imagedata fileref="screenshots/video-tab&scs;"/>
</imageobject>
</mediaobject>
</figure>
+<section>
+<title>Image type</title>
+
<para>
-The first option on this tab is the format. This will govern the
-shape that DCP-o-matic will make your image into. Select the aspect
-ratio that your content should be presented in. The ‘4:3 within
-Flat’ and ‘16:9 within Flat’ 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 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
+left-right pair, as shown in <xref linkend="fig-3d-left-right"/>.
</para>
+<figure id="fig-3d-left-right">
+ <title>3D left/right image type</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata scale="100" fileref="diagrams/3d-left-right&dia;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
<para>
-The remaining options can often be left alone, but may sometimes be
-useful. The ‘crop’ 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 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.
+This option can be used to generate a 3D DCP. Other means of creating
+3D will be added in the future.
</para>
+</section>
+
+
+<!-- ============================================================== -->
+<section>
+<title>Filtering</title>
+
<para>
The ‘filters’ settings allow you to apply various video
filters to the image. These may be useful to try to improve
-poor-quality sources like DVDs. We will discuss filtering later in the manual.
-<!-- XXX: link -->
+poor-quality sources like DVDs. You can set up the filters by clicking the
+<guilabel>Edit</guilabel> button next to the filters entry in the
+setup area of the DCP-o-matic window; this opens the filters selector
+as shown in <xref linkend="fig-filters"/>.
</para>
+<figure id="fig-filters">
+ <title>Filters selector</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/filters&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
<para>
-The ‘scaler’ is the method that will be used to scale up
-your content to the required size for the DCP, if required. We will
-discuss the options in more detail later; Bicubic is a fine choice in
-most situations.
-<!-- XXX: link -->
+After changing the filters setup, you will need to regenerate the DCP
+to see the effect on the cinema screen. The preview in DCP-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>
+
+
+<!-- ============================================================== -->
+<section>
+<title>Other settings</title>
<para>
-The ‘colour look-up table’ specifies the colour space that
-your input content will be expected to be in. If in doubt, leave it
-set to ‘sRGB’.
+The ‘crop’ 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 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>
-Finally, the ‘JPEG2000 bandwidth’ 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).
+The <guilabel>Scale to</guilabel> option governs the shape that
+DCP-o-matic will scale the content's image into. Select the aspect
+ratio that your content should be presented in.
+</para>
+
+</section>
+<section>
+<title>Video description</title>
+
+<para>
+At the bottom of the video tab is a short description of what will
+happen to your video with the current settings. In the example of
+<xref linkend="fig-video-tab"/>, DCP-o-matic is telling you that the
+video file is 1920x1080 pixels (which is a ratio of 1.78:1). Since
+the controls specify ‘Flat’ for the ratio, DCP-o-matic
+scales the content image to 1998x1080, which is the DCI flat
+resolution at 2K.
+</para>
+
+<para>
+This description also gives the frame rate of the content and what
+will happen to it when it is played at the DCP's frame rate.
+<!-- XXX: link to more detailed discussion of this -->
</para>
</section>
+</section>
+
<section>
-<title>Audio tab</title>
+<title>Audio</title>
<para>
-This tab contains settings related to the sound in your DCP, as shown in <xref linkend="fig-audio-tab"/>.
+The <guilabel>Audio</guilabel> tab controls properties of the image, 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;"/>
+ <imagedata fileref="screenshots/audio-tab&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<section>
+<title>Show audio</title>
+
+<para>
+The <guilabel>Show Audio</guilabel> button will instruct DCP-o-matic
+to examine the audio in your content and plot a graph of its level
+over time. This can be useful for getting a rough idea of how loud
+the sound will be in the cinema auditorium. A typical plot is shown
+in <xref linkend="fig-audio-plot"/>
+</para>
+
+<figure id="fig-audio-plot">
+ <title>Audio plot</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/audio-plot&scs;"/>
</imageobject>
</mediaobject>
</figure>
+<para>
+The plot gives the audio level (vertical axis, in dB) with time
+(horizontal axis). 0dB represents full scale, so if there is anything
+near this you are in danger of clipping the projector's audio outputs.
+</para>
+
+<para>
+There are two plot types: the peak level and the RMS, which can be
+shown or hidden using the check-boxes on the right hand side of the
+window.
+</para>
+
+<para>
+The channel check-boxes will show or hide the plot(s) for
+the corresponding channels in the DCP.
+</para>
+
+<para>
+The smoothing slider applies a variable degree of temporal smoothing
+to the plots, which can make them easier to read in some cases.
+</para>
+
+<para>
+Obviously the audio plot is no substitute for listening in an
+auditorium, but it can be useful to get levels in the right rough area.
+</para>
+
+</section>
+
+<section>
+<title>The audio map</title>
+
+<para>
+The section at the bottom of the audio tab is the ‘audio
+map’. This governs how sound from the content will be arranged
+in the DCP.
+</para>
+
+<para>
+Down the left-hand side of the map is the list of audio channels in
+the currently-selected piece of content. Along the top is each
+channel in the DCP. A checked box means that the corresponding
+content channel will be copied into the corresponding DCP channel.
+</para>
+
+<para>
+Consider, for example, the case in <xref linkend="fig-audio-map-eg1"/>.
+</para>
+
+<figure id="fig-audio-map-eg1">
+ <title>Audio map example 1</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/audio-map-eg1&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+Here, we have two channels in the source which are mapped to left and
+right, respectively, in the DCP. If we modify that as in <xref
+linkend="fig-audio-map-eg2"/>
+</para>
+
+<figure id="fig-audio-map-eg2">
+ <title>Audio map example 2</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/audio-map-eg2&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+we now have the content's streams mapped to left and right and also
+mixed together and placed in the DCP's centre channel.
+</para>
+
+<figure id="fig-audio-map-eg3">
+ <title>Audio map example 3</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/audio-map-eg3&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+As a final example, the map in <xref linkend="fig-audio-map-eg3"/>
+shows the mapping of a 5.1 source into a 5.1 DCP.
+</para>
+
+</section>
+
+<section>
+<title>Other controls</title>
<para>
‘Audio Gain’ is used to alter the volume of the
soundtrack. The specified gain (in dB) will be applied to each sound
-channel before it is written to the DCP.
+channel of your content before it is written to the DCP.
</para>
<para>
</para>
<para>
-‘Audio Delay’ is used to adjust the synchronisation
+<guilabel>Audio Delay</guilabel> is used to adjust the synchronisation
between audio and video. A positive delay will move the audio later
with respect to the video, and a negative delay will move it earlier.
</para>
<para>
-By default the <guilabel>Use content‘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.
+The <guilabel>Audio Stream</guilabel> option allows you to select the
+audio stream to use, if the content contains more than one. There
+might be different soundtrack languages, for example.
</para>
-<para>
-Note that if your content's audio is mono, DCP-o-matic will place it
-in the centre channel in the DCP.
-</para>
+</section>
+</section>
-<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>
+<title>Subtitles</title>
<para>
-This tab contains settings related to subtitles in your DCP, as shown in <xref linkend="fig-subtitles-tab"/>.
+The subtitles tab contains settings related to subtitles in your
+content, 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;"/>
+ <imagedata fileref="screenshots/subtitles-tab&scs;"/>
</imageobject>
</mediaobject>
</figure>
</para>
<para>
-Future versions of DCP-o-matic will hopefully include the option to
+All being well, future versions of DCP-o-matic will include the option to
use text subtitles (as is the norm with most professionally-mastered
DCPs).
</para>
-</section>
</section>
-<section>
-<title>Making the DCP</title>
+<!-- XXX: timing tab -->
+
+</chapter>
+
+<chapter xml:id="ch-dcp" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<title>DCP settings</title>
<para>
-Now that we have set everything up, choose <guilabel>Make
-DCP</guilabel> from the <guilabel>Jobs</guilabel> menu. DCP-o-matic
-will encode your DCP. This may take some time (many hours in some
-cases). While the job is in progress, DCP-o-matic will update you on
-how it is getting on with the progress bar in the bottom of its window, as shown in <xref linkend="fig-making-dcp"/>.
+This chapter describes the settings that apply to the whole DCP. The
+controls for these settings are in the <guilabel>DCP</guilabel> tab of
+the main window, as shown in <xref linkend="fig-dcp-tab"/>.
</para>
-<figure id="fig-making-dcp">
- <title>Making the DCP</title>
+<figure id="fig-dcp-tab">
+ <title>DCP settings tab</title>
<mediaobject>
<imageobject>
- <imagedata fileref="screenshots/making-dcp&scs;"/>
+ <imagedata fileref="screenshots/dcp-tab&scs;"/>
</imageobject>
</mediaobject>
</figure>
<para>
-When it has finished, the DCP will end up on your disk inside the
-film's directory. You can then copy this to a projector via a USB
-stick, hard-drive or network connection.
+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>
-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 <xref linkend="sec-tms-upload"/>.
+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>
-</section>
-</chapter>
-
-
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
-<title>Creating a still-image DCP</title>
+<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>
-DCP-o-matic can also be used to create DCPs of a still image, perhaps
-for an advertisement or an on-screen announcement. This chapter shows you
-how to do it.
+The <guilabel>Container</guilabel> option sets the ratio of the image
+in the DCP. If this ratio is different to the ratio used for any
+content, DCP-o-matic will pad the content with black. In simple cases
+this should be set to the same ratio as that for the the primary piece
+of video content. Alternatively, you might want to pillarbox a small
+format into a Flat container: in this case, select the small format
+for the content's ratio and ‘Flat’ for the DCP.
</para>
<para>
-As with video DCPs, the first step is to create a new
-‘Film’; select <guilabel>New</guilabel> from the
-<guilabel>File</guilabel> menu and the new film dialogue will open as
-shown in <xref linkend="fig-still-new-film"/>.
+Next up is the content type. This can be
+‘feature’, ‘trailer’ or whatever; select the
+required type from the drop-down list.
</para>
-<figure id="fig-still-new-film">
- <title>Dialogue box for creating a new film</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="screenshots/still-new-film&scs;"/>
- </imageobject>
- </mediaobject>
-</figure>
+<para>
+The <guilabel>Frame Rate</guilabel> control sets the frame rate of
+your DCP. This can be a little tricky to get right. Ideally, you
+want it to be the same as the video content that you are using. If it
+is not the same, DCP-o-matic must resort to some tricks to alter your
+content to fit the specified frame rate. Frame rates are discussed in more detail later.
+<!--- XXX: link -->
+</para>
<para>
-Enter a name and click <guilabel>OK</guilabel>. Then we set up the
-content; click the content selector as before, and this time we will
-choose an image file, as shown in <xref
-linkend="fig-still-select-content-file"/>.
+The <guilabel>Use best</guilabel> button sets the DCP video frame rate
+to what DCP-o-matic thinks is the best given the content that you have
+added.
</para>
-<figure id="fig-still-select-content-file">
- <title>Selecting a still content file</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="screenshots/still-select-content-file&scs;"/>
- </imageobject>
- </mediaobject>
-</figure>
+<para>
+The <guilabel>Audio Channels</guilabel> control sets the number of
+audio channels that the DCP will have. If the DCP has any channels
+for which there is no content audio they will be replaced by silence.
+</para>
<para>
-Setting up for a still image DCP is somewhat simpler than for a video;
-the tabs are all the same, but many options are removed and a few are added.
+The <guilabel>3D</guilabel> button will set your DCP to 3D mode if it
+is checked. A 3D DCP will then be created, and any 2D content will be
+made 3D compatible by repeating the same frame for both left and right
+eyes. A 3D DCP can be played back on many 3D systems (e.g. Dolby 3D,
+Real-D etc.) but not on a 2D system.
</para>
<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 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 DCP-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.
+The <guilabel>Resolution</guilabel> tab allows you to choose the
+resolution for your DCP. Use 2K unless you have content that is of
+high enough resolution to be worth presenting in 4K.
</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.
+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).
</para>
<para>
-Finally, as with video, you can choose <guilabel>Make DCP</guilabel>
-from the <guilabel>Jobs</guilabel> menu to create your DCP. This will
-be much quicker than creating a video DCP, as DCP-o-matic only needs
-to encode a single frame which it can then repeat.
+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>
</chapter>
<para>
The preferences dialogue is opened by choosing
<guilabel>Preferences...</guilabel> from the <guilabel>Edit</guilabel>
-menu. The dialogue is shown in <xref linkend="fig-prefs"/>.
+menu. The dialogue is split into four tabs.
</para>
-<figure id="fig-prefs">
- <title>Preferences</title>
+<section>
+<title>Miscellaneous</title>
+
+<para>
+The miscellaneous tab is shown in <xref linkend="fig-prefs-misc"/>.
+</para>
+
+<figure id="fig-prefs-misc">
+ <title>Miscellaneous preferences</title>
<mediaobject>
<imageobject>
- <imagedata fileref="screenshots/prefs&scs;"/>
+ <imagedata fileref="screenshots/prefs-misc&scs;"/>
</imageobject>
</mediaobject>
</figure>
<section>
-<title>TMS setup</title>
+<title>Language</title>
<para>
-The first part of the dialogue gives some options for specifying
-details about your TMS. If you do this, and your TMS accepts SSH
-connections, you can upload DCPs directly from DCP-o-matic to the TMS.
-This is discussed in <xref linkend="sec-tms-upload"/>.
+If you tick the <guilabel>Set Language</guilabel> checkbox and choose
+a language from the list, that language will be used for DCP-o-matic.
+You will need to restart DCP-o-matic to see the new language.
</para>
<para>
-<guilabel>TMS IP address</guilabel> should be set to the IP address of
-your TMS, <guilabel>TMS target path</guilabel> to the place that DCPs
-should be uploaded to (which will be relative to the home directory of
-the SSH user). Finally, the user name and password are the
-credentials required to log into the TMS via SSH.
+The translations for DCP-o-matic have been contributed by helpful
+users. If your language is not on the last, head to <ulink
+url="http://dcpomatic.com/i18n.php">the DCP-o-matic website</ulink> to
+read about how to contribute a translation.
</para>
</section>
</section>
<section>
-<title>Default directory for new films</title>
+<title>Defaults</title>
<para>
-This is the directory which DCP-o-matic will suggest initially as a place to put new films.
+The next few options allow you to set up default values for several
+properties of new films that you create.
</para>
+</section>
</section>
<section>
-<title>A/B options</title>
+<title>Encoding servers</title>
<para>
-These options are for DCP-o-matic's special mode of making A/B
-comparison DCPs for checking the performance of video filters. Their
-use is described in <xref linkend="sec-ab"/>.
+The encoding servers tab is shown in <xref linkend="fig-prefs-servers"/>.
</para>
-</section>
-
-<section>
-<title>Encoding servers</title>
+<figure id="fig-prefs-servers">
+ <title>Encoding servers preferences</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/prefs-servers&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
<para>
If you have spare machines sitting around on your network not doing
</section>
-</section>
-</chapter>
+<section>
+<title>Metadata</title>
-<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
-<title>Advanced topics</title>
+<para>
+The metadata tab is shown in <xref linkend="fig-prefs-metadata"/>.
+</para>
+
+<figure id="fig-prefs-metadata">
+ <title>Metadata preferences</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="screenshots/prefs-metadata&scs;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
-<para>This chapter describes some parts of DCP-o-matic that are
-probably not essential, but which you might find useful in some
-circumstances.
+<para>
+This allows you to set up a couple of identifiers that are written
+into the DCP. The default values should cause no problems.
</para>
-<section>
-<title>Filtering</title>
+</section>
+
+<section xml:id="prefs-tms">
+<title>TMS</title>
<para>
-DCP-o-matic offers a variety of filters that can be applied to your
-video content. You can set up the filters by clicking the
-<guilabel>Edit</guilabel> button next to the filters entry in the
-setup area of the DCP-o-matic window; this opens the filters selector
-as shown in <xref linkend="fig-filters"/>.
+The TMS tab (shown in <xref linkend="fig-prefs-tms"/>) gives some
+options for specifying details about your theatre management system
+(TMS). If you do this, and your TMS accepts SSH connections, you can
+upload DCPs directly from DCP-o-matic to the TMS using the
+<guilabel>Send DCP to TMS</guilabel> option in the
+<guilabel>Jobs</guilabel> menu.
</para>
-<figure id="fig-filters">
- <title>Filters selector</title>
+<figure id="fig-prefs-tms">
+ <title>TMS preferences</title>
<mediaobject>
<imageobject>
- <imagedata fileref="screenshots/filters&scs;"/>
+ <imagedata fileref="screenshots/prefs-tms&scs;"/>
</imageobject>
</mediaobject>
</figure>
<para>
-After changing the filters setup, you will need to regenerate the DCP
-to see the effect on the cinema screen. The preview in DCP-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!
+<guilabel>TMS IP address</guilabel> should be set to the IP address of
+your TMS, <guilabel>TMS target path</guilabel> to the place that DCPs
+should be uploaded to (which will be relative to the home directory of
+the SSH user). Finally, the user name and password are the
+credentials required to log into the TMS via SSH.
</para>
+</section>
+
</section>
+</chapter>
+
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<title>Frame rates</title>
+
+<para>
+In an ideal world, a DCP would be created using content at the same
+video frame and audio sampling rates as the DCP. This is not,
+however, always possible.
+</para>
<section>
-<title>Scaling</title>
+<title>DCP rate limitations</title>
<para>
-If your source material is not of the DCI-specified size, or if it
-uses non-square pixels, DCP-o-matic will need to scale it. The
-algorithm used to scale is set up by the <guilabel>Scaler</guilabel>
-entry in the film setup area. We think ‘Bicubic’ is the
-best all-round option, but tests are ongoing.
+There are some limitations to video and audio 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
+play fine, but another (of a different type) will refuse to play, or
+even refuse to ingest.
+</para>
+
+<section>
+<title>Guaranteed rates</title>
+
+<para>
+The only rates that are (pretty much) guaranteed to work on all DCI
+projectors is 24 frames per second (fps) for video and 48kHz or 96kHz
+for audio. If you are sending your DCPs to unknown places it wise to
+consider using these rates if at all possible.
</para>
</section>
-<section xml:id="sec-tms-upload">
-<title>TMS upload</title>
+<section>
+<title>Other often-supported rates</title>
+<para>
+Many projectors now in the wild support additional video frame rates:
+25, 30 and 48 fps.
+</para>
+</section>
+
+<section>
+<title>Adapting content to fit the DCP rate</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 buy choosing <guilabel>Send DCP to TMS</guilabel>
-from the <guilabel>Jobs</guilabel> menu.
+DCP-o-matic has a few tricks to allow you to use content that is not
+in one of the ‘approved’ rates.
</para>
-</section>
+<para>
+Audio is easy: DCP-o-matic can resample to 48kHz from any source rate
+with minimal loss in quality.
+</para>
+<para>
+Video rate conversion is harder. DCP-o-matic's basic strategy to deal
+with a non-supported content rate is to run it at the wrong speed, and
+to adjust the audio to keep it in sync.
+</para>
-<section xml:id="sec-ab">
-<title>A/B comparison</title>
+<para>Let us consider the example of a 25fps source for which you want
+to create a 24fps DCP. DCP-o-matic will put the frames from the
+source directly into the DCP without modification, but will tell the
+projector to play them back at 24fps. This means that the DCP's video
+will run slightly slower than the original.
+</para>
<para>
-When evaluating the effects of different filters or scalers on the
-image quality, A/B mode might be useful. In this mode, DCP-o-matic
-will generate a DCP where the left half of the image uses some
-‘reference’ filtering and scaling, and the right half of
-the image uses a different set of filters and a different scaler.
-This DCP can then be played back on a projector and the image quality
-evaluated.
+If DCP-o-matic did nothing else, the result of this would be that the
+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
+slightly different but will remain in sync with the video.
</para>
<para>
-To enable A/B mode, click the A/B checkbox in the setup area of the
-DCP-o-matic window. When you generate your DCP, the left half of the
-screen will use the filters and scaler specified in the <xref
-linkend="ch-preferences">preferences</xref> dialogue, and the right
-half will use the filters and scaler specified in the film setup.
+For very low or high frame rates, DCP-o-matic can also skip or duplicate frames.
</para>
+</section>
</section>
-<section xml:id="sec-servers">
+<section>
+<title>Setting up</title>
+
+<para>
+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 DVD-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.
+</para>
+
+<para>
+After this, the <guilabel>Video</guilabel> tab for each piece of
+content will give a summary of what DCP-o-matic is doing with that
+content.
+</para>
+
+</section>
+
+</chapter>
+
+
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<title>Encoding servers</title>
<para>
offload some of the time-consuming JPEG2000 encoding to any number of
other machines on a network. To do this, one ‘master’
machine runs DCP-o-matic, and the ‘server’ machines run
-a small program called ‘servomatic’.
+a small program called ‘dcpomatic_server’.
</para>
<section>
<para>
There are two options for the encoding server;
-<code>servomatic_cli</code>, which runs on the command line, and
-<code>servomatic_gui</code>, which has a simple GUI. The command line
+<code>dcpomatic_server_cli</code>, which runs on the command line, and
+<code>dcpomatic_server</code>, which has a simple GUI. The command line
version is well-suited to headless servers, especially on Linux, and
the GUI version works best on Windows where it will put an icon in the
system tray.
</para>
<programlisting>
-servomatic_cli
+dcpomatic_server_cli
</programlisting>
<para>
</para>
<programlisting>
-servomatic_cli -t 4
+dcpomatic_server_cli -t 4
</programlisting>
<para>
</para>
</section>
-</section>
+
+</chapter>
+
+<chapter xml:id="ch-files" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<title>Generated files</title>
+
+<para>
+DCP-o-matic generates a number of files as it makes a DCP. <xref
+linkend="fig-file-structure"/> shows the files that might be generated
+after you have created a DCP for a film called ‘DCP Test’.
+</para>
+
+<figure id="fig-file-structure">
+ <title>Creating a new film</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="diagrams/file-structure&dia;"/>
+ </imageobject>
+ </mediaobject>
+</figure>
+
+<para>
+The <code>DCP Test</code> folder is the one that you specify when you
+select the <guilabel>New Film</guilabel> option from DCP-o-matic's
+menu. Everything is stored inside this folder.
+</para>
+
+<para>
+DCP-o-matic generates some working files as it goes along. These are as follows:
+<itemizedlist>
+
+<listitem><code>log</code> is a list of notes that DCP-o-matic makes as it goes
+along. This can be useful for debugging purposes if something goes
+wrong.</listitem>
+
+<listitem><code>metadata</code> stores the settings that you have made
+for this film: things like cropping, output format and so on.</listitem>
+
+<listitem><code>video</code> is where DCP-o-matic writes the DCP's
+video data as it encodes it.</listitem>
+
+<listitem><code>analysis</code> is used to keep the results of audio analysis runs.</listitem>
+
+<listitem><code>info</code> contains details of each video frame that
+DCP-o-matic has written so far. This is used when an encoding
+operation is interrupted and DCP-o-matic must resume it.</listitem>
+</itemizedlist>
+</para>
+
+<para>
+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
+(<code>DCP-TEST_EN-XX_...</code>) is what you should ingest, or pass
+to the cinema which is showing your DCP.
+</para>
</chapter>
projects / dcpomatic.git / blobdiff