Subversion Repositories LCARS

\" dvdsubtitles.1 - the *roff document processor src for the dvdsubtitles manual

\" dvdsubtitles.1 - the *roff document processor src for the dvdsubtitles manual

\"

\"

\" This file is part of PointedEars' DVD Subtitles.

\" This file is part of PointedEars' DVD Subtitles.

\" Copyright (C) 2005, 2006  Thomas Lahn <dvd@PointedEars.de>

\" Copyright (C) 2005, 2006  Thomas Lahn <dvd@PointedEars.de>

\"

\"

\" Permission is granted to copy, distribute and/or modify this document

\" Permission is granted to copy, distribute and/or modify this document

\" under the terms of the GNU Free Documentation License, Version 1.2

\" under the terms of the GNU Free Documentation License, Version 1.2

\" or any later version published by the Free Software Foundation;

\" or any later version published by the Free Software Foundation;

\" with no Invariant Sections, no Front-Cover Texts, and no Back-Cover

\" 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

\" Texts.  A copy of the license is available on the Web[1] or

\" from the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,

\" from the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,

\" Boston, MA  02110-1301  USA.

\" Boston, MA  02110-1301  USA.

\" 

\" 

\" [1] <http://www.gnu.org/licenses/licenses.html#FDL>

\" [1] <http://www.gnu.org/licenses/licenses.html#FDL>

\"

\"

\" You may contact the author by:

\" You may contact the author by:

\" e-mail: dvd@PointedEars.de

\" e-mail: dvd@PointedEars.de

\" snail mail:

\" snail mail:

\"   Thomas Lahn

\"   Thomas Lahn

\"   Warschauer Strasse 1a/0403

\"   Warschauer Strasse 1a/0403

\"   D-99089 Erfurt

\"   D-99089 Erfurt

\"   Federal Republic of Germany

\"   Federal Republic of Germany

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

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

.SH NAME

.SH NAME

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

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

.SH SYNOPSIS

.SH SYNOPSIS

.B dvdsubtitles

.B dvdsubtitles

.br

.br

.RB [ -hVkl ]

.RB [ -hVkl ]

.RB [ -t

.RB [ -t

.IR TITLE ]

.IR TITLE ]

.RB [ -s

.RB [ -s

.IR SUBTITLE ]

.IR SUBTITLE ]

.RB [ -o

.RB [ -o

.IR TARGET ]

.IR TARGET ]

.RB [ -g

.RB [ -g

.IR GREY_LEVELS ]

.IR GREY_LEVELS ]

.RI [ SOURCE ]

.RI [ SOURCE ]

.PP

.PP

.B dvdsubtitles

.B dvdsubtitles

.B -c

.B -c

.RI ( FILE " | " DIRECTORY )

.RI ( FILE " | " DIRECTORY )

.RB [ -o

.RB [ -o

.IR TARGET ]

.IR TARGET ]

.PP

.PP

.B dvdsubtitles

.B dvdsubtitles

.RB [ -hVkl ]

.RB [ -hVkl ]

.RI [ SOURCE

.RI [ SOURCE

.RI [ TITLE

.RI [ TITLE

.RI [ SUBTITLE

.RI [ SUBTITLE

.RI [ TARGET

.RI [ TARGET

.RI [ GREY_LEVELS ]]]]]

.RI [ GREY_LEVELS ]]]]]

.br

.br

(deprecated)

(deprecated)

.SH DESCRIPTION

.SH DESCRIPTION

Uses

Uses

.BR tccat (1)

.BR tccat (1)

and

and

.BR tcextract (1)

.BR tcextract (1)

from the

from the

.B transcode

.B transcode

package to extract a subtitle stream from DVD-Video data.  This stream

package to extract a subtitle stream from DVD-Video data.  This stream

is converted into image files with

is converted into image files with

.BR subtitle2pgm ,

.BR subtitle2pgm ,

and those are converted to text files using

and those are converted to text files using

.BR pgm2txt ,

.BR pgm2txt ,

both from the

both from the

.B subtitleripper

.B subtitleripper

package, which in turn calls

package, which in turn calls

.BR gocr (1).

.BR gocr (1).

.PP

.PP

The previously created subtitle index file (.srtx) and the resulting text

The previously created subtitle index file (.srtx) and the resulting text

files are then compiled into one text file using either

files are then compiled into one text file using either

.BR srttool ,

.BR srttool ,

from the

from the

.B subtitleripper

.B subtitleripper

package, or

package, or

.BR sed (1).

