Remuco
===============================================================================

Remuco is a duplex remote control system for media players and mobile devices.
With Remuco, you can remotely control your favorite media player. You can
switch to the next, previous, or any other media within the current playlist,
browse your media library and activate other playlists, rate your media, adjust
volume, and more. On the mobile device (the remote control), it displays
information about the current media, including cover art. Remuco has clients
for MIDP (JavaME) and Android phones.

 - Project Website: <http://remuco.googlecode.com>
 - Issues and support: <http://code.google.com/p/remuco/wiki/Issues?tm=3>
 - Developer mailing list: <http://groups.google.com/group/remuco>
 - License: GPL3

The most recent version of the following documentation can be found at [the
Remuco website][wgs] - that's probably easier to read. Stick to this
documentation file if you don't use the most recent Remuco version.

[wgs]: http://code.google.com/p/remuco/wiki/GettingStarted

Outline
-------------------------------------------------------------------------------

 1. [Quick Start][]
 2. [Requirements][]
 3. [Installation][]
 4. [Usage][]
 5. [Configuration][]
 6. [Known Issues][]
 7. [Troubleshooting][]
 8. [Development][]
 9. [Packager Information][]

<!-- WIKI -->

Quick Start
===============================================================================

In case you can't wait, here's a quick start for using Remuco.

 1. [Download][dlo] the latest Remuco package and extract it to a place of your
    choice.
 2. In a terminal switch into `/path/to/extracted-remuco-package`.
 3. Run `sudo make install-PLAYER` where *PLAYER* is the player you want to use
    with Remuco. Inspect the output for possibly missing requirements.
 4. See section [Usage][] for how to enable the just installed player adapter.
 5. Install the client, located in `client/midp/app` onto your phone.
 6. Start the client and have fun.

Got it working? Great! Otherwise follow the more detailed documentation below.

[dlo]: http://code.google.com/p/remuco/downloads/list


Requirements
===============================================================================

General
-------------------------------------------------------------------------------

 - Python ≥ 2.6 and < 3.0
 - Python modules *Image* (a.k.a. PIL), *logging*, *bluetooth*, *dbus*,
   *gobject* and *xdg*

Player specific
-------------------------------------------------------------------------------

 - __Amarok:__        Amarok ≥ 2.0
 - __Amarok14:__      Amarok ≥ 1.4 and < 2.0, Python module *eyeD3*
 - __Audacious:__     Audacious ≥ 1.5.1 (2.1 has issues, 2.2 works again)
 - __Banshee:__       Banshee ≥ 1.6.0
 - __Clementine:__    Clementine ≥ 0.7.1 (older versions not tested)
 - __Exaile:__        Exaile ≥ 0.3.1
 - __gmusicbrowser:__ gmusicbrowser ≥ 1.0.2
 - __MPD:__           MPD ≥ 0.13.2, Python module [*mpd*][pym] (≥ 0.2)
 - __Quod Libet:__    Quod Libet ≥ 2.2
 - __Rhythmbox:__     Rhythmbox ≥ 0.11.5, Python module *gconf*
 - __Songbird:__      Songbird ≥ 1.2 with the [MPRIS Add-on][sbm] installed
 - __Totem:__         Totem ≥ 2.22
 - __TVtime:__        TVtime ≥ 0.9.11
 - __VLC:__           VLC ≥ 0.9 with DBus control enabled (see [screenshot][vls])
 - __XMMS2:__         XMMS2 ≥ 0.5, Python module *xmmsclient* (≥ 0.5)

[pym]: http://mpd.wikia.com/wiki/ClientLib:python-mpd
[sbm]: http://addons.songbirdnest.com/addon/1626
[vls]: http://wiki.remuco.googlecode.com/hg/images/exos/vlc-preferences.png

MIDP Client
-------------------------------------------------------------------------------

