1 <?xml version="1.0" encoding="utf-8"?>
3 <!ENTITY % sgml.features "IGNORE">
4 <!ENTITY % xml.features "INCLUDE">
5 <!ENTITY % dbcent PUBLIC "-//OASIS//ENTITIES DocBook Character Entities V4.5//EN"
6 "/usr/share/xml/docbook/schema/dtd/4.5/dbcentx.mod">
8 <!ENTITY % extensions SYSTEM "extensions.ent">
11 <book xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
14 <title>DVD-o-matic</title>
15 <author><firstname>Carl</firstname><surname>Hetherington</surname></author>
18 <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
19 <title>Introduction</title>
22 Hello, and welcome to DVD-o-matic!
26 <title>What is DVD-o-matic?</title>
29 DVD-o-matic is a program to generate <ulink
30 url="http://en.wikipedia.org/wiki/Digital_Cinema_Package">Digital
31 Cinema Packages</ulink> (DCPs) from DVDs, Blu-Rays, video files such as MP4
32 and AVI, or still images. The resulting DCPs will play on modern digital
37 You might find it useful to make DVDs easier to present, to encode
38 independently-shot feature films, or to generate local advertising for
45 <title>Licence</title>
48 DVD-o-matic is licensed under the <ulink url="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GNU GPL</ulink>.
55 <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
56 <title>Installation</title>
59 <title>Windows</title>
62 To install DVD-o-matic on Windows, simply download the installer from
63 <ulink url="http://carlh.net/software/dvdomatic">http://carlh.net</ulink>
64 and double-click it. Click through the installer wizard, and
65 DVD-o-matic will be installed onto your machine.
69 If you are using a 32-bit version of Windows, you will need the 32-bit
70 installer. For 64-bit Windows, either installer will work, but I
71 suggest you used the 64-bit version as it will allow DVD-o-matic to
72 use more memory. You may find that DVD-o-matic crashes if you run
73 many parallel encoding threads (more than 4) on the 32-bit
80 <title>Ubuntu Linux</title>
83 You can install DVD-o-matic on Ubuntu 12.04 (‘Precise Pangolin’) or
84 12.10 (‘Quantal Quetzal’) using <code>.deb</code> packages. Simply
85 download the appropriate package from <ulink
86 url="http://carlh.net/software/dvdomatic">http://carlh.net</ulink> and
87 double-click it. Ubuntu will install the necessary bits and pieces
88 and set DVD-o-matic up for you.
94 <title>Other Linux distributions</title>
97 Installation on non-Ubuntu Linux is currently a little involved, as
98 there are no packages available (yet); you will have to compile it
99 from source. If you are using a non-Ubuntu distribution, do let me
100 know via the <ulink url="mailto:dvdomatic@carlh.net">mailing
101 list</ulink> and I will see about building some packages.
105 The following dependencies are required:
107 <listitem><ulink url="http://ffmpeg.org/">FFmpeg</ulink></listitem>
108 <listitem><ulink url="http://www.mega-nerd.com/libsndfile/">libsndfile</ulink></listitem>
109 <listitem><ulink url="http://www.openssl.org/">OpenSSL</ulink></listitem>
110 <listitem><ulink url="http://www.openjpeg.org/">libopenjpeg</ulink></listitem>
111 <listitem><ulink url="http://www.imagemagick.org/script/index.php">ImageMagick</ulink></listitem>
112 <listitem><ulink url="http://www.boost.org/">Boost</ulink></listitem>
113 <listitem><ulink url="http://www.libssh.org/">libssh</ulink></listitem>
114 <listitem><ulink url="http://www.gtk.org/">GTK</ulink></listitem>
115 <listitem><ulink url="http://www.wxwidgets.org/">wxWidgets</ulink></listitem>
116 <listitem><ulink url="http://carlh.net/software/libdcp/">libdcp</ulink></listitem>
121 Once you have installed the development packages for the dependencies,
122 download the source code from <ulink
123 url="http://carlh.net/software/dvdomatic">http://carlh.net</ulink>,
124 unpack it and run the following commands from inside the source
135 With any luck, this will build and install DVD-o-matic on your system. To run it, enter:
149 <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
150 <title>Creating a video DCP</title>
153 In this chapter we will see how to create a video DCP using
154 DVD-o-matic. We will gloss over some of the finer details, which are
155 explained in later chapters.
159 <title>Creating a new film</title>
162 Let's make a very simple DCP to see how DVD-o-matic works. First, we
163 need some content. Download the low-resolution trailer for the open
164 movie <ulink url="http://sintel.org/">Sintel</ulink> from <ulink
165 url="http://ftp.nluug.nl/ftp/graphics/blender/apricot/trailer/Sintel_Trailer1.480p.DivX_Plus_HD.mkv">their
166 website</ulink>. Generally, of course, one would want to use the
167 highest-resolution material available, but for this test we will use
168 the low-resolution version to save everyone's bandwidth bills.
172 Now, start DVD-o-matic and its window will open. First, we will
173 create a new ‘film’. A ‘film’ is how DVD-o-matic refers to
174 a piece of content, along with some settings, which we will make into
175 a DCP. DVD-o-matic stores its data in a folder on your disk while it
176 creates the DCP. You can create a new film by selecting
177 <guilabel>New</guilabel> from the <guilabel>File</guilabel> menu, as
178 shown in <xref linkend="fig-file-new"/>.
181 <figure id="fig-file-new">
182 <title>Creating a new film</title>
185 <imagedata fileref="screenshots/file-new&scs;"/>
191 This will open a dialogue box for the new film, as shown in <xref
192 linkend="fig-video-new-film"/>.
195 <figure id="fig-video-new-film">
196 <title>Dialogue box for creating a new film</title>
199 <imagedata fileref="screenshots/video-new-film&scs;"/>
205 In this dialogue box you can choose a name for the film. This will be
206 used to name the folder to store its data in, and also as the initial
207 name for the DCP itself. You can also choose whereabouts you want to create
208 the film. In the example from the figure, DVD-o-matic will create a
209 folder called ‘DCP Test’ inside my home folder (carl) into which it
210 will write its working files.
214 If you always create your DCPs in a particular folder, you can use
215 DVD-o-matic's <guilabel>Preferences</guilabel> to make life a little
216 easier by setting the default folder that DVD-o-matic will offer in this dialogue.
217 See <xref linkend="ch-preferences"/>.
223 <title>Selecting content</title>
226 The next step is to set the content that you want to use. Click the
227 content selector, as shown in <xref
228 linkend="fig-click-content-selector"/>, and a file chooser will
229 open for you to select the content file to use, as shown in <xref
230 linkend="fig-video-select-content-file"/>.
233 <figure id="fig-click-content-selector">
234 <title>Opening the content selector</title>
237 <imagedata fileref="screenshots/click-content-selector&scs;"/>
242 <figure id="fig-video-select-content-file">
243 <title>Selecting a video content file</title>
246 <imagedata fileref="screenshots/video-select-content-file&scs;"/>
252 Select your content file and click <guilabel>Open</guilabel>. In this
253 case we are using the Sintel trailer that we downloaded earlier.
257 When you do this, DVD-o-matic will take a look at your file. After a
258 short while (when the progress bar at the bottom right of the window
259 has finished), you can look through your content using the slider to
260 the right of the window, as shown in <xref linkend="fig-examine-thumbs"/>.
263 <figure id="fig-examine-thumbs">
264 <title>Examining the content</title>
267 <imagedata fileref="screenshots/examine-thumbs&scs;"/>
273 Dragging the slider will move through your video. You can also click
274 the <guilabel>Play</guilabel> button to play the content back. Note
275 that there will be no sound, and playback might not be entirely
276 accurate (it may be slightly slower or faster than it should be, for
277 example). This player is really only intended for brief inspection of
278 content; if you need to check it more thoroughly, use another player
279 such as Totem, mplayer or VLC.
285 <title>Setting up</title>
288 Now there are a few things to set up to describe how the DCP should be
289 created. The settings are divided into four tabs: film, video, audio and subtitles.
293 <title>Film tab</title>
296 The ‘film’ tab contains settings that pertain to the whole film, as shown in <xref linkend="fig-film-tab"/>.
299 <figure id="fig-film-tab">
300 <title>Film settings tab</title>
303 <imagedata fileref="screenshots/film-tab&scs;"/>
309 The first thing here is the name. This is generally set to the title
310 of the film that is being encoded. If <guilabel>Use DCI
311 name</guilabel> is not ticked, the name that you specify will be used
312 as-is for the name of the DCP. If <guilabel>Use DCI name</guilabel>
313 is ticked, the name that you enter will be used as part of a
318 Underneath the name field is a preview of the name that the DCP will
319 get. To use a DCI-compliant name, tick the <guilabel>Use DCI
320 name</guilabel> checkbox. The DCI name will be composed using details
321 of your content's soundtrack, the current date and other things that
322 can be specified in the DCI name details dialogue box, which you can
323 open by clicking on the <guilabel>Details</guilabel> button.
327 The <guilabel>Trust content's header</guilabel> button starts off
328 checked, and this means that DVD-o-matic will use the content's header
329 information to determine its length. If, for some reason, this header
330 length is wrong, uncheck the <guilabel>Trust content's
331 header</guilabel> button and DVD-o-matic will run through the content
332 to find its exact length. This may take a while for large pieces of content.
336 Next up is the content type. This can be
337 ‘feature’, ‘trailer’ or whatever; select the
338 required type from the drop-down list.
342 The <guilabel>trim frames</guilabel> settings allow you to trim frames
343 from the beginning and end of the content; any trimmed frames will not
344 be included in the DCP.
350 <title>Video tab</title>
353 This tab contains settings related to the picture in your DCP, as shown in <xref linkend="fig-video-tab"/>.
356 <figure id="fig-video-tab">
357 <title>Video settings tab</title>
360 <imagedata fileref="screenshots/video-tab&scs;"/>
366 The first option on this tab is the format. This will govern the
367 shape that DVD-o-matic will make your image into. Select the aspect
368 ratio that your content should be presented in. The ‘4:3 within
369 Flat’ and ‘16:9 within Flat’ settings will put the
370 image at the specified ratio within a Flat (1.85:1) frame, so that you
371 can project the DCP using your projector's Flat preset.
375 The remaining options can often be left alone, but may sometimes be
376 useful. The ‘crop’ settings can be used to crop your
377 content, which can be used to remove black borders from round the
378 edges of DVD images, for example. The <guilabel>L</guilabel>,
379 <guilabel>R</guilabel>, <guilabel>T</guilabel> and
380 <guilabel>B</guilabel> settings correspond to the left, right, top and
381 bottom of the image respectively. The specified number of pixels will
382 be trimmed from each edge, and the content image in the right of the
383 window will be updated to show the cropping in action.
387 The ‘filters’ settings allow you to apply various video
388 filters to the image. These may be useful to try to improve
389 poor-quality sources like DVDs. We will discuss filtering later in the manual.
394 The ‘scaler’ is the method that will be used to scale up
395 your content to the required size for the DCP, if required. We will
396 discuss the options in more detail later; Bicubic is a fine choice in
404 <title>Audio tab</title>
407 This tab contains settings related to the sound in your DCP, as shown in <xref linkend="fig-audio-tab"/>.
410 <figure id="fig-audio-tab">
411 <title>Audio settings tab</title>
414 <imagedata fileref="screenshots/audio-tab&scs;"/>
421 ‘Audio Gain’ is used to alter the volume of the
422 soundtrack. The specified gain (in dB) will be applied to each sound
423 channel before it is written to the DCP.
427 If you use a sound processor that DVD-o-matic knows about, it can help
428 you calculate changes in gain that you should apply. Say, for
429 example, that you make a test DCP and find that you have to run it at
430 volume 5 instead of volume 7 to get a good sound level in the screen.
431 If this is the case, click the <guilabel>Calculate...</guilabel>
432 button next to the audio gain entry, and the dialogue box in <xref
433 linkend="fig-calculate-audio-gain"/> will open.
436 <figure id="fig-calculate-audio-gain">
437 <title>Calculating audio gain</title>
440 <imagedata fileref="screenshots/calculate-audio-gain&scs;"/>
446 For our example, put 5 in the first box and 7 in the second and click
447 <guilabel>OK</guilabel>. DVD-o-matic will calculate the audio gain
448 that it should apply to make this happen. Then you can re-make the
449 DCP (this will be reasonably fast, as the video data will already have
450 been done) and it should play back at the correct volume with 7 on
451 your sound-rack fader.
455 Current versions of DVD-o-matic only know about the Dolby CP750. If
456 you use a different sound processor, and know the gain curve of its
457 volume control, <ulink url="mailto:cth@carlh.net">get in
462 ‘Audio Delay’ is used to adjust the synchronisation
463 between audio and video. A positive delay will move the audio later
464 with respect to the video, and a negative delay will move it earlier.
468 By default the <guilabel>Use content‘s audio</guilabel> button
469 will be selected. This means that the DCP will use one of the
470 soundtracks from your content file; you can select the soundtrack that
471 you wish to use from the drop-down box.
475 Alternatively, you can supply different sound files by clicking the
476 <guilabel>Use external audio</guilabel> button and choosing a WAV file
477 for any channels that you want to appear in the DCP. These files can
478 be any bit depth and sampling rate, and will be re-sampled and
479 bit-depth converted if required.
484 <title>Subtitles tab</title>
487 This tab contains settings related to subtitles in your DCP, as shown in <xref linkend="fig-subtitles-tab"/>.
490 <figure id="fig-subtitles-tab">
491 <title>Subtitle settings tab</title>
494 <imagedata fileref="screenshots/subtitles-tab&scs;"/>
500 DVD-o-matic will extract subtitles from the content, if present, and
501 they can be ‘burnt into’ the DCP (that is, they are
502 included in the image and not overlaid by the projector). Note that
503 DVD and Blu-Ray subtitles are stored as bitmaps, so it is not possible
504 (automatically) to use non-burnt-in subtitles with these sources.
505 Select the <guilabel>With Subtitles</guilabel> checkbox to enable
506 subtitles. The <guilabel>offset</guilabel> control moves the
507 subtitles up and down the image, and the <guilabel>scale</guilabel>
508 control changes their size.
512 Future versions of DVD-o-matic will hopefully include the option to
513 use text subtitles (as is the norm with most professionally-mastered
521 <title>Making the DCP</title>
524 Now that we have set everything up, choose <guilabel>Make
525 DCP</guilabel> from the <guilabel>Jobs</guilabel> menu. DVD-o-matic
526 will encode your DCP. This may take some time (many hours in some
527 cases). While the job is in progress, DVD-o-matic will update you on
528 how it is getting on with the progress bar in the bottom right hand
529 corner of its window, as shown in <xref linkend="fig-making-dcp"/>.
532 <figure id="fig-making-dcp">
533 <title>Making the DCP</title>
536 <imagedata fileref="screenshots/making-dcp&scs;"/>
542 When it has finished, the DCP will end up on your disk inside the
543 film's directory. You can then copy this to a projector via a USB
544 stick, hard-drive or network connection.
548 Alternatively, if you have a projector or TMS that is accessible via
549 SCP across your network, you can upload the content directly from
550 DVD-o-matic. See <xref linkend="sec-tms-upload"/>.
557 <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
558 <title>Creating a still-image DCP</title>
561 DVD-o-matic can also be used to create DCPs of a still image, perhaps
562 for an advertisement or an on-screen announcement. This chapter shows you
567 As with video DCPs, the first step is to create a new
568 ‘Film’; select <guilabel>New</guilabel> from the
569 <guilabel>File</guilabel> menu and the new film dialogue will open as
570 shown in <xref linkend="fig-still-new-film"/>.
573 <figure id="fig-still-new-film">
574 <title>Dialogue box for creating a new film</title>
577 <imagedata fileref="screenshots/still-new-film&scs;"/>
583 Enter a name and click <guilabel>OK</guilabel>. Then we set up the
584 content; click the content selector as before, and this time we will
585 choose an image file, as shown in <xref
586 linkend="fig-still-select-content-file"/>.
589 <figure id="fig-still-select-content-file">
590 <title>Selecting a still content file</title>
593 <imagedata fileref="screenshots/still-select-content-file&scs;"/>
599 Setting up for a still image DCP is somewhat simpler than for a video;
600 the tabs are all the same, but many options are removed and a few are added.
604 As with video, you can select a content type and the format (ratio)
605 that your image should be presented in. It will be scaled and padded
606 to fit the selected ratio, but in such a way that the pixel aspect
607 ratio is preserved. In other words, the image will not be stretched,
608 merely scaled; if you want to stretch your image, you will need to do
609 so in a separate program before importing it into DVD-o-matic. You
610 can also crop your image, if you so choose, and then set a duration
611 (in seconds) that the image should appear on screen.
615 Still-image DCPs can include sound; this can be added from the
616 <guilabel>Audio</guilabel> tab. If your specified duration is shorter
617 than the audio, the audio will be cut off at the duration; if it is
618 longer, silence will be added after your audio.
622 Finally, as with video, you can choose <guilabel>Make DCP</guilabel>
623 from the <guilabel>Jobs</guilabel> menu to create your DCP. This will
624 be much quicker than creating a video DCP, as DVD-o-matic only needs
625 to encode a single frame which it can then repeat.
631 <chapter xml:id="ch-preferences" xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
632 <title>Preferences</title>
635 DVD-o-matic provides a few preferences which can be used to modify its
636 behaviour. This chapter explains those options.
640 <title>The preferences dialogue</title>
643 The preferences dialogue is opened by choosing
644 <guilabel>Preferences...</guilabel> from the <guilabel>Edit</guilabel>
645 menu. The dialogue is shown in <xref linkend="fig-prefs"/>.
648 <figure id="fig-prefs">
649 <title>Preferences</title>
652 <imagedata fileref="screenshots/prefs&scs;"/>
658 <title>TMS setup</title>
661 The first part of the dialogue gives some options for specifying
662 details about your TMS. If you do this, and your TMS accepts SSH
663 connections, you can upload DCPs directly from DVD-o-matic to the TMS.
664 This is discussed in <xref linkend="sec-tms-upload"/>.
668 <guilabel>TMS IP address</guilabel> should be set to the IP address of
669 your TMS, <guilabel>TMS target path</guilabel> to the place that DCPs
670 should be uploaded to (which will be relative to the home directory of
671 the SSH user). Finally, the user name and password are the
672 credentials required to log into the TMS via SSH.
677 <title>Threads</title>
680 When DVD-o-matic is encoding DCPs it can use multiple parallel threads
681 to speed things up. Set this value to the number of threads
682 DVD-o-matic should use. This would typically be set to the number of
683 processors (or processor cores) in your machine.
689 <title>Default directory for new films</title>
692 This is the directory which DVD-o-matic will suggest initially as a place to put new films.
698 <title>Colour look-up table</title>
701 This specifies the colour space that your input content will be
702 expected to be in. If in doubt, leave it set to ‘sRGB’.
708 <title>A/B options</title>
711 These options are for DVD-o-matic's special mode of making A/B
712 comparison DCPs for checking the performance of video filters. Their
713 use is described in <xref linkend="sec-ab"/>.
719 <title>Encoding servers</title>
722 If you have spare machines sitting around on your network not doing
723 much, they can be pressed into service to speed up DCP encodes. This
724 is done by running a small server program on the machine, which will
725 encode video sent to it by the ‘master’ DVD-o-matic. This
726 option is described in more detail in <xref linkend="sec-servers"/>.
727 Use these preferences to specify the encoding servers that should be
736 <chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:lang="en">
737 <title>Advanced topics</title>
739 <para>This chapter describes some parts of DVD-o-matic that are
740 probably not essential, but which you might find useful in some
745 <title>Filtering</title>
748 DVD-o-matic offers a variety of filters that can be applied to your
749 video content. You can set up the filters by clicking the
750 <guilabel>Edit</guilabel> button next to the filters entry in the
751 setup area of the DVD-o-matic window; this opens the filters selector
752 as shown in <xref linkend="fig-filters"/>.
755 <figure id="fig-filters">
756 <title>Filters selector</title>
759 <imagedata fileref="screenshots/filters&scs;"/>
765 As it stands, these filters are somewhat disorganised! Work is
766 ongoing to test them with various content and choose a selection which
767 work well for cinema applications.
771 If you want to examine them yourself, you may find the A/B option (see
772 <xref linkend="sec-ab"/>) useful.
776 After changing the filters setup, you will need to regenerate the DCP
777 to see the effect on the cinema screen. The preview in DVD-o-matic
778 will update itself whenever filters are changed, though of course this
779 image is much smaller and of lower resolution than a projected image!
785 <title>Scaling</title>
788 If your source material is not of the DCI-specified size, or if it
789 uses non-square pixels, DVD-o-matic will need to scale it. The
790 algorithm used to scale is set up by the <guilabel>Scaler</guilabel>
791 entry in the film setup area. We think ‘Bicubic’ is the
792 best all-round option, but tests are ongoing.
797 <section xml:id="sec-tms-upload">
798 <title>TMS upload</title>
801 If you have configured details of a TMS in the preferences dialogue
802 (<xref linkend="ch-preferences"/>) you can upload a completed DCP
803 straight to your TMS but choosing <guilabel>Send DCP to TMS</guilabel>
804 from the <guilabel>Jobs</guilabel> menu.
810 <section xml:id="sec-ab">
811 <title>A/B comparison</title>
814 When evaluating the effects of different filters or scalers on the
815 image quality, A/B mode might be useful. In this mode, DVD-o-matic
816 will generate a DCP where the left half of the image uses some
817 ‘reference’ filtering and scaling, and the right half of
818 the image uses a different set of filters and a different scaler.
819 This DCP can then be played back on a projector and the image quality
824 To enable A/B mode, click the A/B checkbox in the setup area of the
825 DVD-o-matic window. When you generate your DCP, the left half of the
826 screen will use the filters and scaler specified in the <xref
827 linkend="ch-preferences">preferences</xref> dialogue, and the right
828 half will use the filters and scaler specified in the film setup.
833 <section xml:id="sec-servers">
834 <title>Encoding servers</title>
837 One way to increase the speed of DCP encoding is to use more
838 than one machine at the same time. An instance of DVD-o-matic can
839 offload some of the time-consuming JPEG2000 encoding to any number of
840 other machines on a network. To do this, one ‘master’
841 machine runs DVD-o-matic, and the ‘server’ machines run
842 a small program called ‘servomatic’.
846 <title>Running the servers</title>
849 There are two options for the encoding server;
850 <code>servomatic_cli</code>, which runs on the command line, and
851 <code>servomatic_gui</code>, which has a simple GUI. The command line
852 version is well-suited to headless servers, especially on Linux, and
853 the GUI version works best on Windows where it will put an icon in the
858 To run the command line version, simply enter:
866 at a command prompt. If you are running the program on a machine with
867 a multi-core processor, you can run multiple parallel encoding threads
868 by doing something like:
876 to run 4 threads in parallel.
880 To run the GUI version on windows, run the ‘DVD-o-matic encode
881 server’ from the start menu. An icon will appear in the system
882 tray; right-click it to open a menu from whence you can quit the
883 server or open a window to show its status.
888 <title>Setting up DVD-o-matic</title>
891 Once your servers are running, you need to tell your master
892 DVD-o-matic instance about them. Start DVD-o-matic and open the
893 <guilabel>Preferences</guilabel> dialog from the
894 <guilabel>Edit</guilabel> menu. At the bottom of this dialog is a
895 section where you can add, edit and remove encoding servers. For each
896 encoding server you need only specify its IP address and the number of
897 threads that it is running, so that DVD-o-matic knows how many
898 parallel encode jobs to send to the server.
902 Once this is done, any encodes that you start will split the workload
903 up between the master machine and the servers.
908 <title>Some notes about encode servers</title>
911 DVD-o-matic does not mind if servers come and go; if a server
912 disappears, DVD-o-matic will stop sending work to it, and will check
913 it every minute or so in case it has come back online.
917 You will probably find that using a 1Gb/s or faster network will
918 provide a significant speed-up compared to a 100Mb/s network.
922 Making changes to the server configuration in the master DVD-o-matic
923 will have no effect while an encode is running; the changes will only
924 be noticed when a new encode is started.