
            WeLcOMe tO ReMoot!

                                 - the pseudo-universal
                        remote control wrapper!


==============================================================================
ABOUT
==============================================================================


ReMoot is written in perl and is a user friendly command wrapper for many
multimedia applications running on GNU/Linux systems and possibly other *nix
systems as well. ReMoot provides a simple interface to control all supported
apps in a simple and consistent way. The package now consists of three core
executables:

- i)    "daemoot", which is a daemon that passes arguments to the targeted
        apps.

- ii)   "remoot", which is a command-line program that is typically executed
        either in a shell or using quick key-bindings. It contacts daemoot
        on its fifo channel in the users home directory.

- iii)   "remoot-remote", which is a simple proof of concept graphical
        frontend to remoot written in Tk. It also contacts daemoot over the
        fifo.

The official versions of the package is maintained by Andreas Wallberg
(andreas.wallberg@gmail.com), Joel Berglund (joel.berglund@gmail.com).

We are now hosted on SourceForge! Please contact us if you have ideas, find
bugs or heaps of nicely documented code to donate. Please use the Sourceforge
contact resources, such as the email list and forum, primarily. Heaps of hugs
and fanmail are also welcome. And money.

          Visit http://sourceforge.net/projects/remoot/ for more info!

               Thanx for using ReMoot!


==============================================================================
PREREQUISITES AND INSTALLATION
==============================================================================


* You system needs to:

  - Understand some standard commands like "cat", "grep", "echo" and "ps".

  - Have alsa up and running to detect actively running apps. The program
    still works without alsa, but you lose some magic.

  - Have "dcop" to control some KDE apps.

  - Have "wget" to control vlc.

  These prerequisites should be met by default on almost all GNU/Linux
  desktops out there.

* You need to make the program executable, for instance like this:

  chmod +x remoot

* You then need to put daemoot somewhere in your $PATH, for instance in
  /usr/bin (for that particular directory you need to be root).

* If you want to use the console frontend remoot or the graphical
  remote-control frontend you do the same procedure with their files.
  They will access daemoot when you use them.


==============================================================================
USAGE
==============================================================================


Darn simple. If you want to toggle play/pause:

* Using the "remoot" client in a console
  --------------------------------------

  remoot playpause

* Communicating directly to daemoot
  ---------------------------------

  echo "playpause" >> ~/.remoot/fifo

  This method is more responsive than "remoot playpause", but it requires you
  to start daemoot manually first.


==============================================================================
CHANGELOG
==============================================================================


0.9     "Vårgårda" 20071002 - Sort of a complete rewrite of everything
        --------------------------------------------------------------

        - This release introduces a new client/daemon usage model. "remoot"
          and "remoot-remote" are now clients that communicates with the
          master control daemon "daemoot". They start the daemon automatically
          if it is not already running. daemoot listens for input on a fifo
          located in: ~/.remoot/fifo. You are free to use the provided clients
          or communicate directly with daemoot over the fifo. See the FAQ.

        - Added or improved support for many apps:

          moc
          mpd (and presumably all its clients)
          quark
          beep media player
          pytone
          gmusicbrowser
          xmms2 (and presumably all its clients), yes we can toggle play/pause
          smplayer (prev/next seeks +/- its "middle" skip interval)

          mplayer now seeks +/- 20 seconds when next/prev is pressed

        - Important updates to Do the Right Thing. daemoot is now quite a bit
          smarter. We're closing in on a Singularity event here folks :-)

        - "Rewwwoot" is now distributed in a separate package.       


0.4     20070804 - Major updates to remoot
        ----------------------------------

        - Added support for mplayer, VLC, exaile, aqualung, audacious, kscd
          and listen.

        - Much improved handling of multiple running supported apps:

          ReMoot now tries to "Do the Right Thing"TM and will first check if
          any supported program is actively streaming media (playing) and only
          pass commands to those. If no such apps were found, it looks for
          paused ones and passes the command to those. Finally, if no paused
          programs were found either, it passes the command to all running and
          supported but stopped apps.

          Typical case: If you watch a movie on high volume in Kaffeine and
          your phone rings, you will press playpause to pause Kaffeine. In
          this new version your old forgotten backgrounded Amarok session
          will not start playing when this happens. Next time you press
          playpause it depends on the state you had put Amarok in: if Amarok
          was just paused, it and and your paused Kaffeine will start playing;
          if Amarok was really stopped, only Kaffeine will start. So you will
          need a little discipline, but play around with it and you'll get it
          eventually :-)

          The catch? This only works when your media contains audio ;-)

        - The license of remoot and remoot-remote was is now updated to the
          Perl Artistic License 2.0.