The Remuco MIDP client requires a JavaME (J2ME) capable phone with MIDP ≥ 2.0
and CLDC ≥ 1.1. To connect via Bluetooth the phone must support JSR-82 (Java
Bluetooth API).  To check if your device matches the requirements take a look
at the [FPC database][fpc] (add your phone if it's not listed yet).

[fpc]: http://www.dpsoftware.org/filter.php

Additionally check [the list of phones successfully used with Remuco][wcd].
Once Remuco is running on your system, please help to extend this list by
running the tool _remuco-report_.

[wcd]: http://code.google.com/p/remuco/wiki/ClientDevices

Android Client
-------------------------------------------------------------------------------

The Android client requires Android ≥ 2.1 (though older versions may work).
Check the [client device list][wcd], maybe your phone is already listed there.


Installation
===============================================================================

To use Remuco you need to install one or more player adapters on your computer
and a client for your mobile device.

Player Adapters
-------------------------------------------------------------------------------

You can either install [packages for your distribution][wdp] (may be a bit
outdated) or you can [download][dlo] the latest Remuco release, extract it to a
place of your choice and install one or more player adapters as follows:

    $ cd path/to/extracted-remuco-package
    $ make help
    ... wow, good to know ...
    $ sudo make install-PLAYER
    ... check output for missing requirements ...

The last command installs the player adapter for *PLAYER* (replace this with a
real name). After installation there are some files called `install-...log`.
They are needed if you want to uninstall Remuco later.

[wdp]: http://code.google.com/p/remuco/wiki/DistributionPackages
[dlo]: http://code.google.com/p/remuco/downloads/list

MIDP Client
-------------------------------------------------------------------------------

The MIDP client application consists of 2 files:

 - *remuco.jar*: The client application to install on your mobile phone.
 - *remuco.jad*: A descriptor file which is needed additionally by some phones
   for installation.

The files are located in `client/midp/app/` (if you installed using
distribution packages they probably are at `/usr/share/remuco/client/`).

The concrete steps to install the client depend on your phone. Usually the
*JAR* file has to be sent or copied to the device. Some phones then already
trigger the installation, others require to open the file with the device's
file manager.

Next to the regular client you'll find special variants of the client
in the above mentioned directory:

 - *motorola-fix*: Use this for older Motorola phones like ROKR E2, ROKR E6,
   MOTOZINE ZN5 and A1200e.
 - *no-bluetooth*: A client without Bluetooth functionality. Some Windows based
   phones (using JBed) are known to require this client version.

Android Client
-------------------------------------------------------------------------------

Remuco's Android client still is in it's beta phase, i.e. it generally works
but yet requires some tweaks, features and fixes. That's why you won't find it
in the Market. However, you'll find a test version in `client/android/app` to
install manually (e.g. via USB) on your device.

**Note:** You have to tune your phone settings to allow the installation of
applications from untrusted sources (i.e. not from the market).

Additionally you may want to check the [Android page in the wiki][wan] for
further information. There you'll also find some instructions how to build
the client from source, in case you want to contribute or use the most recent
version.

[wan]: http://code.google.com/p/remuco/wiki/Android

Usage
===============================================================================

Amarok, Amarok14, Audacious, Clementine, Banshee, gmusicbrowser, Quod Libet, Songbird, VLC
------------------------------------------------------------------------------------------

The player adapter can be started with the command `remuco-PLAYER` (replace
*PLAYER* with a real player name).

A good choice is to set up `remuco-PLAYER` as a startup application when you
log in to your desktop session. When the player is not running then the adapter
is in sleep mode and won't eat much resources.

*Note:* Remember to enable DBus control in VLC and to install the Songbird
MPRIS Add-on (see above in section [Requirements][]).

Exaile, Rhythmbox, Totem
-------------------------------------------------------------------------------

The player adapter actually is a plugin of the player. Thus it gets started
automatically once you activate the Remuco plugin within the player.

MPD
-------------------------------------------------------------------------------

The player adapter can be started with the command `remuco-mpd`.

A good choice is to set up `remuco-mpd` as a startup application when you log
in to your desktop session (in case MPD is already running at this time) or
when MPD itself get's started. It mainly depends on your MPD setup.

If the player adapter is not running on the same computer as MPD have a look
into the [Configuration][] section below.

MPlayer
-------------------------------------------------------------------------------

**The lazy way:**
Assuming both *mplayer* and *remuco-mplayer* are in your *PATH* variable, just
run

    $ remuco-mplayer myawesomefile1 myawesomefile2 ... myawesomefileN

and *remuco-mplayer* will call *mplayer* files it can find in that list.
As of now, you cannot pass arguments to *mplayer*.

**The kludgy but one-off way:**
Add a line to your `~/.mplayer/config` file, telling *mplayer* to read from the
file `.cache/remuco/mplayer.cmdfifo` folder:

    echo "input=file=$HOME/.cache/remuco/mplayer/cmdfifo" >> ~/.mplayer/config

This will allow you to control *mplayer* from the client, and should be done
only once. Next start the adapter (as of now, you need to run the adapter
before you run mplayer):

    $ remuco-mplayer

To be able to get information from *mplayer* to clients, you need to pipe its
output to a location known to remuco.

    $ mplayer mymovie.avi | tee $HOME/.cache/remuco/mplayer.statusfifo

This should be all, you can now start the client. But note that you'll need to
type that last command every time you want to play something with *mplayer*.

To make your life easier, add this script to your `~/bin` directory:

    [ -z $1 ] && echo "Usage: $0 file2 file2 ..." && exit 1

    # if mplayer is installed elsewhere, change /usr/bin/mplayer to the correct location
    /usr/bin/mplayer $@ | tee $HOME/.cache/remuco/mplayer.statusfifo

Name this script `~/bin/mplayer` and make sure `~/bin` precedes `/usr/bin` in
your *PATH* environment variable.

TVtime
-------------------------------------------------------------------------------

The player adapter can be started with the command `remuco-tvtime`.

For navigating in TVtime's menu with the Remuco client, the keys on the client
have special functions when using the TVtime adapter:

Client Key | TVtime Key
-----------|-----------
Playback   | *MENU_ENTER*
Repeat     | *SHOW_MENU*
Shuffle    | *SHOW_MENU*
Previous   | *LEFT*
Next       | *RIGHT*
Vol. up    | *UP*
Vol. down  | *DOWN*

XMMS2
-------------------------------------------------------------------------------

The player adapter can be started with the command `remuco-xmms2`.

To let it start automatically when XMMS2 starts, create a symbolic link in the
XMMS2 user startup script directory, for instance like this:

    $ ln -s `which remuco-xmms2` ~/.config/xmms2/startup.d/remuco-xmms2

Client (MIDP and Android)
-------------------------------------------------------------------------------

Using the client should be quite obvious -- just start and use it ;) .

