
                    XNSCast v0.4.1 by Tusse/nonSense (c) 2003
                        a Shoutcast to XNS stream relayer
                                   Be inspired!


Licence
You may do with XNSCast as you wish, but any derivative work *must* recognize 
Tusse/nonSense as the original author. If you reimplement this concept in a 
different programming language than perl, some credit would be nice, but it is 
not required. If you base something on this code that you plan to sell for 
money (you must be mad), I expect to be getting a free copy somehow.


Requirements
1. A decent PC
2. An internet connection
3. A recent build of XBMP (XNSCast was tested only with the 29-Jan CVS-build)
4. A recent build of XBMP (I used xbmp2_cvs_compile_xbins_1-29-03.zip)


Recommended
1. Activestate Perl v5.8.0 - get it here:
   http://www.activestate.com/Products/Download/Download.plex?id=ActivePerl


History
v0.4   - Initial release
v0.4.1 - Small workaround for to make it work on even newer XBMP versions


About
XNSCast is an experimental Shoutcast/Icecast stream relayer for use with XBMP. 
It works by presenting fake files to XBMP, and when these files are requested, a 
connection to a Shoutcast/Icecast-server is made, and data from the 
Shoutcast/Icecast stream is relayed to XBMP, imitating regular Relax behaviour.

Please note that XNSCast is mostly a nasty perl kludge, and there's a big chance 
that it won't work for you, although it has been streaming hours of content
pretty nicely for me by now. Because of the rather lacking protocol
specification, I had to do some packet sniffing in order to find out what was
really going on at times. A consequence of not knowing exactly how ths protocol
is, is that this implementation might break with future upgrades to XBMP. The
intention of this is mostly to get some working concept code "out there" to
push those who implement real XNS servers to get working on stream relaying, I 
sure don't expect (hope) this little hack will be around for too long :-)

