by Dan Williams and Erik Osheim
Mpycurse is actually part of a suite of tools which can be called 'mpy3'. These tools provide the following:
The mpycurse application specifically provides the following features:
Mpycurse can run in a console, or a terminal emulator. It can be run locally or across an SSH or telnet session. While it can be used in a console window of 80x25 characters (or smaller in some cases), it can also make use of larger displays.
Mpycurse can use a database to store information about mp3 locations, id3 data, or other user-defined attributes. This can drastically increase start up speeds and allow mpycurse to manage collection of thousands of mp3s (currently works easily with a 6,000 song library). Mpycurse can store user-defined playlists in this library, and can also generate playlists by search strings, album or artist queries, or by directory location.
The library information is stored in a relational database using Gadfly, a python-based database. It can be queried using standard SQL syntax, and can be modified or tied-into by third party applications. Gadfly requires minimal user set up, and does not require an standalone database server to be running.
Mpycurse supports song queueing for playback as well as the standard playlist format. Queueing can be done by song or by album, and will take precedence over other playing. Songs can be played out of the queue in sequence or randomly.
Mpycurse has a large collection of powerful actions it can perform, using default keybindings which closely mirror those used by GNU Emacs. However, these keybindings are overridable, both from a configuration file and from a dialog box in the application.
Users can modify the base application class from within an init file, writing their own python code to augment or change how mpycurse functions. Further, all mpycurse python functions and objects are available to the user through a python console and M-x style function calls.
Due to the design of mpycurse, it is relatively straight-forward to add the capability both to process different kinds of audio data, and to perform various kinds of playback. Currently, on mp3 is supported, but ogg vorbis is expected to follow soon after. Playback can be done through libao, mpg123(1), or a streaming module called "lameshout."
While user configuration for this feature is currently not supported, it is possible to change hard-coded values to allow mpycurse to stream audio data to an icecast server instead of playing it locally. This allows anyone with an internet connection to listen to your mp3 collection as if they were browsing it locally. Mpycurse over SSH plus a local audio player allows you to listen to your music collection anywhere you are.
Mpycurse is currently licensed under the General Public License (GPL). This gives you the freedom to modify and reuse mpycurse's code under the same license.
After installing mpycurse (see the INSTALL file), you should be able to type mpycurse to run it. mpycurse --help will print a list of options you can use to modify how mpycurse starts up. By default, it will open all mp3 files in the current directory (or sub-directories thereof) in a FS Library for you to view or play.
To specify one or more mp3 directories for the FS Library to use on startup, you can do one of two things:
--fs-lib DIR on the command-line to use DIR as the location.(TIP: you can do --fs-lib DIR multiple times to add more than one mp3 directory to the FS Library)
By default, mpycurse will use the OSS driver of pymad to play audio. However, newer systems using ALSA or ESD (?) support OSS emulation, so you may not need to change anything. However, like before, there are two ways of overriding the default:
mpycurse --pymad NAME to use NAME (alsa|oss|esd|macosx)If pymad is not working for you, you can always try the mpg123 driver. Please be aware that this driver is a hack, that it should not be considered stable, and that it will not work on all systems. Instead of handling audio playback using C modules, this will pipe the mp3 data to the mpg123 program. If you still want to do this, you can edit the custom file or do this:
mpycurse --mpg123 CMD
where CMD is the mpg123 command to execute (most likely "mpg123").
NOTE: mpg321(1) and other drop-in replacements for mpg123 will probably not work. There is buffering going on which makes the driver very delicate, and for whatever reason other mp3 players seem to do more buffering.
Mpycurse looks for two files on startup: .custom.mpc.py and .binding.mpc.py. If neither are available, it opens using application defaults or options provided on the command-line. If the files are present, then mpycurse will use the options they provide (but will still override those options with those on the command-line).
By default, the configuration files are located in ~/.mp3. If this directory does not exist mpycurse will try to create it. This location can be overridden on the command-line like this:
mpycurse -c CONF-DIR
A sample .custom.mpc.py file is provided in share/examples directory. The file is named .custom.mpc.py.example, and can safely be renamed and copied into ~/.mpy3. Here is a (notable) excerpt from it:
##use FSLibrary
use_db = False
mp3_dir = os.path.join(os.getenv("HOME"), "mp3")
##use GadLibrary
#use_db = True
#gad_db = "cagedb"
#gad_dir = "/home/moculus/mpy123/cagedb"
##decoding/playing driver
## ttype = { mpy123.pymad | mpy123.mpg123 | mpy123.lameshout }
## dev = { "oss" | "alsa" | "esd" | "macosx" }
ttype = mpy123.pymad
dev = "oss"
By commenting or un-commenting a line (adding or remoing the '#'s), it is possible to set up a default behavior for mpycurse.
use_db tells mpycurse whether you want to use an FS Library or a gadfly database. See the DATABASE section if you are interested in this; it is *highly* recommended for users with large mp3 collections.
mp3_dir specifies for an FS Library (the default kind) which directory your mp3s are stored in. To specify multiple directories, you can set this to a list, as follows:
mp3_dir = ["/path/to/dir/1", "/path/dir/2"]
ttype specifies which output driver you want to use, and can be changed in the same way as above (although only one driver can be specified).
dev specifies an argument to pass to the driver. In the case of pymad, it tells it which driver to use (as shown above). For mpg123, it is the command to launch mpg123 (often just "mpg123"). For lameshout, it is (currently) unused: you can just enter "x".
The outer block of python code shown above is executed when the application launcher starts. There are only a small number of variables here that can influence program behavior (and they are all listed above).
However, the file also contains a MyMpyCurse class. This class extends the generic mpycurse application class, and can be used to insert new features, modify or remove existing ones, or change default settings or bindings.
Currently this section will not explain how to do this, but comments in custom.mpc.py.example and other code should help you get started.
One drawback to reading in all the mp3s on startup is that it can take a long time. Mpycurse grabs the ID3 information from each file on startup (in the case of an FS Library), so the startup time is linear with the number of files in your collection. If your collection numbers several thousand, you could be waiting several minutes.
The solution is to use a database. Gadfly databases are stored in files (often in ~/.mpy3) and can offer signifigant speed-ups for startup and searching without most of the overhead that setting up a MySQL might.
Also, the DB can store the playlists you create in mpycurse. While we are also planning to incorporate this feature into the FS Library, it does not exist currently.
To initialize a database, you can use the mpylib command. As usual, --help will print usage options. Assuming you are using the default configuration directory (~/mp3) and you want your database installed in the default way, you can use the following command:
mpylib -i DIR [DIR] [DIR] ...
where each DIR is a directory with mp3s in it (or in sub-directories). If you have defined mp3_dir (with one or more directories) in .custom.mpc.py it will also be used. After running for awhile (up to 20 minutes in the case of a really large number of mp3s), mpylib will return. At this point you have a database! All you have to do now is tell mpycurse to use it.
If you want the DB stored somewhere else, or to use a different DB name (for whatever reason), use the command-line arguments provided. This will require you to modify .custom.mpc.py to set those values.
If you go back to the previous section on configuration, you will see an excerpt of .custom.mpc.py. To enable DB support (using the default locations) you would need to uncomment the line use_db = True, and comment the other one (use_db = False). If you have non-default setup, you must modify one or both of the other values as well.
Song you add to your library will now be added to the DB by default. However, if you have added songs to your mp3 directories, or want to add many files at once without running mpycurse, you can use this command:
mpylib -u DIR [DIR] [DIR] ...
Again, DIR is a directory with mp3s, and again, if you have defined mp3_dir in .custom.mpc.py, those will be used as well. After running for awhile, this command will have added the new songs into your DB.
Mpycurse is a curses-based program. As such, there is no mouse control: everything in mpycurse is controller via keypresses (or remote-commands sent by another program; see REMOTE for more information on this). Because of this, it can be a little intimidating to use for the first time. Here is a list of very basic keys which should get you started:
In the main window:
U_ARROW up
D_ARROW down
C-v page down
M-v page up
RETURN play selected song
SPACE pause (or resume) currently playing song
s stop playing
b next song
v previous song
g skip 5% ahead in song
f skip 5% back in song
r switch playmode (to or from randomized)
j search current playlist
i view id3 information window
o sorting options window
C-o sort current playlist (library cannot be sorted)
C-x C-f add mp3 file to the library
OR: add mp3 files in directory to the library
OR: add mp3 files listed in m3u file to the library
w remove selected song from playlist
C-x k delete current playlist (library and playqueue cannot be deleted)
TAB jump over to the sidebar
C-x a make a playlist of all songs by an artist
C-x m make a playlist of all songs from an album
C-x j make a playlist of all songs matching a search
q quit mpycurse
The notation C-v means "hold the CTRL key and press v". M-v is similar, meaning "hold the Meta key (also known as ALT) and press v". Finally, C-x C-f means "hold down CTRL and hit x, then release those keys, hold down CTRL again, and hit f".
[document in progress]
Check http://www.bearhome.net/mpy3 for updates. If nothing else, you should be able to find a complete README and other documentation there.
Email mpy3@bearhome.net with bug reports or comments. Please be as specific as possible with regard to bug reports.