.BR sed (1).

(See Output Format below.)

(See Output Format below.)

.PP

.PP

The

The

.B -c

.B -c

option allows for compiling existing text files into that format according to

option allows for compiling existing text files into that format according to

a subtitle index file without extracting a subtitle stream first (see below).

a subtitle index file without extracting a subtitle stream first (see below).

\" .PP

\" .PP

\" If the

\" If the

\" .B -S

\" .B -S

\" option is used, this program also performs a minor correction of common

\" option is used, this program also performs a minor correction of common

\" misrecognition errors via

\" misrecognition errors via

\" .BR sed (1),

\" .BR sed (1),

\" i.e. a standalone `l' (small letter L) or one followed by an apostrophe

\" i.e. a standalone `l' (small letter L) or one followed by an apostrophe

\" is converted to `I' (capital letter I).

\" is converted to `I' (capital letter I).

.PP

.PP

All temporary files are deleted afterwards (`clean-up'), unless a fatal error

All temporary files are deleted afterwards (`clean-up'), unless a fatal error

occurred or a user interrupt was detected; the extracted subtitle stream file

occurred or a user interrupt was detected; the extracted subtitle stream file

is kept for future use if the

is kept for future use if the

.B -k

.B -k

option is used.

option is used.

.PP

.PP

Based on

Based on

.B DVD ripping and transcoding with Linux

.B DVD ripping and transcoding with Linux

by Moritz Bunkus <moritz@bunkus.org>, available at

by Moritz Bunkus <moritz@bunkus.org>, available at

.br

.br

<\fIhttp://www.bunkus.org/dvdripping4linux/\fP>.

<\fIhttp://www.bunkus.org/dvdripping4linux/\fP>.

.SS Output Format

.SS Output Format

The format of the subtitle text file this program creates is similar to that the

The format of the subtitle text file this program creates is similar to that the

.B SubRip

.B SubRip

program creates:

program creates:

.PP

.PP

.I Subtitle number

.I Subtitle number

.br

.br

.IB "Start time " --> " End time"

.IB "Start time " --> " End time"

.br

.br

.I Text of subtitle (one or more lines)

.I Text of subtitle (one or more lines)

.br

.br

.I Blank line

.I Blank line

.PP

.PP

Like the SubRip format, field data starts at the beginning of each line.

Like the SubRip format, field data starts at the beginning of each line.

The time format used is `\fIhours\fB:\fIminutes\fB:\fIseconds\fR',

The time format used is `\fIhours\fB:\fIminutes\fB:\fIseconds\fR',

.I hours

.I hours

and

and

.I minutes

.I minutes

with two digits each. The

with two digits each. The

.I seconds

.I seconds

field is precise to three decimal points; the decimal separator used is

field is precise to three decimal points; the decimal separator used is

the comma.

the comma.

.PP

.PP

Different to the SubRip format, the line break used is the

Different to the SubRip format, the line break used is the

standard UNIX Line Feed (LF, 0x0A) character.  The

standard UNIX Line Feed (LF, 0x0A) character.  The

.I Subtitle number

.I Subtitle number

field was not included before version 0.6.1.

field was not included before version 0.6.1.

.SH OPTIONS

.SH OPTIONS

Options are supported since version 0.4.  This aims at achieving POSIX

Options are supported since version 0.4.  This aims at achieving POSIX

conformance and easy introduction of new features while maintaining

conformance and easy introduction of new features while maintaining

backwards compatibility to versions before 0.4.  However, non-option

backwards compatibility to versions before 0.4.  However, non-option

calls are deprecated and may not be supported in future versions.

calls are deprecated and may not be supported in future versions.

.PP

.PP

If additional program arguments are used, any option argument is

If additional program arguments are used, any option argument is

overwritten by the corresponding program argument.  Options may be

overwritten by the corresponding program argument.  Options may be

given in any order, and are also considered options if located after

given in any order, and are also considered options if located after

the first program argument.  Too many program arguments are silently

the first program argument.  Too many program arguments are silently

ignored.

ignored.

.IP "\fB-c\fP, \fB--compile\fP (\fIFILE\fP | \fIDIRECTORY\fP)"

.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

(since version 0.6.1, \fBTODO\fP)  Compile one group, or all groups of

subtitle text files in

subtitle text files in

.IR DIRECTORY ,

.IR DIRECTORY ,

according to a corresponding subtitle index

according to a corresponding subtitle index

.I FILE

.I FILE

(.srtx), into one text file each.  If this is successful, clean up (see

(.srtx), into one text file each.  If this is successful, clean up (see

.BR -k )

.BR -k )

and exit.  

and exit.  

Options irrelevant to this process are ignored.

Options irrelevant to this process are ignored.

.RS

.RS

If a

If a

.I DIRECTORY

.I DIRECTORY

is specified as argument, the

is specified as argument, the

.B -o

.B -o

option is ignored.  The resulting text files are named after the

option is ignored.  The resulting text files are named after the

corresponding subtitle index files found in the

corresponding subtitle index files found in the

.I DIRECTORY

.I DIRECTORY

instead, and their name is suffixed with `\fB.srt\fP'.

instead, and their name is suffixed with `\fB.srt\fP'.

.RE

.RE

.IP "\fB-k\fP, \fB--keep\fP"

.IP "\fB-k\fP, \fB--keep\fP"

(since version 0.6)  Keep subtitle stream file even if conversion is successful.

(since version 0.6)  Keep subtitle stream file even if conversion is successful.

.IP "\fB-l\fP, \fB--list\fP"

.IP "\fB-l\fP, \fB--list\fP"

(since version 0.5)  List subtitles for

(since version 0.5)  List subtitles for

.I TITLE

.I TITLE

using

using

.BR mplayer (1)

.BR mplayer (1)

and exit.  If

and exit.  If

.I TITLE

.I TITLE

is not provided or

is not provided or

.RB ` - ',

.RB ` - ',

list subtitles for title #2 (as title #1 may be an intro without subtitles) and

list subtitles for title #2 (as title #1 may be an intro without subtitles) and

exit.

exit.

.IP "\fISOURCE\fP"

.IP "\fISOURCE\fP"

Video DVD data source, i.e. a device

Video DVD data source, i.e. a device

.RI "(usually " /dev/dvd ),

