MSERV-IRMAN(1)

NAME
mserv-irman - control mserv mp3 jukebox program via infra-red remote controls.

SYNOPSIS
mserv-irman [-v] [-c conf]

DESCRIPTION
mserv is an mp3 jukebox who's features include allowing people to rate songs so it can pick tracks appropriate to who is currently connected.

mserv-irman extends this to remote controls using irman receivers from evation.com to control one or more mserv jukeboxes.

It will automatically connect to the mserv to ensure a user's ratings are active when they use their remote control.

INSTALLATION
If running NetBSD or pkgsrc on another system, install pkgsrc/audio/mserv-irman, otherwise follow the (brief) install notes in the README.

CONFIGURATION
It is recommended you configure mserv first, then the irman, and finally mserv-irman to hook them together.

  mserv configuration
There are various other options when setting up mserv, this is intended to provide a 'quick setup' route.

-   Create an mserv user (eg: 'mserv').

-   As that user run 'mserv' then ^C.

-   Edit ~mserv/.mserv/config to point path_tracks to your mp3s (or put all the mp3s in ~mserv/.mserv/tracks).

-   Login to the mserv (telnet localhost 4444), and create a user for each person who will be using the system. 'create <user> <pass> user'. You will need the usernames and passwords when you setup the mserv-irman.conf later.

  irman setup
If you have not installed from pkgsrc ensure you have installed irman_name (modified test_name from libirman - see README).

-   Connect up the irman to a serial port and ensure the 'port' is set correctly in etc/irman.conf.

-   chown the serial device to the user who will run mserv-irman (usually mserv).

-   Run irman_name - it should report 'ok' if it can initialise the irman.

-   Point a remote control anywhere near the irman and press some buttons. It should report 'rx ....' for each button.

  irman remote configuration
Now you are ready to configure in each remote. Repeat the following for each remote.

-   Press each button briefly in turn on a remote and note the rx number. Note that some remote controls may repeat buttons.

-   For each key add a line to etc/irman.conf of the form:

        bind <remotename>-<keyname> <rx_number>

    Where <remotename> is the (user specified) name of the remote control unit which can contain alphanumeric and '-' characters, <keyname> is a key from the recognised list (see RECOGNISED KEYS below).

    A sample section for a Hauppauge WinTV PVR would be:

        bind hauppauge-wintvpvr-tv              55a000000000
        bind hauppauge-wintvpvr-ch+             575000000000
        bind hauppauge-wintvpvr-radio           559000000000
        bind hauppauge-wintvpvr-vol-            544000000000
        bind hauppauge-wintvpvr-fullscreen      57b000000000
        bind hauppauge-wintvpvr-vol+            545000000000
        bind hauppauge-wintvpvr-mute            558000000000
        bind hauppauge-wintvpvr-ch-             574000000000
        bind hauppauge-wintvpvr-source          577000000000
        bind hauppauge-wintvpvr-1               554000000000
        bind hauppauge-wintvpvr-2               557000000000
        bind hauppauge-wintvpvr-3               556000000000
        bind hauppauge-wintvpvr-4               551000000000
        bind hauppauge-wintvpvr-5               550000000000
        bind hauppauge-wintvpvr-6               553000000000
        bind hauppauge-wintvpvr-7               552000000000
        bind hauppauge-wintvpvr-8               55d000000000
        bind hauppauge-wintvpvr-9               55c000000000
        bind hauppauge-wintvpvr-pause           54b000000000
        bind hauppauge-wintvpvr-repeat          555000000000
        bind hauppauge-wintvpvr-next            573000000000

    If you wish to map more than one button on a given control to the same feature you should append '.n' to the second and subsequent buttons. Eg 'vol+' 'vol+.2' 'vol+.3' etc.

-   Kill and restart irman_name and confirm it now reports the correct names when each button is pressed.

  mserv-irman configuration
Finally you need ${SYSCONFDIR}/mserv-irman.conf. It contains four sections:

An (optional) general section which permits you to tune overall configuration.

    [general]

    ### Ignore any repeated key for this number of seconds
    # default_debounce = 0.5

    ### If an owner is idle for the nyumber of seconds, disconnect them
    # idle_timeout = 3600

    ### Insert this many favourite tracks
    # favourite_inserts = 5

    ### Check sockets, plus check owner idle. Should not need to change.
    # flush_timeout = 60

    ### Optional percentage increase/decrease for volume control
    # volume_down = 10
    # volume_up = 10