Also note that XNSCast was developed on Win32. I have no idea wether or not this 
works with Linux (shouldn't be too hard making it work, though). I also do not
know if it works with ogg-streams, as I have only tested with mp3.


Quick Setup guide
1. Get and install perl - default options should be good. You may skip this
   part if you plan on using the "compiled" version (easiest for most people).

2. Configure XBMP (config.xml)

You need to add a section under Music that looks like this (the ip probably 
needs changing)

    <music>
    ...
      <share>
        <name>XNSCast</name>
        <url>$ROOT$XNSCast@192.168.0.1</url>
      </share>
    ...
    </music>

You should also tweak the xnsbuffer down to 256kb, which matches the default
buffer settings for XNSCast. The xnsbuffer setting is near the bottom of the
XBMP configuration file.

    <xnsbuffer>256</xnsbuffer>

It is *strongly* recommended to set xnsbuffer to 256, however, you can keep
this setting at 1024 like it is shipped with XBMP, but then you will have to
change the cachedrop and cachemax settings to match this (refer to
xnscast.ini for more info) i.e prebuffer=1048576, cachedrop=1048576 and
cachemax=1310720, but this is not recommended as it will consume a lot of
RAM and CPU. If you want something in between, try setting xnsbuffer to 512
in XBMP, and then prebuffer=524288, cachedrop=524288 and cachemax=655360. At
this setting, CPU use will be a little lower, but still huge.


2. Configure XNSCast
xnscast.ini has several parameters that you could use to tune it to suit your 
setup. Refer to the file itself for further explanation and hints. If you 
have problems getting XNSCast to work properly for you, you definately want
to have a look in this file.


3. Add some Shoutcast/Icecast streams
Below the streams directory, you will find a bunch of .ini files. These each 
represent a shoutcast stream. I've included streams for somafm.com, but here's 
how to build your own.

   a. Get the stream playlist (Try your browser's "Save As.."
   b. Look inside it (with notepad or some other editor) - you'll see something 
      like this:

[playlist]
numberofentries=2
File1=http://blender.somafm.com:9000
Title1=SomaFM Presents: Beat Blender 128k (Feed #1)
Length1=-1
File2=http://server2.somafm.com:8900
Title2=SomaFM Presents: Beat Blender 128k (Feed #2)
Length2=-1
Version=2

   c. Transform that info into this:

[stream]
host=blender.somafm.com
port=9000
file=/

   d. Save your file below the streams catalog in the XNSCast directory. Don't 
     forget to put .mp3.ini or .ogg.ini as the file extension (depending on
     stream format) - if you leave out .mp3 or .ogg, the station won't show up
     when you're browsing for your stations in XBMP.
 
   
4. Make sure "Display ID3 tags" in XBMP is DISABLED.


Run XNSCast
1. Make sure Relax, or anything else using port 1400, is NOT running. As far
   as I know, there is no way to specify what port XBMP should listen to. If
   this changes, you will be able to run XNSCast and Relax along side each
   other by specifying a different port for XNSCast in xnscast.ini and
   and set up XBMP accordingly.
2. Run xnscast.exe (for the "compiled" version - does not require ActivePerl)
 -or-
3. Run the .bat file (requires ActivePerl v5.8.0 or equivalent)


Listening to Shoutcast/Icecast streams
1. Navigate the XNSCast share under Music as you usually do with Relax-shares
2. Open the file that corresponds to the stream you want to listen to
3. Wait for the prebuffering to finish (might take a few seconds, depending
   on the stream quality. 128kbps will generally buffer up faster than
   streams with lower bitrate).
4. Enjoy (or tweak the code/ini-file untill you do :-)

   Note: Not all the somafm-streams seem to be reliable. I've been testing
   this mosly using the 128kbps and 24kbps Beat Blender stream, which seems
   to be accessible most of the time (and ok to listen to aswell :)


Stop XNSCast
1. Press CTRL-C while the dos-box XNSCast is running in is active and press
   "Y" at the question about ending the batch job if you get one.
 -or-
2. Kill the "xnscast.exe" process in the Windows Task Manager
 -or-
2. Kill the "perl.exe" process in the Windows Task Manager (if are not using
   the "compiled" version)


Known problems
1. XNSCast may eat *a lot* of CPU time. This is mostly because of the crappy
   caching method, and the way I pull data from the shoutcast stream. Ususally
   it will use plenty of CPU while filling the cache, and then settle down for
   a while untill some data gets dumped out of the buffer to leave room for
   more data from the shoutcast stream. This problem is largely nonexistant
   when microsleep is enabled (see xnscast.ini) as it is as default.
2. XNSCast does not function correctly when XBMP is configured to use ID3-tags
   for display.
3. If you run out of Shoutcast buffer, XNSCast *might* need a restart.
4. The buffering system and its management is pretty braindead, and might
   introduce some stream errors and hickups every now and then ( though, not at
   all often ).
5. If XNSCast is unable to fetch stream data it might throw some funky
   errors on screen about missing data in the buffer and will often sometimes
   need a restart.
6. XNSCast doesn't always work properly when stopping and restaring a stream
   or restaring a new stream.
7. Pausing, rewind and fast forward does not work (its a stream after all)
8. Using XNSCast to relay a Shoutcast stream being produced on the same
   computer might give you problems, because of XNSCast's tendency to use a lot
   of CPU time, atleast in bursts. Give it a shot, though, your milage may vary
   (and my PC is no powerhouse! :)
9. If the exe doesn't work for you, give the pure perl version a shot. XNSCast
   was developed with ActiveState Perl v5.8.0 and although the exe has been 
   tested and seems to work pretty nicely, the compiler is still in beta stage.


Contact
This program has no official homepage. I might be lurking on xboxmediaplayer.de
forums, and I might hang around in #xboxstuff.no @ efnet or #lostatlantis @
undernet as Tusse if you need to get in touch...


Aknowledgements
XBMP Team - for the truly excellent media player
beardballz - for the protocol spec (kind of ;)
Relax Team - for giving me something to sniff while trying to filling in the
             protocol holes :)
Taxi - for providing a tcp/ip sniffer
CISC - for help with Shoutcast and some general perl issuse
Whooper - for testing and taunting
#xboxstuff.no - for everlasting entertainment
