Subversion Repositories LCARS

Rev

Rev 20 | Go to most recent revision | Details | Compare with Previous | Last modification | View Log | RSS feed

Rev Author Line No. Line
20 PointedEar 1
\" dvdsubtitles.1 - the *roff document processor src for the dvdsubtitles manual
2
\"
3
\" This file is part of PointedEars' DVD Subtitles.
4
\" Copyright (C) 2005, 2006  Thomas Lahn <dvd@PointedEars.de>
5
\"
6
\" Permission is granted to copy, distribute and/or modify this document
7
\" under the terms of the GNU Free Documentation License, Version 1.2
8
\" or any later version published by the Free Software Foundation;
9
\" with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
10
\" Texts.  A copy of the license is available on the Web[1] or
11
\" from the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
12
\" Boston, MA  02110-1301  USA.
13
\"
14
\" [1] <http://www.gnu.org/licenses/licenses.html#FDL>
15
\"
16
\" You may contact the author by:
17
\" e-mail: dvd@PointedEars.de
18
\" snail mail:
19
\"   Thomas Lahn
20
\"   Warschauer Strasse 1a/0403
21
\"   D-99089 Erfurt
22
\"   Federal Republic of Germany
23
 
24
.TH dvdsubtitles 1 "2006-02-15" "0.6.1.2006021519" "DVD Tools"
25
 
26
 
27
.SH NAME
21 PointedEar 28
dvdsubtitles \- Extract subtitle stream from DVD-Video data to text file
20 PointedEar 29
 
30
 
31
.SH SYNOPSIS
32
 
33
.B dvdsubtitles
34
.br
35
.RB [ -hVkl ]
36
.RB [ -t
37
.IR TITLE ]
38
.RB [ -s
39
.IR SUBTITLE ]
40
.RB [ -o
41
.IR TARGET ]
42
.RB [ -g
43
.IR GREY_LEVELS ]
44
.RI [ SOURCE ]
45
 
46
.PP
47
.B dvdsubtitles
48
.B -c
49
.RI ( FILE " | " DIRECTORY )
50
.RB [ -o
51
.IR TARGET ]
52
 
53
.PP
54
.B dvdsubtitles
55
.RB [ -hVkl ]
56
.RI [ SOURCE
57
.RI [ TITLE
58
.RI [ SUBTITLE
59
.RI [ TARGET
60
.RI [ GREY_LEVELS ]]]]]
21 PointedEar 61
.br
62
(deprecated)
20 PointedEar 63
 
64
 
65
.SH DESCRIPTION
66
 
