       _             __
  ____(_)__ _______ / /____ ____
 / __/ (_-</ __(_-</ __/ -_) __/
/_/ /_/___/\__/___/\__/\__/_/   
                              v1.20

About
=====

Riscster is a RISC OS compatible client for Napster, the online mp3 music
community. The Napster community allows users to share mp3's directly, with
the Napster server providing search and chat facilities. 

It was based on gnap, a GPLed Linux client, although there isn't much gnap
code left since gnap 'disagreed' with the co-operative multitasking of 
RISC OS. It was started and mostly done over the Easter holidays before
A-Levels, and probably shouldn't have been.

Riscster is available from <http://riscster.iconbar.com>.

Riscster is FREE SOFTWARE.

Support
=======

Riscster currently supports a subset of the Napster protocol which provides
the basic functionality of logging in and downloading from other users.

Riscster is actively developed, with new versions becoming available every
few months (or even weeks/days!) depending on the amount of time I have to
spend on it.  New versions usually include bug fixes and add new features.
New versions tend to come in 'waves'.  The best way to find out about new
versions is to join the mailing list (see 'help' below).  I often notify
ANS, drobe and The Iconbar when a new version offers a significant improvement.


Bugs
====

Yes.  Riscster is an unfinished piece of software!

If you discover any then please either

 - Download the source and fix what you can 
 - Tell me about them

Various people have been very kind in giving up time to beta test this
software, but unfortunately it is unlikely that every possible situation has
been tested, with the Internet being the unpredictable and complex monster
that it is.

Help
====

If you have any problems, feel free to email me (robert.dimond@ic.ac.uk) and
I'll almost always remember to reply.  I have also set up a smartgroup at
http://www.smartgroups.tv/groups/riscster which you can sign up to and post
messages.  Loads of Riscster users are signed up, myself included, so if you're
thinking about emailing me about Riscster it might be worth emailing the whole
group... you could get a faster response.
It seems that most RISC OS browsers have problems with the Smartgroups site... so
let me know if you can't sign up and I'll do it for you.
All messages posted are publicly readable, and there is no restriction on joining 
so the smartgroups site is the most sensible first port of call if you are having
problems.

Test versions
=============

There are normally three versions of Riscster available:

Stable
This is where a horse lives, but it is also a version of Riscster which
has been tested enough for me to consider it working and free from glaring
bugs.

Beta (on the website)
I will normally upload beta versions to the website if they are reasonably
stable and if they add features which may be particularly useful.  Another
reason for uploading a beta to the website is if the Napster system changes
in a way that breaks the stable version (this will happen from time to time
since there is no official Napster protocol documentation).

Beta (on the mailing list)
These versions are made available to people on the mailing list (see 'help' above)
they are 'hot off the press' and hence may not even be in a usable state.
You may want to download these if you want to help me with debugging.  I really
appreciate bug reports and comments... however small/insignificant you might think
they are.

At the moment I am updating the binary distributions more frequently than the
source and so the source on the website is often outdated.  If you would like
the latest source then please drop me an email and I'll email it back or make
it available on the website.


Requirements
============

RISC OS 3.1 or better. RISC OS 4 is recommended for use of long file names,
but raFS is just as effective.

You will require a StrongARM CPU for playing MP3 files in real time.

An Acorn compatible TCP/IP stack:

 - Acorn's Internet module
 - FreeNet by Tom Hughes
 
Almost all commercial Internet products (DialUp, Voyager, the ANT Suite)
qualify barring Termite. If you're still using Termite Internet, consider 
replacing it!
 
Basic Instructions
==================

Install by dragging both !Riscster and !MP3's to a convenient place. 

!MP3's must be seen and in a read/write partition. 

I'd recommend putting it somewhere where long filenames are supported,
like an E+ formatted partition, or an raFS disc.

Double click !Riscster and click menu over the iconbar icon. Select console
to bring up the console if you wish to see exactly what Riscster is doing,
then select Connect and fill in the relevant details to create a new account.

Click 'Connect' and then wait until the message of the day appears in the
console and the search and disconnect options are ungreyed on the menu. 

If the server is busy the login process may take a while. If everything seems
to lock up then you can try disconnecting and reconnecting.

To search for an MP3, enter the relevant details into the search window, and
click the 'Search' button. Set the maximum results to about 10, which should
be plenty.

Choose an MP3 from the list which appears below and click Menu over the most
suitable, then click download in this window.

Hopefully after a short while, the progress bar should begin to climb. 
You can download up to 20 files concurrently. 

You can also download from users who are behind firewalls.

A StrongHelp manual is now available from the website which supersedes these instructions.

Playing
=======

To take full advantage of the MP3 format, you need to be able to
play in real time so as to keep your files compressed.

If you don't have an ARM7M (not fitted to any RISC OS machine at present) or
a StrongARM, then you will need to convert the MP3 files you download to PCM format to play them with something like PlaySound.

'dmpa' allows both real-time decoding for StrongARM users and decoding to
file. 'AudioMPEG', written by Peter Teichmann, is of better quality than dmpa
and does not run in a TaskWindow, making it the better choice if you have a
StrongARM CPU.

Undoubtedly the best choice is AMPlayer, by Thomas Olsson, for StrongARM or
ARM7M-based computers.

It may also be possible to use a fast (100MHz+) PC card plus Acorn's SB16
drivers for Windows to play your MP3 files in real time.  MPXPLAY, a DOS
based player can be made to work, although the quality isn't really bearable.
MPXPLAY on a 5x86 100 card can decompress an MP3 to disc significantly faster
than dmpa on an ARM710 however.

Something similar to FPEPC or RC5 for the PC card could also be developed,
to decode the MPEG frames to PCM using the PC card's processor running a
small microkernel (is there such thing as a big one?  Ah yes... Windows NT), 
and play those through the sound system, but those people
that have fast PC cards often have StrongARM processors too.

If you want to compress your own MP3's (for when sharing is implemented) then
(in the authors very humble opinion) the best choice is the Shine port by
Pete Everett available from <http://www.everett9981.freeserve.co.uk>.  It's not quite
so sophisticated as some of the other encoders (Blade for example) but it's
incredibly quick; a three minute track takes about 5 minutes on a StrongARM.

If you want to compress an MP3 direct from a CD:

Download the excellent AudioFS from <http://www.xlcus.co.uk>.
Try something like:

shine -b 160 -r audiofs::0.$.0  My_Non_Copyright_Track


Compiling
=========

At the time of writing I use: 

Archimedes GNU make 1.02 
GCC 2.96 (prerelease 2) 
!Clib 1.03 
!Netlib 
!OSLib 6.2

Porting
=======

proto.c should be fairly portable, if you replace the socket SWI calls with
the relevant calls for your operating system. 

Lots of Napster client sources are available under the GPL, but Riscster may
have a few advantages for people porting to non UNIX platforms.  That said... if
you want to make your own Napster client, there are better starting points than
Riscster ;-).

