Linux Napster Client: User Guide

Peter Selinger (selinger at theory.stanford.edu)

Created March 28, 2001. Updated April 23, 2001.


This document describes the linux napster client "nap". It covers basic installation, configuration, and usage, as well as some finer points.

1. Introduction

2. Author and copyright

3. Downloading and installation

4. Basic nap usage

5. More on searching and downloading

6. Messages, channels, and hotlists

7. Configuration and user variables

8. Advanced features

9. Summary of command line options

10. Summary of nap commands


1. Introduction

Nap is a a linux console napster client written by Kevin Sullivan. This user guide is an attempt to summarize some of the most important features, from a user's point of view. Additions and corrections are always welcome.

2. Author and copyright

This user guide can be freely copied, modified, and distributed under the GNU public license.

The nap software is copyrighted by Kevin Sullivan, under conditions set forth in the file COPYRIGHT.

3. Downloading and installation

The current release of nap is available from http://theory.stanford.edu/~selinger/nap. You can download nap in one of several formats. In the following, XXX stands for a version number.

3.1. Source distribution

This is the most complete distribution of nap, since it contains all the source code necessary to compile nap. On the other hand, this means you have to compile it yourself. This is not very difficult, but if nap is available in precompiled form for your platform, you might find that easier.

Instructions: download the file nap-XXX.tar.gz. The following sequence of commands should compile and install nap.

        tar -zxf nap-XXX.tar.gz
        cd nap-XXX
        ./configure
        make
        su
        (type root password)
	make install

3.2. Linux precompiled distribution

Instructions: download the file nap-linux-XXX.tar.gz. Install nap as follows:

        tar -zxf nap-linux-XXX.tar.gz
        cd nap-XXX
	su
	(type root password)
	cp nap /usr/local/bin/nap
	chmod 0755 /usr/local/bin/nap

3.3. RPM package

RPM is the Redhat Package Manager. It allows for easy installation of packages on Redhat Linux systems, and on other systems where it is available. Instructions: download the file nap-XXX.i386.rpm. As root, install nap with the single command

        rpm -ivh nap-XXX.i386.rpm

3.4. Debian package

A nap package is distributed with the next relase (2.3) of Debian. To install nap on a properly configured Debian system you should use the "apt-get" command:

        apt-get install nap
Alternatively you can download the latest nap_XXX.deb package from the Debian nap page and install it manually with the "dpkg" command:

        dpkg -i nap_XXX.deb
You must be root to do this. If you are not root, read point 3.7.

3.5. OpenBSD package

Instructions: download the file nap-XXX.tgz. Install it with the single command

        pkg_add nap-XXX.tgz
Note: this file is an OpenBSD Package, not a regular tar archive. It should be installed with "pkg_add". If you unpack it with "tar", do it in an empty directory, as it will spill some files into the current working directory. If you do unpack this as a tar file, you will find an executable binary in the "bin" subdirectory.

3.6. Other formats

Nap may be available in other formats, for instance in precompiled form for other operating systems. Something similar to the above instructions should work. Note that precompiled code for Windows is available at http://www.gis.net/~nite/ for an older version of nap.

3.7. "What if I don't have root privileges on my machine?"

Don't worry. It is not really necessary to install nap in /usr/local/bin; you can install it anywhere you like. All that is really necessary is that the nap binary is somewhere in your PATH. The recommended steps are as follows:

1. create a directory bin in your home directory, and move the file nap there.

        mkdir $HOME/bin
	mv nap $HOME/bin
2. If the shell you are using is sh or bash, put the following lines in the file .bashrc in your home directory:

        PATH=$PATH:$HOME/bin
	export PATH
If the shell you are using is tcsh, put the following line in the file .tcshrc in your home directory:

        set path = ($path $HOME/bin)
3. Restart the shell. You should now be able to invoke nap by typing nap.

4. Basic nap usage

This section gives a brief overview of the most important features of nap, particulary how to search and download files, and how to navigate nap's two screens. It should be enough to get you started. We will take a more detailed look at some of these features in the section that follows after this one.

4.1 Starting nap

Congratulations, you have installed nap, and you are ready to give it a try. Simply invoke nap by typing

        nap
