Provided by: jack_3.1.1+cvs20050801-29_amd64 bug

NAME

       Jack - rip and encode CDs with one command

SYNOPSIS

       jack [options]

DESCRIPTION

       Jack  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 cdparanoia (in which case the ripping status
       is displayed by Jack as well) or cdda2wav.   Jack  works  with  several  encoders,  namely
       oggenc,  flac,  lame,  gogo,  bladeenc, l3enc, mp3enc and 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 freedb.org 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  directory  ~/jack/jack-
       xxxxxxxx,  with  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 defaults in /etc/jackrc or by saving them
       to ~/.jack3rc.  Additional rippers, encoders and FreeDB servers can be  defined  by  users
       through  the  help  of  a  plug-in  directory  (as defined by the plugin_path option which
       defaults to ~/.jack_plugins).

       While Jack is running, these keyboard commands are available:

              q or Q quit

              p or P disable ripping (for example, if you need the CD drive)

              p or P (again) or c or C
                     resume ripping

              e or E pause/continue all encoders

              r or R pause/continue all rippers.

              ?      toggle the copyright/help box

OPTIONS

       Different options need different data-types as arguments:

       bool   can be "yes" or "no", like in --vbr=yes

       string can be anything, like in --rename-fmt "%n.%t"

       int    an integer number, like in --bitrate 192 (or --bitrate=192 )

       list   multiple strings, delimited by  the  final  ";".   Example:  --guess-toc  file1.mp3
              file2.mp3 ... fileN.mp3 \;

       Jack understands the following options:

       --append-year string
              append  this  string to the directory name (useful with %y to add the year an album
              was released)

       -b, --bitrate int
              target bitrate (in kbit/s, default is 160).

       --char-filter string
              convert file names using a python method

       --charset string
              charset of filenames (defaults to your locale).

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

       -C, --claim-dir
              rename directories even if they were was not created by Jack.

       --cont-failed-query
              continue without FreeDB data if query fails.

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

       --device string
              The device-name of your cdrom-drive. The default is /dev/cdrom

       --dir-template string
              if directories are renamed, this is the format used (default "%a/%l")

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

       --edit-freedb
              open  an  editor  to change the CDDB information which has been obtained previously
              (only useful with -Q).

       --encoder-name, -E string
              use which encoder (default "oggenc")

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

       -x, --exec
              run predefined command when finished.

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

       --extt-is-title
              the track title is contained in the EXTT fields.

       --extt-is-comment
              a track comment is contained in the EXTT fields.

       --force
              do not ask. Like when deleting incomplete files.

       -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 -F if jack can't find the image file.

       -F, --from-image string
              read  audio  data  from  image  file.  Like --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.

       -g, --guess-toc list
              make  up  a  TOC  from the list of sound file given. The format is 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 these!

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

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

       -h, --help
              Show summary of options.

       -k, --keep-wavs
              do not delete WAVs after encoding them.

       -m, --mail-submit
              submit  FreeDB  entry  via  e-mail. HTTP submission is preferred.  You will have to
              enter the category of the CD.

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

       --multi-mode
              try to query FreeDB for all dirs in searchdirs which have no FreeDB data.

       --my-mail string
              your e-mail address, needed for FreeDB submissions.

       -n, --nice int
              nice-level  with which the encoders are started. Default is 12 which shouldn't hurt
              your system much.

       -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 know something went wrong last time.
              This is off by default.

       -O, --only-dae
              only produce WAVs, implies --keep-wavs.  This is off by default.

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

       --quality int
              vbr encoding quality. -1 is lowest, 10 highest (default 6). You can also specify  a
              float.

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

       --query-if-needed=bool
              like --query-now, but only if FreeDB data hasn't been successfully queried before.

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

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

       --remove-files
              have Jack remove its temp jack*-files.  Be careful - don't delete them too early!

       -R, --rename
              rename and tag files according to FreeDB file. On startup,  Jack  creates  a  blank
              FreeDB  entry  file  (except  if --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 audio files accordingly, use
              this option.  Give all other needed options too, like -t , -E , ...

       --rename-dir=bool
              rename directory as well (default).

       --rename-fmt string
              format of normal files (default "%n - %t")

       --rename-fmt-va string
              format of Various Artists files (default "%n - %a - %t")

       --rename-num string
              format of the track number (%n, printf() style) used to rename the  files  (default
              "%02d")

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

       --replacement-chars list
              unusable chars are replaced by the corresponding list item (default "%").

       --ripper string
              which program to use for extracting the audio data (default "cdparanoia").

       --save save options to ~/.jack3rc file and exit.

       --scan-dirs int
              Scan this many levels from the current working directory for a matching toc-file (0
              to disable, default 2).

       --search list
              add these directories to the list of directories  searched  when  looking  for  the
              workdir (default ".").

       --server string
              which  FreeDB server to use. Don't forget to set your HTTP proxy.  Currently either
              "freedb" (default) or "freedb-de".

       --silent-mode=bool
              be quiet (no screen output).

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

       --submit
              submit FreeDB entry via HTTP. You will have to enter the category of the CD.

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

       --todo print what would be done and exit.

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

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

       --unusable-chars list
              characters which can't be used in filenames (default "/").

       --upd-progress
              have Jack re-create its temp files. Use this if you deleted them too early.

       --update-freedb, -U
              update the FreeDB info and exit.

       --usage-win=bool
              show the help screen while running.

       -v, --vbr=bool
              Generate variable bitrate files, only on encoders which support  this.  Default  is
              yes.

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

       --various-swap
              exchange artist and title, many FreeDB entries have them wrong.

       --wait=bool
              wait for key press before quitting.

       -w, --workdir string
              where to create directories and put the files.

       --write-id3v1=bool
              write a smart id3v1 tag to the encoded file.

       --write-id3v2=bool
              write an id3v2 tag to the encoded file.

       --write-m3u
              create a playlist in .m3u format. This has bugs, don't rely on it.

CONFIG FILE OPTIONS

       In  addition  the  the  command  line options, there are some options that can only be set
       directly in the config file.

       freedb_dir
              all FreeDB queries will be done in this (local)  directory;  failed  local  queries
              will be done via the network.  Example: /var/spool/freedb

EXAMPLES

       Insert a CD, fire up jack:
              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 - Title".

       When jack is interrupted, call it again using the same command line as  before  to  resume
       work, in this case
              jack

       Now let's try a FreeDB query:
              jack -q
       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.

       You  can use the --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 (/) 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   unusable_chars   together   with
       replacement_chars.  For example,
              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 occurances of the letters A
       and  I  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:[' ', '/']
              replacement_chars:['_', '_']
       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:
              char_filter:.lower()

       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.

PLUG-INS

       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 the ~/.jack_plugins directory
       (or the path defined by the plugin_path 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 plugin_helpers has to be defined  while  additional  FreeDB
       servers  are  specified  in  plugin_freedb_servers.   Both expect another hash whose names
       corresponds to the entry you want to add (prefixed by plugin_) and have to define  certain
       values.   Two  examples  are provided, jack_plugin_cddb.py (to define a new FreeDB server)
       and jack_plugin_lame.py (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.

ENVIRONMENT VARIABLES

       There are several environment variables which can be used in jack's exec hooks:

       JACK_BASE_DIR
              lists jack's base directory in which files are stored.

       JACK_CUR_DIR
              lists the current directory of jack in which files of the current album are put.

       JACK_JUST_ENCODED
              lists all track names which have just been encoded.

       JACK_JUST_RIPPED
              lists all track names which have just been ripped.

FORMAT STRINGS

       %n     Track number

       %a     Artist

       %t     Track title

       %l     Album title

       %y     Album release year

       %g     Album genre

FILES

       /etc/jackrc
              Site-wide configuration file.

       ~/.jack3rc
              User-specific  configuration file. Use the --save option to save your configuration
              to this file.

AUTHOR

       Arne Zellentin <zarne@users.sf.net> is the author of Jack.

SEE ALSO

       cdparanoia(1), cdda2wav(1), flac(1), oggenc(1) and lame(1)

                                        November 22, 2004                                 JACK(1)