This is MP3::Napster, a pure-Perl interface to the Napster MP3 file
search and distribution servers (www.napster.com).  With this module,
you can connect to Napster servers, participate in online chat
channels, search the Napster virtual library of MP3 sound files, and
exchanged selected MP3s with other users.

PREREQUISITES
-------------

Prerequisites are:

	Digest::MD5
	MPEG::MP3Info

You can find these modules on CPAN.  For your convenience, you may
install them all with the Bundle::MP3 module, which also installs Doug
MacEachern's Xmms modules.

In order to play songs directly from the napster.pl example front end, 
you must install the command-line MPEG-decoder mpg123 (or adapt the
front end to use a different player).  mpg123 can be downloaded from:

  http://ftp.tu-clausthal.de/pub/unix/audio/mpg123

In order to use the tknapster PerlTk front end, you must have PerlTK
version 8.00 or higher installed.

INSTALATION
-----------

To install:

	% perl Makefile.PL
	% make
	% make test  # may not work on windows systems
	% make install UNINST=1

If "make test" fails, run "make test TEST_VERBOSE=1" and send the
output to me, along with the output of perl -V.  The UNINST=1 option
unlinks older versions of this module before installing the new one,
which is generally a good idea.

"make test" hasn't been tested on Windows systems and may not work.
It takes advantage of forking and Perl pipes, which are iffy on
non-Unix systems.  Even though some tests fail, the module may still
work.

STABILITY
---------

This module was originally written to use Perl threads, but the thread
API changed considerably between 5.005 and 5.6, and is expected to
change even more before Perl 6.0.  So starting with version 2.0, I
rewrote the module to use non-blocking I/O instead.  This should make
it much more stable than before!

However, because much of the code was rewritten to accomodate this
change, there may be bugs lurking.  Please send bug reports to me at
the e-mail listed below.

DOCUMENTATION
-------------

The documentation is in POD format.  To read:

	% perldoc MP3::Napster
	% perldoc MP3::Napster::User
	% perldoc MP3::Napster::Channel
	% perldoc MP3::Napster::Song

Additional documentation on the Napster protocol can be found in the
file "napster.txt" that accompanies this distribution.

APPLICATIONS
------------

A few test applications come with this module.

napster.pl
----------

This distribution includes an interactive line-oriented Napster client
named napster.pl.  It will be installed into your scripts directory
during make install.  You can get brief usage instructions by typing:

	% napster.pl -h

A typical connection will look like this:

        % napster.pl -l 56K -p 6699 -d ~/mp3s

Here you are specifying a link speed of 56K, an upload port of 6699,
and a download directory of ~/mp3s.  This is all customizable, and has
reasonable defaults.

You will then be greeted with a login and password prompt:

       [connecting...]
       login: (type your nickname here)
       password: *********

If you authenticate correctly, you will see the message of the day.
Now type "/help" to get a list of the commands you can issue to view
and join channels, send public and private messages, search for files, 
and initiate downloads.

To register as a new user, run napster.pl with the -r flag.  It will
prompt you for a nickname and a new password.

An annoying problem with the napster.pl client is that output from
chatty users can mix in with your commands as you are typing them.  I
run the client in an Emacs shell to avoid this problem.  The client
was developed mainly as a debugging tool and not as a full-fledged
application.  Someone should really write a nice curses or Perl-Tk
front end to this.


tknapster.pl
------------

This is an incomplete Napster browser based on PerlTk version 8.00.  I
used it to test whether the Tk interfaces are working.  The
application can search for songs and participate in channel
discussions, but cannot currently download or upload (this is coming).

It should be easy to use.  After launching the application select
File->Login.  Select the server to connect to, and type in your user
name.  After a short delay, a Channels menu will appear.  Select the
channel(s) you are interested in joining.  

A scrolling list of users in the current channel occupies the right
side of the main window.  Try double-clicking or right-clicking on a
user name either in the list, or in the main discussion area.

Search using the Search menu.

tknapster.pl has not been tested on Windows platforms.  It might work,
it might not.


simple_download.pl
------------------

You will find this script in the eg/ subdirectory of this
distribution.  It illustrates how to write a batch script to search
for some songs and download them, printing status messages as the
download proceeds.  It is hard-coded to search for Beatles songs, but
you can easily modify it to make it into a more general utility.


miniserver.pl
-------------

This is a pure-Perl Napster server.  It is very limited compared to
the real Napster server, since it keeps everything in memory and
doesn't remember users from launch to launch.  Nevertheless, it
implements most of the core Napster functionality, including chat,
channels, private messages, and file transfer.

I wrote it to support the regression tests.  Someone might want to
make it into a real server by adding a persistent database backend.

HELP
----

First ask for help in the Usenet newsgroup comp.lang.perl.modules.  If
you get no help after a few days, feel free to contact me.

Lincoln D. Stein
lstein@cshl.org