Current TODO list
=================

Support 206 errors.
Support whois (603).
Implement file sharing.
Better error handling.
Fall over nicely when no TCP/IP stack is running.
Sorting of search window.
Better handling of private messages.

Not supported (yet)
=============

Sharing (i.e. uploading).  You can only download ATM.

Credits
=======

Coding, templates, general:
Rob Dimond (Drobe Software)

Fixes, features, updates to this file (for version 1.16+):
James MacDonald

Sorting code (and some more help/suggestions):
Neil Walker

Testing:
Chris Egan 

Thanks:
Friendly people on <comp.sys.acorn.programmer>, notably Mr. David Ruck.

The numerous unofficial documenters of the Napster protocol: 
DrScholl 
Ben Byer
JT
Evan Martin
Colten Edwards

Ryan Dahl (author of gnap).
Colin Plumb (author of MD5 code used).
Josh Guilfoyle (author of gnapster). 
Nick Burrett (porter of GCC to RISC OS).

People who have sent me bug reports and fixes:
Chris Egan
Michael Barnes
PaulBell
Chris Morison
David Bryan
Ross Maltby
Dave Stubbs

Thanks are also due to people who link to the Riscster website:

iconbar.com
opennap.sourceforge.net
drobe.co.uk
riscos.net
riscos.org

and my good friends....
www.sublimex.co.uk
www.doc.ic.ac.uk/~nm300e

And many others...

No thanks to:
=============

Plusnet Ltd. (the most underhand and untrustworthy ISP I have had the displeasure
of dealing with... for gods sake do not give these pirates your credit card details!).
Microsoft Corporation... goes without saying.
Acorn... for vanishing :-(


Disclaimer
==========
Napster Inc's official message is, at the time of release:

PLEASE NOTE: Napster, Inc. makes no representations or warranties regarding
MP3 files possessed by Napster users. Thousands of MP3 files have been
authorised for distribution over the Internet by copyright owners; however,
Napster users should understand that MP3 files may have been created without
copyright owner authorisation. Neither the MP3 file format not the Napster
software indicates whether a particular MP3 file has been authorised for
copying or distribution. Copying or distributing unauthorised MP3 files may
violate United States and/or foreign copyright laws. Compliance with
copyright law remains your responsibility.

I similarly disclaim responsibility for whatever use this software is put to.

It is YOUR responsibility to ensure that you have a legal right to anything
that you download through Riscster.  
 
Note about sharing
==================

There is a slight possibility that bugs in the sharing
code could make any part of your hard drive and even the contents of your machines
RAM available to anyone on the internet.  The code is correct to the best
of my knowledge... but security is not guaranteed.  You have been warned!

Note about 32bit compatibility
==============================

It will be possible to compile a 32bit clean Riscster for when 32bit RISC OS is
available.

Licence
=======

Napster client for RISC OS Copyright (C) 2000 Robert Dimond

Portions are based on gnap by Ryan Dahl and public domain MD5 code is
included written by Colin Plumb.

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
details.

You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 59 Temple
Place - Suite 330, Boston, MA 02111-1307, USA

Robert Dimond, ISE Course, Imperial College, Department of Electrical &
Electronic Engineering, Exhibition Road, London. SW7 2BT.

robert.dimond@ic.ac.uk
<http://www.doc.ic.ac.uk/~rgd00e>

If you are unfamiliar with the GPL (full details in 'COPYING') then the
gist of it is that you can include Riscster on any CD or website and
otherwise distribute it as you wish.


Registering
===========

Riscster is GPL licenced so there is no need to register it, although you
may like to register anyway.
Registration costs 1050 in unmarked, non-sequential notes (sterling).
Registered users will receive a card every birthday together with a badge
and a novelty bonus item chosen from my shed.


