.\" 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)
Jack \- rip and encode CDs with one command
.RI [ options ]
transforms your audio-CDs to FLAC, MP3 or Ogg Vorbis files. It uses several
helper programs in order to achieve functions such as ripping, encoding and,
tagging files with meta information. Ripping is either done via
(in which case the ripping status is displayed by Jack as well) or
Jack works with several encoders, namely
.B oggenc, flac, lame, gogo, bladeenc, l3enc, mp3enc
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
and rename the tracks accordingly. Tagging of audio files with meta
information about artist, track title, etc. is performed as well.
If no freedb-lookup has been performed, Jack drops all files in a
.BR ~/jack/jack-xxxxxxxx ,
representing the CD's CDDB/FreeDB disc ID.
This directory is renamed by Jack when the appropriate information is known.
Most options like ripper, encoder, preferred FreeDB-Server, directory
and sound file format, etc. can be user defined by changing the
or by saving them to
.BR ~/.jack3rc .
Additional rippers, encoders and FreeDB servers can be defined by users
through the help of a plug-in directory (as defined by the
option which defaults to
.BR ~/.jack_plugins ).
While Jack is running, these keyboard commands are available:
.BR q " or " Q
.BR p " or " P
disable ripping (for example, if you need the CD drive)
.BR p " or " P " (again) or " c " or " C
.BR e " or " E
pause/continue all encoders
.BR r " or " R
pause/continue all rippers.
toggle the copyright/help box
Different options need different data-types as arguments:
can be "yes" or "no", like in
can be anything, like in
an integer number, like in
.B \-\-bitrate 192
multiple strings, delimited by the final ";".
.B \-\-guess\-toc file1.mp3 file2.mp3 ... fileN.mp3
Jack understands the following options:
.B \-\-append-year string
append this string to the directory name (useful with %y to add the year
an album was released)
.B \-b, \-\-bitrate int
target bitrate (in kbit/s, default is 160).
.B \-\-char-filter string
convert file names using a python method
.B \-\-charset string
charset of filenames (defaults to your locale).
.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.
.B \-C, \-\-claim-dir
rename directories even if they were was not created by Jack.
continue without FreeDB data if query fails.
.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
, 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
.B \-\-device string
The device-name of your cdrom-drive. The default is
.B \-\-dir-template string
if directories are renamed, this is the format used (default "%a/%l")
.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.
open an editor to change the CDDB information which has been obtained
previously (only useful with \-Q).
.B \-\-encoder-name, \-E string
use which encoder (default "oggenc")
.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 (default 1).
.B \-x, \-\-exec
run predefined command when finished. The command is defined by "exec_rip_done"
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.
the track title is contained in the EXTT fields.
a track comment is contained in the EXTT fields.
do not ask. Like when deleting incomplete files.
.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
if jack can't find the image file.
.B \-F, \-\-from-image string
read audio data from image file. Like
.BR \-\-from-tocfile ,
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.
.B \-g, \-\-guess-toc list
make up a TOC from the list of sound file given. The format is
.B track_01.ogg ... track_nn.ogg ;
Note that the trailing "
" 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 your sound files
alone - no need for the CD. Very useful if you have no idea
which CD the songs are from. The songs 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
.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)
.B \-Y, \-\-id3-year int
set the year of the album (the term ID3 comes from MP3 but this option also
works with other audio formats, such as OGG Vorbis and FLAC)
.B \-h, \-\-help
Show summary of options.
.B \-k, \-\-keep-wavs
do not delete WAVs after encoding them.
.B \-m, \-\-mail-submit
submit FreeDB entry via e-mail. HTTP submission is preferred.
You will have to enter the category of the CD.
.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.
try to query FreeDB for all dirs in searchdirs which
have no FreeDB data.
.B \-\-my-mail string
your e-mail address, needed for FreeDB submissions.
.B \-n, \-\-nice int
nice-level with which the encoders are started. Default is 12
which shouldn't hurt your system much.
.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
something went wrong last time. This is off by default.
.B \-O, \-\-only-dae
only produce WAVs, implies
This is off by default.
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.
.\" .B \-\-playorder
.\" use the FreeDB PLAYORDER field to limit the tracks to
.\" rip (non-functional, sorry)
.B \-\-quality int
vbr encoding quality. \-1 is lowest, 10 highest (default 6). You can also specify a float.
.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.
like \-\-query-now, but only if FreeDB data hasn't been successfully
.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.
.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.
have Jack remove its temp jack*\-files.
Be careful - don't delete them too early!
.B \-R, \-\-rename
rename and tag files according to FreeDB file. On startup, Jack
creates a blank FreeDB entry file (except if
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 audio files accordingly, use this option.
Give all other needed options too, like
rename directory as well (default).
.B \-\-rename-fmt string
format of normal files (default "%n - %t")
.B \-\-rename-fmt-va string
format of Various Artists files (default "%n - %a - %t")
.B \-\-rename-num string
format of the track number (%n, printf() style) used to rename the files (default "%02d")
.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.
.B \-\-replacement-chars list
unusable chars are replaced by the corresponding list item (default "%").
.B \-\-ripper string
which program to use for extracting the audio data (default "cdparanoia").
save options to \fI~/.jack3rc\fP file and exit. The following options are
.BR \-\-todo ,
.BR \-\-check-toc ,
.BR \-\-undo-rename ,
.BR \-\-dont-work ,
.BR \-\-update-freedb ,
.BR \-\-tracks ,
.BR \-\-query-now ,
.BR \-\-query ,
.BR \-\-various ,
.BR \-\-various-swap ,
.BR \-\-extt-is-artist ,
.BR \-\-extt-is-title ,
.BR \-\-extt-is-comment ,
.BR \-\-submit ,
.BR \-\-mail-submit ,
.BR \-\-rename ,
.BR \-\-id3-genre ,
.BR \-\-id3-year ,
.BR \-\-from-tocfile ,
.BR \-\-from-image ,
.BR \-\-toc-file ,
.BR \-\-upd-progress ,
.BR \-\-multi-mode ,
.BR \-\-claim-dir ,
.B \-\-scan-dirs int
Scan this many
levels from the current working directory for a matching toc-file (0
to disable, default 2).
.B \-\-search list
add these directories to the list of directories searched when looking for the
workdir (default ".").
.B \-\-server string
which FreeDB server to use. Don't forget to set your HTTP proxy.
Currently either "freedb" (default) or "freedb-de".
be quiet (no screen output).
.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
submit FreeDB entry via HTTP. You will have to enter the category
of the CD.
.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
This is on by default as cdrdao currently generates .cdr files
that are "wrong".
print what would be done and exit.
.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.
.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 meta information tags are not restored.
.B \-\-unusable-chars list
characters which can't be used in filenames (default "/").
have Jack re-create its temp files. Use this if you deleted them
.B \-\-update-freedb, -U
update the FreeDB info and exit.
show the help screen while running.
.B \-v, \-\-vbr=bool
Generate variable bitrate files, only on encoders which support
this. Default is yes.
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
exchange artist and title, many FreeDB entries have them wrong.
wait for key press before quitting.
.B \-w, \-\-workdir string
where to create directories and put the files.
write a smart id3v1 tag to the encoded file.
write an id3v2 tag to the encoded file.
create a playlist in .m3u format. This has bugs, don't rely on it.
.SH CONFIG FILE OPTIONS
In addition the the command line options, there are some options that
can only be set directly in the config file.
all FreeDB queries will be done in this (local) directory; failed local
queries will be done via the network. Example: /var/spool/freedb
Insert a CD, fire up jack:
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.
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 -
When jack is interrupted, call it again using the same command line as
before to resume work, in this case
Now let's try a FreeDB query:
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
You can use the
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
should most certainly be replaced with something else. The VFAT filesystem
also does not support double quotes
In order to replace such characters, you can specify the options
jack \-Q \-\-rename-fmt "%n-%t" \-\-unusable-chars A I \; \-\-replacement-chars a i \;
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 occurrences of the letters
will be replaced with their lower-case versions. These options can also be
put in one's configuration file using the following format:
unusable_chars:[\(aq \(aq, \(aq/\(aq]
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:
All in one: query, rip, encode, cleanup:
jack \-Q \-\-remove-files
Editing / normalizing / stripping the WAV files before encoding:
jack \-O \-D \-\-remove-files ; gnoise *wav ; jack \-g *wav ; jack
Just replace gnoise by the operation you'd like to perform.
Additional rippers, encoders and FreeDB servers currently not known by jack
can be defined using jack's plug-in mechanism. Plug-ins have to be put in
directory (or the path defined by the
option). The plug-ins are simple Python scripts which define a hash with
the values for your ripper, encoder or FreeDB server. For rippers and
encoders, the hash
has to be defined while additional FreeDB servers are specified in
.BR plugin_freedb_servers .
Both expect another hash whose names corresponds to the entry you want to
add (prefixed by
.BR plugin_ )
and have to define certain values. Two examples are provided,
(to define a new FreeDB server) and
(to show how rippers and encoders can be defined). After defining
plug-ins, you have to manually select them by specifying the ripper,
encoder, or CDDB server. An example would be:
jack \-\-encoder-name plugin_lame \-\-ripper plugin_foo \-\-server plugin_cddb
Plug-ins can also be used to define your own rippers and encoders which
uses different options than those used by default by jack.
.SH ENVIRONMENT VARIABLES
There are several environment variables which can be used in jack's exec
lists jack's base directory in which files are stored.
lists the current directory of jack in which files of the current album are
lists all track names which have just been encoded.
lists all track names which have just been ripped.
.SH FORMAT STRINGS
Album release year
Site-wide configuration file.
User-specific configuration file. Use the
option to save your configuration to this file.
Arne Zellentin <firstname.lastname@example.org> is the author of Jack.
.SH SEE ALSO
.BR cdparanoia (1),
.BR cdda2wav (1),
.BR flac (1),
.BR oggenc (1)
.BR lame (1)