You will be prompted for any necessary information, and you will be asked whether you want to save the information in a configuration file. It is a good idea to answer yes [y]. Eventually you will see nap's main screen, which looks more or less like this:


                                                             [nap v1.4.4-ps-2] 

     _.-------._
    |\          /|
   /| \_.----._/ |\                                  __
  .$:            :$.    _____  ____   _____  _____  / /__ ___   ____
 |$$:  ___  ___  :$$|  / __  // _  `// _   //  ___//  __// _ \ / ___/
  "$: \___\/___/ :$"  / / / // /_/ // /_/ /(__   )/  /_ /  __// /
    |     __     |   /_/ /_/ \__,_// ____//_____/ \___/ \___//_/mG!
    `.    \/    .'                /_/
      `. .__, .'
        `----'

* This is the main screen of nap.
*
* In this space, you will usually see some welcome messages from your 
* Napster server.
*
* In the upper right corner, you see the version number of nap.
* The blue line below is called the status line.
* It displays the user name, and some other information. In the right part
* of the status line, you see the number of current uploads, downloads,
* and queued downloads.
 [username] [474042 songs in 8066 libraries (1954 gigs)]         [U/0 D/0 Q/0] 

The very last line, after the status line, has a cursor. This is where you can enter commands. All commands start with a slash "/"; if you forget the slash, nap will complain that you are "not on a channel". But more about that later.

4.2. Simple searches and downloads

To perform a search, you use the /search command. For instance, if you want to search for a song called "Yucky green goo", you type

        /search yucky
This will cause nap to search for files that contain the word "Yucky". Napster queries are case insensitive, so it doesn't matter if you search for "yucky" or "Yucky". If fact, napster is generally very tolerant regarding search queries.

After a few moments, another screen will pop up with the search results. This is called the result screen. It might look as follows:


Filename (total = 14)                    | BRate       | Length       | Conn
-----------------------------------------|-------------|--------------|---------
1) Bobby Bones - Yucky.mp3               | 64          | 3:24         | T3
2) HOT 5- [07]Time Will Tell.mp3         | 128         | 2:12         | T3  
3) WB theme songs - Jack and Jill .mp3   | 128         | 3:00         | Cable
4) Korean Rap-YG family - 1tym attack.mp | 128         | 3:35         | 56k
5) Felicity THEME season 3 (New version  | 128         | 0:53         | 56k
6) Passions theme.mp3                    | 128         | 2:24         | 33.6
7) Korean - Uptown(03)- Han Oh Baek Nyun | 128         | 4:25         | 28.8
8) BB Mack  - Back Here.mp3              | 192         | 3:40         | 28.8
9) Cher_with_Peter_Cetera-After_All.mp3  | 128         | 4:04         | 28.8
10) Gob- Paint it Black.mp3              | 160         | 1:49         | 28.8
11) 3lw (Three Little Women) - NO MORE3. | 192         | 4:26         | 28.8
12) kpop-CLICK B-EXIT.mp3                | 128         | 4:21         | 14.4
13) Duets - Gwyneth Paltrow & Huey Le wi | 192         | 4:51         | 14.4
14) Dawson's Creek 2 Soundtrack - Shawn  | 128         | 4:38         | Unknown
                                         |             |              |
                                         |             |              |
                                         |             |              |
                                         |             |              |
                                         |             |              |
                                         |             |              |
                                         |             |              |
1:\1\Mp3\Bobby Bones - Yucky.mp3

Note that not all files listed actually contain the word "yucky". For instance, some of them might be found in a directory named "yucky", but the directory name is not displayed in the results list.

The files are listed in decreasing order of connection speed. On the result screen, you can move up and down with the respective arrow keys, or you can move faster with the "PgUp" and "PgDn" keys. The red line at the bottom displays the full filename of the song currently selected; if it does not fit on the screen, you can scroll it from side to side with the right and left arrow keys. If you press "h", a help message is displayed at the bottom of the screen.

You can hit "return" for any song you wish to download. Note: do not use nap to download or distribute any copyrighted material.

Type "q" to return to the main screen. From the main screen, enter /results to return to the result screen. You can also switch back and forth between the main screen and the result screen with the function keys "F1" and "F2".

Back on the main screen, nap will inform you about any downloads or uploads that have been started or stopped. If you want to see a detailed list of downloads that are currently going on, type

        /pdown
This will tell you, among other things, how far each download has progressed.

If you want to delete a particular download, first find out what its number is by using /pdown. Suppose you want to delete download number 3, then you type

        /ddown 3

Files that are currencly downloading are kept in your "incomplete" directory. Once a download has completed, the file is move to your "download" directory. You can specify the location of your "download" and "incomplete" directories on the command line, in the configuration file, or when nap prompts you for this information. If you do not specify a download directory, nap will use the current working directory. If you do not specify an incomplete directory, nap will use the download directory.

Incomplete files of size 100000 bytes or smaller will be considered "turds" and removed; all other incomplete files will be kept in the "incomplete" directory. You can change this behavior; see 5.3. Incompete downloads and turds.

4.3. Browsing another user's files

Browsing works almost exactly like searching. Just type

        /browse user
and that user's files will appear on the result screen.

4.4. Uploads

Uploads are similar to downloads, except that they are initiated by a remote user, and not by you. (Of course, what's an upload for you is a download for the remote user). You use /pup to print a list of current uploads, and /dup n to delete upload number n from that list.

You can specify one or more upload directories, either in the config file, or on the command line, or when nap prompts you for it. Multiple upload directories are separated by semicolons.

4.5. Navigating the main screen

On the main screen, you can use your "PgUp" and "PgDn" keys to scroll up and down. This allows you to see stuff that has disappeared off the top of the screen. "Ctrl-L" refreshes the screen.

You can use to "up" and "down" keys to scroll through a history list of previous commands. This will help you save time typing. You can also use the "tab" key for completing partially typed commands. For instance, /res[tab] will yield /results.

Press "F1" or type /results to return to the results screen after a previous search.

You can type /help to see a list of available commands. (There are so many that you will probably have to use "PgUp" and "PgDn" to see them all). You can get usage info for a particular command by typing /help followed by the command name (without the leading slash).

4.6. Quitting nap

To quit nap, type /quit. If there are any uploads or downloads going on, nap will refuse to quit unless you type /quit yes. You can also give the command /tquit, which will schedule the program to quit after all current transfers (including queued ones) have been completed. When /tquit is in effect, no new uploads will be accepted, but you can still initiate new downloads. You can undo the effect of /tquit with /unquit, in case you change your mind.

An emergency exit from nap is to press "Ctrl-C" twice in short succession. Note that a single "Ctrl-C" does not usually cause nap to quit.

4.7. Creating a new account

If you do not have an account on napster yet, you can easily use nap to create a new account. Just type

        nap -m -u username
You will be prompted for your password and email address as usual, and possibly for some other information. Then your account will be created, and you immediately get logged into your new account. If the username is already taken, you will get an error message (or several) to that effect; you'll have to choose a different username until you find one that is not taken.

4.8. News about new releases

As of version 1.4.4-ps7, nap will check online whether a newer release is available. If this is the case, it will inform you of the new release while starting up, with a gentle reminder to upgrade. If you would not like to be informed of new releases in this way, put nonews=1 in your config file or start nap with the option -ononews. You can also check for news from the main screen by typing /news.

5. More on searching and downloading

5.1. Advanced searches

The /search command has several options. They are:

        -m n            return at most n search results
        -l              local search: do not search on linked servers
        -p              do not send ping requests
        -f              list full filenames (only if noresultscreen=1)

        -b=rate, -b<rate, -b>rate   
                        bitrate equal to, at most, or at least rate.

        -c=speed, -c<speed, -c>speed   
                        link speed equal to, at most, or at least speed.

        -r=freq, -r<freq, -r>freq   
                        sample rate equal to, at most, or at least freq.

        -s=size, -s<size, -s>size   
                        file size equal to, at most, or at least
                        size, in bytes (OpenNap only).
The "-s" option only works on OpenNap servers; it has no effect on Napster.

Here's the story regarding pings. In principle, the /search command will try to ping the remote clients. However, the ping feature usually does not work unless you run nap with root privileges (which is a bad, bad idea). Thus, pings are usually disabled, and the "-p" option is irrelevant.

The "-l" option will cause the search to only be performed on the server you're connected to, and not on any other servers that might be linked to it in a network.

The "-m" option limits the number of results returned. However, even if n is greater than 100, most servers will only return 100 results.

5.2. Advanced navigation of the search result screen

By default, the result screen displays the bitrate and length of each song, as well as the connection speed and/or ping results. However, you have full control over what information is displayed: The following keys toggle each category of information on and off:
        b - bitrate
	l - length
	m - megabytes
	f - frequency
	u - user name
	s - speed
	p - ping
The "m" key also toggles between displaying the file size in megabytes and in bytes. Moreover, if you press "a", all categories of information will be turned on, and if you press "n", they will all be turned off (i.e., you will only see the filenames).

The search results can also be sorted by various different criteria. Pressing the uppercase equivalents of the above keys ("B", "L", etc) will sort the search results by that particular category (bitrate, length...). You can also press "N" (uppercase) to sort by filename. If you press a sort key more than once, the items will alternately be sorted in ascending and descending order.

When you sort, the cursor will remain on the same item that it was on. Thus, if your cursor is on an item shared by a particular user, and you press "U", you will see other items of the same user nearby. Notice that after sorting, the search results are re-numbered starting from 1. Any subsequent /get commands must use the new numbering. (The sorting feature was introduced in version 1.4.4-ps9).

5.3. Incomplete downloads and turds

Files that are currently downloading are kept in your "incomplete" directory. They also have the suffix ".incomplete" added to their filename (or alternatively the suffix defined by the user variable "incompletesuffix", if any). When a download has been successfully completed, the suffix is removed and the file is moved to your "download" directory. (Separate "incomplete" and "download" directories were introduced in version 1.4.4-ps8). Nap will also attach a special mark to incomplete files, to facilitate a later resumed download. (However, resumed downloads are not yet implemented).

In addition, nap will, by default, delete any incomplete files whose size is 100000 bytes or smaller. Nap considers such files "turds": they are too small to be of any value, and just tend to clutter up your hard drive. You can override the default cutoff of 100000 bytes by setting the user variable "turdsize" (See 7.2. User variables). In particular, if you set turdsize to 0, only empty files will be deleted, and if you set it to -1, no files will be deleted at all.

Note that the turdsize only applies to incomplete files. Nap will never delete a completed file, even if the file size is very small.

Note that the convention on incomplete files makes it possible to choose the same directory as your download directory and your incomplete directory (incomplete files will still be recognizable because they have the suffix ".incomplete"). On the other hand, you may choose to include your download directory in your upload path. However, you should never include your incomplete directory in your upload path, as people will probably not be too happy about downloading your incomplete files.

Previous versions of nap got very confused when you tried to download two files with identical names. Nap would append one file to the end of the other, or worse. Fortunately, with version 1.4.4-ps8, you don't have to worry about this problem any more; nap will automatically choose a different name for a file if necessary.

5.4. Queueing and the download list

As of version 1.4.4-ps9, nap now has the ability to queue your downloads. You can set both global and per-user limits on the maximal number of downloads. The global limit is useful if you are on a slow connection, and you want to download a number of files, but you'd rather download them one or two at a time (in order to end up with a few complete files, rather than a large number of incomplete ones). The global download limit is set as the value of the user variable maxdownloads. By default, there is no limit.

You can also set a limit on the number of simultaneous downloads from each user. This is useful if you're on a fast connection, but you are downloading files from remote users who are potentially on a slow connection. The per-user uploads limit is the value of the user variable maxdownuser, if any. By default, there is no limit.

If you requested more downloads than the current limits can support, your remaining downloads will be queued. They will be listed along with all other downloads by /pdown command. If you want to force a queued item to start downloading now, you can do so with the /force command.

Items which are stopped (finished, interrupted, timed out, or failed) are no longer automatically removed from the download list. By default, they remain on the list until you remove them explicitly. You can delete individual items from the list with the /ddown command, or you can clean up all stopped items with the /purgedown command. If you prefer stopped items to be automatically purged, you can set the user variable autopurge to 0. In general, autopurge, if set, defines the number of seconds an item will stay in the download list after it is stopped.

The command /retry n will put an interrupted, timed out, or failed item back in the download queue. The command /retryall will put all such items back in the download queue.

5.5. Uploads

Uploads are simpler than downloads, because uploads cannot be queued. Otherwise, a lot of what I said about downloads also applies to uploads. You can view the upload list with /pup, you can delete items from it with /dup, you can delete all stopped items with /purgeup or by setting autopurge. The handy command /purge purges both the up- and download lists at the same time.

If maxuploads is set, it defined a limit on the total number of simultaneous uploads. A per-user limit can be set in the variable maxupuser.

6. Messages, channels, and hotlists

One of the nice things about napster is that it allows you to communicate with other users. This is done through messages or channels.

6.1. Private messages

A "private" message is a message that you send to a specific user. You do this by typing

        /msg user msg
If you don't want to receive such messages from a particular user, you can ignore the user by typing

        /ignore user message
You will no longer see that user's messages or files. If you have regrets later, you can also /unignore a user.

If you intend to carry on an extended conversation with another user, it quickly becomes annoying to type /msg user all the time. You can tell nap which user you want to talk to by "querying" that user:

        /query user
Nap will now open a private channel to that user. The name of the user you are querying will be shown on the top blue status line, and also at the command prompt. You can now talk to the user just by typing messages and hitting return. Messages can be distinguished from commands because commands start with a "/". If you query more than one user, or you are querying a user while also on a channel, you can switch between users and channels by pressing "Ctrl-X". If you want to end the query with a user, just type

        /part user
You can also just type /part to end the current query.

If you're going to be away from your computer, and you are worried that other users might consider you rude for not replying to them, you can set the user variable "autoreply" to any string which will then be used as an automated reply. For instance, you can set it to "Hi, this is an automated reply. I'm away from my computer. Sorry for not responding personally." Nap will not autoreply a second time to a user it has just autoreplied to; this is to discourage infinite chats between two autoreplying clients!

6.2. Napster channels

When you join a channel, you can post messages to the channel and see what other users on the channel are saying. Type

        /clist
or      /clist2
to see a list of available channels. /clist lists only the official channels, while /clist2 also lists user-defined ones (see 6.3. Creating your own). To join a channel, type

 /join channel
Being on a channel is very similar to querying a user. You can be on several channels simultaneously. To switch between channels, press "Ctrl-X". The top blue status line shows the "topic" of the current channel. Press "Ctrl-T" to scroll the topic if it does not all fit on the screen. To leave a channel, type

 
        /part channel
You can omit the channel name if you want to leave the current channel. You can save the set of currently open channels to a file, or join all the channels previously saved in a file, by typing

        /savechannels [filename]
and     /loadchannels [filename]
If you omit the filename, the default file .nap/channels-username (relative to your home directory) will be used. Also, if the user variable savechannels is set to "1", nap will save your channels automatically when quitting and rejoin them when starting. See 7.2. User variables.

While you're on a channel, you will see a special prompt telling you what channel is currently active. To say something on that channel, simply type the message. This is why all command names start with a slash "/": so that when you're on a channel, nap can distinguish between a command and a post to a channel.

A word of caution about double quotes ("). The napster protocol is extremely dumb when it comes to double quotes. It cannot tolerate any data which contains double quotes. Thus nap will replace double quotes by single quotes when you say something to a user or on a channel.

To see a list of all channels you are currently on, type /pchans. To see a list of users on your active channels, type /names.

Just like for private messages, you can /ignore a user that is bothering you. More severe punishments are also available for users that behave truly inappropriately: you can request to kick a user from a channel or all channels, or request that a user be muzzled, killed, or banned. Such measures should of course be taken only under extreme circumstances, and might be subject to review by the administrators of your napster server. The corresponding commands are called /kick, /kickall, /muzzle, /kill, and /ban. Try

        /help command
for more info.

6.3. Creating your own

You can easily create a new channel. Simply join a channel that does not already exist, and it will be created. Normally, such channels have names that start with "#", although the official Napster servers do not enforce this. Once you have created your channel, you are probably the only person on it, but you can invite others to join the channel as well. The channel will continue to exist as long as there are users on it; it will be deleted when the last user parts. You can see a list of all channels, including user-defined ones, by typing /clist2.

You can set or change the topic on a channel by typing

        /topic channel topic
However, this does not work on the official Napster servers. It works on OpenNap servers, if you are the user who created the channel.

6.4. IRC channels

Nap can also be used as an IRC client. I have not yet have time to find out how, so probably there will be more information here in a future version of this User Guide.

6.5. The hotlist

Napster allows you to specify a "hotlist" of users, and you will be notified whenever these users log on or off napster. In nap, simply type

        /notify user
and     /unnotify user
to add a user to your hotlist, or respectively, to remove a user. To see who is on your hotlist, and which of those users are currently on napster, type

        /hotlist

Hotlists in nap are permanent; each time you make a change to your hotlist, it is automatically saved to a file (usually ~/.nap/hotlist-username). The hotlist is automatically loaded when nap starts.

7. Configuration and user variables

7.1. The configuration file

It used to be that you had to create a configuration file before you could start nap. However, starting with version 1.4.4-ps6, nap will simply create a configuration file for you, if it does not already exist. By default, this file is called napconf and resides in the directory ~/.nap. The default configuration file looks something like this:

# your napster username
user=username

# your napster password - optional
pass=?

# your napster email address
email=user@mydomain.com

# list of upload directories, separated by semicolon
upload=/home/username/shared;/home/username/other

# your download directory
download=/home/username/download

# your directory for incomplete files
incomplete=/home/username/incomplete

# maximal number of simultaneous uploads allowed
maxuploads=4

# your connection speed, according to the following chart:
#
# Connection | Number
# -------------------
# Unknown    |  0
# 14.4       |  1
# 28.8       |  2
# 33.6       |  3
# 56.7       |  4
# 64K ISDN   |  5
# 128K ISDN  |  6
# Cable      |  7
# DSL        |  8
# T1         |  9
# T3 or >    | 10
connection=4

# list of servers, separated by semicolon
#servers=

# port or range of ports to use for client-client connections
dataport=6699-6799

# log file for transfer logs
#logfile=

# log file for logging everything
#logallfile=

This is the file which nap will create automatically for you, except it will use the settings that you enter. Note that the password entry is left blank or set to a question mark. If you want, you can edit your configuration file and put your password in it; in this case, nap will not prompt you for it in the future. But nap will never save your password for you; whenever you save your config file, your password will show up as a question mark.

If you tend to use several different accounts on napster, and you don't want to be prompted for passwords, you can now also specify passwords and email addresses for each different account. Simply add some lines such as

        pass.username1=passwd1
        pass.username2=passwd2
        email.username1=email1
        email.username2=email2
to your config file. If you specify passwords in this way, it is understood that you don't want to be prompted for them; thus, such passwords never get be replaced by "?".

Any options that are set in the configuration file can be overridden on the command line, by using the "-o" option. It is also possible to have more than one configuration file (for instance, if you have two different napster accounts with different usernames and passwords), and to specify on the command line which one to use.

7.2. User variables

Nap has a general mechanism called "user variables". These are internal variables that correspond to nap's settings; for instance, anything you specify in your config file corresponds to such a setting. You can type

        /pvars
to see these settings, or you can change them using the commands

        /set variable value
and     /unset variable
There are some user variables that are not set in the default configuration file, but you can still change them. Some of them control rather obscure settings of nap. Here is an alphabetical list: You can load or save the values of the user variables with the commands

         /saveconfig filename
and      /loadconfig filename
The filename can be omitted, in which case your settings will be saved to your default configuration file (usually .napconf).

7.3. Building your library

Nap maintains a list of the files that you sharing in the file ~/.nap/shared. This file is called the "library". Normally, when you start nap, it will automatically detect whether the information in the library is up-to-date, and rebuild it if necessary. This may take a few moments, especially if you are sharing a lot of files.

You can force nap to rebuild your library by giving it the --build or --build-only options. Conversely, you can prevent it from building the library, even if it is out of date, by giving the --nobuild. This might be useful if you want to start two copies of nap simultaneously and you don't want them to interfere building the same library.

You can also issue the /update command from within nap, which will check if your library is up-to-date, and rebuild it if necessary. This is useful, for instance, if you have added new files to your upload directories while nap is already running. It is also possible to change your upload directories while nap is running, either by /set upload or by using the special /chupload command. But when you change your upload path, it is still necessary to rebuild your library for the changes to take effect. The /rebuild command works like /update, except it builds your library no matter whether it was up-to-date or not.

7.4. "Some files in my upload directory don't show up on napster."

There are two common reasons for your files not to show up on napster. The first reason is that Napster is blocking more and more copyrighted files, plain and simple. In any case, you should never use nap to share or download copyrighted material. If your files appear in your shared library file (usually ~/.nap/shared), but they do not show up online, then you can be almost certain that they were blocked by the napster server.

The other reason some files do not show up is that nap does a basic sanity check on your mp3 files before it adds them to your shared library. It will refuse to share any files that it considers broken. Usually, this means the file does not start with a proper mp3 frame header. (However, nap does recognize id3v2 style headers correctly). Often this means that a few bytes of music have been cut off from the beginning of the file, after the file was originally created.

It is my belief that the overall quality of music files on the network will improve if clients prevent users from sharing broken files. After all, wouldn't you rather download a good mp3 file than a crappy one? If you have some extremely valuable mp3 which you feel you absolutely must share, but nap prevents you from doing so, please consider repairing the file first using some other software. For example, notlame is a high quality free mp3 encoder which allows you, among other things, to reencode existing mp3 files. You just type something like

        notlame --mp3input infile outfile
Needless to say that this process does not actually fix any audibly problems with mp3 files.

(There are some cases of legitimate mp3 files which nap does not recognize. This is usually due to the presence of other non-standard headers. If nap does not recognize your favorite header, let me know, preferably with a spec of that header type, and I'll see what I can do to make nap recognize it).

8. Advanced features

8.1. User defined commands and handlers

One interesting feature of nap is the ability to add new user-defined commands. This is done via so-called aliases (also called macros). I mostly use aliases for defining shortcuts to commands that I use often. An alias definition is of the form

 
        /alias name replacement
For instance, if you type

 
        /alias x get $1
this will define "x" to be an alias, and you can henceforth type "/x arg" instead of "/get arg". In the replacement text, you can use variables such as "$1", "$2" etc to stand for the first, second argument and so on. You can also use "$1-" to stand for the first and all remaining arguments, "$2-" for the second and all remaining arguments, and so on. This is useful, for instance, in a alias like this:

        /alias s search -b>128 -c>7 $1-
The replacement text for an alias can contain several commands separated by "|", as in

        /alias f finger $1 | browse $1
or      /alias i ignore user1 | ignore user2 | ignore user3
Commands can also be grouped with braces "{" and "}". It is also possible, although maybe less useful, to construct more complex aliases, using control features such as "if" and "while".

Aliases can also be saved and loaded from a file with the /savealias and /loadalias commands. By default, alias are saved in and loaded from the file "~/.nap/aliases". This file is also automatically loaded every time your start nap.

There is also the ability to add user-defined "handlers". Handlers are similar to aliases, but they react to messages from the server, rather than to commands from the user. Handlers are automatically loaded from a file "~/.nap/handlers", and they can also be saved there.

The particular syntax and semantics of aliases and handlers is a bit obscure, and to my knowledge it has not been documented anywhere. If you ever have any use for them (other than defining a shortcut for a command), let me know.

There is also another feature in nap which allows you to write a library of user-defined commands and handlers in C, and dynamically link it to nap at runtime. This feature is being discontinued (as it seems to make little sense in an open source program). If you really need it, let me know.

8.2. Daemon mode

Sometimes you might want to share your files on napster, even when you're not currently actively using it. For instance, if you're on a multi-user system, you might want to run a napster client in the background at all times, even when you're not logged in. (Beware though that downloads generate quite a bit of network traffic, so you better had a fast connection and be sure it is not going to upset other users).

Nap's daemon mode allows you to do exactly that. If you invoke nap as follows:

        nap --daemon --autorestart
it will connect to the napster server and then run silently. While connecting, it will still print the usual informational messages, and prompt you for any missing information. As soon as the connection succeeds, it will print something like

        Connected to 208.184.216.40:8888
and then fall silent. It will produce no further output, nor react to input. Moreover, if your config file is complete, and you are sure that nap will not prompt you for any information, you can even suppress the informational messages by redirecting its output:

        nap --daemon --autorestart > /dev/null

By the way, the --autorestart option is so that nap will automatically reconnect whenever it detects that it has been disconnected from the server. It tries to do this at most once a second, so that your computer will not overheat in case you get disconnected from the network. Using this method, I have been able to run nap unsupervised for days and even weeks at a time.

Two words of caution on using the --autorestart feature: nap may not always be able to detect when you have been disconnected from the server; thus autorestart may not always be triggered (although it has worked okay for me). Also, do not try to run two copies of nap with the same username and both with autorestart enabled; the napster network will allow at most one simultaneous session per username, and the two copies of nap will continue to kick each other out until the end of time.

If you feel uncomfortable with nap's silence, and you would rather like to see whether it is actually working (and not just dozing off), you have the ability to write something to a log file. The option

        --log logfile
will cause nap to log all uploads and downloads to the specified file. (But beware that log files might later be used against you in court). If you'd like even more information, you can specify

        --logall logfile2
and nap will log everything that would have normally been written to the main screen to that file. Note that these log files can take up a tremendous amount of disk space, so you might want to delete them and restart nap periodically, for instance once a week. If a log file already exists, nap will append its output to the end of the existing file.

8.3. Running nap as a nohup process

On unix systems, it is possible to run a process as a "nohup" process - this means, the process will not be killed when you log out. This might come in handy if you want to run nap in the background while you're not logged in. Nap's daemon mode is perfect for a nohup process. For instance, the following works:

        nohup nap --daemon --autorestart --log logfile >/dev/null &
Note that you have to put an explicit ampersand "&", or otherwise the process will not fork to the background. To stop such a process, you will have to kill it explicitly, by saying

        kill -KILL pid
or      killall -KILL nap
where pid is the process id, as reported by the command ps -e. The second form kills all processes whose name is nap.

On my system, I use a shell script called server, which automates these tasks. Here is the script:

#! /bin/bash

napservers="-s 63.196.54.15:8888"
napservers="$napservers -s 63.196.54.248:8888"
napservers="$napservers -s 63.196.54.4:8888"
# etc

if [ $# -gt 0 ]; then
    action=$1
    shift
else
    action=start
fi

if [ $# -gt 0 ]; then
    target=$1
    shift
else
    target=all
fi

do_action () {
 local action target
 action=$1
 target=$2
   
 case $action in
  start )
    do_action stop $target

    if [ "$target" = all -o "$target" = gnut ]; then
	echo -n "Starting gnut "
	nohup gnut -d >/dev/null &
	echo $! > gnut.pid
	echo "(PID $!)"
    fi
    if [ "$target" = all -o "$target" = nap ]; then
	echo -n "Starting nap "
	nohup nap --daemon --reconnect --autorestart $napservers --log nap.log >/dev/null &
	echo $! > nap.pid
	echo "(PID $!)"
    fi
    ;;
  stop )
    if [ "$target" = all -o "$target" = gnut ] &&  [ -r gnut.pid ]; then
	pid=`cat gnut.pid`
	echo "Stopping gnut (PID $pid)"
	kill -KILL $pid
	rm gnut.pid
    fi
    if [ "$target" = all -o "$target" = nap ] &&  [ -r nap.pid ]; then
	pid=`cat nap.pid`
	echo "Stopping nap (PID $pid)"
	kill -KILL $pid
	rm nap.pid
    fi
    ;;
 esac
}

do_action $action $target

This shell script illustrates a number of things: first, note the use of the "-s" option to pass an alternative list of server addresses to nap. Second, the script can be used to start and stop not only nap, but also gnut, another neat file sharing client for linux (gnut is a Gnutella client). Third, the script automatically saves the process id so that it knows how to stop the process later.

I invoke this script as follows:

        ./server start nap      (to start or restart nap)
        ./server stop nap       (to stop nap)
        ./server start gnut     (ditto for gnut)
        ./server stop all       (stop them both)

9. Summary of command line options

Usage: nap [options]

Options:
-h, --help         - print this help message
-v, --version      - print version info and exit
-b, --build        - build library of your current mp3s to send to server
-B, --build-only   - build library and exit
-N, --nobuild      - do not build library, even if it is out of date
-m, --create       - create a new account with the napster server
-r, --reconnect    - keep reconnecting until server connection established
-a, --autorestart  - automatically reconnect when connection to server lost
-q, --daemon       - run without user interface; file sharing only
-t, --notitle      - do not display the title bar (fixes messed-up displays)
-l, --nxterm       - try using a terminal which is compatible with most
                     systems (fixes some messed-up displays)
-f fn, --config fn - specifies the config file to use (default ~/.nap/napconf)
-x fn, --log fn    - log all transfers to a specific filename
-g fn, --logall fn - log everything to a specific filename
-s sv, --server sv - select a specific server (multiple -s opts possible)
-d n, --debug n    - set debug level
-u str, --user str     - specify napster username
-p str, --pass str     - specify user's password
-e str, --email str    - specify user's email address
-U dir, --upload dir   - specify upload directory (multiple -U opts possible)
-D dir, --download dir - specify download directory
-I dir, --incomplete dir - specify directory for incomplete files
-P n, --dataport n     - specify local data port to use
-C n, --connection n   - specify connection speed number (see README)
-M n, --maxuploads n   - specify maximum number of simultaneous uploads
-o var=value, --option var=value  - set user variable

10. Summary of nap commands

I did not have time to write a detailed description of each command. Here is the complete list of commands, along with the short descriptions given by /help. Some command have additional options which are not documented.

about                alias                aliaslist            announce
ban                  banlist              block                blocklist
break                browse               cban                 cbanlist
chupload             clear                clearalias           clearhandler
clist                clist2               cloak                conf
cunban               ddown                dec                  debug
disconnect           dns                  done                 dup
echo                 eval                 exec                 finger
force                g                    get                  gusers
handler              handlerlist          help                 hotlist
if                   ignore               ignoreclear          ignorelist
inc                  irc                  join                 kick
kickall              kill                 lastlog              loadalias
loadchannels         loadconfig           loadhandler          me
msg                  muzzle               names                news
noprint              notify               opsay                part
pchans               pdown                ping                 psocks
pup                  purge                purgedown            purgeup
pvars                query                q                    quit
rebuild              reconnect            reload               results
retry                retryall             savealias            savechannels
saveconfig           savehandler          say                  search
serv                 server               set                  setdataport
setlevel             setlinespeed         setpassword          setuserlevel
sraw                 stop                 sver                 tell
timer                tlist                topic                tquit
unalias              unban                unblock              unhandler
unignore             unmuzzle             unnotify             unquit
unset                update               while                whois
window               wstats

/about - No help available
/alias name args - Creates an alias
/aliaslist - Returns a list of aliases created
/announce msg - Broadcasts a message to all users
/ban user/IP - Bans the specified user or IP
/banlist - Prints a list of the current bans on the server
/block IP [reason] - Blocks the specified IP
/blocklist - Gives a list of current blocked
/break - Breaks out of a loop
/browse user - Browses user's files
/cban user [reason] - Bans a user from a channel
/cbanlist - Returns a list of banned users in a channel
/chupload path - Changes your upload path (still need to /rebuild to update your files)
/clear - Clears your screen buffer
/clearalias - Clears all aliases
/clearhandler - Clears all handlers
/clist - Gets a list of channels
/clist2 - Gets a list of channels (includes user created)
/cloak - Cloaks yourself
/conf - No help available
/cunban user [reason] - Unbans a user from a channel
/ddown number or range - Deletes downloads by number as returned from /pdown
/dec - Decreases the variable by one
/debug - No help available
/disconnect - Disconnects you from the server
/dns host/IP - Attempts to resolve the specified address
/done - Ends an alias
/dup number or range - Deletes uploads by number as returned from /pup
/echo text - Echos text to the screen
/eval name - Returns the value of a variable
/exec [-o] command - Executes a command from a shell and redirects the input to the client
/finger user - Gets information on the specified user
/force number or range - Forces download of queued items, overriding download limit
/g number or range - Gets files by number as returned from /search
/get number or range - Gets files by number as returned from /search
/gusers - Gets a global list of users
/handler code args - Adds a handler
/handlerlist - Returns a list of handlers created
/help command - Returns help on the specified command
/hotlist - Lists users on your hotlist that are on
/if (val op val) cmd - Compares two values
/ignore user - Ignores a user
/ignoreclear - Clears your ignore list
/ignorelist - Lists ignored users
/inc var - Increases the variable by 1
/irc - No help available
/join chan - Joins the specified channel
/kick user [reason] - Kicks a user from a channel
/kickall user [reason] - Kicks a user from all channels you and the user are in
/kill user - Kills the specified user
/lastlog str - Returns all occurences of "str" that have been said or printed
/loadalias [filename] - Loads a list of aliases from a file
/loadchannels [filename] - Reads channels from a filename and joins them
/loadconfig [filename] - Loads a list of settings from a filename
/loadhandler filename - Loads a list of handlers from a filename
/me string - Does an emotion
/msg user msg - Sends the user the message specified
/muzzle user msg - Muzzles the user with the specified message
/names channel - Gets a list of channel users
/news - Checks for any news on the client
/noprint - Stops the client from echoing anything until the command returns
/notify user - Attempts to add a user to your hotlist
/opsay msg - Broadcasts a message to all moderators/admins/elite
/part [chan/user] - Parts the specified or current channel or query
/pchans - Shows which channels you are on
/pdown - Gives a listing of your current downloads
/ping user - Pings a user
/psocks - Print the socket list (for debugging purposes)
/pup - Gives a listing of your current uploads
/purge - Removes all stopped items from upload and download lists
/purgedown - Removes all stopped items from download list
/purgeup - Removes all stopped items from upload list
/pvars - Prints the values of all variables currently set
/query user - Queries a user
/q - Closes the program
/quit - Closes the program
/rebuild - Rebuilds your library unconditionally. See also /update
/reconnect - Reconnects you to the server
/reload - No help available
/reloadm - Reloads the user command module (only if supported)
/results - Switches to the search results screen
/retry number or range - Puts stopped downloads back in the download queue
/retryall - Puts all stopped downloads back in the download queue
/savealias [filename] - Saves current aliases
/savechannels [filename] - Saves current channels to a filename
/saveconfig [filename] - Saves current settings to a filename
/savehandler filename - Saves current handlers to a filename
/say msg - Sends msg to the current channel
/search [-b>bitrate] [-c>conn] [-mmaxres] query - Searches the napster database
/serv - Returns the current IP and port of the server you're connected to
/server IP:port - Connects to the specificed server and port
/set name value - Sets a variable to the specified value
/setdataport user port - Sets a user's data port
/setlevel channel level - ?
/setlinespeed user speed - Changes a user's linespeed
/setpassword user password - Sets a user's password
/setuserlevel user level - Changes a user's userlevel
/sraw - No help available
/stop - Returns from the current command and stops all processing on it
/sver - Returns the server version
/tell user msg - Sends the user the message specified
/timer min:sec cmd - Initiates a timer to execute in the specified time
/tlist - Prints out a list of the current timers
/topic channel topic - Changes a channel's topic
/tquit - Quits when all remaining transfers have completed. Can be canceled with /unquit
/unalias name - Removes an alias
/unban IP - Unbans the specified IP
/unblock IP - Unblocks the specified IP
/unhandler code - Removes a handler
/unignore user - Unignores a user
/unmuzzle user - Unmuzzles the user
/unnotify user - Removes a user from your hotlist
/unquit - Cancels the effect of /tquit
/unset name - Unsets a variable
/update - Rebuilds your library if necessary. See also /rebuild
/while (val op val) cmd - Keeps executing cmd while the comparison is true
/whois user - Gets information on the specified user
/window - Enables/disables window mode
/wstats - No help available