X-Git-Url: https://git.carlh.net/gitweb/?a=blobdiff_plain;f=doc%2Fmanual%2Fdcpomatic.xml;h=bd42747de0153b90292bcf9b7311c8432d1a2075;hb=28224b347dd993d635ba8a0f2e7db20130483bd4;hp=5b30bcf70b9ccda32103e9ef884bb0834a891267;hpb=c5ab3bded4d8a523fe7f3ab3256e17ef3ab96615;p=dcpomatic.git diff --git a/doc/manual/dcpomatic.xml b/doc/manual/dcpomatic.xml index 5b30bcf70..bd42747de 100644 --- a/doc/manual/dcpomatic.xml +++ b/doc/manual/dcpomatic.xml @@ -101,6 +101,12 @@ many parallel encoding threads (more than 4) on the 32-bit version. + +If you are still using Windows XP, download the specific XP version as +it should be more stable on your machine than the ‘normal’ +Windows version. + + @@ -139,7 +145,6 @@ depend on it. Debian unstable (‘sid’) Ubuntu 12.04 (‘Precise Pangolin’) Ubuntu 14.04 (‘Trusty Tahr’) - Ubuntu 15.10 (‘Wily Werewolf’) Ubuntu 16.04 (‘Xenial Xerus’) @@ -531,6 +536,19 @@ playback will be very slow as decoding of DCPs is almost as computationally intensive as encoding them. + +If your DCP is a Version File (VF), in other words it refers to +another DCP's assets, you should import it as follows: + + + +Use Add folder... to import the VF DCP. +The VF DCP will be added to the content list and marked “NEEDS +OV”. +Right-click on the VF DCP in the content list and choose Add OV... from the menu. +Choose the folder that contains the OV DCP. The VF will now be playable as normal. + + @@ -610,7 +628,7 @@ DCP-o-matic will decode and then re-encode the JPEG2000 data. -
+
Making overlay files @@ -717,7 +735,7 @@ 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, .ssa or .xml +.srt, .ssa, .ass or .xml files. DCP — an existing DCP. @@ -815,12 +833,25 @@ The Video tab controls properties of the image, as shown in + +
+Refer to existing DCP + + +This option is only applicable if the selected content is an existing +DCP. It allows you to get the video content from the existing DCP by +referencing it (rather than copying). See . + + +
+
Image type -The first option on this tab is the ‘type’ of the video. +The next option on this tab is the ‘type’ of the video. This specifies how DCP-o-matic should interpret the video's image. 2D is the default; this just takes the video image as a standard 2D frame. The 3D @@ -1038,7 +1069,6 @@ The Audio tab controls properties of the image, as shown in -
The audio map @@ -1143,7 +1173,20 @@ shows the mapping of a 5.1 source into a 5.1 DCP.
-Other controls + Other controls + + +The Refer to existing DCP checkbox isonly +applicable if the selected content is an existing DCP. It allows you +to get the audio content from the existing DCP by referencing it +(rather than copying). See . + + + +Show graphs of audio levels will analyse the +audio of the selected content and plot it on a graph. See for more details. + ‘Audio Gain’ is used to alter the volume of the @@ -1304,6 +1347,11 @@ frame) than those typically used for DCP, so it is often useful to scale such subtitles down using these controls. + +The Line spacing control adjusts the line spacing +of the subtitles. This only works for non-embedded (text) subtitles. + + The Stream control changes the subtitle stream that is used when the content has more than one. @@ -1372,11 +1420,17 @@ should be displayed using this control. -Trim from start specifies the amount that should be trimmed from the start of the content. +Trim from start specifies the amount that should +be trimmed from the start of the content. You can set this amount to +trim up to the current preview position by clicking Trim up +to current position. -Trim from end specifies the amount that should be trimmed from the end of the content. +Trim from end specifies the amount that should be +trimmed from the end of the content. You can set this amount to trim +after the current preview position by clicking Trim after to +current position. @@ -1791,7 +1845,7 @@ you must specify a reel length in Gb. Then no file in the DCP will be larger th -
+
Show audio @@ -1842,6 +1896,77 @@ auditorium, but it can be useful to get levels in the right rough area. + + + +Templates + + +If you frequently make DCPs with similar settings you may find it +useful to use templates. + + + +Say, for example, you often make 4K feature DCPs from video files in +’scope at 25fps. You can speed up this process by following +these steps: + + + + Create a film with any content and set it up how you like; + in our example, set the content to scale to DCP, the DCP resolution + to 4K, and so on. + Choose Save as template... from the File menu. + Enter a name for your template. + + + +Then in the future you can create a new film, tick the +Template box and choose your previously-saved +template. The basic film's settings will come from your template, and +when you add some content it will take on the settings of the +first similarly-typed piece of content in your template. + + + +For example if the template has a piece of video content and some +subtitles, any video that you add to the new film will take on the +settings of the video in the template. Similarly, any subtitles that +you add will take on the settings of the subtitles from the template. + + + +The following settings from the DCP tab are saved +in templates: + + + + “Use ISDCF name” checkbox + Content type (FTR, TLR etc.) + Container + Resolution + JPEG200 bandwidth + Video frame rate + Signed and encrypted checkboxes + Audio channels + Standard (Interop / SMPTE) + Audio processor + Reel type and length + Upload after make DCP checkbox + + + +In addition to this, the settings (but not the filenames) of any +content in the template are stored, as discussed above. The status of +the Keep video and subtitles in sequence checkbox +from the timeline is also preserved. + + + + + + + Encryption @@ -1991,7 +2116,7 @@ linkend="fig-kdm"/>. KDM dialog - + @@ -2131,7 +2256,7 @@ DCP-o-matic. Its window is shown in . The KDM creator - + @@ -2188,15 +2313,10 @@ DCP-o-matic provides a few preferences which can be used to modify its behaviour. This chapter explains those options. - - -
-The preferences dialogue - -The preferences dialogue is opened by choosing +Preferences can be edited by choosing Preferences... from the Edit -menu. The dialogue is split into seven tabs. +menu. This opens a dialogue which is split into seven tabs. @@ -2418,13 +2538,19 @@ 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 +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. + +Clicking Export DCP decryption chain... will +export the whole certificate chain, rather than just the leaf +certificate. + +
@@ -2567,6 +2693,14 @@ 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. + +With the filename format fields you can adjust the filenames that are +used for metadata (CPL and PKL files) and assets (MXF and subtitle +files). Below each field there is a list of the ‘magic’ +values that you can use in the format and an example of a filename +that you might see with your current settings. + + The four checkboxes labelled Log control what sort of messages DCP-o-matic writes to its log file when creating a @@ -2583,7 +2717,6 @@ that are generated, so in normal use it is best to leave this unticked. -
@@ -2711,6 +2844,7 @@ purposes. + Encoding servers @@ -2876,6 +3010,130 @@ to the cinema which is showing your DCP. + + + Command-line tools + + + DCP-o-matic includes some tools which allow DCP creation from the + command line or from scripting languages. This chapter covers the + use of those tools. + + + + There are two command-line tools in DCP-o-matic. + dcpomatic2_create creates film directories, with the + associated metadata, from a list of content files. Then + dcpomatic2_cli runs the transcode process on these + film directories. + + + + Some applications will benefit from setting up the films using the + main DCP-o-matic GUI and then using dcpomatic2_cli to + do the encode. This allows, for example, setup on a relatively + low-powered machine before running the encode on a higher-powered + headless server. + + +
+ <code>dcpomatic2_create</code> + + + The syntax for dcpomatic2_create is: + + + + dcpomatic2_create [OPTION] [CONTENT] [<CONTENT> ...] + + + + [CONTENT] are the files or folders that you want to use in the + DCP. They can be: + + ‘Movie’ files in almost any common format (e.g. MP4, MOV, MKV, etc.) + A folder containing and image sequence in almost any common format (e.g. TIFF, DPX etc.) + Sound files (e.g. WAV, MP3, AIFF) + Subtitles files (e.g. .srt, DCP XML, .ssa etc.) + + + + + The options are: + + + + -v, --version — show DCP-o-matic version + -h, --help — show this help + -n, --name — <name> film name + -t, --template <name> — template name + -c, --dcp-content-type <type> — FTR, SHR, TLR, TST, XSN, RTG, TSR, POL, PSA or ADV + --container-ratio <ratio> — 119, 133, 137, 138, 166, 178, 185 or 239 + --content-ratio <ratio> — 119, 133, 137, 138, 166, 178, 185 or 239 + -s, --still-length <n> — number of seconds that still content should last + --standard <standard> — SMPTE or interop (default SMPTE) + --no-use-isdcf-name> — do not use an ISDCF name; use the specified name unmodified + --no-sign— do not sign the DCP + -o, --output <dir> — output directory + + + + For example, to setup a film using a MP4 file you might do: + + + + dcpomatic2_create -o my_film --container-ratio 185 --content-ratio 185 -c FTR -n "My Film" Stuff.mp4 + + + + This will create a folder called my_film which is ready for a DCP to be made by dcpomatic2_cli. + + + + dcpomatic2_create will use any default settings that you have configured in the main DCP-o-matic preferences. + +
+ +
+ <code>dcpomatic2_cli</code> + + + The syntax for dcpomatic2_cli is: + + + + dcpomatic2_cli [OPTION] [FILM] + + + + + -v, --version — show DCP-o-matic version + -h, --help — show this help + -f, --flags — show flags passed to C++ compiler on build + -n, --no-progress — do not print progress to stdout + -r, --no-remote — do not use any remote servers + -t, --threads — specify number of local encoding threads (overriding configuration) + -j, --json <port> — run a JSON server on the specified port + -k, --keep-going — keep running even when the job is complete + -s, --servers — just display a list of encoding servers that DCP-o-matic is configured to use; don't encode + -d, --dcp-path — echo DCP's path to stdout on successful completion (implies -n) + --dump — just dump a summary of the film's settings; don't encode + + + + + For example, to encode a film called my_film you might do: + + + + dcpomatic2_cli my_film + +
+ + + + + Loose ends @@ -2910,4 +3168,171 @@ hashes. + + +Common tasks + + +This chapter describes how to carry out some commonly-required tasks +with DCP-o-matic. The full details are elsewhere in the manual: here +we just discuss different approaches to these tasks and how to carry +them out. + + +
+Adding subtitles to an existing DCP + + +You have three options: + + + +Make a “Version File” (VF) DCP. +Make a complete DCP with projector-added subtitles. +Make a complete DCP with burnt-in subtitles. + + + +Making a VF DCP is usually the best option. This will be a very small +DCP which contains only the subtitles: it refers to your existing DCP +for the picture and sound. The projectionist will ingest both the +existing and VF DCPs and play back the VF. The advantages of this +approach are that the VF is very quick to generate, and small in size, +making it easy to distribute. This is especially useful if you have +to make VF DCPs in many different languages. + + + +Making a complete DCP with projector-added subtitles gives you a new, +single DCP which the projectionist can ingest and play. It will be +the same size as your existing DCP, and fairly quick to create. This +approach relies on the projector (or server) to create the subtitles +and overlay them on the image, which mostly works well but is not +100% reliable. + + + +Making a complete DCP with burnt-in subtitles gives you a new, single DCP +but with the subtitles rendered by DCP-o-matic and copied into your +image. This is slower to create than a DCP with projector-added +subtitles as every video frame with a subtitle must be re-encoded. +The advantage of this approach is that it is less likely to go wrong, +especially if you are using unusual subtitle positioning or character +sets. + + +
+Making a VF DCP + + +Start a new DCP-o-matic film. +Click Add folder... and specify your existing DCP's folder. +Go to the DCP tab and choose Split by video content for Reel type. +Go to the Video and +Audio tabs in turn and tick the Refer to existing DCP checkboxes. +Add your subtitles to the film in whatever format you have. +Check the subtitle appearance in the preview; it will be +slow to respond as it is having to decompress images from the existing +DCP. +Choose Make DCP from the menu. + + +
+ +
+Making a complete DCP with projector-added subtitles + + +Start a new DCP-o-matic film. +Click Add folder... and specify your existing DCP's folder. +Add your subtitles to the film in whatever format you have. +Check the subtitle appearance in the preview; it will be +slow to respond as it is having to decompress images from the existing +DCP. Adjust the appearance using controls in the +Subtitle tab if required. +Choose Make DCP from the menu. + + +
+ +
+Making a complete DCP with burnt-in subtitles + + +Start a new DCP-o-matic film. +Click Add folder... and specify your existing DCP's folder. +Add your subtitles to the film in whatever format you have. +Go to the Subtitle tab and tick the Burn subtitles into image checkbox. +Check the subtitle appearance in the preview; it will be +slow to respond as it is having to decompress images from the existing +DCP. Adjust the appearance using controls in the +Subtitle tab if required. +Choose Make DCP from the menu. + + +
+
+ +
+Adding soundtracks or subtitles in different languages + + +If you have a film that is to be dubbed or subtitled in several +languages, the best approach with DCP-o-matic is as follows: + + + +Make a DCP with the common elements (perhaps just the video, or maybe the video and sound); this is known as the Original Version (OV). +For each language, make a new Version File (VF) DCP which refers to the OV. + + + +Once you have done this, you send the OV DCP to every cinema and then +the appropriate VF to each cinema depending on what language they want +to play the film in. The projectionist ingests both DCPs and then plays the VF. + + + +The advantage of this approach is that the VF DCPs are much smaller +than the OV since they only have the language-specific parts. If you +are just changing the subtitles you can often ship the OV by normal +transport means (e.g. a hard drive or high-speed download) and send +the VF by email. + + + +The full details of OV and VF files are discussed in . The steps can be summarised as follows: + + + +Create a new DCP-o-matic project for the OV, as normal, adding video and perhaps sound. Make the DCP. +Create a new DCP-o-matic project for the VF. +Use Add folder... to add your OV DCP to the project. +Select the video tab and tick Refer to existing DCP (you may need to select By video content for Reel type in the DCP tab). +Do the same in the Audio tab if your OV has audio. +Add your language-specific audio and/or subtitles and Make DCP. + + +
+ + + + + +Configuration files + +Most of DCP-o-matic's configuration is stored in an XML file called config.xml. This is stored in different places depending on your operating system: + + + Windows: c:\Users\your_user_name\AppData\Local\dcpomatic + OS X: /Users/your_user_Name/Library/Preferences/com.dcpomatic/2 + Linux: ~/.config/dcpomatic2 + + +Possible XML tags are as follows: + + + + +