Subversion Repositories LCARS

\" dvdsubtitles.1 - the *roff document processor src for the dvdsubtitles manual
\"
\" This file is part of PointedEars' DVD Subtitles.
\" Copyright (C) 2005, 2006  Thomas Lahn <dvd@PointedEars.de>
\"
\" Permission is granted to copy, distribute and/or modify this document
\" under the terms of the GNU Free Documentation License, Version 1.2
\" or any later version published by the Free Software Foundation;
\" with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
\" Texts.  A copy of the license is available on the Web[1] or
\" from the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
\" Boston, MA  02110-1301  USA.
\" 
\" [1] <http://www.gnu.org/licenses/licenses.html#FDL>
\"
\" You may contact the author by:
\" e-mail: dvd@PointedEars.de
\" snail mail:
\"   Thomas Lahn
\"   Warschauer Strasse 1a/0403
\"   D-99089 Erfurt
\"   Federal Republic of Germany

.TH dvdsubtitles 1 "2006-02-15" "0.6.1.2006021519" "DVD Tools"


.SH NAME
dvdsubtitles \- Extract subtitle stream from Video DVD data to text file


.SH SYNOPSIS

.B dvdsubtitles
.br
.RB [ -hVkl ]
.RB [ -t
.IR TITLE ]
.RB [ -s
.IR SUBTITLE ]
.RB [ -o
.IR TARGET ]
.RB [ -g
.IR GREY_LEVELS ]
.RI [ SOURCE ]

.PP
.B dvdsubtitles
.B -c
.RI ( FILE " | " DIRECTORY )
.RB [ -o
.IR TARGET ]

.PP
.B dvdsubtitles
.RB [ -hVkl ]
.RI [ SOURCE
.RI [ TITLE
.RI [ SUBTITLE
.RI [ TARGET
.RI [ GREY_LEVELS ]]]]]


.SH DESCRIPTION