.RI "(usually " /dev/dvd ),

a directory e.g. one containing content created via

a directory e.g. one containing content created via

.BR dvdbackup (1),

.BR dvdbackup (1),

or a Video DVD image file.

or a Video DVD image file.

.br

.br

If

If

.RB ` - ',

.RB ` - ',

a previously created subtitle stream file named

a previously created subtitle stream file named

\fBsubtitle_stream-\fP*\fB-\fP\fITITLE\fP-\fISUBTITLE\fP

\fBsubtitle_stream-\fP*\fB-\fP\fITITLE\fP-\fISUBTITLE\fP

in the current working directory will be used for only the

in the current working directory will be used for only the

stream-to-graphics-to-text conversion instead.  Both

stream-to-graphics-to-text conversion instead.  Both

.I TITLE

.I TITLE

and

and

.I SUBTITLE

.I SUBTITLE

must not be

must not be

.BR ` - '

.BR ` - '

in that case.

in that case.

.br

.br

The default is

The default is

.RI ` /dev/dvd '.

.RI ` /dev/dvd '.

.IP "\fB-t\fP, \fB--title\fP \fITITLE\fP"

.IP "\fB-t\fP, \fB--title\fP \fITITLE\fP"

Number of the title (1-n) which will be accessed for subtitle stream extraction.

Number of the title (1-n) which will be accessed for subtitle stream extraction.

If omitted or

If omitted or

.RB ` - ',

.RB ` - ',

the program uses

the program uses

.BR mplayer (1)

.BR mplayer (1)

to detect how many titles are available on the DVD data source and asks for the

to detect how many titles are available on the DVD data source and asks for the

title to be accessed.

title to be accessed.

.IP "\fB-s\fP, \fB--subtitle-id\fP \fISUBTITLE\fP"

.IP "\fB-s\fP, \fB--subtitle-id\fP \fISUBTITLE\fP"

ID of the subtitle stream to be extracted (0-n).  If omitted or

ID of the subtitle stream to be extracted (0-n).  If omitted or

.RB ` -  ',

.RB ` -  ',

the program uses its

the program uses its

.B -l

.B -l

option (or

option (or

.BR mplayer (1)

.BR mplayer (1)

directly, before version 0.5) to detect which subtitles are available for the

directly, before version 0.5) to detect which subtitles are available for the

given TITLE and asks for the ID to be used.

given TITLE and asks for the ID to be used.

.IP "\fB-o\fP, \fB--output-target\fP \fITARGET\fP"

.IP "\fB-o\fP, \fB--output-target\fP \fITARGET\fP"

Name of the resulting subtitles text file.  If not provided or

Name of the resulting subtitles text file.  If not provided or

