back to chris' bitpool

the chaplin homepage

a dvd chapter tool for Linux

(and all other *ixes with libdvdread support)


The tool parses a DVD disc or image and extracts the exact duration for each chapter of a given title. Then the total list of chapters is split into a user-selectable number of subsets. Each subset should have approximately the same duration.

This is a very useful approach for multi-cd rips. You no longer simply split the movie in the middle of the frame count but you choose two sets of chapters for both parts which both have (almost) the same length. Then the disc-break is not at a rather random point (concering the story telling of the movie) but at the end of a dvd-chapter.

The chapter timings and the split sets are also very useful for chapter navigation (even on a single disc). The normal output mode of chaplin thus prints the chapter's relative beginning time and the duration in a wide number of formats, ranging from seconds, frame counts to timestamps.

For S/VCD mastering chaplin can also produce vcdimager XML files for each disc. There a complete sequence structure with chapter entry points is defined. Also the full navigation setup for chapter hopping is provided. Additionally you can add chapter menus and automatically create the necessary menu pages out of thumbnails extracted directly from the DVD.


Revision: 1.10 (21.3.2004) chaplin-1.10.tgz (md5: 76971356e3c2aebaca45dc0780490c0a)

Revision: 1.9 (1.2.2004) chaplin-1.9.tgz

Revision: 1.8 (15.9.2002) chaplin-1.8.tgz

Revision: 1.7 (19.5.2002) chaplin-1.7.tgz


You will need the libdvdread library for this tool. Specify its installation path in the provided Makefile. Then a simple call to "make" should build the chaplin binary. Copy the binary into your PATH. It is very useful to have transcode and vcdimager installed. The chaplin-genmenu tool needs transcode, ImageMagick and the mjpegtools.


Simple Usage

Just call chaplin the following way:

chaplin -d <dvd_path> -t <title>

This will display a chapter summary and places all chapters into a single subset (the default). This is useful for a single cd transfer. For multi-cd targets you specify the number of subsets with the -p option:

chaplin -d <dvd_path> -t <title> -p 2

This will divide the chapters up into 2 subsets. They should have almost the same size (this depends largely on the granularity of the provided chapters). Now you know which chapters fit on the first disc, know the exact frame count and you can calculate the exact bitrate for this part and finally transcode each part.

Chapter Info

Detailed info on the chapters is also available. Just add the -c option and per chapter info is printed:

chaplin ... -c

The standard output mode prints the relative offset of each chapter in the part. With the -l option you can replace this display with the length of each chapter.

S/VCD Mastering

If your target is a set of S/VCDs then the -x option is very useful:

chaplin ... -x MYMOVIE

MYMOVIE is the basename of the VCDs.

This option generates a XML S/VCD description for vcdimager which contains the exact chapter setup found by chaplin. The XML files are called "vcdNN.xml" and are created in the current directory. Name the MPEG files made from each subset "partNN.mpg" and place them in the same directory (NN=part number). Now a call to:

vcdxbuild vcdNN.xml

should generate a SVCD image with chapters and navigation information.

You can control the XML generation by passing suboptions to -x:

chaplin ... -x MYMOVIE,vcd,my%02d.xml,movie%02.mpg

This will generate VCD 2.0 XML files called myNN.xml and refers to MPEG movie files called movieNN.mpg. Do not forget to include a "%d" expression in the XML and MPEG file patterns. This will be replaced by the current part number. Numbering starts with one by default. Chaplin will begin with zero if you pass the -z option.

The second argument defines the type of the disc: vcd or svcd.

S/VCD Chapter Menus

Since version 1.9 chaplin also supports the creation of XML mastering files for S/VCDs with chapter menus. Add the -m option to -x to enable menu creation. You have to specify how many chapters are selectable on each menu page. chaplin will then create a menu page set for each of the selected parts and each menu page will contain at most the given number of entries:

chaplin ... -x MYMOVIE,svcd,my%02d.xml,movie%02.mpg,menu%02d-%d.mpg -m 6 

In this example menu pages with up to six entries are created and labeled menu%02d-%d.mpg. Note the two %d replacement tags in the menu file name. The first one is replaced with the current part number and the second one counts the menu pages for this part. The generated XML will create a SVCD that shows the first menu page and allows to select the first six chapters with the numeric buttons. Furthermore you can switch to the next menu page.

The referenced menu pages are MPEG files containing still images. Each menu page should depict the chapters that can be selected on this page. The menu pages can be rendered automatically with the chaplin-genmenu tool.

Automatic Chapter Menu Generation

The chaplin-genmenu script creates the chapter menu still image MPG files that are referenced in the S/VCD chapter menus. To guide this tool what should be rendered on each menu page, you have to create a chapling menu description with the -g command:

chaplin ... -x ... -m <n> -g menu.txt 

Now have a look a the created menu description text file. Its splitted into blocks for each menu page:

chaplin-menu 9
dvd "/dev/dvd" title 10 PAL 4:3

menu01-1.mpg 9 Part 1 Menu 1
01 0 Chapter 1
02 0 Chapter 2
03 0 Chapter 3
04 0 Chapter 4
05 0 Chapter 5
06 0 Chapter 6
07 0 Chapter 7
08 0 Chapter 8
09 0 Chapter 9
menu01-2.mpg 6 Part 1 Menu 2
10 0 Chapter 10
11 0 Chapter 11
12 0 Chapter 12
13 0 Chapter 13
14 0 Chapter 14
15 0 Chapter 15

The description contains the menu files to create and the chapters that are referenced on each page. You can edit this file to change the sample frame for each chapter that will be extracted to get the thumbnail image on the menu page: change the 0 value in the second column to the requested frame number. Finally you can edit the text that gets rendered on the menu pages: The title of each menu page is given in the title line (e.g.: "Part 1 Menu 1") and the chapter description after each frame number (e.g.: "Chapter 1").

Now run the menu page creator:

chaplin-genmenu menu.txt

This sets the dvd input device and title similar to the chaplin call and pass the generated chaplin menu description. This will create the MPG still images needed for S/VCD creation out of the XML file.

Specify -n NTSC if creating a NTSC and not a PAL S/VCD. Use -v if creating a VCD and not a SVCD.

With -o you can set a global offset for each chapter sample frame number. The -u option cleans up all temporary files created during program call. -x will display all external command calls to debug the tool.

With -b, -l and -f you can adjust the rendering of the menu pages.

Note that chaplin-genmenu is an incremental tool that only creates files that are not yet existing in the current path. So you can first call the tool (without -u) to create all intermediate files. Then you can retouch or repaint the menu PNG files and call the tool again to build MPG files. If you pass the -c switch then all files are recreated always.


Switch Purpose Default
-d <dvd_path> Specify DVD disc device or image directory /dev/dvd
-t <title> Select DVD title 1
-p <n> Split chapters into <n> subsets 1
-r Reset chapter numbering in each subset off
-z Start part numbering with zero not one off
-c Print chapter information off
-l Print chapter length not offset off
-f <framerate> Calculate the frame numbers of the output for the given framerate PAL: 25, NTSC: 30
-x <opts>

Generate XML files for vcdimager

opts: <title>[,<vcdtype>][,<xml-file-pattern>][,<mpg-video-pattern>][,<mpeg-menu-pattern>]

-m <entries> Generate XML chapter menus with <entries> entries on each page off
-g <file> Save the menu layout of the -m command for the chaplin-genmenu tool to a file off
-y <file> Save the 16 colors of the YUV color palette of the selected title as a text file off
-v Be very verbose off