Uses
.BR tccat (1)
and
.BR tcextract (1)
from the
.B transcode
package to extract a subtitle stream from DVD data.  This stream is converted
into image files with
.BR subtitle2pgm ,
and those are converted to text files using
.BR pgm2txt ,
both from the
.B subtitleripper
package, which in turn calls
.BR gocr (1).
.PP
The previously created subtitle index file (.srtx) and the resulting text
files are then compiled into one text file using either
.BR srttool ,
from the
.B subtitleripper
package, or
.BR sed (1).
(See Output Format below.)
.PP
The
.B -c
option allows for compiling existing text files into that format according
a subtitle index file without extracting a subtitle stream first (see below).
\" .PP
\" If the
\" .B -S
\" option is used, this program also performs a minor correction of common
\" misrecognition errors via
\" .BR sed (1),
\" i.e. a standalone `l' (small letter L) or one followed by an apostrophe
\" is converted to `I' (capital letter I).
.PP
All temporary files are deleted afterwards (`clean-up'), unless a fatal error
occurred or a user interrupt was detected; the extracted subtitle stream file
is kept for future use if the
.B -k
option is used.
.PP
Based on
.B DVD ripping and transcoding with Linux
by Moritz Bunkus <moritz@bunkus.org>, available at
.br
<\fIhttp://www.bunkus.org/dvdripping4linux/\fP>.

.SS Output Format
The format of the subtitle text file this program creates is similar to that the
.B SubRip
program creates:
.PP
.I Subtitle number
.br
.IB "Start time " --> " End time"
.br
.I Text of subtitle (one or more lines)
.br
.I Blank line
.PP
Like the SubRip format, field data starts at the beginning of each line.
The time format used is `\fIhours\fB:\fIminutes\fB:\fIseconds\fR',
.I hours
and
.I minutes
with two digits each. The
.I seconds
field is precise to three decimal points; the decimal separator used is
the comma.
.PP
Different to the SubRip format, the line break used is the
standard UNIX Line Feed (LF, 0x0A) character.  The
.I Subtitle number
field was not included before version 0.6.1.


.SH OPTIONS

Options are supported since version 0.4.  This aims at achieving POSIX
conformance and easy introduction of new features while maintaining
backwards compatibility to versions before 0.4.
.PP
If additional program arguments are used, any option argument is
overwritten by the corresponding program argument.  Options may be
given in any order, and are also considered options if located after
the first program argument.  Too many program arguments are silently
ignored.

.IP "\fB-c\fP, \fB--compile\fP (\fIFILE\fP | \fIDIRECTORY\fP)"
(since version 0.6.1, \fBTODO\fP)  Compile one group, or all groups of
subtitle text files in
.IR DIRECTORY ,
according to a corresponding subtitle index
.I FILE
(.srtx), into one text file each.  If this is successful, clean up (see
.BR -k )
and exit.  
Options irrelevant to this process are ignored.

.RS
If a
.I DIRECTORY
is specified as argument, the
.B -o
option is ignored.  The resulting text files are named after the
corresponding subtitle index files found in the
.I DIRECTORY
instead, and their name is suffixed with `\fB.srt\fP'.
.RE

.IP "\fB-k\fP, \fB--keep\fP"
(since version 0.6)  Keep subtitle stream file even if conversion is successful.

.IP "\fB-l\fP, \fB--list\fP"
(since version 0.5)  List subtitles for
.I TITLE
using
.BR mplayer (1)
and exit.  If
.I TITLE
is not provided or
.RB ` - ',
list subtitles for title #2 (as title #1 may be an intro without subtitles) and
exit.

.IP "\fISOURCE\fP"
Video DVD data source, i.e. a device
.RI "(usually " /dev/dvd ),
a directory e.g. one containing content created via
.BR dvdbackup (1),
or a Video DVD image file.
.br
If
.RB ` - ',
a previously created subtitle stream file named
\fBsubtitle_stream-\fP*\fB-\fP\fITITLE\fP-\fISUBTITLE\fP
in the current working directory will be used for only the
stream-to-graphics-to-text conversion instead.  Both
.I TITLE
and
.I SUBTITLE
must not be
.BR ` - '
in that case.
.br
The default is
.RI ` /dev/dvd '.

.IP "\fB-t\fP, \fB--title\fP \fITITLE\fP"
Number of the title (1-n) which will be accessed for subtitle stream extraction.
If omitted or
.RB ` - ',
the program uses
.BR mplayer (1)
to detect how many titles are available on the DVD data source and asks for the
title to be accessed.

.IP "\fB-s\fP, \fB--subtitle-id\fP \fISUBTITLE\fP"
ID of the subtitle stream to be extracted (0-n).  If omitted or
.RB ` -  ',
the program uses its
.B -l
option (or
.BR mplayer (1)
directly, before version 0.5) to detect which subtitles are available for the
given TITLE and asks for the ID to be used.

.IP "\fB-o\fP, \fB--output-target\fP \fITARGET\fP"
Name of the resulting subtitles text file.  If not provided or
.RB ` - ',
the file is named after the subtitle stream file.

.RS
Versions prior to 0.6 appended the filename suffix
.B .txt
automagically always, and version 0.6 appended this suffix only if this option
was not provided; since version 0.6.1, the filename suffix
.B .srt
(SubRip text) is appended in that case.

.PP
If the file already existed, behavior depends on the program version.

.IP "Since version 0.6.1:"
The program asks whether the file should be overwritten, new content should
be appended to it (including a marker identifying the start of new content),
or if a new file should be created.  If the latter, the name of new file
includes the ID of the
.B dvdsubtitles
process which created it.

.IP "Version 0.6:"
The program asks whether the file should be overwritten. If no, a new file
is created, its name including the ID of the
.B dvdsubtitles
process which created it.

.IP "Versions prior to 0.6:"
New content is appended to the file without marker.
.RE