.RB ` - ',

.RB ` - ',

the file is named after the subtitle stream file.

the file is named after the subtitle stream file.

.RS

.RS

Versions prior to 0.6 appended the filename suffix

Versions prior to 0.6 appended the filename suffix

.B .txt

.B .txt

automagically always, and version 0.6 appended this suffix only if this option

automagically always, and version 0.6 appended this suffix only if this option

was not provided; since version 0.6.1, the filename suffix

was not provided; since version 0.6.1, the filename suffix

.B .srt

.B .srt

(SubRip text) is appended in that case.

(SubRip text) is appended in that case.

.PP

.PP

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

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

.IP "Since version 0.6.1:"

.IP "Since version 0.6.1:"

The program asks whether the file should be overwritten, new content should

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),

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

or if a new file should be created.  If the latter, the name of new file

includes the ID of the

includes the ID of the

.B dvdsubtitles

.B dvdsubtitles

process which created it.

process which created it.

.IP "Version 0.6:"

.IP "Version 0.6:"

The program asks whether the file should be overwritten. If no, a new file

The program asks whether the file should be overwritten. If no, a new file

is created, its name including the ID of the

is created, its name including the ID of the

.B dvdsubtitles

.B dvdsubtitles

process which created it.

process which created it.

.IP "Versions prior to 0.6:"

.IP "Versions prior to 0.6:"

New content is appended to the file without marker.

New content is appended to the file without marker.

.RE

.RE

.IP "\fB-g\fP, \fB--grey-levels\fP \fIGREY_LEVELS\fP"

.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 <=

Optional grey-levels value `\fIc0\fP,\fIc1\fP,\fIc2\fP,\fIc3\fP' with 0 <=

.I cN

.I cN

<= 255, where 0 means black and 255 means white.

<= 255, where 0 means black and 255 means white.

.RS

.RS

.PP

.PP

DVD subtitles allow up to 4 colors.  The comma-separated arguments to this

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

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

the subtitle stream graphics into plain text via OCR.  The default is

.RB ` 255,255,0,255 '.

.RB ` 255,255,0,255 '.

The values

The values

.RB ` 255,0,255,255 ',

.RB ` 255,0,255,255 ',

.RB ` 255,255,255,0 ',

.RB ` 255,255,255,0 ',

and

and

.RB ` 0,255,255,255 '