Report Tool
-------------------------------------------------------------------------------

Remuco comes with a tool called *remuco-report*. This tool submits information
of seen Remuco client devices to the Remuco project. Help setting up a Remuco
compatible device list, by using remuco-report! See the tool's man page for
more information.

Configuration
===============================================================================

Each player adapter can be configured in Remuco's configuration file placed in
`~/.config/remuco/remuco.cfg`. This file is created automatically when a player
adapter has been started the first time. The file contains a section `DEFAULT`
which defines options for *all* player adapters and additional sections for
each player used with Remuco. These sections overwrite global options in
`DEFAULT`and are used to define options which only make sense for specific
players (look for options starting with `x-`).

Global options in section `DEFAULT` are documented within the configuration
file. The player specific options are described below.

Amarok, Audacious, Songbird, VLC (MPRIS based adapters)
-------------------------------------------------------------------------------

 - `x-playlist-jump-enabled`:
   Toggle playlist jump action (default: `0`). If enabled, clients may jump
   within the player's playlist. This is disabled by default because the player
   interface does not support such an action. Remuco implements a dirty hack to
   realize that anyway but this only works on *non-dynamic* playlists. If you
   think that's okay, feel free to set a *1* here.

MPD
-------------------------------------------------------------------------------

 - `x-mpd-host`:
   Host running MPD (default: `localhost`).
 - `x-mpd-port`:
   Port used by MPD (default: `6600`).
 - `x-mpd-password`:
   Password to use when connecting to MPD. Must be set if MPD is configured to
   restrict certain actions with a password requirement.
 - `x-mpd-music`:
   Root directory of MPD's music directory (default: `/var/lib/mpd/music`).
   Used for searching cover art files and only works if MPD is at localhost.

The defaults should work for most MPD setups.

MPlayer
-------------------------------------------------------------------------------

 - `x-cmdfifo`:
   FIFO file to use to send commands to MPlayer (default:
   `~/.cache/remuco/mplayer.cmdfifo`). For details see MPlayer usage in the
   [Usage][] section above.
 - `x-statusfifo`:
   FIFO file to use to read output from MPlayer (default:
   ~/.cache/remuco/mplayer.statusfifo). For details see MPlayer usage in the
   [Usage][] section above.

Known Issues
===============================================================================

Bluetooth service search
-------------------------------------------------------------------------------

On some phones the Remuco client does not find the player adapter services
running on a computer. See the [FAQ][faq] for instructions how to fix this.

**BlackBerry devices:** The default service search fails on BlackBerry devices.
You have to manually set a service channel ≥ 7 in the client *and* in the
player adapter configuration. For details see the [FAQ][wfq].

[wfq]: http://code.google.com/p/remuco/wiki/FAQ

WiFi connections on BlackBerry devices
-------------------------------------------------------------------------------

On some BlackBerry devices (e.g. Bold 9000 or Pearl 8120) you need to set the
option `interface=wifi` in a WiFi connection's configuration screen
([screenshot][ccs]). Otherwise the phone tries to connect using BIS (BlackBerry
Internet Service) instead of the real WiFi interface.

