mp3blaster(1)mp3blaster(1)NAMEmp3blaster - An interactive text-console based mp3 player.
SYNOPSISmp3blaster [options]
mp3blaster [options] [file ...]
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 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 `groups' (directories). With one function, you can
load 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 all files into the playlist and shuffle them, just like regular
players.
The interface is described in the INTERFACE ELEMENTS section.
The configuration file is described in the MP3BLASTERRC section.
The different program modes are described in the PROGRAM MODES section.
The playlist playback modes are described in the PLAYMODES section.
Who coded this program? How to report bugs? It's in 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 CPU time)
--8bits,-8
Convert audio to 8bits (necessary on 8bit soundcards, but it can
also be used to use less CPU time)
--chroot=rootdir, -o=rootdir
Set <rootdir> as mp3blaster's root dir. This affects ALL file
operations in mp3blaster!! (including reading and writing of
playlists). Note that only users 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 you trust
all local users!!!!.
--config-file,-c=<file>
Use <file> as config-file instead of ~/.mp3blasterrc
--debug, -d
Log debug-info in $HOME/.mp3blaster (use this when sending
bugreports!)
--status-file, -f
Write info on the mp3's being played to the specified file.
--help,-h
Gets you this nice 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
version 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 random order.
--dont-quit,-q
Dont't quit after playing all command-line supplied mp3's (only
makes sense in combination with --autolist or files from com‐
mand-line)
--repeat/-R
Repeat the playlist indefinitely.
--runframes/-r=<number>
Number or frames to decode in one loop. Range: 1 to 10
(default=5). On slow machines, a lower number might improve
reaction time of the interface, but it's quite unlikely this
will have any effect from version 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 name followed by a
colon and a server number, like bla.foo.com:0). (NOTE: NAS sup‐
port doesn't work in version 3.0 or above yet)
--threads/-t=<amount>
Numbers of threads to use for buffering. Range is 0..500 in
increments of 50. 0 threads means no buffering (thus no hickup
prevention).
--version,-v
Displays mp3blaster's version number.
INTERFACE ELEMENTS
Since version 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 mp3blaster's config file (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 the mode
mp3blaster is in 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 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 window. Its
content is usually determined by the mode mp3blater is in (see
section PROGRAM MODES). If you're editing the playlist, the
playlist is shown. In file 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 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 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.
Many users will simply use the single (root) group that
mp3blaster starts with. In that case, shuffling all songs is
simply a question of toggling the GroupShuffle mode (default
keybinding: F7).
If you have multiple groups, and you want to shuffle all songs
from all groups, you will have to set the global playback mode
(see section PLAYMODES). Without shuffling, the songs will be
played in the order you added them from the file 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 the subgenres you can add
albums as groups. Starting and stopping a playlist can be done
with '5' (default keybinding for the Play button). If you stop
playback using the Stop button, all information about which song
has already been played is lost. If you want to stop playback to
continue later, pause the current song.
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 manager, files will be added in the
group that was selected in the main window. This even works for
playlists; if you load a playlist from the file manager (which
you always do), it will be added in the current group! Using
this feature, you can merge multiple playlists into one.
If you're listening to your current playlist, but you want to
hear another song in between, you can simply do so by highlight‐
ing this song (either in playlist mode or file manager mode) and
pressing enter. When the song is finished, the playlist contin‐
ues with the next song in the list.
File Manager
You can enter the file 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 by looking
at the keybindings in the keybindings window which is automati‐
cally updated. In the file manager, you can add files to the
group you had currently selected in the playlist editor. You can
also listen to a file by selecting it with the highlighted bar
and pressing enter over it. Adding files can be done in 2 ways:
Selecting a file by moving the bar over it and pressing the
spacebar, or by recursively selecting all files in the current
directory and all directories in it. If you select some files,
change to another directory (by pressing enter over one) and
then select 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 the order in 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 the current directory is to invert the selection (using
F2) when none are selected. If you want to select all files but
one, select the one you don't want and then invert the selec‐
tion.
The recursive selection can be done in two ways: By pressing F3,
you add all audiofiles that are found in the current directory
and all directories in it. By using F5 (add dirs as groups),
mp3's are added in groups that are named 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 manager mode!)
Help mode
You can get in this mode by pressing '?'. Leave it by pressing
'?' again. It will always return you to playlist mode.
Playing Mode
Mp3blaster versions prior to version 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 all program modes. Keybindings specific to playback are
always listed in the keybindins window.
PLAYMODES
The order in which files are played in the playlist is determined by 2
settings: The global playback mode (displayed in the info window), and
each group's independant shuffle setting. The 'current group' in the
global playback modes means: The group that is shown in the main window
at the time 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 the current group, as well as all songs
in all subgroups. First, all groups will be played in the order
you have added them (unless the current group's shuffle is
enabled, then the order is randomly determined). Then, the songs
in the group itself will be played. You can determine for each
individual group whether you want to shuffle the songs in 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 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 a completely random order.
MP3BLASTERRC
You can store many settings and keybindings in a config file. By
default, mp3blaster will look for ~/.mp3blasterrc, unless you specify
another file on the command-line (using -c/--config-file).
The structure of the config file is pretty straightforward. Look at
sample.mp3blasterrc in 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 that case it's:
Keyword = Value1, Value2
Escape comma's in 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 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:
AudioDriver (string)
Which audiodriver to use for playback. Currently, you can choose
between the following drivers: oss, esd, nas and sdl. If SDL is
available, it will be used by default. OSS is the next alterna‐
tive. ESD should only be used if everything else fails. Note
that, if you use SDL as audio driver, you can select from many
output devices by setting the environment variable SDL_AUDIO‐
DRIVER. This is an SDL feature, please refer to the FAQ on lib‐
sdl.org for more information.
AudiofileMatching (list of strings)
List of file patterns (in regexp 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)
Specify a character recoding table which maps ID3 songinfo to
your local charset. For more info about how to create one, see
the README in 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 the file manager will show mp3's
by their ID3-tag by default, instead of their filename.
(default: disabled) (TODO: Make this directive a string with
printf-like format for the id3tag fields).
File.SortMode (string)
Determines the default file sorting mode for the file 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 the
file manager.
MixerDevice (string)
Mixer device to use for mixing (default: /dev/mixer).
PlaylistDir (string)
Directory path where playlists are stored (default:
~/.mp3blaster_playlists)
PlaylistMatching (list of strings)
List of file patterns (in regexp 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, it will read each mp3 file before playing, to calculate
VBR total time. This might be impractical if mp3's are streamed
over a slow network connection, because the entire file will be
read. Scanning is unnecessary if 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 this option is set. (default:
disabled)
SelectItems.SearchRegex (boolean)
If set, 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, 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
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)
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
use.
Now a list of keywords that set colours. Not all keywords are well
tested to do the right thing at the time 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 file manager
Color.FileDir.fg (colour)
Foreground colour of directories in file manager
Color.FileLst.fg (colour)
Foreground colour of playlist files in file manager
Color.FileWin.fg (colour)
Foreground colour of other files in file 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 report them on the sourceforge project site.
AUTHORmp3blaster 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 leave comments, suggestions, complaints, bug fixes, coffee and
porting experiences on the sourceforge project page. If you want to
report a bug, please include the version number.
mp3blaster(1)