.IP "\fB-g\fP, \fB--grey-levels\fP \fIGREY_LEVELS\fP"
Optional grey-levels value `\fIc0\fP,\fIc1\fP,\fIc2\fP,\fIc3\fP' with 0 <=
.I cN
<= 255, where 0 means black and 255 means white.

.RS
.PP
DVD subtitles allow up to 4 colors.  The comma-separated arguments to this
option specify the grey level for each these colors that are used for converting
the subtitle stream graphics into plain text via OCR.  The default is
.RB ` 255,255,0,255 '.
The values
.RB ` 255,0,255,255 ',
.RB ` 255,255,255,0 ',
and
.RB ` 0,255,255,255 '
can also produce viable OCR input.

.PP
Use solid (not outlined) shapes as input when possible to make things easier
for the
.BR gocr (1)
program.  It will ask you about a character if it does not recognize it; if
that has an outlined shape, you are advised to cancel the OCR process (with
Ctrl+C).  This program will then allow you to use another grey-levels value
without the need to extract the subtitle stream again.

.PP
See the README file of the
.B subtitleripper
package and of the
.B subtitle2pgm
program, which -c option requires this value, for details.  (See FILES below.)
.RE

.IP "\fB-h\fP, \fB--help\fP"
Display this help and exit.

.IP "\fB-V\fP, \fB--version\fP"
Display version information and exit.
               

.SH "EXIT STATUS"

.TP
.B "  0"
Successful program execution

.TP
.B "  1"
Error detecting/extracting subtitle stream, or cancelled without selecting a
title number or subtitle ID

.TP
.B "  2"
Unable to convert subtitle stream to image files

.TP
.B "  3"
Cancelled due to
.BR gocr (1)
error or without entering another grey-levels value

.TP
.B "  4"
Unable to compile to text file

.TP
.B "  5"
Unable to clean up

.TP
.B "127"
Insufficient number of arguments / help was displayed
  

.SH FILES
.TP
.I /usr/share/doc/subtitleripper/README.gz
Location of the
.B subtitleripper
package README on Debian systems

.TP
.I /usr/share/doc/subtitleripper/README.subtitle2pgm.gz
Location of the
.B subtitle2pgm
program README on Debian systems


.SH NOTES
Tested with GNU/Linux 2.4.31 and 2.6.1.13 to .15
.B [1]
(Debian
.B [2]
Sarge).

.PP
.B [1]
.RI < http://kernel.org/ >
.br
.B [2]
.RI < http://debian.org/ >


.SH BUGS
Please send comments and bug reports to
.RI < dvd@PointedEars.de >.


.SH "LEGAL NOTICE"
Copyright (c) 2005, 2006  Thomas Lahn <dvd@PointedEars.de>
.PP
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
.PP
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
(GPL) for more details.

You should have received a copy of the GNU GPL along with this program
.RI ( COPYING " file);"
if not, go to
.B [1]
or write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
Boston, MA  02110-1301, USA.
.PP
.B [1]
.RI < http://www.gnu.org/licenses/licenses.html#GPL >
.PP
.br
--
.br
Standard shell script disclaimer blurb thing:

This script is a hack.  It's brute force.  It's horrible.
It doesn't use Artificial Intelligence.  It doesn't use Virtual Reality.
It's not perl.  It's not python.  It probably won't work unchanged on
the "other" thousands of unices.  But it worksforme.  --ramiro
.br
(from
.IR /usr/local/mozilla/run-mozilla.sh )


.SH CREDITS
Thanks to Boris 'bolau' Lau <mail@bolau.de> for translation support,
and to Erkan Yanar <erkan.yanar@t-online.de> for pointing out how to
use
.BR sed (1)
to replace a filename with the file content.


.SH AVAILABILITY
The author's latest version can be obtained from
.br
.RI < http://PointedEars.de/tools/multimedia/dvd/ >.


.SH "SEE ALSO" 

.BR dvdbackup (1),
.BR gocr (1),
.BR mplayer (1),
.BR pgm2txt ,
.BR sed (1),
.BR srttool " and " subtitle2pgm
(from <\fIhttp://subtitleripper.sourceforge.net/\fP>),
.BR tccat (1),
.BR tcextract (1)