Another user [reported][i67] that the option `deviceside=true` had to be set in
order to circumvent BES proxy connections. If it still fails, have a try with
some other [options for WiFi connections on BlackBerry devices][owb] and drop a
note on the [mailing list][rml] in case you found a useful option.

[ccs]: http://wiki.remuco.googlecode.com/hg/images/exos/emulator-ifacewifi.png
[i67]: http://code.google.com/p/remuco/issues/detail?id=67
[owb]: http://www.blackberry.com/developers/docs/5.0.0api/javax/microedition/io/Connector.html#socket
[rml]: http://groups.google.com/group/remuco

Phones operated by AT&T Wireless or T-Mobile U.S.
-------------------------------------------------------------------------------

These operators have very restrictive access rights for third party JavaME
applications. As a result it is likely that the Remuco client is not allowed to
setup WiFi or Bluetooth connections. Read [all the details][wjp].

[wjp]: http://code.google.com/p/remuco/wiki/JavaMeApiPermissions

Windows Mobile devices
-------------------------------------------------------------------------------

The default client fails to start on Windows Mobile devices using JBed for
JavaME apps. Bluetooth is a problem here so you have to use the special client
in the `no-bluetooth` sub-directory where the default client files are located.

Motorola devices
-------------------------------------------------------------------------------

Some Motorola devices (ROKR E2, ROKR E6, MOTOZINE ZN5 and A1200e) crash with
the default client when adding a new Bluetooth connection. This is a bug in the
devices' Java implementation. There's a special client version with a
work-around for this bug. It's located in the `motorola-fix` sub-directory
where the default client files are located.

### Motorola K1 ###

The default client fails on the K1 when using Bluetooth on the. A special
client version in the `motorola-k1-fix` sub-directory fixes this problem.

Troubleshooting
===============================================================================

General
-------------------------------------------------------------------------------

 - If you experience any problems first have have a look into the log file of
   the player adapter your are using (`~/.cache/remuco/PLAYER.log` - replace
   *PLAYER* with a specific player name.
 - In case this does not help to find and solve the problem, enable debug log
   by setting the option *log-level* in `~/.config/remuco/remuco.cfg` to
   *DEBUG*. Restart the player adapter and inspect the log again.
 - If you are still lost, then it's time to [ask for help][hlp].

[hlp]: http://code.google.com/p/remuco/wiki/Issues?tm=3

MIDP Client
-------------------------------------------------------------------------------

 - The client has a menu option called *Log* - check it.
 - If the client fails to start on your device, although it meets all
   requirements, have a look at [MIDP][wmp] for possible reasons and solutions.

[wmp]: http://code.google.com/p/remuco/wiki/MIDP

Android
-------------------------------------------------------------------------------

 - Go and fix it :-P (client is still in development).

<!-- WIKI -->

Development
===============================================================================

If you'd like to contribute to Remuco, read [Contribute][wco] as a starting
point. You may also be interested in the other [wiki pages related to
development][wdv]. Feel free to say hello on the [Remuco development mailing
list][rml].

[wco]: http://code.google.com/p/remuco/wiki/Contribute
[wdv]: http://code.google.com/p/remuco/w/list?q=label:Development
[rml]: http://groups.google.com/group/remuco


Packager Information
===============================================================================

Packagers should not use the top level make file -- this is a wrapper around
'setup.py'. Instead use setup.py directly, which installs all Remuco components
(base, player adapters and MIDP client binaries) by default. To install only
some components, the environment variable REMUCO_COMPONENTS may be set
appropriately. Additionally some more environment variables may be used to
adjust the installation process. Just search for 'os.getenv' within setup.py
to get more detailed information.

If your distribution requires source only packages, use the package
`remuco-source-x.x.x.tar.gz`. Building the MIDP client requires Ant (including
optional tasks), ProGuard and JavaME libraries. You can use JavaME libraries
from SUN's Wireless Toolkit, from the MicroEmu project or generate them from
scratch as described in `client/midp/ligben/README`.

The Android client is still in development and should not yet get packaged.

<!-- ---------------------------------------------------------------------- -->
<!-- in-document section links                                              -->
<!-- ---------------------------------------------------------------------- -->

[Quick Start]:          #Quick_Start
[Requirements]:         #Requirements
[Installation]:         #Installation
[Usage]:                #Usage
[Configuration]:        #Configuration
[Known Issues]:    	    #Known_Issues
[Troubleshooting]:      #Troubleshooting
[Development]:          #Development
[Packager Information]: #Packager_Information