byRequest is "yet another TiVo HMO server", written for Linux systems.  It may
also be portable to other systems.  It was written from the TiVo developer
documentation, and isn't related to the TiVo Perl example code, or any
project based on that code.  To be different, it's written in C.

byRequest has handled large "playlists" effectively.  I have tried shuffle
play through ~2100 file, and ~2700 file directories.  With nothing in the
directory cache, those take 10 seconds or so to start playing.  With a fully
populated cache, those lists start almost immediately.

Note that this server is young; only a few weeks old.  Expect bugs.  If you're
interested in experimenting with it, the download url is at the end of this
message.  I would be interested in comments.

It implements the basic portions of the TiVo HMO protocol:

   the beacon discovery protocol; TiVo's should see this server automatically

   exporting ("publishing") audio and image files to the TiVo

   answering TiVo requests for audio MP3 streams.  MP3 id information is
   picked up using code merged into byRequest from the "mp3info" project.
   To my understanding, that code supports mp3 id3v1, and id3v1.1 
   metadata.  I don't think that id3v2 information is supported.

   answering TiVo requests for JPEG images of various sizes & rotations

   responding to the sorting and anchor parameters from the TiVo to allow
   the TiVo to step through a playlist, to implement "shuffle" play mode, etc.

Directory structures, and file MP3 metadata, is cached in memory.  Cache
structures are automatically updated as directories changes.

My experimentation, at least with my systems (Athlon XP 1800 Gentoo, and
Pentium III 633 Mandrake 9.0), has shown no need for on disk caches.

On top of these basic support, there are a number of "extended" features:

   A few playlist formats have limited support; basically all meta-information
   in playlist files is ignored.  The file formats that should work are
      m3u
      pls
      ram

   non-MP3 audio formats can be supported by decoding them on the server system,
   and re-encoding the data as an MP3 stream to send to the TiVo.  The "lame"
   mp3 encoder is used.

   Ogg Vorbis format "should" be supported, using "ogg123" as a decoder.
   ("should", as in I don't have any ogg files to test it with)

   The RealAudio player "splay" from Real's community development project,
   "Helix DNA" (www.helixcommunity.org), along with the LD_PRELOAD library
   /usr/lib/vsound/libvsound.so from the "vsound" project, can be used to
   decode RealAudio streams.

   The "mplayer" player can be used to decode any supported audio format.
   A complete enough installation of mplayer can play at least some
   Windows Media streams.

   MP3 internet radio streams can be played, if the URL goes directly to the
   MP3 stream (e.g., no redirection), and no extra authentication is needed.

   At least some RealAudio and Windows Media internet radio streams can be
   played (assuming appropriate installations of splay or mplayer).  I have
   tried some BBC wma streams (BBC World, BBC Radio 7), and some BBC
   RealAudio streams (BBC Radio 4).

   You can define virtual "views" of MP3 directory structures, that organize
   the files into virtual directories based on either artist names or
   genres.  Of course, the correctness of that is based on the correctness of
   the mp3id information in the mp3 files.

   If you a "Format=text/html" parameter, the server can communicate with
   web browsers.  If that web browser has the appropriate mime types, it
   can pick up the mp3, etc. streams for individual files.  An example url,
   (ignoring special character encoding) would be something like:

   http://hostname:2190/TiVoConnect?Command=QueryContainer&Container=/&Format=text/html

   That url would display a simple root directory listing of the files
   exported by the server.  Selecting a directory generates another page
   showing the contents of the directory.  Selecting a file sends the
   contents of the file.

You define the exported directory structures ("published files") using a
configuration file.  Every file of a supported type below an exported
directory is available to the client of the server.  There are some security
checks that try to prevent references to files outside of an exported 
directory structure.

A configuration file also defines exported file types, locations of special
non-standard files if present (splay and vsound), and the location of the
logfile.

Basically, after compiling the server, and creating a configuration file,
you start it by saying:

   byRequest <configuration file>

where <configuration file> is the pathname to the configuration file.

The server defaults to running in the background, disconnected from all
windows.  The "-debug" flag causes it to run in the foreground, and print
extra debugging information.

The server defaults to automatically filling its in-memory directory cache
as needed.  You can give the server the "-preload" flag on invocation;
that causes all information on all exported files to be first added to the
cache before the server starts listening to the network.  Note that if you
are exporting thousands of files, that can take a few minutes.

The configuration file is a simple textfile; blank lines and comments (lines
beginning with a '#' character) are ignored.  All other lines have the format
"keyword: value".  The example configuration file in the distribution,
"byRequest.conf", has an example for each configuration file keyword.

Other than the "special" tools "splay" and "vsound", all other executables
used by the server must be in its PATH when run.  This includes...

   ImageMagick (specifically it's "convert" executable)
      for image file conversion, resizing and rotation

   ogg123 (for Ogg Vorbis files)

   lame (for re-encoding non-mp3 audio streams)

   mplayer (for decoding non-mp3 audio streams)

   sox (used when splay and vsound decodes RealAudio files)

byRequest dynamically creates a separate thread for each audio or image
stream being sent to the client.  Currently, directory information is sent
using the main thread.

**********

byRequest can be downloaded from:

   http://www.easystreet.com/~dgc/byRequest-0.4.tar.gz

Unpack the tar file somewhere, check the Makefile, and build.  Currently
there is no autoconfig, etc. build system.

byRequest has been built on a Gentoo 1.4rc4, and a Mandrake 9.0 system.

byRequest doesn't have to be installed in any special location.  It doesn't
need any special permissions.