67
Uses
68
.BR tccat (1)
69
and
70
.BR tcextract (1)
71
from the
72
.B transcode
21 PointedEar 73
package to extract a subtitle stream from DVD-Video data.  This stream
74
is converted into image files with
20 PointedEar 75
.BR subtitle2pgm ,
76
and those are converted to text files using
77
.BR pgm2txt ,
78
both from the
79
.B subtitleripper
80
package, which in turn calls
81
.BR gocr (1).
82
.PP
83
The previously created subtitle index file (.srtx) and the resulting text
84
files are then compiled into one text file using either
85
.BR srttool ,
86
from the
87
.B subtitleripper
88
package, or
89
.BR sed (1).
90
(See Output Format below.)
91
.PP
92
The
93
.B -c
21 PointedEar 94
option allows for compiling existing text files into that format according to
20 PointedEar 95
a subtitle index file without extracting a subtitle stream first (see below).
96
\" .PP
97
\" If the
98
\" .B -S
99
\" option is used, this program also performs a minor correction of common
100
\" misrecognition errors via
101
\" .BR sed (1),
102
\" i.e. a standalone `l' (small letter L) or one followed by an apostrophe
103
\" is converted to `I' (capital letter I).
104
.PP
105
All temporary files are deleted afterwards (`clean-up'), unless a fatal error
106
occurred or a user interrupt was detected; the extracted subtitle stream file
107
is kept for future use if the
108
.B -k
109
option is used.
110
.PP
111
Based on
112
.B DVD ripping and transcoding with Linux
113
by Moritz Bunkus <moritz@bunkus.org>, available at
114
.br
115
<\fIhttp://www.bunkus.org/dvdripping4linux/\fP>.
116
 
117
.SS Output Format
118
The format of the subtitle text file this program creates is similar to that the
119
.B SubRip
120
program creates:
121
.PP
122
.I Subtitle number
123
.br
124
.IB "Start time " --> " End time"
125
.br
126
.I Text of subtitle (one or more lines)
127
.br
128
.I Blank line
129
.PP
130
Like the SubRip format, field data starts at the beginning of each line.
131
The time format used is `\fIhours\fB:\fIminutes\fB:\fIseconds\fR',
132
.I hours
133
and
134
.I minutes
135
with two digits each. The
136
.I seconds
137
field is precise to three decimal points; the decimal separator used is
138
the comma.
139
.PP
140
Different to the SubRip format, the line break used is the
141
standard UNIX Line Feed (LF, 0x0A) character.  The
142
.I Subtitle number
143
field was not included before version 0.6.1.
144
 
145
 
146
.SH OPTIONS
147
 
148
Options are supported since version 0.4.  This aims at achieving POSIX
149
conformance and easy introduction of new features while maintaining
21 PointedEar 150
backwards compatibility to versions before 0.4.  However, non-option
151
calls are deprecated and may not be supported in future versions.
20 PointedEar 152
.PP
153
If additional program arguments are used, any option argument is
154
overwritten by the corresponding program argument.  Options may be
155
given in any order, and are also considered options if located after
156
the first program argument.  Too many program arguments are silently
157
ignored.
158
 
159
.IP "\fB-c\fP, \fB--compile\fP (\fIFILE\fP | \fIDIRECTORY\fP)"
160
(since version 0.6.1, \fBTODO\fP)  Compile one group, or all groups of
161
subtitle text files in
162
.IR DIRECTORY ,
163
according to a corresponding subtitle index
164
.I FILE
165
(.srtx), into one text file each.  If this is successful, clean up (see
166
.BR -k )
167
and exit.
168
Options irrelevant to this process are ignored.
169
 
170
.RS
171
If a
172
.I DIRECTORY
173
is specified as argument, the
174
.B -o
175
option is ignored.  The resulting text files are named after the
176
corresponding subtitle index files found in the
177
.I DIRECTORY
178
instead, and their name is suffixed with `\fB.srt\fP'.
179
.RE
180
 
181
.IP "\fB-k\fP, \fB--keep\fP"
182
(since version 0.6)  Keep subtitle stream file even if conversion is successful.
183
 
184
.IP "\fB-l\fP, \fB--list\fP"
185
(since version 0.5)  List subtitles for
186
.I TITLE
187
using
188
.BR mplayer (1)
189
and exit.  If
190
.I TITLE
191
is not provided or
192
.RB ` - ',
193
list subtitles for title #2 (as title #1 may be an intro without subtitles) and
194
exit.
195
 
196
.IP "\fISOURCE\fP"
197
Video DVD data source, i.e. a device
198
.RI "(usually " /dev/dvd ),
199
a directory e.g. one containing content created via
200
.BR dvdbackup (1),
201
or a Video DVD image file.
202
.br
203
If
204
.RB ` - ',
205
a previously created subtitle stream file named
206
\fBsubtitle_stream-\fP*\fB-\fP\fITITLE\fP-\fISUBTITLE\fP
207
in the current working directory will be used for only the
208
stream-to-graphics-to-text conversion instead.  Both
209
.I TITLE
210
and
211
.I SUBTITLE
212
must not be
213
.BR ` - '
214
in that case.
215
.br
216
The default is
217
.RI ` /dev/dvd '.
218
 
219
.IP "\fB-t\fP, \fB--title\fP \fITITLE\fP"
220
Number of the title (1-n) which will be accessed for subtitle stream extraction.
221
If omitted or
222
.RB ` - ',
223
the program uses
224
.BR mplayer (1)
225
to detect how many titles are available on the DVD data source and asks for the
226
title to be accessed.
227
 
228
.IP "\fB-s\fP, \fB--subtitle-id\fP \fISUBTITLE\fP"
229
ID of the subtitle stream to be extracted (0-n).  If omitted or
230
.RB ` -  ',
231
the program uses its
232
.B -l
233
option (or
234
.BR mplayer (1)
235
directly, before version 0.5) to detect which subtitles are available for the
236
given TITLE and asks for the ID to be used.
237
 
238
.IP "\fB-o\fP, \fB--output-target\fP \fITARGET\fP"
239
Name of the resulting subtitles text file.  If not provided or
240
.RB ` - ',
241
the file is named after the subtitle stream file.
242
 
243
.RS
244
Versions prior to 0.6 appended the filename suffix
245
.B .txt
246
automagically always, and version 0.6 appended this suffix only if this option
247
was not provided; since version 0.6.1, the filename suffix
248
.B .srt
249
(SubRip text) is appended in that case.
250
 
251
.PP
252
If the file already existed, behavior depends on the program version.
253
 
254
.IP "Since version 0.6.1:"
255
The program asks whether the file should be overwritten, new content should
256
be appended to it (including a marker identifying the start of new content),
257
or if a new file should be created.  If the latter, the name of new file
258
includes the ID of the
259
.B dvdsubtitles
260
process which created it.
261
 
262
.IP "Version 0.6:"
263
The program asks whether the file should be overwritten. If no, a new file
264
is created, its name including the ID of the
265
.B dvdsubtitles
266
process which created it.
267
 
268
.IP "Versions prior to 0.6:"
269
New content is appended to the file without marker.
270
.RE
271
 
