/*! \page tutorial A libdvdnav Tutorial The libdvdnav library provides a powerful API allowing your programs to take advantage of the sophisticated navigation features on DVDs. \subsection wherenow Tutorial sections - For an introduction to the navigation features of DVDs look in section \ref dvdnavissues . This also provides an overview of the concepts required to understand DVD navigation. - For a step-by step walkthrough of a simple program look in section \ref firstprog . - FIXME: More sections :) */ /*! \page dvdnavissues An introduction to DVD navigation The DVD format represents a radical departure from the traditional form of video home-entertainment. Instead of just being a linear programme which is watched from beginning to end like a novel DVD allows the user to jump about at will (much like those 'Choose your own adventure' or 'Which Way' books which were popular a while back). Such features are usually referred to under the moniker 'interactive' by marketing people but you aren't in marketing since you are reading the libdvdnav tutorial. We'll assume you actually want to know precisely what DVD can do. \subsection layout DVD logical layout A DVD is logically structured into titles, chapters (also known as 'parts'), cells and VOBUS, much like the filesystem on your hard disc. The structure is heirachical. A typical DVD might have the following structure: \verbatim . |-- Title 1 | |-- Chapter 1 | | |-- Cell 1 | | | |-- VOBU 1 | | | |-- ... | | | `-- VOBU n | | |-- ... | | `-- Cell n | |-- ... | `-- Chapter 2 | |-- Cell 1 | | |-- VOBU 1 | | |-- ... | | `-- VOBU n | |-- ... | `-- Cell n |-- ... `-- Title m |-- Chapter 1 | |-- Cell 1 | | |-- VOBU 1 | | |-- ... | | `-- VOBU n | |-- ... | `-- Cell n |-- ... `-- Chapter 2 |-- Cell 1 | |-- VOBU 1 | |-- ... | `-- VOBU n |-- ... `-- Cell n \endverbatim A DVD 'Title' is generally a logically distinct section of video. For example the main feature film on a DVD might be Title 1, a behind-the-scenes documentary might be Title 2 and a selection of cast interviews might be Title 3. There can be up to 99 Titles on any DVD. A DVD 'Chapter' (somewhat confusingly referred to as a 'Part' in the parlence of DVD authors) is generally a logical segment of a Title such as a scene in a film or one interview in a set of cast interviews. There can be up to 999 Parts in one Title. A 'Cell' is a small segment of a Part. It is the smallest resolution at which DVD navigation commands can act (e.g. 'Jump to Cell 3 of Part 4 of Title 2'). Typically one Part contains one Cell but on complex DVDs it may be useful to have multiple Cells per Part. A VOBU (Video OBject Unit) is a small (typically a few seconds) of video. It must be a self contained 'Group of Pictures' which can be understood by the MPEG decoder. All seeking, jumping, etc is guaranteed to occur at a VOBU boundary so that the decoder need not be restarted and that the location jumped to is always the start of a valid MPEG stream. For multiple-angle DVDs VOBUs for each angle can be interleaved into one Interleaved Video Unit (ILVU). In this case when the player get to the end of the VOBU for angle n instead of jumping to the next VOBU the player will move forward to the VOBU for angle n in the next ILVU. This is summarised in the following diagram showing how the VOBUs are actually laid out on disc. \verbatim ,---------------------------. ,---------------------------. | ILVU 1 | | ILVU m | | ,--------. ,--------. | | ,--------. ,--------. | | | VOBU 1 | ... | VOBU 1 | | ... | | VOBU m | ... | VOBU m | | | |Angle 1 | |Angle n | | | |Angle 1 | |Angle n | | | `--------' `--------' | | `--------' `--------' | `---------------------------' `---------------------------' \endverbatim \subsection vm The DVD Virtual Machine If the layout of the DVD were the only feature of the format the DVD would only have a limited amount of interactivity, you could jump around between Titles, Parts and Cells but not much else. The feature most people associate with DVDs is its ability to present the user with full-motion interactive menus. To provide these features the DVD format includes a specification for a DVD 'virtual machine'. To a first order approximation x86 programs can only be run on x86-based machines, PowerPC programs on PowerPC-based machines and so on. Java, however, is an exception in that programs are compiled into a special code which is designed for a 'Java Virtual Machine'. Programmes exist which take this code and convert it into code which can run on real processors. Similarly the DVD virtual machine is a hypothetical processor which has commands useful for DVD navigation (e.g. Jump to Title 4 or Jump to Cell 2) along with the ability to perform simple arithmetic and save values in a number of special variables (in processor speak, they are known as 'registers'). When a button is pressed on a DVD menu, a specified machine instruction can be executed (e.g. to jump to a particular Title). Similarly commands can be executed at the beginning and end of Cells and Parts to, for example, return to the menu at the end of a film. Return to the \ref tutorial. */ /*! \page firstprog A first libdvdnav program \section compiling Compiling a libdvdnav program Below is a simple libdvdnav program. Type/copy it and save it into the file 'dvdtest.c'. \verbatim #include #include #include #include int main(int argc, char **argv) { dvdnav_t *dvdnav; int finished, len, event; uint8_t buf[2050]; /* Open the DVD */ dvdnav_open(&dvdnav, "/dev/dvd"); fprintf(stderr, "Reading...\n"); finished = 0; while(!finished) { int result = dvdnav_get_next_block(dvdnav, buf, &event, &len); if(result == DVDNAV_STATUS_ERR) { fprintf(stderr, "Error getting next block (%s)\n", dvdnav_err_to_string(dvdnav)); exit(1); } switch(event) { case DVDNAV_BLOCK_OK: /* Write output to stdout */ fwrite(buf, len, 1, stdout); break; case DVDNAV_STILL_FRAME: { fprintf(stderr, "Skipping still frame\n"); dvdnav_still_skip(dvdnav); } break; case DVDNAV_STOP: { finished = 1; } default: fprintf(stderr, "Unhandled event (%i)\n", event); finished = 1; break; } } dvdnav_close(dvdnav); return 0; } \endverbatim If you have correctly installled libdvdnav, you should have the command 'dvdnav-config' in your path. If so you can compile this program with \verbatim gcc -o dvdtest dvdtest.c `dvdnav-config --cflags --libs` \endverbatim If all goes well, this should generate the 'dvdtest' program in your current working directory. You can now start saving a MPEG 2 stream directly off your DVD with \verbatim ./dvdtest 2>error.log >out.mpeg \endverbatim If the command fails, check the error.log file for details. \section walkthrorugh Line-by-line walk through \verbatim include include include include \endverbatim These lines include the necessary headers. Almost all libdvdnav programs will only need to include the dvdnav.h and dvdnav_events.h header files from the dvdnav directory. \verbatim dvdnav_open(&dvdnav, "/dev/dvd"); \endverbatim The libdvdnav uses libdvdread for its DVD I/O. libdvdread accesses the DVD-device directly so dvdnav_open() needs to be passed the location of the DVD device. libdvdread can also open DVD images/mounted DVDs. Read the libdvdread documentation for more information. \verbatim int result = dvdnav_get_next_block(dvdnav, buf, &event, &len); \endverbatim Return to \ref tutorial. */