0.3.1.2 - Included Rewwwoot, the web interface written in Ruby! Thanks to
          Linus who forever now is doomed to maintain that chunk of code!

0.3.1.1 - Fixed a stupid bug that prevented the program to list supported
          programs.


==============================================================================
DO THE RIGHT THING ETC
==============================================================================


Do the Right Thing
------------------

ReMoot supports a lot of multimedia apps but assumes that you probably only
want to control one app at a time when you have more than one supported
running at the same time. To pull this off, the cunning "daemoot" daemon
watches your every move ;-)

Apart from keeping track on whether media apps are playing, paused or stopped,
(as in remoot version 0.4) the daemoot daemon introduced in version 0.9 goes
through some extra pain to make you forget it exists by trying really hard to
control only one app at a time - the one you mean. daemoot introduces
some additional important status concepts, inspired by real life :-)

* "domination", a dominating app always receives the argument the user
  specified, such as "play" or "next"; it has top priority no matter if it is
  playing, paused or stopped. A newly started app becomes dominant and
  removes the dominating status from the presently dominating app, if any. As
  long as there is a dominating app up and running, daemoot ignores the other
  apps. The dominating app remains so until it is closed or until daemoot
  notices that a non-dominating app is suddenly playing. This can only happen
  because you manually started playing the app without using daemoot. daemoot
  then assumes that it is now the one you would like to continue to use and it
  now becomes the dominating app instead. When any argument is passed to a
  "freshly elevated" dominating app, all other playing apps, if any, are
  paused.

* "popularity" and "age", should it happen that daemoot finds itself having to
  control several apps at the sime time, it will pick one of them, first
  according to popularity - how many times you have accessed it since daemoot
  started - and if there are two equally popular running programs, secondly
  according to age - how long the program has been open relative to the other
  programs - where the older app wins. Should there still be more than one app
  with the same age, daemoot picks one of them according your local weather
  conditions. The selected app, if non-dominating, now becomes dominating.


==============================================================================
HINTS
==============================================================================


* If you want to have play and pause mapped to the same key, use
  "remoot playpause" for that key to get consistent behaviour across apps.


* Use ReMoot with your multimedia (or any) keyboard by using key bindings
  instead of typing the commands in a console.

  i)   The LinEAK way
       --------------

       LinEAK is a very nice program that provides a way to play, pause,
       increase / decrease volume etc via your multimedia keyboard. LinEAK
       can't handle calls to multiple players, but it provides a way to
       execute commands mapped to specific keys. This can be used with ReMoot

       Download LinEAK and Klineakconfig from your repositories or
       http://lineak.sourceforge.net/

       Start Klineakconfig and choose your keyboard "brand" and "type". Then
       fill in your "Key Mappings". For example: choose "Next" and under "Run
       Command" you write 'remoot next'.

  ii)  The Keytouch way
       ----------------

       Keytouch is an alternative method of getting your multimedia keyboard
       up and running and you can also map the keys to remoot using the
       application chooser.


  iii) The Fluxbox way
       ---------------

       You know what to do.


* Create aliases for those apps that need to be started with extra parameters
  to work with ReMoot (for instance, VLC and mplayer). You simply put lines
  like this:

  alias mplayer="mplayer -input file=~/.mplayer/fifo"
  alias vlc="vlc --extraintf http"
  alias xine="xine -n"

  in your .bashrc or .bash_profile file in you home directory. We never
  remember which one, and you wont either, so try any :-)


==============================================================================
LICENSE
==============================================================================


"remoot" and "remoot-remote" are licensed under the Perl Artistic License 2.0.
For details, please see:

http://www.perlfoundation.org/artistic_license_2_0
http://www.fsf.org/licensing/licenses/index_html#PerlLicense


==============================================================================
FAQ
==============================================================================


* OMG perl!? Why don't you use my favorite programming language instead?
  ----------------------------------------------------------------------

  $question = undef;


* What happened to versions 0.5 - 0.8?
  ------------------------------------

  We skipped those :-)

  ReMoot suddenly started to behave like what we expect from a 1.0 release
  after we switched to the daemon/client model so we jumped from 0.4 directly
  to 0.9.


* Why isn't my favorite program XYZ supported?
  -------------------------------------------

  Maybe we have checked it and it does not support any means of remote access,
  or it is too poorly documented. Maybe we have forgotten about it or not even
  heard of it. File a request to us in the latter case, and one to the
  developers in the former :-)