272
.IP "\fB-g\fP, \fB--grey-levels\fP \fIGREY_LEVELS\fP"
273
Optional grey-levels value `\fIc0\fP,\fIc1\fP,\fIc2\fP,\fIc3\fP' with 0 <=
274
.I cN
275
<= 255, where 0 means black and 255 means white.
276
 
277
.RS
278
.PP
279
DVD subtitles allow up to 4 colors.  The comma-separated arguments to this
280
option specify the grey level for each these colors that are used for converting
281
the subtitle stream graphics into plain text via OCR.  The default is
282
.RB ` 255,255,0,255 '.
283
The values
284
.RB ` 255,0,255,255 ',
285
.RB ` 255,255,255,0 ',
286
and
287
.RB ` 0,255,255,255 '
288
can also produce viable OCR input.
289
 
290
.PP
291
Use solid (not outlined) shapes as input when possible to make things easier
292
for the
293
.BR gocr (1)
294
program.  It will ask you about a character if it does not recognize it; if
295
that has an outlined shape, you are advised to cancel the OCR process (with
296
Ctrl+C).  This program will then allow you to use another grey-levels value
297
without the need to extract the subtitle stream again.
298
 
299
.PP
300
See the README file of the
301
.B subtitleripper
302
package and of the
303
.B subtitle2pgm
304
program, which -c option requires this value, for details.  (See FILES below.)
305
.RE
306
 
307
.IP "\fB-h\fP, \fB--help\fP"
308
Display this help and exit.
309
 
310
.IP "\fB-V\fP, \fB--version\fP"
311
Display version information and exit.
312
 
313
 
314
.SH "EXIT STATUS"
315
 
316
.TP
317
.B "  0"
318
Successful program execution
319
 
320
.TP
321
.B "  1"
322
Error detecting/extracting subtitle stream, or cancelled without selecting a
323
title number or subtitle ID
324
 
325
.TP
326
.B "  2"
327
Unable to convert subtitle stream to image files
328
 
329
.TP
330
.B "  3"
331
Cancelled due to
332
.BR gocr (1)
333
error or without entering another grey-levels value
334
 
335
.TP
336
.B "  4"
337
Unable to compile to text file
338
 
339
.TP
340
.B "  5"
341
Unable to clean up
342
 
343
.TP
344
.B "127"
345
Insufficient number of arguments / help was displayed
346
 
347
 
348
.SH FILES
349
.TP
350
.I /usr/share/doc/subtitleripper/README.gz
351
Location of the
352
.B subtitleripper
353
package README on Debian systems
354
 
355
.TP
356
.I /usr/share/doc/subtitleripper/README.subtitle2pgm.gz
357
Location of the
358
.B subtitle2pgm
359
program README on Debian systems
360
 
361
 
362
.SH NOTES
363
Tested with GNU/Linux 2.4.31 and 2.6.1.13 to .15
364
.B [1]
365
(Debian
366
.B [2]
367
Sarge).
368
 
369
.PP
370
.B [1]
371
.RI < http://kernel.org/ >
372
.br
373
.B [2]
374
.RI < http://debian.org/ >
375
 
376
 
377
.SH BUGS
378
Please send comments and bug reports to
379
.RI < dvd@PointedEars.de >.
380
 
381
 
382
.SH "LEGAL NOTICE"
383
Copyright (c) 2005, 2006  Thomas Lahn <dvd@PointedEars.de>
384
.PP
385
This program is free software; you can redistribute it and/or modify it
386
under the terms of the GNU General Public License as published by the
387
Free Software Foundation; either version 2 of the License, or (at your
388
option) any later version.
389
.PP
390
This program is distributed in the hope that it will be useful, but
391
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
392
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
393
(GPL) for more details.
394
 
395
You should have received a copy of the GNU GPL along with this program
396
.RI ( COPYING " file);"
397
if not, go to
398
.B [1]
399
or write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
400
Boston, MA  02110-1301, USA.
401
.PP
402
.B [1]
403
.RI < http://www.gnu.org/licenses/licenses.html#GPL >
404
.PP
405
.br
406
--
407
.br
408
Standard shell script disclaimer blurb thing:
409
 
410
This script is a hack.  It's brute force.  It's horrible.
411
It doesn't use Artificial Intelligence.  It doesn't use Virtual Reality.
412
It's not perl.  It's not python.  It probably won't work unchanged on
413
the "other" thousands of unices.  But it worksforme.  --ramiro
414
.br
415
(from
416
.IR /usr/local/mozilla/run-mozilla.sh )
417
 
418
 
419
.SH CREDITS
420
Thanks to Boris 'bolau' Lau <mail@bolau.de> for translation support,
421
and to Erkan Yanar <erkan.yanar@t-online.de> for pointing out how to
422
use
423
.BR sed (1)
424
to replace a filename with the file content.
425
 
426
 
427
.SH AVAILABILITY
428
The author's latest version can be obtained from
429
.br
430
.RI < http://PointedEars.de/tools/multimedia/dvd/ >.
431
 
432
 
433
.SH "SEE ALSO"
434
 
435
.BR dvdbackup (1),
436
.BR gocr (1),
437
.BR mplayer (1),
438
.BR pgm2txt ,
439
.BR sed (1),
440
.BR srttool " and " subtitle2pgm
441
(from <\fIhttp://subtitleripper.sourceforge.net/\fP>),
442
.BR tccat (1),
443
.BR tcextract (1)