X-Git-Url: https://git.carlh.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fdcpomatic.xml;h=3df603a85d55e83261011e911b730732eebaa094;hb=b0297f77b23099a52d37becfa45930ee730bda4b;hp=cd27bef726f816e4e104ce2d7dfca74308ea9527;hpb=0b6c6de07f9a3aa28c2e8ca8ef30340e3fa1bfc6;p=dcpomatic.git
diff --git a/doc/manual/dcpomatic.xml b/doc/manual/dcpomatic.xml
index cd27bef72..3df603a85 100644
--- a/doc/manual/dcpomatic.xml
+++ b/doc/manual/dcpomatic.xml
@@ -16,7 +16,7 @@
-->
-DCP-o-matic
+DCP-o-matic users' manualCarlHetherington
@@ -39,12 +39,6 @@ and AVI, or still images. The resulting DCPs will play on modern digital
cinema projectors.
-
-You might find it useful to make DVDs easier to present, to encode
-independently-shot feature films, or to generate local advertising for
-your cinema.
-
-
@@ -53,7 +47,9 @@ your cinema.
Licence
-DCP-o-matic is licensed under the GNU GPL.
+DCP-o-matic is free and open-source and is licensed under the GNU
+GPL.
@@ -70,6 +66,8 @@ This manual uses icons from the Tango
+
+
Installation
@@ -117,8 +115,9 @@ like to install it.
You can install DCP-o-matic on Ubuntu 12.04 (‘Precise
-Pangolin’) or 14.04 (‘Trusty Tahr’) using .deb packages: download the
-appropriate package from .deb packages:
+download the appropriate package from http://dcpomatic.com/ and
double-click it. Ubuntu will install the necessary bits and pieces
and set DCP-o-matic up for you.
@@ -131,7 +130,7 @@ and set DCP-o-matic up for you.
Debian Linux
-Packages are available for Debian 7 (squeeze) and unstable (sid) from http://dcpomatic.com/.
@@ -163,10 +162,11 @@ thanks to Stefan Karner.
Other Linux distributions
-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 by email and I will see about building some packages.
+Installation on other Linux systems (for which no packages are
+available) is quite hard; you will have to compile it from source. If
+you are using distribution for which no packages are available, do let
+me know by email and I
+will look into providing packages on the website.
@@ -181,7 +181,6 @@ The following dependencies are required:
libsshGTK (on Linux)wxWidgets
-libquickmaillibxml++xmlseccurl
@@ -210,7 +209,7 @@ With any luck, this will build and install DCP-o-matic on your system. To run i
-dcpomatic
+dcpomatic2
@@ -254,11 +253,11 @@ shown in .
@@ -268,11 +267,11 @@ linkend="fig-video-new-film"/>.
@@ -302,21 +301,21 @@ select the content file to use, as shown in .
-
- Adding content files
+
-
- Selecting a video content file
+
@@ -332,19 +331,19 @@ has finished), you can look through your content using the slider to
the right of the window, as shown in .
-
+
Dragging the slider will move through your video. You can also click
-the Play button to play the content back. Note
-that there will be no sound, and playback might not be entirely
+the Play 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
@@ -380,9 +379,9 @@ linkend="fig-making-dcp"/>.
@@ -394,9 +393,10 @@ linkend="ch-files"/> for details about the files that DCP-o-matic creates.
-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 .
+Alternatively, if you have a projector or Theatre Management System
+(TMS) that is accessible via SCP across your network, you can upload
+the content directly from DCP-o-matic. See the in .
@@ -420,12 +420,12 @@ As with video DCPs, the first step is to create a new
shown in .
-
- Dialogue box for creating a new film
+
@@ -436,12 +436,12 @@ For our example, we will add a single image file, as shown in .
-
- Selecting a still content file
+
@@ -449,16 +449,16 @@ linkend="fig-still-select-content-file"/>.
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 Timing tab and
-you will see a Length setting, as shown in Play length setting, as shown in .
-
+
@@ -500,7 +500,7 @@ content as you like, and they can be of the following types:
Movie — a file containing some video, probably some
-audio and possibly some subtitles; for example, a MOV, MP4 or VOB.
+audio and possibly some embedded subtitles; for example, a MOV, MP4 or VOB.
Sound — a file containing one or more channels of
@@ -514,13 +514,26 @@ example, a JPEG, PNG or TIFF file.
Moving image — a directory containing many still
images which should be treated as the frames of a video.
+
+Subtitle — a file containing subtitle which will be
+superimposed on the image of the DCP. These can be
+.srt or .xml
+files.
+
+DCP — an existing DCP.
-To add one or more movie, sound or still-image files, select
+To add one or more movie, sound, still-image or subtitle files, select
Add file(s)... and choose them from the selector.
-To add a directory of images, choose Add
-directory... and do similar.
+
+
+
+To add a directory (folder) of images or a DCP, choose Add
+folder... and choose the directory from the selector. If
+you select a folder of images DCP-o-matic will open a small dialogue
+box where you can enter the frame rate that the image sequence should
+be run at.
@@ -530,6 +543,30 @@ clicking the Remove button.
+
+
+Adding existing DCPs
+
+Adding existing DCPs to a DCP-o-matic film is a little different
+to adding other types of content. Most content has to be converted to
+JPEG2000, the compression scheme used by DCPs, which is a very
+time-consuming process. Existing DCPs are already in JPEG2000 format
+so do not require conversion. This means that, provided no settings
+such as crop are used on the DCP content, picture and sound data will
+be passed from existing to new DCP unaltered.
+
+
+Encrypted DCPs that are added as content will require a KDM
+targeted at DCP-o-matic so that DCP-o-matic can decrypt them. You
+should ask the creator of the imported DCP to provide a KDM for
+DCP-o-matic's decryption certificate, which can be obtained by
+clicking Export DCP decryption certificate...
+from the Keys tab of the
+Preferences dialog (see ).
+
+
+
@@ -542,6 +579,13 @@ content list. The content property controls will then become active
for that piece of content.
+
+If you want to change the properties for multiple pieces of content at
+the same time, select the content in the list by clicking the first
+piece then clicking the other pieces with shift key
+held down. Note that not all settings can be changed in this way.
+
+
The content properties are split up into four sections:
Video, Audio,
@@ -561,12 +605,12 @@ in each section are described below.
The Video tab controls properties of the image, as shown in .
-
+
@@ -584,12 +628,12 @@ left/right option tells DCP-o-matic to interpret the frame as a
left-right pair, as shown in .
-
+
@@ -599,12 +643,12 @@ DCP-o-matic to see the frame as a top-bottom pair, as shown in .
-
+
@@ -636,12 +680,12 @@ setup area of the DCP-o-matic window; this opens the filters selector
as shown in .
-
- Filters selector
+
@@ -666,36 +710,59 @@ converting the selected content into the XYZ colourspace for the DCP.
-Clicking Edit... will open the colour conversion
-dialogue box, as shown in .
+The easiest way to select the required conversion is to choose one of
+DCP-o-matic's presets. DCP-o-matic knows how to convert from four
+common colourspaces: sRGB, Rec. 601, Rec. 709 and P3. If you do not
+know which preset you should use, refer to the suggestions in .
+
+
+
+Suggested colour conversion settings
+
+
+
+
+
+sRGBStill images in RGB, e.g. photographs.
+
+
+Rec. 601Standard-definition content (fewer than about 1000 pixels across) including DVD rips.
+
+
+Rec. 709High-definition content including Blu-Ray rips.
+
+
+P3Content explicitly graded to P3.
+
+
+
+
+
+
+For other required colour conversions, and if you know what you are
+doing, you can choose Custom which will open the full
+colour conversion editing dialogue box:
-In most cases, it is only necessary to select one of DCP-o-matic's
-presets. DCP-o-matic knows how to convert from two common
-colourspaces: sRGB and Rec. 709, so if your content was graded using
-one of those you can select the appropriate preset.
-
-
-
-For other colour spaces you can edit the values in the lower half of
-the dialogue box as you wish. Alternatively, create a new colour
-conversion preset using the preferences dialog, as described in .
+Alternatively, choose None if your source files
+are already in the XYZ colour space and require no conversion.
-Colour conversion is discussed in more detail in a separate document
-colour.pdf.
+DCP-o-matic's colour conversion processes are discussed in much more
+detail in a separate document colour.pdf.
@@ -705,13 +772,20 @@ Colour conversion is discussed in more detail in a separate document
Other settings
-The ‘crop’ settings can be used to crop your content,
+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.
+
+The fade in and fade out
+settings can be used to apply linear fades into and out of a piece of
+content. Specify the time for each, clicking Set
+after making any changes.
+
+
The Scale to option governs the shape that
DCP-o-matic will scale the content's image into. Select the aspect
@@ -728,16 +802,18 @@ ratio that your content should be presented in.
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
, 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.
+video file is 1920x1080 pixels and it has square pixels (a pixel
+aspect ratio of 1.00) hence its display aspect ratio is 1.78:1. Since
+the controls specify ‘16.9’ for the ratio, DCP-o-matic
+does not scale the image but pads it to the DCP's container ratio of
+1.85:1. For a 2K DCP this is 1998x1080 pixels.
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.
-
+will happen to it when it is played at the DCP's frame rate. See
+ for details of DCP-o-matic's
+frame-rate conversion.
@@ -753,67 +829,16 @@ will happen to it when it is played at the DCP's frame rate.
The Audio tab controls properties of the image, as shown in .
-
@@ -1375,8 +1560,8 @@ methods to understand it.
-We suppose that we are trying to distribute a DCP to
-Alice's cinema, without a troublemaker called Mallory being able to
+We suppose that we are trying to send a DCP to
+Alice's cinema without a troublemaker called Mallory being able to
watch it himself.
@@ -1403,11 +1588,12 @@ happened to know Mallory, she could just send him a copy of the key.
-The clever bit in DCP encryption requires the use of public-key
+The clever bit in the process requires the use of public-key
encryption. With this technique we can encrypt a block of data using
some ‘public’ key. That data can then only be decrypted
-using a different ‘private’ key. The
-private and public keys are related mathematically, but it is
+using a corresponding private key which is
+different to the public key. The private and
+public keys form a pair which are related mathematically, but it is
extremely hard (or rather, virtually impossible) to derive the private
key from the public key.
@@ -1474,11 +1660,11 @@ will open the KDM dialogue box, as shown in .
- KDM dialog
+ KDM dialog
-
+
-
+
@@ -1511,10 +1697,41 @@ from a file. The certificate should be in SHA256 PEM format.
-Once you have set up all the screens that you need KDMs for,
-DCP-o-matic can generate KDMs for the last DCP that you generated for
-the currently-loaded film. Select the cinemas and/or screens that you
-want KDMs for and fill in the start and end dates and times.
+Alternatively, certificates for projection systems made by some
+manufacturers can be downloaded from databases provided by the
+manufacturer. Currently this is supported for Doremi and Dolby
+equipment. If you are targeting a screen with equipment by one of
+these manufacturers you can select Doremi or Dolby from the
+Server manufacturer selection and then click
+Download. In the next dialogue box, enter
+details of the screen and click Download and, all
+being well, the certificate will be fetched.
+
+
+
+Using the download system you will need to know the serial number of
+the media server in use in the screen. Most cinema projection or
+technical departments will know these serial numbers.
+
+
+
+Note that the reliability of the manufacturers' certificate databases
+cannot be guaranteed. It is vital that KDMs are tested by the
+destination cinema will in advance of show time to identify any
+problems.
+
+
+
+Once you have set up all the screens that you need KDMs for, select
+the CPL that you want to create the KDM for. You can use the
+drop-down list to select the CPLs in the current film project, or load
+a CPL from somewhere else. Select the cinemas and/or screens that you
+want KDMs for and fill in the start and end dates and times.
+
+
+
+You must also select the type of KDM that you want to generate. If in
+doubt, use Modified Transitional 1.
@@ -1560,12 +1777,12 @@ menu. The dialogue is split into seven tabs.
The general tab is shown in .
-
- General preferences
+
+ General preferences
-
+
-
+
@@ -1619,11 +1836,21 @@ available
The Check for testing updates as well as stable
ones option will also check for test updates as well as
-those that are formally ‘released’ This is useful if you
+those that are formally ‘released’. This is useful if you
like to live on the bleeding edge!
+
+
+Issuer and creator
+
+
+With these controls you can set the issuer and creator strings that
+will be put into the DCPs which you create.
+
+
+
@@ -1635,11 +1862,11 @@ The defaults tab is shown in .
- Defaults preferences
+ Defaults preferences
-
+
-
+
@@ -1650,43 +1877,101 @@ various properties of new films.
-
+
+
+Servers
+
+
+The servers tab is shown in .
+
+
+
+ Servers preferences
+
+
+
+
+
+
+
+
+If Use all servers is ticked DCP-o-matic will
+locate encoding servers automatically (see ).
+
+
+
+Instead of this (or in addition) servers can be specified explicitly.
+To add a server, click Add... and enter the host
+name or IP address of the server to use.
+
+
+
+
-
-Colour conversions
+
+Keys
-The colour conversions tab is shown in .
+The Keys tab (shown in ) holds options
+related to the keys and certificates used in some parts of DCP
+creation.
-
- Colour conversions preferences
+
+ Keys preferences
-
-
-
+
+
+
-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.
+At the top of the tab is the chain of certificates that will be used
+to sign DCPs and KDMs. DCP-o-matic creates a random chain when you
+first run it and if you are happy to use this chain you can ignore the
+preferences. Otherwise, you can add or remove certificates from the
+chain using the Add... and
+Remove buttons.
-Colour conversion is discussed in more detail in a separate document
-colour.pdf.
+If you want DCP-o-matic to re-create the certificate chain (using new,
+random certificates) click Re-make
+certificates... and specify your organisation and common
+names in the dialogue box that opens.
-These preferences control a list of presets which are suitable for
-converting from common input colour spaces to XYZ.
+Underneath the certificate chain is the private key that corresponds
+to the leaf certificate in the chain. You can specify your own
+private key by clicking Load.... You must do
+this if you change the leaf certificate, so that the leaf private key
+corresponds to the public key held in the leaf certificate.
-
+
+Underneath the details of the certificate chain and private key for
+signing of DCPs and KDMs is a second chain and key which is used by
+DCP-o-matic when you import an encrypted DCP as a piece of content.
+The leaf certificate of this chain contains the public key that should
+be used when targeting a KDM at DCP-o-matic.
+
+
+If you want to import an encrypted DCP you will need to give the
+decryption certificate to the distributor of the DCP so that they can
+generate a DKDM for you. You can save this certificate to disk by
+clicking Export DCP decryption certificate. As
+with the signing chain, DCP-o-matic will create a certificate chain
+and private key for you. You can also choose to load your own
+certificates and key or re-make the chain and key with new, random
+values.
+
+
+
@@ -1696,28 +1981,43 @@ converting from common input colour spaces to XYZ.
The TMS tab (shown in ) 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
+(TMS). If you do this, and your TMS accepts SSH or FTP connections,
+you can upload DCPs directly from DCP-o-matic to the TMS using the
Send DCP to TMS option in the
Jobs menu.
-
- TMS preferences
+
+ TMS preferences
-
+
-
+
+
+Protocol should be set to SCP or FTP as
+appropriate for your TMS. We know that the Arts Alliance Media (AAM)
+and the Doremi ranges uses SCP connections, and that Dolby's TMSs use
+FTP. Do let us know if you use any other type of TMS with the
+Send DCP to TMS feature.
+
+
TMS IP address should be set to the IP address of
your TMS, TMS target path 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 SSH or FTP user). Finally, the user name and password are the
+credentials required to log into the TMS via SSH or FTP.
+
+
+
+Note that for this to work on Doremi servers you will need to set the
+PasswordAuthentication option in your server's
+sshd_config to yes.
+
@@ -1729,12 +2029,12 @@ credentials required to log into the TMS via SSH.
The KDM email is shown in .
-
- KDM email preferences
+
+ KDM email preferences
-
+
-
+
@@ -1784,12 +2084,12 @@ The Reset to default text will replace the current KDM emai
The advanced preferences are shown in .
-
- Advanced preferences
+
+ Advanced preferences
-
+
-
+
@@ -1807,6 +2107,12 @@ useful for experimentation. Again, you are strongly advised to leave
this unticked for normal use.
+
+Only servers encode makes DCP-o-matic encode
+JPEG2000 data only on encoding servers and not on the host. We
+suggest you leave this un-ticked unless you have a good reason to do otherwise.
+
+
The four checkboxes labelled Log control what
sort of messages DCP-o-matic writes to its log file when creating a
@@ -1856,7 +2162,7 @@ even refuse to ingest.
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
+projectors are 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.
@@ -1926,7 +2232,7 @@ For very low or high frame rates, DCP-o-matic can also skip or duplicate frames.
The Frame Rate control in the
DCP tab sets the video frame rate that the DCP
will use. Clicking Use best sets the rate to
-what DVD-o-matic thinks is the best for your content. With this
+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.
@@ -1987,7 +2293,7 @@ To run the command line version, simply enter:
-dcpomatic_server_cli
+dcpomatic2_server_cli
@@ -1997,7 +2303,7 @@ by doing something like:
-dcpomatic_server_cli -t 4
+dcpomatic2_server_cli -t 4
@@ -2067,12 +2373,12 @@ linkend="fig-file-structure"/> shows the files that might be generated
after you have created a DCP for a film called ‘DCP Test’.
-
- Creating a new film
+
+ Creating a new film
-
+
-
+