An (optional) irman section which links irman receivers to mserv servers. mserv-irman can handle multiple irman receivers and multiple mserv servers. The system will default to a single irman on the default serial port linked to an mserv on the default port on the current machine (localhost:4444).

    ### List of <command to recieve irman data> = <host:port of mserv>
    ### Leave empty to default to 'irman_name' and 'localhost:4444'
    [irman]

A list of valid 'owners', each user and pass values from mserv.

    ### Add list of owners here, in the form '<mservuser> = <mservpass>'
    [owners]

A list of valid remotes, linking each remote to a user. A given user can have more than one remote.

    ### Add your remotes here, in the form '<remotename> = <mservuser>'
    [remotes]

Each section can be overridden on a per host basis by adding _`hostname -s` to the section key - for example [irman_iris]

RECOGNISED KEYS
    vol-, vol+      Volume down and up
    mute            Volume to 10%
    play            Play music
    pause/10        Pause or resume - also any unrecognised key
    stop            Stop playing (and disconnect from mserv)
    next/fwd/ch+    Skip current track
    prev/rew/ch-    Put previous track on queue, then skip current track
    repeat          Put current track back onto queue to play again
    recall          Put previous track on the queue to play again
    1, 2, 3, 4, 5   Rate track 1=AWFUL 2=BAD 3=NEUTRAL 4=GOOD 5=SUPERB
    6               Add five unrated tracks to the queue (*1)
    7               Add five tracks from current album (*2)
    8               Add five tracks from current artist (*2)
    9               Add five random SUPERB tracks to queue (*3)
    0/reset/power/cancel/clear    Clear queue

        (*1) Will try to queue tracks that no-one connected has rated, and
             fall back to the current user.
        (*2) Tracks rated AWFUL/BAD/NEUTRAL will not be picked, will try to
             queue UNRATED/UNHEARD tracks before SUPERB/GOOD.
        (*3) Will try to queue tracks that have not been rated BAD/AWFUL by
             other connected users first.

SETTING UP MULTIPLE MSERV SERVERS
This is a more advanced section for those who wish to run multiple mserv servers (One each for the office, bedroom, and bathroom maybe?)

  mserv
Assuming you want to share user passwords and track ratings between more than one simultaneous mserv sessions.

-   From the mserv user's home directory execute:

        mkdir .mserv2
        ln -sf ../.mserv/acl .mserv2/acl
        ln -sf ../.mserv/trackinfo .mserv2/trackinfo
        ln -sf ../.mserv/webacl .mserv2/webacl
        cp ../.mserv/config .mserv2/config

-   Edit .mserv2/config and update the audio device.

-   Run the second mserv with a new root dir portnumber:

        mserv -r .mserv2 -p 4445 &

mserv will automatically merge in any ratings update so it is safe to rate the same song via different mserv servers. It will however have issues merging in new users, so when adding a user shut down all but one mserv, create the user on that mserv, then start up the other mservs.

  mserv-irman
Update the [irman] section in mserv-irman.conf to list each irman and its destination mserv. If you are running an mserv on a remote system you may want to setup the appropriate ssh keys and have an entry something like:

    ssh -1 shim 'pkill irman_name ; irman_name' = shim:4444

CAVEATS
Where to begin... here are a few of my favourites:

-   The mserv-irman.conf file contains mserv passwords in the clear. It should only be readable by the user running mserv-irman. mserv-irman should also enforce this.

-   If an mserv to which mserv-irman has an open connection dies it will abort next time it tries to write to that socket.

-   If an irman connection dies mserv-irman will close it down and (if there are any remaining active) continue running. It should periodically try to restart any closed irman connections.

-   Debouncing is completely broken on slower machines. We need to get a timestamp for each button to make this work correctly. Not difficult, just a little time.

-   When queuing a set of songs it should weight the selection by the rating, rather then just cutting off NEUTRAL, BAD, and AWFUL.

-   There should be a clean way to hook in non mserv uses of other buttons.