Because copyright is loathsome, I have waived all copyright and related or neighboring rights to all information published on this site, to the extent possible under law. See CC0 for exact terms of this waiver.

Moosic Documentation

Requirements

The primary requirement for using Moosic is a Python interpreter that supports version 2.2 of the language (or later) and also includes support for threads. The command-line client also relies on the Unix find utility. The server relies upon external command-line programs for actually playing the music files. The default setup uses mpg123 for MP3, timidity for MIDI, ogg123 for Ogg/Vorbis, mikmod for the whole range of MOD formats, and sox for a wide variety of other (mostly uncompressed) sound file formats. Moosic will only work on Unix systems, since it uses a wide variety of Unix-only features. All of these portability issues are noted within the source code.

Installation

After extracting the archive file (tarball) used to distribute Moosic, the executables and manpages can be installed by using the "make install" command from within the directory that contains Moosic's source files. By default, this command installs Moosic within the /usr/local directory, and thus requires the command to be run as the root user to be effective. If you wish to install Moosic into another directory, use the following command, replacing "[dest]" with the name of the directory you wish to use: "make install INSTALL_PREFIX=[dest]".

Usage

moosic is the command-line program that provides the main interface to the Moosic jukebox. It works by sending a command to the Moosic server and returning the response, if any. The first non-option argument given to moosic is the name of the command to be performed. Use "moosic --showcommands" to get a list of all the different possible commands, or read moosic's manual page. There are very many commands, so you should start by just learning a few commonly used commands, and only learning others as you feel the need. I recommend starting with the following short command vocabulary: add, list, stop, play, and shuffle.

For example, "moosic add foo.mp3" adds the file foo.mp3 (in the current directory) to the end of the song queue and returns you immediately back to your shell prompt without printing any output (unless an error occurs). Compare with "moosic list", which will list the contents of the song queue. Note that if the song queue is empty, "moosic list" will not display anything.

Any command which takes a list of files as an argument will also accept directories, and doing so will cause every file below that directory to be included in the file-list. Note that the default behavior of moosic is to shuffle everything in a file-list before sending the list to the server, but only after recursively expanding named directories. Use "moosic --help" to learn about options for changing the shuffling behavior, as well as other options.

When the Moosic server isn't already running, moosic will automatically start it for you by launching the program named "moosicd" (unless you specifically request otherwise).

Configuration

moosicd creates a default configuration file for you in the ~/.moosic/ directory. This configuration file associates filename patterns to player programs. Although the defaults should be sufficient for many people, there is a very good chance that you will want to change this default configuration. Simply open up the config file in your favorite text editor, and follow the instructions. Note that you need to start moosicd at least once for it to generate a configuration file for you.

Manuals

moosic(1)
The manual page for the command-line Moosic client.
moosicd(1)
The manual page for the Moosic server.
Moosic_API
The specification for the Moosic server's API and protocol. Read this if you want to write a new Moosic client.

Outstanding Bugs

Restarting the current song instead of skipping to the next one

Very rarely, performing "moosic next" will cause the currently playing song to restart rather than causing the next song in the queue to start playing. I have no idea why this happens, and it happens so infrequently that I've not yet had the patience to monitor the server long enough and carefully enough to reveal any clues.

Random junk shown for current song

This bug causes the "moosic current" command to output a string of junk characters when moosicd is not playing anything. This is really a manifestation of a bug in the Python standard library included with Python version 2.2.2 (specifically, in the function for decoding base64 data in the binascii module). This bug has been fixed in version 2.2.3, and is not present in versions between 2.2 and 2.2.2, so you can fix this problem by using these versions of Python instead of version 2.2.2.

Skipping too many songs

The "moosic next" command can sometimes cause too many items to be skipped when ogg123 is being used to play the current song. The problem is that the Moosic server sends a "terminate" signal to ogg123 and starts processing the next item in the queue as soon as ogg123 claims that it has exited. But it seems to be possible for ogg123 to somehow keep the sound card busy for a short period of time after it has exited (although I have no idea how this is possible). This behavior interferes with any new player processes spawned by moosicd. As long as ogg123 retains its wrongful strangle-hold over the sound card, the player programs that moosicd tries to start will fail with an error such as "Device or resource busy". This lingering lock on the sound card generally won't continue for more than a fraction of a second after ogg123's death, but that is long enough for moosicd to attempt to play a very significant number of songs.

One way to work around this problem is to use a system such as aRts or EsounD, which allows multiple programs to access the sound device at the same time. It also seems possible to work around this bug in ogg123 by having moosicd artificially send it a "keyboard interrupt" signal instead of the more appropriate "terminate" signal. Versions of Moosic since 1.3.3 include a hack that does this, but I really do not like this hack. I really wish the maintainers of ogg123 would fix their program so that it responds properly to "terminate" signals.

Please report any bugs that you discover to me, Daniel Pearson.