]>
<book xmlns="http://docbook.org/ns/docbook" xmlns:mml="http://www.w3.org/1998/Math/MathML" 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 users' manual</title>
<author><firstname>Carl</firstname><surname>Hetherington</surname></author>
<para>
DCP-o-matic is a program to generate <ulink
url="http://en.wikipedia.org/wiki/Digital_Cinema_Package">Digital
-Cinema Packages</ulink> (DCPs) from DVDs, Blu-Rays, video files such as MP4
-and AVI, or still images. The resulting DCPs will play on modern digital
+Cinema Packages</ulink> (DCPs) from almost any video, audio and/or
+subtitle source files. The resulting DCPs will play on modern digital
cinema projectors.
</para>
</section>
+<!-- ============================================================== -->
<section>
-<title>Ubuntu Linux</title>
+<title>Debian or Ubuntu Linux</title>
<para>
-You can install DCP-o-matic on Ubuntu 12.04 (‘Precise
-Pangolin’), 14.04 (‘Trusty Tahr’) or 15.04
-(‘Vivid Vervet’) 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.
+ You can install DCP-o-matic on:
</para>
+<itemizedlist>
+ <listitem>Debian 7 (‘wheezy’)</listitem>
+ <listitem>Debian 8 (‘jessie’)</listitem>
+ <listitem>Debian unstable (‘sid’)</listitem>
+ <listitem>Ubuntu 12.04 (‘Precise Pangolin’)</listitem>
+ <listitem>Ubuntu 14.04 (‘Trusty Tahr’)</listitem>
+ <listitem>Ubuntu 15.04 (‘Vivid Vervet’)</listitem>
+ <listitem>Ubuntu 15.10 (‘Wily Werewolf’)</listitem>
+</itemizedlist>
+
+<para>
+using <code>.deb</code> packages: download the appropriate package
+from <ulink url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>
+and double-click it. Debian or Ubuntu will install the necessary bits and
+pieces and set DCP-o-matic up for you.
+</para>
</section>
+<!-- ============================================================== -->
<!-- ============================================================== -->
<section>
-<title>Debian Linux</title>
-<para>
-Packages are available for Debian 7 (squeeze), 8 (jessie) and unstable (sid) from <ulink
-url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>.
-</para>
+ <title>Fedora Linux</title>
+
+ <para>There are <code>.rpm</code> packages for Fedora 22 and 23 on
+ <ulink url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>
+ </para>
</section>
+<!-- ============================================================== -->
<!-- ============================================================== -->
<section>
-<title>Centos Linux</title>
-<para>
-Packages are available for Centos 6.5 and 7 from <ulink
-url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>.
-</para>
+ <title>Centos Linux</title>
+ <para>There are <code>.rpm</code> packages for Centos 6.5 and 7 on
+ <ulink url="http://dcpomatic.com/">http://dcpomatic.com/</ulink>
+ </para>
</section>
+<!-- ============================================================== -->
<!-- ============================================================== -->
<itemizedlist>
<listitem><ulink url="http://ffmpeg.org/">FFmpeg</ulink></listitem>
<listitem><ulink url="http://www.mega-nerd.com/libsndfile/">libsndfile</ulink></listitem>
+<listitem><ulink url="http://www.mega-nerd.com/SRC/">libsamplerate</ulink></listitem>
<listitem><ulink url="http://www.openssl.org/">OpenSSL</ulink></listitem>
<listitem><ulink url="http://www.openjpeg.org/">libopenjpeg</ulink></listitem>
<listitem><ulink url="http://www.imagemagick.org/script/index.php">ImageMagick</ulink></listitem>
<listitem><ulink url="http://www.aleksey.com/xmlsec/">xmlsec</ulink></listitem>
<listitem><ulink url="http://curl.haxx.se/">curl</ulink></listitem>
<listitem><ulink url="http://www.nih.at/libzip/">libzip</ulink></listitem>
-<listitem><ulink url="http://carlh.net/software/libdcp/">libdcp</ulink></listitem>
-<listitem><ulink url="http://carlh.net/software/libcxml/">libcxml</ulink></listitem>
+<listitem><ulink url="http://carlh.net/libdcp/">libdcp</ulink></listitem>
+<listitem><ulink url="http://carlh.net/libsub/">libsub</ulink></listitem>
+<listitem><ulink url="http://carlh.net/libcxml/">libcxml</ulink></listitem>
+<listitem><ulink url="http://site.icu-project.org">libicu</ulink></listitem>
</itemizedlist>
</para>
</chapter>
+<!-- ============================================================== -->
+<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
+<title>Manipulating existing DCPs</title>
+
+<para>
+Frequently DCP-o-matic is used to take content in formats such as MP4
+and convert it to JPEG2000 for a DCP. Alternatively, it can be used
+to take existing DCPs and modify them in various ways.
+</para>
+
+<section>
+<title>Importing a DCP into DCP-o-matic</title>
+
+<para>
+If you want to do something to an existing DCP the first step is to
+import it. Click <guilabel>Add folder...</guilabel> and select your
+DCP's folder. It will be added to the DCP-o-matic project. If the
+DCP is unencrypted you can preview it in the normal way, though
+playback will be very slow as decoding of DCPs is almost as
+computationally intensive as encoding them.
+</para>
+
+</section>
+
+
+<section>
+<title>Decrypting encrypted DCPs</title>
+
+<para>
+DCPs can be encrypted (see <xref linkend="ch-encryption"/> for
+details). If you import an encrypted DCP you will need a key, in the
+form of a Key Delivery Message (KDM), to decrypt it.
+</para>
+
+<para>
+KDMs must be prepared by the organisation which created the DCP. They
+contain the keys to decrypt the DCP wrapped up in such a way that only
+the intended recipient can read them. You will need to provide the
+organisation with a certificate which identifies your copy of
+DCP-o-matic and allows them to create a KDM for you.
+</para>
+
+<para>
+To get DCP-o-matic's decryption certificate, open the Preferences
+dialogue (see <xref linkend="ch-preferences"/>) and go to the
+<guilabel>Keys</guilabel> tab. Click the <guilabel>Export DCP
+decryption certificate...</guilabel> button at the bottom of this tab
+and save the certificate. Send this certificate to the DCP creators
+and they can create a KDM to allow DCP-o-matic to decrypt their DCP.
+</para>
+
+<para>
+Once you have your KDM, right-click the DCP's name in DCP-o-matic and
+choose <guilabel>Add KDM...</guilabel>. Specify your KDM and (all
+being well) the DCP will be decrypted and become available for preview.
+</para>
+
+</section>
+
+
+<section>
+<title>Making a DCP from a DCP</title>
+
+<para>
+In many ways, using DCPs as <emphasis>content</emphasis> in
+DCP-o-matic is the same as using any other content. There are a few
+things to note, though.
+</para>
+
+
+<section>
+<title>Re-use of existing data</title>
+
+<para>
+Where possible DCP-o-matic will re-use existing JPEG2000-compressed
+data from DCP content without modification. This has the advantage
+that creation of the new DCP will be quick, as the time-consuming
+JPEG2000 encoding is not necessary.
+</para>
+
+<para>
+DCP-o-matic can do this if you avoid changes to the following content
+settings:
+</para>
+
+<itemizedlist>
+<listitem>Crop</listitem>
+<listitem>Scaling</listitem>
+<listitem>Subtitle burn-in</listitem>
+<listitem>Fades</listitem>
+<listitem>Colour conversion</listitem>
+</itemizedlist>
+
+<para>
+If you do change any of these settings on a piece of DCP content
+DCP-o-matic will decode and then re-encode the JPEG2000 data.
+</para>
+
+</section>
+
+
+<section>
+<title>Making overlay files</title>
+
+<para>
+With its default settings, DCP-o-matic will take any data from DCP
+content and copy it into the DCP that it creates. See <xref linkend="fig-dcp-copy"/>.
+</para>
+
+<figure id="fig-dcp-copy">
+<title>Creating a new DCP by copying an existing one</title>
+<mediaobject><imageobject><imagedata scale="100" fileref="diagrams/dcp-copy&dia;"/></imageobject></mediaobject>
+</figure>
+
+<para>
+This can be inefficient in some cases. Consider, for example, a film
+which has ten different translations for which the subtitles are
+different but video and audio are the same. If the video and audio
+content takes up, say, 100Gb this means that the set of DCPs for every
+translation would be about 1Tb with a lot of duplicated data.
+</para>
+
+<para>
+The DCP format has a solution to this problem. One DCP can refer to
+the ‘assets’ (picture, sound or subtitle) of another DCP.
+For our translation example this means that we could have a
+‘base’ DCP (often called the OV or Original Version)
+containing video, audio and one set of subtitles and then any number
+of overlay DCPs (often called VF or Version Files) which refer to the
+base version and replace the original subtitles with their own. <xref
+linkend="fig-dcp-refer"/> shows this principle for one of our
+translations. The DCP that we make refers to the original content
+DCP's video and audio rather than containing a copy.
+</para>
+
+<figure id="fig-dcp-refer">
+<title>Creating a new DCP by referring to an existing one</title>
+<mediaobject><imageobject><imagedata scale="100" fileref="diagrams/dcp-refer&dia;"/></imageobject></mediaobject>
+</figure>
+
+<para>
+To play back the subtitled DCP the projectionist ingests both the base
+(OV) DCP and the overlay (VF) DCP, then plays the VF one.
+</para>
+
+</section>
+
+</section>
+
+
+
+</chapter>
+<!-- ============================================================== -->
+
+
<!-- ============================================================== -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
<title>Content settings</title>
<para>
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.
+content that goes into your DCP, and this chapter describes those
+features in detail.
</para>
<section>
<title>Burnt-in subtitles</title>
<mediaobject>
<imageobject>
- <imagedata scale="80" fileref="diagrams/burn-in&dia;"/>
+ <imagedata scale="100" fileref="diagrams/burn-in&dia;"/>
</imageobject>
</mediaobject>
</figure>
<title>Separate subtitles</title>
<mediaobject>
<imageobject>
- <imagedata scale="80" fileref="diagrams/discrete&dia;"/>
+ <imagedata scale="100" fileref="diagrams/discrete&dia;"/>
</imageobject>
</mediaobject>
</figure>
</para>
<para>
-Select the <guilabel>With Subtitles</guilabel> check-box to enable
-subtitles.
+Select the <guilabel>Use Subtitles</guilabel> check-box to enable
+these subtitles.
+</para>
+
+<para>
+Select the <guilabel>Burn subtitles into image</guilabel> 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.
</para>
<para>
<title>Timecode</title>
<mediaobject>
<imageobject>
- <imagedata fileref="diagrams/timecode&dia;"/>
+ <imagedata scale="100" fileref="diagrams/timecode&dia;"/>
</imageobject>
</mediaobject>
</figure>
added.
</para>
-<para>
-<guilabel>Burn subtitles into image</guilabel> should be selected if
-you want DCP-o-matic to overlay the subtitles onto the video frame
-before encoding. Leave this un-ticked to include the subtitles
-separately in the DCP.
-</para>
-
<para>
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
<listitem>DCP Ls is input L bandpass-filtered between 4.8kHz and 20kHz.</listitem>
<listitem>DCP Rs is input R bandpass-filtered between 4.8kHz and 20kHz.</listitem>
</itemizedlist>
-</listitem>
-</itemizedlist>
-
<para>
This upmixing algorithm is due to Gérald Maruccia.
</para>
-
+</listitem>
+<listitem>Stereo to 5.1 up-mixer B — this uses a different approach:
+<itemizedlist>
+ <listitem>DCP L is input L.</listitem>
+ <listitem>DCP R is input R.</listitem>
+ <listitem>DCP C is input L + input R taken down by 3dB.</listitem>
+ <listitem>DCP Lfe is DCP C bandpass filtered between 20Hz and 150Hz.</listitem>
+ <listitem>DCP Ls and Rs are input L - input R with a 20ms delay.</listitem>
+</itemizedlist>
+</listitem>
+</itemizedlist>
<!-- ============================================================== -->
<section>
To add a cinema, click <guilabel>Add Cinema...</guilabel>. This opens
a dialogue box into which you can enter the cinema's name, and
optionally an email address. This email address can be used to
-get DCP-o-matic to deliver KDMs via email, but it is optional.
+get DCP-o-matic to deliver KDMs via email.
</para>
<para>
</para>
</section>
+<!-- ============================================================== -->
+<section>
+<title>Issuer and creator</title>
+
+<para>
+With these controls you can set the issuer and creator strings that
+will be put into the DCPs which you create.
+</para>
+</section>
+
</section>
<!-- ============================================================== -->
<para>
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 <guilabel>Add...</guilabel> 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 <guilabel>Add...</guilabel> and
<guilabel>Remove</guilabel> buttons.
</para>
</para>
<para>
-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.
+</para>
+
+<para>
+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 <guilabel>Export DCP decryption certificate</guilabel>. 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.
</para>
</section>
<para>
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
+(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
<guilabel>Send DCP to TMS</guilabel> option in the
<guilabel>Jobs</guilabel> menu.
</para>
</mediaobject>
</figure>
+<para>
+<guilabel>Protocol</guilabel> 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
+<guilabel>Send DCP to TMS</guilabel> feature.
+</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 SSH or FTP user). Finally, the user name and password are the
+credentials required to log into the TMS via SSH or FTP.
</para>
<para>
this unticked for normal use.
</para>
+<para>
+<guilabel>Only servers encode</guilabel> 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.
+</para>
+
<para>
The four checkboxes labelled <guilabel>Log</guilabel> control what
sort of messages DCP-o-matic writes to its log file when creating a
<title>Creating a new film</title>
<mediaobject>
<imageobject>
- <imagedata fileref="diagrams/file-structure&dia;"/>
+ <imagedata scale="100" fileref="diagrams/file-structure&dia;"/>
</imageobject>
</mediaobject>
</figure>
projects / dcpomatic.git / blobdiff