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)