* How can I control ReMoot on my machine from some other device?
  --------------------------------------------------------------

  We recommend you to try "Rewwwoot", which is a web interface that turns your
  gadgets like Palm pilots or the Nokia N800 into a remote for your multimedia
  apps using any web browser. This package is maintained by Linus Berglund
  downloadable from the ReMoot sourceforge page as well and distributed under
  a BSD-license. See that program for more details.


* Why on earth do so many GTK apps lack a proper stop button?
  -----------------------------------------------------------

  We have no idea. Seriously.


* Why doesn't xine work?
  ----------------------

  You need to start xine with the "network remote control server" by running
  it like this:

  xine -n

  You also need to have a password file saved as ~/.xine/passwd containing
  a line with something like this (look that up in the xine documentation,
  you may not want to have it that way):

  ALL:ALLOW


* Why doesn't mplayer work?
  -------------------------

  If one does not already exist, the daemoot daemon creates a fifo file in
  mplayer's directory that it uses to communicate with mplayer. You need to
  start mplayer with an extra option, like this:

  mplayer -input file=~/.mplayer/fifo


* Nooo! VLC doesn't work!?
  ------------------------

  Cool down kid! Santa has a very special gift your you. ReMoot 0.4 supports
  VLC control if VLC was started with the extra http web interface:

  vlc --extraintf http

  ReMoot then connects with wget to port 8080 (the default port for VLC) to
  control VLC. Because "pause" can not unpause a "stopped" VLC session (it is
  not a true play/pause toggle, but an pause/unpause toggle) we have mapped
  VLCs "stop" to "pause" instead.


* XMMS keeps opening new instances instead of executing commands. What gives?
  ---------------------------------------------------------------------------

  Unselect "Allow multiple instances" in Options->Preferences->Options


* Noatun also opens new instances. Huh?
  -------------------------------------

  In Noatun, go to Settings-> Configure Noatun... and check "Allow only
  one instance of Noatun".


* Aha! "Do the Right Thing" doesn't work correctly with Totem!
  ------------------------------------------------------------

  When you playpause Totem it unloads itself completely from alsa and ReMoot
  thinks you have really stopped it.

  This unloading behaviour is true for Amarok as well, but here we can use
  dcop to check the real state of the player and still do the right thing.


* And what about Kaffeine?
  ------------------------

  If you use play-pause you can not start a stopped Kaffeine, because the dcop
  signal only toggles between play (if paused) and pause (if playing). You
  need to use "remoot play" instead, so avoid stopping Kaffeine if this is not
  comfortable.


* And SMPlayer?
  -------------

  You need to start SMPlayers telnet interface. To do this, you go to
  Preferences->Interface and check "Use only one running instance of SMPlayer"
  . Then you select the local port to use. If you stick with the default port,
  thats all you need to do. Otherwise you need to specify the same port when
  you start daemoot by using the "-smp" switch.


* Why is the smplayer interface over daemoot so unresponsive?
  -----------------------------------------------------------

  Long story. smplayer uses telnet for remote access and basically we seem to
  have an input dispatch problem over telnet that may cause smplayer to not
  perform its action at all, or that it or daemoot or even X can crash,
  probably due to this unpredictable input buffering or queuing problem.
  We do not know if this is a daemoot/perl problem or an smplayer/telnet
  problem at this point. Unfortunately implementing a perfect "autoflushing"
  telnet client in perl without extra dependencies is surprisingly difficult.
  However, we have found that the most consistently working remedy (or work-
  around, really) is to have daemoot wait for a second after it has passed the
  argument to smplayer over the telnet session and then close the session,
  whereas the ideal case is of course to not add this pause and be able to
  keep the telnet connection open as long as the particular instance of
  smplayer is running. Our solution seems stable but will make daemoot wait a
  second before listening for input again when you use smplayer. Should you
  experience crashes, contact us! Fixes are deeply appreciated!!


* ReMoot is a little slowish, no?
  -------------------------------

  That probably has more to do with the response time, command and played
  medium of the particular program that is called. Passing playpause to xmms
  playing an OGG-file only takes a few hundreds of a second, whereas playpause
  on a remote stream in amarok may need anything up to 0.7s or more.


* OMG WTF!!! Nooo!! I'll kill you guys!!! Where do you live?
  ----------------------------------------------------------

  Please remember that the code should be considered highly experimental. Do
  not run it as root or on production systems or any systems with sensitive
  and important data, at least not before you have inspected the code and
  confirmed that it is ok. Disclaimer: you are responsible for any data loss
  caused by running this experimental program!


==============================================================
Copyright © 2007 Andreas Wallberg <andreas.wallberg@gmail.com>
