*
*  byRequest; a TiVo HMO server for Linux and other compatible systems.
*
*  Version 0.50; Dave Clemans, 4/2004
*

The big new feature is support for the XM PCR computer controlled satellite
radio.  From the TiVO, you can browse through the "categories" or "genres"
on XM radio; browse through the channels in each category, and select a
channel to play.

Other than that, this version works much cleaner with TiVo's using later
versions of the HMO code; e.g. the Pioneer 810H TiVo / DVD recorder.

Some notes....

   XM PCR Support....
      First make sure the XM PCR radio is working, correctly activated,
      etc. using either the official XM software, or a third party
      alternative.  An example is OpenXM (www.openxm.com), which runs on
      Linux.

      Make sure you know which dsp sound device (/dev/dsp and /dev/dsp1
      are examples) is picking up the sound card input from the XM PCR,
      AND that you can successfully record from it.  You might want to use
      the audio conversion tool (sox) to try recording a short .wav file
      of one channel.

      Note that the byRequest server will use sox to get the stream from
      the XM PCR transcoded for the TiVo; so it must be installed.  You also
      need the "lame" mpeg encoder.

      You can use a usb sound card (assuming the sound card is supported by
      Linux) to pick up the audio from the XM PCR, rather than on the sound
      card in your computer.

         For reference, I'm using my XM PCR with a Creative Extigy USB
         sound card I had lying around.  I use the "exaudio" driver for the
         extigy from the SourceForge extigy project.

      Then, in your byRequest.conf file, add the line
         xmpcr: /dev/ttyUSB0 /dev/dsp1
      or something similar.  The first filename is the usb serial device
      that controls the XM PCR.  The second filename is the sound dsp device
      that picks up the incoming audio stream from the XM PCR.

      When you start byRequest, there will be a 10-20 second wait while it's
      picking up channel information from the XM PCR.  That might become a
      separate thread eventually, but for now it's helpful in making sure
      everything starts off correctly.

      Bugs / TODO......

      There's no way I know of to have the TiVo actually display the current
      song & artist from the XM radio channel being played.  That'll likely
      need TiVo to update their software.

      In theory I could display what's currently playing while you're 
      browing through the XM categories & channels, but a few more things 
      need to be worked out first.  (Basically, I have to be able to tell
      the difference between a TiVo information request for a directory
      display, and one for the currently playing box.  That's probably
      doable, but needs more thought.).

      I've seen a few cases where the XM PCR locks up and stops responding
      to input from the usb port.  That doesn't just affect byRequest; it
      also affects other XM PCR drivers.  In that case you have to power
      cycle the XM PCR by detaching the usb cord for a few seconds.

      The source code currently defaults to directly controlling the XM PCR.
      There's a #define in xmradio.c (USE_XMDAEMON) to instead use the
      XMDaemon tool from the OpenXM software package.

      If you have multiple TiVo's on your home network with HMO support,
      the XM PCR can only play on one (since it only provides a single
      stream).

      Unless you want the currently selected XM channel to also play on
      your computers speakers; mute them; or set mixers so that the dsp
      device can pick up the stream without also sending it to the speakers,
      or use a second sound card (or usb sound card) that isn't connected
      to speakers.

   I've tweaked how byRequest handles the TiVo beacon protocol to make it work
   more reliably with the newer Series 2 TiVo's, like the Pioneer 810H.

   I've tweaked how byRequest does url encoding to make it possible to play
   internet radio streams on newer Series 2 TiVo's, like the Pioneer 810H.
   This means that some path's that didn't have to be encoded before now are,
   and that there are double or triple encodings in some places;  if you look
   at the source code there are many more places where paths have to be 
   decoded.  I think I've found all of the places in the code that now have
   to decode pathnames; but if you see a bug causing something that used to
   work to no longer work, that's a likely suspect.  A side-benefit is that
   the old problem with '&' characters should now be GONE!!!!!

      Note: this change also aids XM radio support, as one of their
      category names has an '&' character in it.

   Also to help supporting internet radio streams on the Pioneer 810H, I've
   now got a first cut implementation of the QueryItem command in the HMO
   protocol.  The current TiVo documentation lists QueryItem as a "not 
   implemented now; probably will be implemented later" command, and the
   standalone TiVo branded Series 2 systems don't issue it.  But Pioneer 810H
   systems do issue QueryItem, when playing internet radio streams.

   I changed the bit rates used for "lame" mpeg transcoding from lame's
   default (which could be as little as 8), to 64 for internet radio streams,
   and 192 for XM radio streams.

   There were comments in the past that byRequest really should use socket
   2190 only for the TiVo beacon protocol; that it should advertise a different
   socket for data.  There's now a way to do that; add a "port: <portnum>"
   line to the byRequest.conf configuration file.  I'm now using that in my
   default home environment.

   And there are a few minor bug fixes, attempts to prevent process threads
   from hanging if an internet connection stops providing data but doesn't
   close, etc.

