Import jack_3.1.1+cvs20050801.orig.tar.gz

[dgit import orig jack_3.1.1+cvs20050801.orig.tar.gz]

1 files changed, 543 insertions, 0 deletions

diff --git a/jack.man b/jack.man
new file mode 100644
index 0000000..1c12ae6
--- /dev/null
+++ b/jack.man
@@ -0,0 +1,543 @@
+.\"                                      Hey, EMACS: -*- nroff -*-
+.\" First parameter, NAME, should be all caps
+.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
+.\" other parameters are allowed: see man(7), man(1)
+.TH JACK 1 "November 22, 2004"
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.\" Some roff macros, for reference:
+.\" .nh        disable hyphenation
+.\" .hy        enable hyphenation
+.\" .ad l      left justify
+.\" .ad b      justify to both left and right margins
+.\" .nf        disable filling
+.\" .fi        enable filling
+.\" .br        insert line break
+.\" .sp <n>    insert n+1 empty lines
+.\" for manpage-specific macros, see man(7)
+.SH NAME
+Jack \- rip and encode CDs with one command
+.SH SYNOPSIS
+.B jack
+.RI [ options ]
+.SH DESCRIPTION
+.B Jack 
+transforms your audio-CDs to FLAC, MP3 or Ogg Vorbis files. It uses several
+helper programs in order to achieve things like ripping, encoding and
+ID3-tagging.  Ripping is either done via
+.B cdparanoia
+(in which case the ripping status is displayed by Jack as well) or
+.B cdda2wav.
+Jack works with several encoders, namely 
+.B oggenc, flac, lame, gogo, bladeenc, l3enc, mp3enc
+and
+.B xing.
+Any time during operation (and even when everything is finished and
+the original CD lost) you can let Jack look up the track names at 
+.B freedb.org
+and rename the tracks accordingly. ID3-tagging of MP3s (or insertion
+of equivalent comment fields in Ogg Vorbis files) is performed
+as well. 
+.PP
+If no freedb-lookup has been performed, Jack drops all files in a
+directory
+.BR ~/jack/jack-xxxxxxxx ,
+with
+.B xxxxxxxx
+representing the CD's CDDB/FreeDB disc ID. 
+This directory is renamed by Jack when the appropriate information is known.
+.PP
+Most options like ripper, encoder, preferred FreeDB-Server, directory
+and MP3-filename format, etc. can be user defined by changing the
+defaults in 
+.B /etc/jackrc
+or by saving them to
+.BR ~/.jack3rc .
+.PP
+While Jack is running, these keyboard commands are available:
+.RS
+.TP
+.BR q " or " Q
+quit
+.TP
+.BR p " or " P
+disable ripping (for example, if you need the CD drive)
+.TP
+.BR p " or " P " (again) or " c " or " C
+resume ripping
+.TP
+.BR e " or " E
+pause/continue all encoders 
+.TP
+.BR r " or " R
+pause/continue all rippers.
+.TP
+.BR ?
+toggle the copyright/help box
+.RE
+.SH OPTIONS
+Different options need different data-types as arguments:
+.TP
+.B bool
+can be "yes" or "no", like in
+.B \-\-vbr=yes
+.TP
+.B string
+can be anything, like in
+.B \-\-rename\-fmt
+"%n.%t"
+.TP
+.B int
+an integer number, like in
+.B \-\-bitrate 192
+(or
+.B \-\-bitrate=192
+)
+.TP
+.B list
+multiple strings, delimited by the final ";".
+Example:
+.B \-\-guess\-toc file1.mp3 file2.mp3 ... fileN.mp3
+\\;
+.PP
+Jack understands the following options:
+.TP
+.B \-\-append-year=bool
+if known, append the year to dir in the format " (%y)"
+.TP
+.B \-b, \-\-bitrate int
+target bitrate (in kbit/s, default is 160).
+.TP
+.B \-\-char-filter string
+convert file names using a python method
+.TP
+.B \-\-charset string
+charset of filenames (defaults to your locale).
+.TP
+.B \-c, \-\-check-toc 
+compare toc-file and cd-toc, then exit. Jack caches the TOC of a
+CD in a file ("jack.toc"). If you want to know if the inserted CD
+matches the toc-file in the current directory, use this option.
+.TP
+.B \-C, \-\-claim-dir
+rename directories even if they were was not created by Jack.
+.TP
+.B  \-\-cont-failed-query  
+continue without FreeDB data if query fails.
+.TP
+.B \-D, \-\-create-dirs 
+tells Jack to create sub-directories in which Jack puts all the
+files for the current CD. If no FreeDB data is available, i.e.
+when not using 
+.B -Q
+, these directories will be named "jack-xxxxxxxx"
+where "xxxxxxxx" stands for the CD's FreeDB ID. Otherwise
+dir_template (see above) will be used. This option is turned on
+by default.
+.TP
+.B \-\-device string
+The device-name of your cdrom-drive. The default is 
+.B /dev/cdrom
+.TP
+.B \-\-dir-template string
+if directories are renamed, this is the format used (default "%a/%l")
+.TP
+.B \-d, \-\-dont-work
+don't do DAE, encoding, tagging or renaming. This may be useful if you only
+want to do a FreeDB query, e.g. while another jack is running.
+.TP
+.B \-\-edit-freedb
+open an editor to change the CDDB information which has been obtained
+previously (only useful with -Q).
+.TP
+.B \-\-encoder-name, -E string
+use which encoder (default "oggenc")
+.TP
+.B \-e, \-\-encoders int
+encode how many files in parallel. If you have a SMP machine or
+simply want to stress your system, you can have Jack encode
+several files at once.
+.TP
+.B \-x, \-\-exec
+run predefined command when finished.
+.TP
+.B \-\-extt-is-artist
+the artist is contained in the EXTT fields. The EXTT fields are lines in the
+FreeDB file which contain additional data for each track. As it's the
+submitting user's choice what to use them for, Jack can't determine by itself
+what they were intended for. You have to provide this information.
+.TP
+.B \-\-extt-is-title
+the track title is contained in the EXTT fields.
+.TP
+.B \-\-extt-is-comment
+a track comment is contained in the EXTT fields.
+.TP
+.B \-\-force
+do not ask. Like when deleting incomplete files.
+.TP
+.B \-f, \-\-from-tocfile string
+rip from a cdrdao created CD image on hd. The specified toc-file 
+contains the name of the image file. Use
+.B \-F
+if jack can't find the image file.
+.TP
+.B \-F, \-\-from-image string
+read audio data from image file. Like
+.BR \-\-from-tocfile ,
+but the
+image itself is specified instead of the tocfile. If you
+do not have a toc-file (or don't specify a toc-file),
+the TOC is read from the CD itself.
+.TP
+.B \-g, \-\-guess-toc list
+make up a TOC from the MP3 file given in mp3_files. Format is 
+.B track_01.mp3 ... track_nn.mp3 ;
+Note that the trailing "
+.B ;
+" is only necessary if you want to
+append more options to your command line.
+You can use it to do a FreeDB query based on
+MP3s alone - no need for the CD. Very useful if you have no idea
+which CD the MP3s are from. The MP3s must be given in the same
+order as they were on their CD. The generated TOC file is
+similar, but not identical to the TOC of the CD - do not submit
+these!
+.TP
+.B \-G, \-\-id3-genre string
+set ID3 genre. Use 'help' to get a list of all known genres. (You can also specify the ID3v1 genre as an int)
+.TP
+.B \-Y, \-\-id3-year int
+set ID3 year.
+.TP
+.B \-h, \-\-help
+Show summary of options.
+.TP
+.B \-k, \-\-keep-wavs
+do not delete WAVs after encoding them.
+.TP
+.B \-m, \-\-mail-submit
+submit FreeDB entry via e-mail. HTTP submission is preferred. 
+You will have to enter the category of the CD.
+.TP
+.B \-l, \-\-max-load float
+only start new encoders if your system's load is below the specified value.
+/proc/loadavg must be readable by you for this to work.
+.TP
+.B \-\-multi-mode         
+try to query FreeDB for all dirs in searchdirs which
+have no FreeDB data.
+.TP
+.B \-\-my-mail string
+your e-mail address, needed for FreeDB submissions.
+.TP
+.B \-n, \-\-nice int
+nice-level with which the encoders are started. Default is 12
+which shouldn't hurt your system much.
+.TP
+.B \-o, \-\-overwrite
+overwrite existing files, i.e. do not check if already
+ripped WAVs or an already encoded file seem to be OK. Use this if
+you
+.B know
+something went wrong last time. This is off by default.
+.TP
+.B \-O, \-\-only-dae
+only produce WAVs, implies 
+.B \-\-keep-wavs.
+This is off by default.
+.TP
+.B \-\-otf=bool
+On-the-fly operation. Only on some encoders/rippers. Do not
+create WAVs, pipe ripper output through the encoder. Default is
+no as it's a torture for the CDROM drive.
+.TP
+.B \-o, \-\-overwrite=bool
+overwrite existing files.
+.\" .TP
+.\" .B \-\-playorder
+.\" use the FreeDB PLAYORDER field to limit the tracks to
+.\" rip (non-functional, sorry)
+.TP
+.B \-\-quality int
+vbr encoding quality. -1 is lowest, 10 highest (default 6). You can also specify a float.
+.TP
+.B \-q, \-\-query
+do FreeDB query when all is done. This is useful if Jack was previously
+run without a FreeDB query. If all tracks are done you don't even
+have to have a CD inserted as the TOC is cached by Jack. After
+having finished ripping and encoding, Jack will rename the files
+and tag them.
+.TP
+.B \-\-query\-if\-needed=bool
+like \-\-query-now, but only if FreeDB data hasn't been successfully
+queried before.
+.TP
+.B \-Q, \-\-query-now
+do FreeDB query when starting. Use this if you are connected to
+the Internet when starting Jack. Know that the query may need
+user-interaction. After having finished ripping and encoding, Jack
+will rename the files and tag them.
+.TP
+.B \-a, \-\-read-ahead int
+read how many WAVs in advance. At most read_ahead + num_encoders
+WAVs are ripped before a track has completely been encoded.
+Default is 99 which will read the whole CD, provided there is
+enough disk space.
+.TP
+.B \-\-remove-files
+have Jack remove its temp jack*-files.
+Be careful - don't delete them too early!
+.TP
+.B \-R, \-\-rename
+rename and tag files according to FreeDB file. On startup, Jack
+creates a blank FreeDB entry file (except if 
+.B \-\-query-now
+is used, 
+then the file is queried from your FreeDB server). If you have
+changed its contents (e.g. because the CD was unknown to FreeDB)
+and want to rename and tag your MP3s accordingly, use this option.
+Give all other needed options too, like
+.B \-t
+, 
+.B \-E
+, ...
+.TP
+.B \-\-rename-dir=bool
+rename directory as well (default).
+.TP
+.B \-\-rename-fmt string
+format of normal files (default "%n - %t")
+.TP
+.B \-\-rename-fmt-va string
+format of Various Artists files (default "%n - %a - %t")
+.TP
+.B \-\-rename-num string
+format of the track number (%n, printf() style) used to rename the files (default "%02d")
+.TP
+.B \-r, \-\-reorder=bool
+optimize track-order for disk space. This can save you some peak
+disk space during the encoding process; this may make it possible
+to do a CD which would otherwise fail to be encoded.
+.TP
+.B \-\-replacement-chars list
+unusable chars are replaced by the corresponding list item (default "%").
+.TP
+.B \-\-ripper string
+which program to use for extracting the audio data (default "cdparanoia").
+.TP
+.B \-\-save
+save options to \fI~/.jack3rc\fP file and exit.
+.TP
+.B \-\-scan-dirs int
+Scan this many
+levels from the current working directory for a matching toc-file (0
+to disable, default 2).
+.TP
+.B \-\-search list
+add these directories to the list of directories searched when looking for the
+workdir (default ".").
+.TP
+.B \-\-server string
+which FreeDB server to use. Don't forget to set your HTTP proxy.
+Currently either "freedb" (default) or "freedb-de".
+.TP
+.B \-\-silent-mode=bool
+be quiet (no screen output).
+.TP
+.B \-s, \-\-space int
+forcibly set usable disk space, in bytes. This option lets you
+limit the disk space Jack uses, maybe you need it for something
+else? Be careful: if set too high or too low, ripping and encoding will
+probably fail. The default is to look how much is free and to use
+this value.
+.TP
+.B \-\-submit
+submit FreeDB entry via HTTP. You will have to enter the category
+of the CD.
+.TP
+.B \-S, \-\-swab=bool
+swap byte order from image file. As cdrdao momentarily only
+outputs "raw" .cdr files, you quite likely want to swap the
+byte order. Try this option if your WAVs and encoded files contain 
+only noise.
+This is on by default as cdrdao currently generates .cdr files
+that are "wrong".
+.TP
+.B \-\-todo
+print what would be done and exit.
+.TP
+.B \-t, \-\-tracks string
+limit ripping and encoding to the specified tracks, use comma to
+separate tracks. Ranges are also possible; 5-9 is equivalent to
+5,6,7,8,9; 12- is like specifying track 12,...,last_track. The
+default is to process the whole CD.
+.TP
+.B \-u, \-\-undo-rename
+undo file renaming and exit. If you don't like how Jack renamed
+your files, use this option to restore the previous state.
+Several levels of undo are possible. Note
+that ID3 tags are not restored.
+.TP
+.B \-\-unusable-chars list
+characters which can't be used in filenames (default "/").
+.TP
+.B \-\-upd-progress
+have Jack re-create its temp files. Use this if you deleted them
+too early.
+.TP
+.B \-\-update-freedb, -U
+update the FreeDB info and exit.
+.TP
+.B \-\-usage\-win=bool
+show the help screen while running.
+.TP
+.B \-v, \-\-vbr=bool
+Generate variable bitrate files, only on encoders which support
+this. Default is no.
+.TP
+.B \-\-various=bool
+when parsing FreeDB data, Jack assumes that if the disc\'s artist
+is set to "Various" the track titles have the format
+"[artist] - [title]". If the disc title is set to something else
+and you still want the above behaviour, use 
+.B \-\-various.
+.TP
+.B \-\-various-swap
+exchange artist and title, many FreeDB entries have them wrong.
+.TP
+.B \-\-wait=bool
+wait for key press before quitting.
+.TP
+.B \-w, \-\-workdir string
+where to create directories and put the files.
+.TP
+.B \-\-write\-id3v1=bool
+write a smart id3v1 tag to the encoded file.
+.TP
+.B \-\-write\-id3v2=bool
+write an id3v2 tag to the encoded file.
+.TP
+.B \-\-write-m3u
+create a playlist in .m3u format. This has bugs, don't rely on it.
+.SH EXAMPLES
+Insert a CD, fire up jack:
+.RS
+jack
+.RE
+.PP
+Now watch it work. It's fun for a while. After having finished, you have
+the following files on your HD: track_01.mp3, track_02.mp3, ...,
+track_nn.mp3 plus jack.toc, jack.freedb, jack.progress. The last three are
+used to store the state jack is in so it can resume work when interrupted.
+.PP
+Jack will create a directory called jack-xxxxxxxx for you, there it
+stores all the file for the CD whose id is xxxxxxxx. After a FreeDB query
+this directory is renamed to something human readable, like "Artist -
+Title".
+.PP
+When jack is interrupted, call it again using the same command line as
+before to resume work, in this case
+.RS
+jack
+.RE
+.PP
+Now let's try a FreeDB query:
+.RS
+jack -q
+.RE
+If the query is successful the files will be renamed to something more readable
+and will be tagged accordingly using ID3 or Vorbis tags.  The file jack.freedb
+will contain the queried FreeDB entry, and the original file will be backed up
+as jack.freedb.bak.
+.PP
+You can use the
+.B \-\-rename\-fmt
+option in order to specify the format of the name which will be given to
+your audio tracks.  A list of valid options can be found below.  You may
+also want to specify a set of characters which are not usable and should
+be replaced.  For example, on Unix systems the slash
+.B (/)
+should most certainly be replaced with something else.  The VFAT filesystem
+also does not support double quotes
+.B (").
+In order to replace such characters, you can specify the options
+.B unusable_chars
+together with
+.B replacement_chars.
+For example,
+.RS
+jack -Q --rename-fmt "%n-%t" --unusable-chars A I \; --replacement-chars a i \;
+.RE
+will query the FreeDB server, rip and encode all tracks of the CD and save
+the files in a format which will contain the track number and the title.
+All occurances of the letters
+.B A
+and
+.B I
+will be replaced with their lower-case versions.  These options can also be
+put in one's configuration file using the following format:
+.RS
+unusable_chars:[\(aq \(aq, \(aq/\(aq]
+.RE
+.RS
+replacement_chars:[\(aq_\(aq, \(aq_\(aq]
+.RE
+This will replace whitespace and slashes with underscores.  If you want to
+convert all characters to lower-case, you don't have to manually specify
+all of them but can use the following option instead:
+.RS
+char_filter:.lower()
+.RE
+.PP
+All in one: query, rip, encode, cleanup:
+.RS
+jack -Q --remove-files
+.RE
+.PP
+Editing / normalizing / stripping the WAV files before encoding:
+.RS
+jack -O --remove-files ; gnoise *wav ; jack -g *wav ; jack
+.RE
+Just replace gnoise by the operation you'd like to perform.
+.SH ENVIRONMENT VARIABLES
+There are several environment variables which can be used in jack's exec
+hooks:
+.IP JACK_BASE_DIR
+lists jack's base directory in which files are stored.
+.IP JACK_CUR_DIR
+lists the current directory of jack in which files of the current album are
+put.
+.IP JACK_JUST_ENCODED
+lists all track names which have just been encoded.
+.IP JACK_JUST_RIPPED
+lists all track names which have just been ripped.
+.SH FORMAT STRINGS
+.IP %n
+Track number
+.IP %a
+Artist
+.IP %t
+Track title
+.IP %l
+Album title
+.IP %y
+Album release year
+.IP %g
+Album genre
+.SH FILES
+.IP \fI/etc/jackrc\fP 
+Site-wide configuration file.
+.IP \fI~/.jack3rc\fP 
+User-specific configuration file. Use the
+.B \-\-save
+option to save your configuration to this file.
+.SH AUTHOR
+Arne Zellentin <zarne@users.sf.net> is the author of Jack.
+.SH SEE ALSO
+.BR cdparanoia (1),
+.BR cdda2wav (1),
+.BR flac (1),
+.BR oggenc (1)
+and
+.BR lame (1)