.RB ` 0,255,255,255 '

can also produce viable OCR input.

can also produce viable OCR input.

.PP

.PP

Use solid (not outlined) shapes as input when possible to make things easier

Use solid (not outlined) shapes as input when possible to make things easier

for the

for the

.BR gocr (1)

.BR gocr (1)

program.  It will ask you about a character if it does not recognize it; if

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

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

Ctrl+C).  This program will then allow you to use another grey-levels value

without the need to extract the subtitle stream again.

without the need to extract the subtitle stream again.

.PP

.PP

See the README file of the

See the README file of the

.B subtitleripper

.B subtitleripper

package and of the

package and of the

.B subtitle2pgm

.B subtitle2pgm

program, which -c option requires this value, for details.  (See FILES below.)

program, which -c option requires this value, for details.  (See FILES below.)

.RE

.RE

.IP "\fB-h\fP, \fB--help\fP"

.IP "\fB-h\fP, \fB--help\fP"

Display this help and exit.

Display this help and exit.

.IP "\fB-V\fP, \fB--version\fP"

.IP "\fB-V\fP, \fB--version\fP"

Display version information and exit.

Display version information and exit.

.SH "EXIT STATUS"

.SH "EXIT STATUS"

.TP

.TP

.B "  0"

.B "  0"

Successful program execution

Successful program execution

.TP

.TP

.B "  1"

.B "  1"

Error detecting/extracting subtitle stream, or cancelled without selecting a

Error detecting/extracting subtitle stream, or cancelled without selecting a

title number or subtitle ID

title number or subtitle ID

.TP

.TP

.B "  2"

.B "  2"

Unable to convert subtitle stream to image files

Unable to convert subtitle stream to image files

.TP

.TP

.B "  3"

.B "  3"

Cancelled due to

Cancelled due to

.BR gocr (1)

.BR gocr (1)

error or without entering another grey-levels value

error or without entering another grey-levels value

.TP

.TP

.B "  4"

.B "  4"

Unable to compile to text file

Unable to compile to text file

.TP

.TP

.B "  5"

.B "  5"

Unable to clean up

Unable to clean up

.TP

.TP

.B "127"

.B "127"

Insufficient number of arguments / help was displayed

Insufficient number of arguments / help was displayed

.SH FILES

.SH FILES

.TP

.TP

.I /usr/share/doc/subtitleripper/README.gz

.I /usr/share/doc/subtitleripper/README.gz

Location of the

Location of the

.B subtitleripper

.B subtitleripper

package README on Debian systems

package README on Debian systems

.TP

.TP

.I /usr/share/doc/subtitleripper/README.subtitle2pgm.gz

.I /usr/share/doc/subtitleripper/README.subtitle2pgm.gz

Location of the

Location of the

.B subtitle2pgm

.B subtitle2pgm

program README on Debian systems

program README on Debian systems

.SH NOTES

.SH NOTES

Tested with GNU/Linux 2.4.31 and 2.6.1.13 to .15

Tested with GNU/Linux 2.4.31 and 2.6.1.13 to .15

.B [1]

.B [1]

(Debian

(Debian

.B [2]

.B [2]

Sarge).

Sarge).

.PP

.PP

.B [1]

.B [1]

.RI < http://kernel.org/ >

.RI < http://kernel.org/ >

.br

.br

.B [2]

.B [2]

.RI < http://debian.org/ >

.RI < http://debian.org/ >

.SH BUGS

.SH BUGS

Please send comments and bug reports to

Please send comments and bug reports to

.RI < dvd@PointedEars.de >.

.RI < dvd@PointedEars.de >.

.SH "LEGAL NOTICE"

.SH "LEGAL NOTICE"

Copyright (c) 2005, 2006  Thomas Lahn <dvd@PointedEars.de>

Copyright (c) 2005, 2006  Thomas Lahn <dvd@PointedEars.de>

.PP

.PP

This program is free software; you can redistribute it and/or modify it

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

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

Free Software Foundation; either version 2 of the License, or (at your

option) any later version.

option) any later version.

.PP

.PP

This program is distributed in the hope that it will be useful, but

This program is distributed in the hope that it will be useful, but

WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY

WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY

or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

(GPL) for more details.

(GPL) for more details.

You should have received a copy of the GNU GPL along with this program

You should have received a copy of the GNU GPL along with this program

.RI ( COPYING " file);"

.RI ( COPYING " file);"

if not, go to

if not, go to

.B [1]

.B [1]

or write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,

or write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,

Boston, MA  02110-1301, USA.

Boston, MA  02110-1301, USA.

.PP

.PP

.B [1]

.B [1]

.RI < http://www.gnu.org/licenses/licenses.html#GPL >

.RI < http://www.gnu.org/licenses/licenses.html#GPL >

.PP

.PP

.br

.br

--

--

.br

.br

Standard shell script disclaimer blurb thing:

Standard shell script disclaimer blurb thing:

This script is a hack.  It's brute force.  It's horrible.

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 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

It's not perl.  It's not python.  It probably won't work unchanged on

the "other" thousands of unices.  But it worksforme.  --ramiro

the "other" thousands of unices.  But it worksforme.  --ramiro

.br

.br

(from

(from

.IR /usr/local/mozilla/run-mozilla.sh )

.IR /usr/local/mozilla/run-mozilla.sh )

.SH CREDITS

.SH CREDITS

Thanks to Boris 'bolau' Lau <mail@bolau.de> for translation support,

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

and to Erkan Yanar <erkan.yanar@t-online.de> for pointing out how to

use

use

.BR sed (1)

.BR sed (1)

to replace a filename with the file content.

to replace a filename with the file content.

.SH AVAILABILITY

.SH AVAILABILITY

The author's latest version can be obtained from

The author's latest version can be obtained from

.br

.br

.RI < http://PointedEars.de/tools/multimedia/dvd/ >.

.RI < http://PointedEars.de/tools/multimedia/dvd/ >.

.SH "SEE ALSO" 

.SH "SEE ALSO" 

.BR dvdbackup (1),

.BR dvdbackup (1),

.BR gocr (1),

.BR gocr (1),

.BR mplayer (1),

.BR mplayer (1),

.BR pgm2txt ,

.BR pgm2txt ,

.BR sed (1),

.BR sed (1),

.BR srttool " and " subtitle2pgm

.BR srttool " and " subtitle2pgm

(from <\fIhttp://subtitleripper.sourceforge.net/\fP>),

(from <\fIhttp://subtitleripper.sourceforge.net/\fP>),

.BR tccat (1),

.BR tccat (1),

.BR tcextract (1)

.BR tcextract (1)