Seth Woolley's Man Viewer

mp3blaster(1) - mp3blaster - An interactive text-console based mp3 player - man 1 mp3blaster

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

mp3blaster(1)                                                    mp3blaster(1)



NAME
       mp3blaster - An interactive text-console based mp3 player.

SYNOPSIS
       mp3blaster [options]

       mp3blaster [options]  [file(1,n) ...]
              Play one or more audio files from the command-line

       mp3blaster [options] --list|-l playlist.lst
              Load a playlist at startup but don't start playing.

       mp3blaster [options] --autolist|-a playlist.lst
              Load a playlist at startup and start playing.

DESCRIPTION
       Mp3blaster  is  an  interactive  audio player for the text-console with
       unique playlist abilities no other programs offer. Its interface is  at
       least  equally  powerful  as  those  featured  in(1,8)  GUI players, without
       requiring bulky graphical environments.

       The most important feature of mp3blaster however is the playlist, which
       structure  is  comparable to that of a filesystem: Songs (files) can be
       grouped together in(1,8) `groups' (directories). With one function, you  can
       load(7,n)  all your albums as groups into mp3blaster's playlist, so that you
       can shuffle your albums instead of your songs. Of course, you can  also
       load(7,n)  all  files  into the playlist and shuffle them, just like regular
       players.

       The interface is described in(1,8) the INTERFACE ELEMENTS section.

       The configuration file(1,n) is described in(1,8) the MP3BLASTERRC section.

       The different program modes are described in(1,8) the PROGRAM MODES section.

       The playlist playback modes are described in(1,8) the PLAYMODES section.

       Who  coded  this  program?  How to report bugs? It's in(1,8) the AUTHORS and
       BUGS section at the end of this manual.


COMMAND-LINE PARAMETERS
       --downsample,-2
              Downsample audio to 22Khz (necessary on some ancient soundcards,
              but it can also be used to use less(1,3) CPU time(1,2,n))

       --8bits,-8
              Convert audio to 8bits (necessary on 8bit soundcards, but it can
              also be used to use less(1,3) CPU time(1,2,n))

       --chroot=rootdir, -o=rootdir
              Set <rootdir> as mp3blaster's root dir. This  affects  ALL  file(1,n)
              operations  in(1,8)  mp3blaster!!  (including  reading and writing of
              playlists).  Note that only users(1,5) with uid 0 (i.e. root) can use
              this  option  (yet). This feeature should be changed so it won't
              require root privileges. Only install it suid root if(3,n) you  trust
              all local users(1,5)!!!!.

       --config-file,-c=<file(1,n)>
              Use <file(1,n)> as config-file instead of ~/.mp3blasterrc

       --debug, -d
              Log  debug-info  in(1,8)  $HOME/.mp3blaster  (use  this  when sending
              bugreports!)

       --status-file, -f
              Write info(1,5,n) on the mp3's being played to the specified file.

       --help,-h
              Gets you this nice(1,2) list of command-line parameters.

       --mixer-device/-m=<devicename>
              Set the mixer device to use  (default  =  /dev/mixer).  For  NAS
              audio  mixing,  use  'NAS'.   (NOTE: NAS support doesn't work in(1,8)
              version(1,3,5) 3.0 or above yet)

       --no-mixer, -n
              Don't start the built-in mixer.

       --playmode/-p=(onegroup,allgroups,allrandom}
              Default playing mode is resp. Play first group  only,  Play  all
              groups, Play all songs in(1,8) random(3,4,6) order.

       --dont-quit,-q
              Dont't  quit after playing all command-line supplied mp3's (only
              makes sense in(1,8) combination with --autolist or  files  from  com-
              mand-line)

       --repeat/-R
              Repeat the playlist indefinitely.

       --runframes/-r=<number>
              Number  or  frames  to  decode  in(1,8)  one  loop.  Range:  1  to 10
              (default=5).  On slow machines, a  lower  number  might  improve
              reaction  time(1,2,n)  of  the  interface, but it's quite unlikely this
              will have any effect from version(1,3,5) 3.0 on)

       --sound-device/-s=<devicename>
              Select the audio device you  wish  to  use  for  sound  playback
              (default  /dev/dsp  or  /dev/audio  for OpenBSD). If you want to
              play over NAS (Network Audio  System),  give  the  audioserver's
              address  here  (usually $DISPLAY, e.g. a host(1,5) name followed by a
              colon and a server number, like bla.foo.com:0). (NOTE: NAS  sup-
              port doesn't work in(1,8) version(1,3,5) 3.0 or above yet)

       --threads/-t=<amount>
              Numbers  of  threads  to  use  for buffering. Range is 0..500 in(1,8)
              increments of 50.  0 threads means no buffering (thus no  hickup
              prevention).

       --version,-v
              Displays mp3blaster's version(1,3,5) number.


INTERFACE ELEMENTS
       Since  version(1,3,5)  3.0,  mp3blaster's interface has changed drastically to
       make it easier to use, without losing functionality. Press '?' to get a
       description  of  all  the commands within mp3blaster. You can scroll up
       and down this helpfile using the cursor keys  and  pageup/pagedown.  To
       leave the help, press '?' again.

       All  keybindings  mentioned  from  here on are the default keybindings.
       Most of them can be altered in(1,8) mp3blaster's config(1,5)  file(1,n)  (see  section
       MP3BLASTERRC)


       Keybindings window
              In  the  top  of the screen is the keybindings window. In it you
              will  find  all  keybindings  that  you  can  use  in(1,8)  the  mode
              mp3blaster  is  in(1,8)  at that time.  If you change modes, the key-
              bindings are dynamically updated. To scroll through this window,
              use '-' and '+'.


       Info window
              This  window is located directly beneath the keybindings window.
              It displays the global playmode (see section PLAYMODES), and the
              next  song  to be played (if(3,n) appropriate). Next to it is a small
              window which displays technical information  about  the  current
              song.


       Main window
              This  window is located directly underneath the info(1,5,n) window. Its
              content is usually determined by the mode mp3blater is  in(1,8)  (see
              section  PROGRAM  MODES).   If  you're editing the playlist, the
              playlist is shown. In file(1,n) manager mode, you will see the direc-
              tory  you're  currently in. In help mode, the help text is being
              displayed.


       CD-style window
              This is the window next to the main window. Here you  will  find
              the  cd-style controls, as well as checkboxes for shuffle/repeat
              mode. When a song is being played, you can see the elapsed/total
              time(1,2,n) here as well.


       Status window
              It's underneath the main window, and displays status information
              like song title, hints, etc. In the top-left, a CD-player  style
              symbol  is  shown  to  indicate  what mp3blaster is doing during
              playback.


       Mixer window
              The mixer is right next to the status window. Although very com-
              pact,  it's  a full sound mixer. Press 't' to toggle between all
              available mixer devices.  Press '<' and '>' to decrease/increase
              the volume of the currently selected mixer device.


PROGRAM MODES
       Playlist Editor
              By default, mp3blaster starts with the playlist editor. All key-
              bindings specific to playlist editing are listed in(1,8) the keybind-
              ings  window.  The playlist consists of one or more groups. Each
              group can have its own groupname and can contain supported audio
              files. You can toggle shuffle mode for each group independantly.
              To shuffle all songs in(1,8) all groups, you will  have  to  set(7,n,1 builtins)  the
              global playback mode (see section PLAYMODES). Without shuffling,
              the songs will be played in(1,8) the order you added  them  from  the
              file(1,n)  manager.  Groups  can  be  nested inside other groups. For
              example, you could make a group for each  music  genre  you  are
              interested  in. Within each genre, you can add subgenres, and in(1,8)
              the subgenres you can add albums as groups. Starting  and  stop-
              ping  a  playlist  can  be done with 'F9'. If you start and stop
              playing songs using F9, all information  about  which  song  has
              already  been  played  is  lost. If you want to stop playback to
              continue later, pause the current song or use the start and stop
              buttons.
              In the main window, the contents of the currently selected group
              is shown.  By default, this is the 'root'  group.  Other  groups
              are  denoted  by  square  brackets  and a purple colour. You can
              enter other groups simply  by  highlighting  them  and  pressing
              enter. If you enter the file(1,n) manager, files will be added in(1,8) the
              group that was selected in(1,8) the main window. This even works  for
              playlists;  if(3,n)  you load(7,n) a playlist from the file(1,n) manager (which
              you always do), it will be added in(1,8)  the  current  group!  Using
              this feature, you can merge(1,8) multiple playlists into one.
              If  you're  listening  to your current playlist, but you want to
              hear another song in(1,8) between, you can simply do so by highlight-
              ing this song (either in(1,8) playlist mode or file(1,n) manager mode) and
              pressing enter. When the song is finished, the playlist  contin-
              ues with the next song in(1,8) the list.


       File Manager
              You  can enter the file(1,n) manager by pressing F1 from the playlist
              editor. The  interface  is  almost  identical  to  that  of  the
              playlist  editor, but you can tell the mode you're in(1,8) by looking
              at the keybindings in(1,8) the keybindings window which is  automati-
              cally  updated.   In  the file(1,n) manager, you can add files to the
              group you had currently selected in(1,8) the playlist editor. You can
              also  listen(1,2,7)  to a file(1,n) by selecting it with the highlighted bar
              and pressing enter over it.  Adding files can be done in(1,8) 2 ways:
              Selecting  a  file(1,n)  by  moving  the bar over it and pressing the
              spacebar, or by recursively selecting all files in(1,8)  the  current
              directory  and  all directories in(1,8) it. If you select(2,7,2 select_tut) some files,
              change to another directory (by pressing  enter  over  one)  and
              then select(2,7,2 select_tut) some more files, the old selection will not be lost,
              even though you can't see it on your screen at the time. As soon
              as  you  return to the playlist editor by using F1, you will see
              they have been added to the group in(1,8)  the  order  in(1,8)  which  you
              selected  them.   However,  you can't deselect selected files as
              soon as you change into another directory: you'll have to remove
              them  from  the playlist editor.  A quick way of selecting *all*
              files in(1,8) the current directory is to invert the selection (using
              F2)  when none are selected. If you want to select(2,7,2 select_tut) all files but
              one, select(2,7,2 select_tut) the one you don't want and then  invert  the  selec-
              tion.
              The recursive selection can be done in(1,8) two ways: By pressing F3,
              you add all audiofiles that are found in(1,8) the  current  directory
              and  all  directories  in(1,8) it.  By using F5 (add dirs as groups),
              mp3's are added in(1,8) groups that are named(5,8) like the directory  the
              mp3's  were  in.  This  is  an  ultimately  fast way of making a
              playlist grouped by albums!
              Help for other keybindings can be  found  inside  mp3blaster  by
              pressing '?'  (note that this leaves file(1,n) manager mode!)

       Help mode
              You  can  get in(1,8) this mode by pressing '?'. Leave it by pressing
              '?' again.  It will always return you to playlist mode.

       Playing Mode
              Mp3blaster versions prior to version(1,3,5) 3.0 featured  another  dis-
              tinctly  different  mode:  the playing mode. The reason for this
              was that it wasn't possible to edit a playlist and play mp3's at
              the same time. Since this is now possible, playing songs is pos-
              sible in(1,8) all program modes. Keybindings specific to playback are
              always listed in(1,8) the keybindins window.


PLAYMODES
       The  order in(1,8) which files are played in(1,8) the playlist is determined by 2
       settings: The global playback mode (displayed in(1,8) the info(1,5,n) window),  and
       each  group's  independant  shuffle setting. The 'current group' in(1,8) the
       global playback modes means: The group that is shown in(1,8) the main window
       at  the  time(1,2,n)  the  playlist  was  started. This is important, since it
       enables you to play a subsection of your playlist  instead  of  playing
       the entire list.
       These are the global playback modes:

       Play current group, including subgroups
              Plays all songs shown in(1,8) the current group, as well as all songs
              in(1,8) all subgroups. First, all groups will be played in(1,8) the  order
              you  have  added  them  (unless  the  current group's shuffle is
              enabled, then the order is randomly determined). Then, the songs
              in(1,8)  the group itself will be played.  You can determine for each
              individual group whether you want to shuffle the songs  in(1,8)  them
              or not, by enabling the group's shuffle setting.

       Play current group, but not its subgroups
              This  is  essentially the same as the previous mode, except that
              subgroups in(1,8) this group will be skipped.

       Shuffle all songs from all groups
              This is comparable to the 'shuffle' mode that all  players  sup-
              port:  It  ignores the group structure totally, and simply shuf-
              fles all songs in(1,8) a completely random(3,4,6) order.


MP3BLASTERRC
       You can store many settings  and  keybindings  in(1,8)  a  config(1,5)  file.  By
       default,  mp3blaster  will look(1,8,3 Search::Dict) for ~/.mp3blasterrc, unless you specify
       another file(1,n) on the command-line (using -c/--config-file).

       The structure of the config(1,5) file(1,n) is  pretty  straightforward.  Look  at
       sample.mp3blasterrc  in(1,8)  your  share or share/doc directory for a quick
       example.  Lines starting with a '#' are ignored. You can  use  them  to
       put  comments on.  All other lines consist of a keyword/value pair like
       this:

       Keyword = Value

       Some keywords can have multiple values, in(1,8) that case it's:

       Keyword = Value1, Value2

       Escape comma's in(1,8) a value with a backslash (). If you want  a  litteral
       backslash, escape it with another backslash (\). Keywords are case-sen-
       sitive.

       There are a  few  types  of  values:  numbers,  booleans,  keybindings,
       colours,  and  everything  else  is a string. The syntax of these types
       are:

       numbers
              Numerical values, in(1,8) decimal notation.

       booleans
              yes/no, 1/0, or true/false (case-insensitive)

       keybindings
              Single-character keybindings represent themselves. If  you  want
              to  specify a scancode, the syntax is 's<hex-digit><hex-digit>'.
              All others are special canonical  names:  'spc'  (space),  'ent'
              (enter),  'kp0'..'kp9'  (keypad  0..9),  'ins'  (insert),  'hom'
              (home), 'del'  (delete),  'end'  (end),  'pup'  (pageup),  'pdn'
              (pagedown),  'f1'..'f12',  'up'/'dwn'/'lft'/'rig' (cursor keys),
              'bsp' (backspace).

       colours
              One of: black, red, green, yellow, blue, magenta, cyan, white

       These keywords are currently supported:

       AudiofileMatching (list of strings)
              List of file(1,n) patterns (in(1,8) regexp(3,n) format) that  determines  which
              files  will  be considered audiofiles (default: all files ending
              on .mp3, .wav,  and  files  starting  with  'http://'  for  http
              streaming). Check sample.mp3blasterrc for a good example.

       CharsetTable (string(3,n))
              Specify  a  character  recoding table which maps ID3 songinfo to
              your local charset. For more info(1,5,n) about how to create  one,  see
              the  README  in(1,8)  the installed mp3blaster documentation (usually
              /usr/local/share/mp3blaster) for more  information.  An  example
              which  recodes the Russian win1251 charset to the koi8-r charset
              is included.


       DownFrequency (boolean)
              If true, downsample audio output to 22Khz instead of 44Khz (nec-
              essary  on  some  ancient  soundcards, like genuine Soundblaster
              Pro's)

       File.ID3Names (boolean)
              If enabled, the display mode in(1,8) the file(1,n) manager will show mp3's
              by   their  ID3-tag  by  default,  instead  of  their  filename.
              (default: disabled) (TODO: Make this  directive  a  string(3,n)  with
              printf-like format for the id3tag fields).

       File.SortMode (string(3,n))
              Determines  the  default file(1,n) sorting mode for the file(1,n) manager.
              Valid modes are: alpha (default), alpha-case,  modify-new,  mod-
              ify-old, size-small, size-big, none.

       HideOtherFiles (boolean)
              If  enabled,  non-audio/playlist  files will not be shown in(1,8) the
              file(1,n) manager.

       MixerDevice (string(3,n))
              Mixer device to use for mixing (default: /dev/mixer).

       PlaylistDir (string(3,n))
              Directory   path   where   playlists   are   stored    (default:
              ~/.mp3blaster_playlists)

       PlaylistMatching (list of strings)
              List  of  file(1,n)  patterns (in(1,8) regexp(3,n) format) that determine which
              files are considered playlists (default:  all  files  ending  on
              .lst/.m3u). Syntax identical to that of AudiofileMatching.

       ScanMP3 (boolean)
              If  set(7,n,1 builtins), it will read(2,n,1 builtins) each mp3 file(1,n) before playing, to calculate
              VBR total time. This might be impractical if(3,n) mp3's are  streamed
              over  a slow network connection, because the entire file(1,n) will be
              read. Scanning is unnecessary if(3,n) the mp3 has  a  so-called  XING
              header  (which  most  VBR  mp3's have, nowadays).  Default: dis-
              abled.

       SelectItems.UnselectFirst (boolean)
              When selecting files from  the  filemanager  or  playlist  using
              'Select some items', unselect previously selected items prior to
              selecting matching new ones if(3,n) this  option  is  set.  (default:
              disabled)

       SelectItems.SearchRegex (boolean)
              If  set(7,n,1 builtins),  use extended regular expression to match files instead
              of using the global (fnmatch-style) matching. This  is  for  the
              'Select some items' feature.  (default: disabled)

       SelectItems.SearchCaseInsensitive (boolean)
              If  set(7,n,1 builtins),  search case-insensitive when using 'Select some items'
              feature. (default: enabled)

       SkipLength (number)
              How many seconds to skip when forwarding or  rewinding  a  song.
              Default is 10.  Change to your liking.

       PanSize (number)
              Number  of  characters  to  pan  content to the left or right in(1,8)
              scrollable window.  Default = 5. Range is 1..40.

       WrapAround (boolean)
              If disabled, the scrollable window will not wrap around when you
              use  attempt  to  go  past the upper or lower boundary using the
              arrow keys. (default: enabled)

       SoundDevice (string(3,n))
              Sound  device  to  use  for  audio  output   (default   /dev/dsp
              (/dev/audio on OpenBSD)).

       Threads (number, range 50..500)
              Amount  of threads to use for buffering. More threads means more
              buffering (thus better hickup prevention)

       WarnDelay (number, obsolete)
              Time before a warning popup will  disappear.  Currently  not  in(1,8)
              use.

       Now  a  list  of  keywords  that set(7,n,1 builtins) colours. Not all keywords are well
       tested to do the right thing at the time(1,2,n) of writing..

       Color.Default.fg (colour)
              Default foreground colour

       Color.Default.bg (colour)
              Default background colour

       Color.Popup.fg (colour)
              Popup window foreground colour

       Color.Popup.bg (colour)
              Popup window background colour

       Color.PopupInput.fg (colour)
              Popup window input box foreground color

       Color.PopupInput.bg (colour)
              Popup window input box background color

       Color.Error.fg (colour)
              Error message foreground colour

       Color.Error.bg (colour)
              Error message background colour

       Color.Button.fg (colour)
              Foreground colour of CD-player buttons

       Color.Button.bg (colour)
              Background colour of CD-player buttons

       Color.ShortCut.fg (colour)
              Foreground colour of keybindings

       Color.ShortCut.bg (colour)
              Background colour of keybindings

       Color.Label.fg (colour)
              Foreground colour of .. something :)

       Color.Label.bg (colour)
              Background colour of .. something :)

       Color.Number.fg (colour)
              Foreground color for numbers and similar status indicators.

       Color.Number.bg (colour)
              Background color for numbers and similar status indicators.

       Color.FileMp3.fg (colour)
              Foreground colour of mp3 files in(1,8) file(1,n) manager

       Color.FileDir.fg (colour)
              Foreground colour of directories in(1,8) file(1,n) manager

       Color.FileLst.fg (colour)
              Foreground colour of playlist files in(1,8) file(1,n) manager

       Color.FileWin.fg (colour)
              Foreground colour of other files in(1,8) file(1,n) manager

       This is the list of all keybindings. It should be  obvious  from  their
       names which function they're attached to.

       Key.SelectFiles (keybinding)

       Key.AddGroup (keybinding)

       Key.LoadPlaylist (keybinding)

       Key.WritePlaylist (keybinding)

       Key.SetGroupTitle (keybinding)

       Key.ToggleRepeat (keybinding)

       Key.ToggleShuffle (keybinding)

       Key.TogglePlaymode (keybinding)

       Key.ToggleDisplay (keybinding)

       Key.ToggleSort (keybinding)

       Key.StartPlaylist (keybinding)

       Key.ChangeThread (keybinding)

       Key.ToggleMixer (keybinding)

       Key.MixerVolDown (keybinding)

       Key.MixerVolUp (keybinding)

       Key.MoveAfter (keybinding)

       Key.MoveBefore (keybinding)

       Key.QuitProgram (keybinding)

       Key.Help (keybinding)

       Key.Del (keybinding)

       Key.Select (keybinding)

       Key.Enter (keybinding)

       Key.Refresh (keybinding)

       Key.PrevPage (keybinding)

       Key.NextPage (keybinding)

       Key.Up (keybinding)

       Key.Down (keybinding)

       Key.Left (keybinding)

       Key.Right (keybinding)

       Key.Home (keybinding)

       Key.End (keybinding)

       Key.StartSearch (keybinding)

       Key.File.Enter (keybinding)

       Key.File.Select (keybinding)

       Key.File.AddFiles (keybinding)

       Key.File.InvSelection (keybinding)

       Key.File.RecursiveSelect (keybinding)

       Key.File.SetPath (keybinding)

       Key.File.Delete (keybinding)

       Key.File.DirsAsGroups (keybinding)

       Key.File.Mp3ToWav (keybinding)

       Key.File.AddURL (keybinding)

       Key.File.UpDir (keybinding)

       Key.Play.Previous (keybinding)

       Key.Play.Play (keybinding)

       Key.Play.Next (keybinding)

       Key.Play.Rewind (keybinding)

       Key.Play.Stop (keybinding)

       Key.Play.Forward (keybinding)

       Key.Play.NextGroup (keybinding)

       Key.Play.PrevGroup (keybinding)

       Key.HelpPrev (keybinding)

       Key.HelpNext (keybinding)

       Key.File.MarkBad (keybinding)

       Key.ClearPlaylist (keybinding)

       Key.DeleteMark (keybinding)

BUGS
       If  you find bugs, please send(2,n) reports to mp3blaster-devel@stack.nl. An
       archive    of     this     maillinglist     can     be     found     on
       http://lists.stack.nl/pipermail/mp3blaster-devel/.  Please use '-d' and
       include debug info(1,5,n) from ~/.mp3blaster in(1,8) your mail.


AUTHOR
       mp3blaster has been written written  and  performed  by  Bram  Avontuur
       <bram@avontuur.org> <http://www.stack.nl/~brama/>

       The  mpegsound lib used is written by many people. The latest port from
       windows c++ source to unix was done by  Jung  woo-jae.  Several  alter-
       ations have been applied since.

       Please  send(2,n)  comments,  suggestions, complaints, bug fixes, coffee and
       porting experiences to mp3blaster-devel@stack.nl, and don't  forget  to
       include the version(1,3,5) number!



                                                                 mp3blaster(1)

References for this manual (incoming links)