mServe Documentation

Running mServe


  1. Getting Started
  2. Standard Clients
  3. The mServe Daemon

Getting Started Top

You will need:

  • An installation of mServe
  • Two terminal windows at your disposal
  • Some MP3 files

Step 1. Start the mServe daemon

If you installed into a standard prefix, you should be able to just type 'mserve' (Without the apostrophes). If it is not, type

$ <PREFIX>/bin/mserve
at your shell prompt, substituting <PREFIX> with your installation prefix.
This should give you some output (thread started, loaded foo, initialized bar etc)

Step 2. Enqueue some media

Bring up your second terminal (You created one before, didn't you?), and type

$ mserve_ctl -e <MEDIA PATH>
, substituting <MEDIA PATH> with the path to an MP3 file. The playback should start immediately, and some more output should have appeared in the first terminal (where we started the daemon)

Step 3. Watch the progress of the playback

The mserve_ctl command should have returned quite quickly. Reuse the same terminal and type

$ mserve_monitor
. It should print some info and then printing a single line that is continuously updated, showing the song filename (paths stripped), the playback position, the number of bytes processed, etc etc. If the terminal window is to narrow, the line may wrap and make the window scroll, should this happen, just resize the terminal so that it stops scrolling.

Step 4. Explore!

Check out the --help for all commands and read the info on this page. If something goes wrong, consult the source or me.

Standard Clients Top

   mServe comes with a few simple clients. All of them connect only to localhost. (This is intended to be fixed in a near future)

mserve_ctl Top

   mserve_ctl performs simple control operations such as skip, seek, stop, pause, resume and enqueue. mserve_ctl will connect to localhost and perform the operations in command line order.
Usage: mserve_ctl  [OPTION...]
-u, --pausePause playback of current song
-p, --playResume paused/stopped playback
-s, --stopAbort playback of current song and stop the queue
-e, --enqueue=url Add file to the playback queue
--seek=secondsSeek in current song. The argument is a float representing the position to seek to
-n, --nextSkip to the next song in the queue

mserve_conf Top

   The server maintains its own config file (described in the mServe daemon section) that can be modified using mserve_conf. Like the mserve_ctl client, mserve_conf connects to localhost and runs its commands in command line order.

Usage: mserve_conf  [OPTION...]

-s NAME=VALUE, --set=NAME=VALUESet a config value. For a list of available config values, consult the mServe daemon section
-g NAME, --get=NAMEGet a config value
-a, --get-allGet all config values
-q, --quietSuppress non-error messages
-v, --verboseBe verbose

mserve_monitor Top

   When the playback has been started, use mserve_monitor to check its progress. mserve_monitor displays all media info it gets hold of, and displays the contents of most messages it receives.

Usage: mserve_monitor

The mServe Daemon Top

   The mServe Daemon is the server process. Since there is no protocol message to shut it down, the only way is killing it or typing Ctrl-C in its terminal. The daemon listens on port 4097 for client connections.

Usage: mserve  [OPTION...]

--out-driver=DRV, -od=DRVSpecify the output driver (overrides out_driver)
--out-driver-dir=DRV_DIRSpecify the output driver search directory (overrides out_driver_dir)


  • mServe.conf (PREFIX/var/mServe/)
    The config file. This file is loaded when the server is started and then saved when the server is shut down. Change it using the mserve_conf client or by editing the file manually when the server is shut down.
  • PREFIX/lib/mserve/decode
    The default decode plugin directory. Overridable through the decode_dir config value.
  • PREFIX/lib/mserve/ext
    The default protocol extension plugin directory. Overridable through the extension_dir config value.
  • PREFIX/lib/mserve/output
    The default directory for output plugins. Overridable through the out_driver_dir config value and the --out-driver-dir command line argument.

Config values:
out_driverThe output driver to use. mServe will try to load the file <out_driver_dir>/<out_driver>.so as an output plugin. If it fails, playback will halt.
out_driver_dirThe directory to search for output plugins
extension_dirThe directory to search for protocol extension plugins
load_extensionsA colon-separated list of protocol extension plugins to load at startup
decode_dirThe directory to search for decoder plugins