gitchangelog.sh: state inside comments that GNU sed is required
[cdimgtools:cdimgtools.git] / dvdimgdecss.1.txt
1 // dvdimgdecss.1.txt - manual page documenting the program dvdimgdecss
2 // Copyright © 2012 Géraud Meyer
3 //   This file is part of dvdimgdecss.
4 //
5 //   This file is released under the same licensing terms as the source code of
6 //   the program which it documents; see the header of the file dvdimgdecss.c.
7
8 DVDIMGDECSS(1)
9 ==============
10 :doctype: manpage
11
12
13 NAME
14 ----
15 dvdimgdecss - CSS descrambling of raw DVD Video images
16
17
18 SYNOPSIS
19 --------
20 [verse]
21 *dvdimgdecss* *-V*
22 *dvdimgdecss* [*-v*|*-q*] [*-c*] [*--*] 'dvd'
23 *dvdimgdecss* [*-v*|*-q*] [*-c*|*-C*] [*--*] 'dvd' 'file'
24
25
26 DESCRIPTION
27 -----------
28 `dvdimgdecss` is a command line program to remove the CSS scrambling of DVD
29 Video image files.
30
31 dvdimgdecss uses libdvdread and libdvdcss, and passes them 'dvd' as is.  'dvd'
32 can be a drive device file or a raw image file.
33
34 If 'file' is not given, dvdimgdecss only computes (and prints) the sector
35 ranges corresponding to each file pertaining to the DVD Video.
36
37 If 'file' is given, it furthermore copies 'dvd' to 'file', possibly decrypting
38 the sector ranges corresponding to VOB files.  The actual reading and
39 decryption is done by libdvdcss.
40
41
42 OPTIONS
43 -------
44 *-V*::
45         Print the version information and exit.
46
47 *-v*, *-q*::
48         Increase or decrease the level of verbosity of messages printed to
49         stdout/stderr.  The default level is 1, at which only error messages are
50         printed.  At level 0 nothing is printed.  At level 2, each domain (title)
51         is displayed as it is processed.  At level 3, a percentage indicator is
52         displayed.
53         The messages printed by libdvdcss are controlled by the environment
54         variable 'DVDCSS_VERBOSE'; libdvdread's messages cannot be silenced.
55
56 *-c*::
57         Make libdvdread search for all the title keys and print the result; while
58         copying and decrypting the 'dvd', enable some consistency checks made by
59         using libdvdread.
60         While decrypting, libdvdcss will nonetheless retrieve the title keys again;
61         if the cache directory is in use, the keys will simply be read from it.
62
63 *-C*::
64         Use libdvdread instead of libdvdcss for reading (and decrypting) the VOB
65         streams of the 'dvd'.  This implies *-c*, and avoids a new search of the
66         title keys by libdvdcss.  It is not known (yet) whether libdvdread perform
67         additional checks (compared to libdvdcss alone).
68
69
70 ENVIRONMENT VARIABLES
71 ---------------------
72 DVDCSS_*::
73         libdvdcss' environment variables.
74
75 DVDREAD_NOKEYS::
76         libdvdread's environment variable.  Setting this variable prevents
77         libdvdread from trying to retrieve all the title keys at once, even when
78         the option *-c* is given.
79
80
81 FILES
82 -----
83 ~/.dvdcss::
84         libdvdcss' default cache directory for the title keys.  Setting
85         `DVDCSS_CACHE=off` in the environment disables the use of the cache.
86
87
88 EXIT STATUS
89 -----------
90 To be interpreted as a bitmask, where each bit set indicates a failure.
91 Because a usage error always sets all the other bits, the values between 128
92 and 254 remain unused; they constitute a range often used by shells (e.g. bash
93 or older versions of ksh) to indicate an abnormal process termination (killed
94 by a signal).
95
96 *0*::
97         No errors.
98
99 *255*::
100         Usage error (invalid option or wrong number of arguments).
101
102 *64*::
103         I/O error.  If a file could not be opened, the exit status is 127.
104
105 *32*::
106         Inconsistencies found (probably because of a bug in dvdimgdecss or its
107         libraries).
108
109 *16*::
110         Cancellation due to a memory allocation error.
111
112 *8*::
113         No VOBs were found in the DVD; the output file is the same as the 'dvd' if
114         there are no other errors.
115
116
117 EXAMPLES
118 --------
119 If the disc can be read without errors, reading directly from the drive has the
120 advantage of making the disc key available to libdvdcss:
121
122 [source,sh]
123 dvdimgdecss /dev/sr0 dvd.img
124
125 It is possible to decrypt a file without a drive (without a disc key);
126 furthermore, we bypass the key cache and make libdvdcss print the new keys
127 found:
128
129 [source,sh]
130 DVDCSS_VERBOSE=2 DVDCSS_CACHE=off dvdimgdecss dvd.img dvd.img.decss
131
132 You might then burn the image to an optical disc.
133
134
135 BUGS
136 ----
137 It seems, after a look at its source code, that libdvdcss does not report all
138 the error conditions that it encounters.
139
140 See also the CDimgtools distribution file 'BUGS'.
141
142
143 AUTHOR
144 ------
145 dvdimgdecss was written by G.raud Meyer.
146
147
148 SEE ALSO
149 --------
150 linkpage:cssdec[1], lsdvd(1), vobcopy(1), dvdbackup(1)