Using an older version (< 0.9.3) of Remuco? See GettingStartedLegacy!

Outline

• Quick Start
• Requirements
• Installation
• Usage
• Configuration
• Known Issues
• Troubleshooting

Quick Start

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

1. Download 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.

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 (≥ 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 installed
• Totem: Totem ≥ 2.22
• TVtime: TVtime ≥ 0.9.11
• VLC: VLC ≥ 0.9 with DBus control enabled (see screenshot)
• XMMS2: XMMS2 ≥ 0.5, Python module xmmsclient (≥ 0.5)

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 (add your phone if it's not listed yet).

Additionally check the list of phones successfully used with Remuco. Once Remuco is running on your system, please help to extend this list by running the tool remuco-report.

Android Client

The Android client requires Android ≥ 2.1 (though older versions may work). Check the client device list, 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 (may be a bit outdated) or you can download 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.

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 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.

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:

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 DEFAULTand 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 FAQfaq 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.

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). Otherwise the phone tries to connect using BIS (BlackBerry Internet Service) instead of the real WiFi interface.

Another user reported 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 and drop a note on the mailing list in case you found a useful option.

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.

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.

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 for possible reasons and solutions.

Android

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