Mpycurse 0.3.0 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: * curses audio player (currently mp3, ogg, wav, mp3 streams) * song database and playlist management * id3 tag decoding * remote mp3 player controls * application bindings suitable for other front-ends (x11 application, java applet/servlet, web page, commandline tool) MPYCURSE: The mpycurse application specifically provides the following features: 1. curses interface: Mpycurse can run in a console, or a terminal emulator. It can be run locally or across an SSH session. While it can be used in a console window of 80x24 characters (or smaller in some cases), it can also make use of larger displays. 2. library/playlist management: Mpycurse has two modes of operation: single-use using an FSLibrary created when the program starts, and via a MetaLibrary, which stores the song and songlist data in a textfile using metakit. MetaLibrary is what most people probably want, but if you desire something more like XMMS which doesn't save state between invocations, use FSLibrary. In either case, the Library allows you to search across all artists, albums, or other search data. PlaySets can be defined by rules and will dynamically adapt as songs are added or removed from the library. These are particularly useful in MetaLibrary as they will stay around between sessions. 3. playsets Playsets are defined by a string of python code which is evaluated based on each song in the library to determine membership. Some knowledge of song.py is helpful, but here are some rules that are pretty generic to learn: #songs from the album "I Care Because You Do" "I Care Because You Do" == song.artist #songs with rock anywhere in the metadata song.match("rock") #artist matches beatles or lennon "Lennon" in song.artist or "Beatles" in song.artist Playsets can be created with the default key-sequence of C-x C-n, This creates a Playset with a rule of "False." To use a different rule, run the "modify_set_buffer" command, C-x C-b. 4. playqueue: Mpycurse supports song queueing for playback as well as the standard playlist format. This is good for things like DJing, parties, or for radio broadcasting. Queueing can be done by song or by album, and will take precedence over other playing. However when the queue becomes empty, your previous playlists will continue. Thus, it is a low impact way to hear the songs you want when you want without disrupting the player's normal operation (stopping one list, starting another, and going back once you hear the desired song vs. queueing the song you want and being done). 5. customizable, emacs-style keybindings: 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. 6. power-user functionality: 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. Code evaulation is fully supported ("self.player.pause()") and arbitrary code execution is very close to fully working (currently statements like print are being worked on). 7. module audio output structure: 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, mp3, ogg, and wav files are supported (as well as mp3 streams) and playback using AO or to a file is supported. In the past, mpycurse was able to function as an icecast client, and this capability is being re-added (vorbis re-encoding is already supported through pyvorbis, and mp3 re-encoding through either py-lame or system() will be supported). This will depend on shout-python when it is finished. 8. free! 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. It also happens to be available at no cost! MPYCURSE KEYS: If you press "?" (shift + /) you will get a complete list of keybindings for the mode you are in. While a song is highlighted, it will give you the full list of core features. Here are some keys to get you started: (C is the "control prefix" and M is the "meta prefix," so C_s is " + s") Quit: q Play: Pause: Stop: s Next: b Previous: v Fast Forward: g Rewind: f Toggle Playmode: r Toggle Shuffle: C_r Toggle Sidebar: Filter: M-f Search: C_s / Search buffer: C_x j Album buffer: C_x m Artist buffer: C_x a Kill buffer: C_x k Delete playlist/playset: C_x C_k Cancel command: C_] Open path (URL, file, dir): C_x C_f New Playlist buffer: C_x n New Playset buffer: C_x C_n Define Playset Rule: C_x C_b Kill Song: C_k Yank Song: C_y Enqueue Song: C_x e Bindings dialog: ? Console dialog: M-c Format dialog: p ID3 dialog: i Sort dialog: o USING MPYCURSE: 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. There are X types of configuration options: 1. audio output options a. type There are only two types of output: 'pyao' and 'file'. Only pyao is used with any frequency. You probably don't need this option, but you can choose which type you want via "-t pyao" on the command-line, or via this line in custom.mpc.py: settings['type'] = 'pyao' b. device This option is what device the output driver will use. In the case of AO, it determines whether you use 'oss','alsa','esd', or 'macosx'. In the case of the file output, it determines the filename that you will write to. The default values are 'oss' and '/tmp/mpy3-output.raw' respectively. 'alsa' seems to be broken; 'oss', 'esd' and 'macosx' all seem to work. This can be specified via "-d oss" or via: settings['device'] = 'oss' 2. library options a. type There are currently two library types: 'meta' and 'fs'. You can use '-f' to specify an FSLibrary, or '-m' to specify a metakit library. The long opts are '--fs' and '--meta' respectively. mpycurse defaults to metakit. b. (metakit) library file This tells MetaLibrary where to find its savefile. The file defaults to ${HOME}/.mpy3/librar.meta, and unless you have multiple libraries there's probably no reason to change it. You can specify this via the command-line via: "--meta-file " or in custom: settings['meta_file'] = c. (fs) startup directories Either library can add files, directories, and m3u playlists to itself at any time. However, you can specify directories which you want FSLibrary to read on startup. By default, FSLibrary starts up using songs in the current directory; this option allows other directories to be specified. From the commandline, do: "--fs-path " for each path you want to add. If this is used, these paths will be used instead of the curren path. From the custom.mpc.py file, do the following: settings['fs_paths'] = [, , ...] 3. miscellaneous options a. no-conf Use "--no-conf" at startup to ignore the custom.mpc.py file. By default, options on the commandline override the settings in this file; this is a convenient way to just ignore them without specifying anything else. b. conf If you want to use a directory other than ${HOME}/.mpy3 for storing all your mpycurse related data (and for reading custom.mpc.py from), you can use "-c " or "--custom " to specify this. NOTE: if you intend to continue using this directory, you need to specify this every time you start mpycurse (or alias the command). c. help Use "--help" or "-h" to get a list of all these options and a brief description of each. d. debug Use "--debug" to have the program output additional information. This is not recommnded unless you are a developer or wish to submit more detail in a bug report. CONFIGURATION: Mpycurse looks for two files on startup: custom.mpc.py and bindings.mpc.py. If neither are available, it opens using defaults or options provided on the commandline. If the files are present, then mpycurse will use the options they provide (but will still override those options with those on the commandline). By default, the configuration files are located in ${HOME}/.mp3. If the conf option (as above) is used, that will be the configuration directory. When the configuration directory does not exist mpycurse will try to create it. A. simple configuration 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. The file is executed as python code. If you are a python programmer, there are many ways you can leverage this file to customize mpycurse's behavior. Even if you aren't a programmer, there are many useful settings here that can configure mpycurse to behave correctly. Lines beginning with # are commented, and thus are disabled. B. complex configuration (for python programmers) 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. Check http://www.bearhome.net/mpy3 for updates. If nothing else, you should be able to find a (semi-)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. If you wish to join the mpy3 development team please send an email there also, and you can get added to the developer's mailing list.