FUTURE WORK!

   If you have a photo directory that contains something that isn't a 
   photo (like a tar file of other photos), and subdirectories of other
   photos, the TiVo will generate an error if you try to browse to the
   subdirectories.  It's being confused by an item count; e.g. it's given
   the total number of entries in the directory, but only given descriptions
   for photos or subdirectories.  This should be fixed.

   Update the byRequest man page.  Do some better documentation to make it
   easier for beginners to install byRequest.  Add support for common
   Linux packaging formats (rpm, gentoo, debian, etc.).

   Add some way of showing current satellite & terrestrial signal strength;
   bit error rate, etc.... maybe as part of the description shown for the
   preview channel?

   Have some way of showing the current artist&song for XM PCR channels;
   probably just in the TiVo directory display.  Unless there's an update
   to the HMO protocol, I don't think there's a way to display that info
   in the now playing box (Basically, once the TiVo gets the info to put
   in the now playing box, there's no way to change it.  So in theory it
   could get the current info when you first go to the channel.  But that
   info will be wrong in a few minutes...)

   Give better descriptions for internet radio stations; probably by picking
   up metadata from the playlist files.

   For better network usage in a multi-TiVo home network; if multiple TiVo's
   are listening to the same internet radio stream, they should share the
   internet connection & transcoding processes.

   Similarly, in a multi-TiVo home network, if multiple TiVo's want to listen
   to the same XM Radio channel, they should share the audio stream &
   transcoding processes.  Use the current locking scheme (e.g., lock an
   inuse XM PCR to the TiVo that's accessing it) only if different
   channels are selected.

   If people want multiple XM PCR streams in a home network, you need 
   multiple XM PCR radios.  You can do that now, but you'd need separate
   sound card connections & run multiple copies of byRequest.  That should
   be easier; e.g. let byRequest control multiple XM PCR's.

   Test support for RealAudio format internet streams, files, etc. with
   the released files from the Helix DNA project, instead of just the early
   developers version of "splay" that I'm using now.  And if Real preserved
   the "automatic" functionality from splay in the current product release,
   maybe even use that?  (Helix DNA is the name of the "partial" open source
   effort from Real).

   If Sirius has a computer controllable receiver, maybe add a way to
   control it?????

   Maybe even add support for "normal" computer controllable am/fm receivers,
   assuming we have a way to know what stations are available....

   Keep track of what songs/streams are played, to build up a "favorites"
   list.  Have some way to display the "favorites" list (another virtual
   directory?).

   Some graphical way of building & verifying a byRequest.conf configuration
   file.  If I had that feature, I'd declare a "1.0" release...

   Maybe even add support for other media server hardware....
      the Linksys box
      the Netgear box
      the Hauppauge MediaMVP
      the SLim devices "SqueezeBox"
      etc.
   ????????????

   Maybe redo the virtual sub-directory support (e.g. accessing music by
   genre or by artist) more cleanly.  Instead of the X_VFOLDER url parameter
   kludge, declare a reserved toplevel namespace; similar to what I'm using
   for XM radio support.  That would make adding other virtual directory
   types easier.

   Suggestions?

Thanks,
dgc
