X-Git-Url: https://git.carlh.net/gitweb/?p=dcpomatic.git;a=blobdiff_plain;f=doc%2Fmanual%2Fdcpomatic.xml;h=3df603a85d55e83261011e911b730732eebaa094;hp=0bb5ed1ca5c811fb074ae21c5494fc45f9889b74;hb=15a22a16c999a936f945d8620d2c64eb5248a505;hpb=2e98263d0aeef4a470209d1cd31e15bdccbeda41 diff --git a/doc/manual/dcpomatic.xml b/doc/manual/dcpomatic.xml index 0bb5ed1ca..3df603a85 100644 --- a/doc/manual/dcpomatic.xml +++ b/doc/manual/dcpomatic.xml @@ -253,11 +253,11 @@ shown in .
- Creating a new film + Creating a new film - + - +
@@ -267,11 +267,11 @@ linkend="fig-video-new-film"/>.
- Dialogue box for creating a new film + Dialogue box for creating a new film - + - +
@@ -301,21 +301,21 @@ select the content file to use, as shown in . -
- Adding content files +
+ Adding content files - + - +
-
- Selecting a video content file +
+ Selecting a video content file - + - +
@@ -331,19 +331,19 @@ has finished), you can look through your content using the slider to the right of the window, as shown in . -
+
Examining the content - + - +
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 @@ -379,9 +379,9 @@ linkend="fig-making-dcp"/>.
Making the DCP - - - + + +
@@ -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 +
+ 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 +
+ 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 . -
+
The timing tab - + - +
@@ -519,6 +519,8 @@ images which should be treated as the frames of a video. superimposed on the image of the DCP. These can be .srt or .xml files. + +DCP — an existing DCP. @@ -527,10 +529,11 @@ To add one or more movie, sound, still-image or subtitle files, select -To add a directory (folder) of images, choose Add -folder... and choose the directory from the selector. -DCP-o-matic will open a small dialogue box where you can enter the -frame rate that your image sequence should be run at. +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. @@ -540,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 ). + + +
@@ -578,12 +605,12 @@ in each section are described below. The Video tab controls properties of the image, as shown in . -
+
Video settings tab - + - +
@@ -601,12 +628,12 @@ left/right option tells DCP-o-matic to interpret the frame as a left-right pair, as shown in . -
+
3D left/right image type - + - +
@@ -616,12 +643,12 @@ DCP-o-matic to see the frame as a top-bottom pair, as shown in . -
+
3D top/bottom image type - + - +
@@ -653,12 +680,12 @@ setup area of the DCP-o-matic window; this opens the filters selector as shown in . -
- Filters selector +
+ Filters selector - + - +
@@ -700,7 +727,7 @@ linkend="tab-colour-conversion"/>. sRGBStill images in RGB, e.g. photographs. -Rec. 601Standard-definition content (lower than about 1000 pixels across) including DVD rips. +Rec. 601Standard-definition content (fewer than about 1000 pixels across) including DVD rips. Rec. 709High-definition content including Blu-Ray rips. @@ -719,11 +746,11 @@ colour conversion editing dialogue box:
- Dialogue box for custom colour conversion + Dialogue box for custom colour conversion - + - +
@@ -784,8 +811,9 @@ does not scale the image but pads it to the DCP's container ratio of 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.
@@ -801,12 +829,12 @@ 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 . -
+
Audio settings tab - + - +
@@ -823,9 +851,13 @@ in the DCP. 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 green box means that the corresponding -content channel will be copied into the corresponding DCP channel. +the currently-selected piece of content. These are labelled with two +numbers; the first is the stream index within the content and the +second is the channel number within that stream. Some content will +have different streams for different languages or audio mixes. Along +the top is each channel in the DCP. A green box means that the +corresponding content channel will be copied into the corresponding +DCP channel. @@ -860,9 +892,9 @@ Consider, for example, the case in .
Audio map example 1 - + - +
@@ -876,9 +908,9 @@ the settings to those shown in
Audio map example 2 - + - +
@@ -895,9 +927,9 @@ and right.
Audio map example 3 - + - +
@@ -929,12 +961,12 @@ button next to the audio gain entry, and the dialogue box in will open. -
+
Calculating audio gain - + - +
@@ -960,12 +992,6 @@ 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. - -The Audio Stream 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. - - @@ -979,24 +1005,71 @@ The subtitles tab contains settings related to subtitles in your content, as shown in . -
+
Subtitle settings tab - + - +
DCP-o-matic will extract subtitles from the content, if present, and they can be ‘burnt into’ the DCP (that is, they are -included in the image and not overlaid by the projector). +included in the image and not overlaid by the projector) or included +as a separate subtitle ‘asset’ within your DCP (in which +case the projector overlays them onto the image on playback). The +difference between these two arrangements is illustrated by and + + +
+ Burnt-in subtitles + + + + + +
+ +
+ Separate subtitles + + + + + +
+ + +The advantage of separate subtitles is that the same video content can +be used for DCPs in many different languages. This means that only a +small text file needs to be changed for each target language, rather +than a large video file. It also means that the time-consuming video +encoding need only be done once for the project rather than once for +every language. + + + +Note that subtitles come in two types: text and bitmap. Text +subtitles are expressed as plain text and can be either burnt into the +image or included as a separate subtitle asset within the DCP. Bitmap +subtitles, on the other hand, are expressed as pre-rendered bitmaps. +They cannot (yet) be added to the DCP as a separate asset and must be +burnt into the image. + + + +Select the Use Subtitles check-box to enable +these subtitles. -Select the With Subtitles check-box to enable -subtitles. +Select the Burn subtitles into image check-box to +burn these subtitles into the image; if this is not ticked the +subtitles will be included separately in the DCP to be rendered by the +projector. @@ -1037,12 +1110,12 @@ The timing tab contains settings related to the timing of your content, as shown in . -
+
Timing settings tab - + - +
@@ -1052,12 +1125,12 @@ These are expressed as four numbers, as shown in . -
+
Timecode - + - +
@@ -1091,7 +1164,9 @@ to the full length minus trim-from-start and minus -Video frame rate specifies the frame rate for still-image content. +Video frame rate specifies the frame rate for +still-image content. It can also be used to override the detected +frame rate of other content if DCP-o-matic has got it wrong. @@ -1122,12 +1197,12 @@ happen with a trailer). The source image is shown in . -
+
Example image to demonstrate video processing - + - +
@@ -1153,12 +1228,12 @@ bottom. This would give the new image shown in . -
+
Example image after cropping - + - +
@@ -1195,12 +1270,12 @@ size of 1998 x 836. This gives us a new version of the image as shown in . -
+
Example image after cropping and scaling - + - +
@@ -1215,12 +1290,12 @@ shares out this black equally, as shown in . -
+
Example image in the DCP - + - +
@@ -1237,12 +1312,12 @@ controls for these settings are in the DCP tab of the main window, as shown in . -
+
DCP settings tab - + - +
@@ -1252,7 +1327,7 @@ of the film that is being encoded. If Use ISDCF name is not ticked, the name that you specify will be used as-is for the name of the DCP. If Use ISDCF name is ticked, the name that you enter will be used as part of a -ISDCF-compliant name. +ISDCF-compliant name. @@ -1275,8 +1350,40 @@ scheme as it makes it easier to identify details of the content. -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. +The Content Type option can be +‘feature’, ‘trailer’ or whatever; select the +required type from the drop-down list. On some projection systems +this will affect where your content appears in the projector's server +user interface, so take care to select an appropriate type. + + + +The Signed check-box sets whether or not the DCP +is signed. This is rarely important; if in doubt, tick it. + + + +The Encrypted check-box will set whether the DCP +should be encrypted or not. If this is ticked, the DCP will require a +KDM to play back. Encryption is discussed in . + + + +If you use encryption DCP-o-matic will generate a random encryption +key for you. To specify your own key, click the +Edit.. button next to the key. + + + +The Standard option specifies which of the two +DCP standards DCP-o-matic should use. If in doubt, use SMPTE (the +more modern of the two). + + + +At the bottom of the DCP tab are a further two tabs, one each to +contain the settings for the DCP's video and audio parts. @@ -1289,12 +1396,6 @@ format into a Flat container: in this case, select the small format for the content's ratio and ‘Flat’ for the DCP. - -Next up is the content type. This can be -‘feature’, ‘trailer’ or whatever; select the -required type from the drop-down list. - - The Frame Rate control sets the frame rate of your DCP. This can be a little tricky to get right. Ideally, you @@ -1310,34 +1411,6 @@ to what DCP-o-matic thinks is the best given the content that you have added. - -The Signed check-box sets whether or not the DCP -is signed. This is rarely important; if in doubt, tick it. - - - -The Encrypted check-box will set whether the DCP -should be encrypted or not. If this is ticked, the DCP will require a -KDM to play back. Encryption is discussed in . - - - -If you use encryption DCP-o-matic will generate a random encryption -key for you. To specify your own key, click the -Edit.. button next to the key. - - - -The Audio Channels 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. -You can only set an even number of channels here, since that is -required by the DCI standard. If you want an odd number of channels, -set the DCP channel count to one greater than you need and the -unused channel will be filled with silence. - - The 3D 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 @@ -1361,17 +1434,44 @@ Most commercial DCPs use bit rates between 75 and 125 MBit/s. -The Standard option specifies which of the two -DCP standards DCP-o-matic should use. If in doubt, use SMPTE (the -more modern of the two). +The Audio Channels 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. +You can only set an even number of channels here, since that is +required by the DCI standard. If you want an odd number of channels, +set the DCP channel count to one greater than you need and the +unused channel will be filled with silence. -Finally, the Scaler is the method that will be used to scale up -your content for the DCP, if required. Bicubic is a fine choice in -most situations. +The Processor control allows you to select a +process to apply to the audio before it goes into the DCP. Two processes are currently provided: + +Mid-side decode — this will take a L/R +stereo input and extract the common part (corresponding to the +‘Mid’ in a mid-side signal) into the DCP's centre channel. +The remaining L/R parts will be kept in the L/R channels of the DCP. +This may be useful to make near-field L/R mixes more compatible with +cinema audio systems. +Stereo to 5.1 up-mixer A — this will take a stereo input and up-mix it to ‘fake’ 5.1. The input L/R are treated as follows: + +DCP L is input L bandpass-filtered between 1.9kHz and 4.8kHz. +DCP R is input R bandpass-filtered between 1.9kHz and 4.8kHz. +DCP C is input L mixed with input R, taken down by 3dB and then bandpass-filtered between 150Hz and 1.9kHz. +DCP Lfe is input L mixed with input R, taken down by 3dB and then bandpass-filtered between 20Hz and 150Hz. +DCP Ls is input L bandpass-filtered between 4.8kHz and 20kHz. +DCP Rs is input R bandpass-filtered between 4.8kHz and 20kHz. + + + + + +This upmixing algorithm is due to Gérald Maruccia. + + +
Show audio @@ -1384,12 +1484,12 @@ the sound will be in the cinema auditorium. A typical plot is shown in -
+
Audio plot - + - +
@@ -1460,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. @@ -1488,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. @@ -1559,11 +1660,11 @@ will open the KDM dialogue box, as shown in .
- KDM dialog + KDM dialog - + - +
@@ -1676,12 +1777,12 @@ menu. The dialogue is split into seven tabs. The general tab is shown in . -
- General preferences +
+ General preferences - + - +
@@ -1740,6 +1841,16 @@ 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. + +
+ @@ -1751,11 +1862,11 @@ The defaults tab is shown in .
- Defaults preferences + Defaults preferences - + - +
@@ -1775,11 +1886,11 @@ The servers tab is shown in .
- Servers preferences + Servers preferences - + - +
@@ -1797,44 +1908,9 @@ name or IP address of the server to use. - -
-Colour conversions - - -The colour conversions tab is shown in . - - -
- Colour conversions 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. - - - -Colour conversion is discussed in more detail in a separate document -colour.pdf. - - - -These preferences control a list of presets which are suitable for -converting from common input colour spaces to XYZ. - - -
- -
+
Keys @@ -1843,21 +1919,21 @@ related to the keys and certificates used in some parts of DCP creation. -
- Keys preferences +
+ Keys preferences - + - +
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, so if you are happy to use a randomly-generated chain -you can ignore the preferences. Otherwise, you can add or remove -certificates from the chain using the Add... and +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. @@ -1877,13 +1953,22 @@ corresponds to the public key held in the leaf certificate. -The bottom of the tab specifies the certificate and private key that -is used to decrypt DCPs if they are imported as sources to -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. As with the certificate chain, -DCP-o-matic will create a certificate and private key for you. You -can also choose to load your own certificate and key. +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.
@@ -1896,28 +1981,43 @@ can also choose to load your own certificate and key. 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. +
@@ -1929,12 +2029,12 @@ credentials required to log into the TMS via SSH. The KDM email is shown in . -
- KDM email preferences +
+ KDM email preferences - + - +
@@ -1984,12 +2084,12 @@ The Reset to default text will replace the current KDM emai The advanced preferences are shown in . -
- Advanced preferences +
+ Advanced preferences - + - +
@@ -2007,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 @@ -2267,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 - + - +