# Linux Napster Client: User Guide

## Peter Selinger (selinger@users.sourceforge.net)

Created March 28, 2001. Updated December 9, 2002 for nap version 1.5.1.

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

## 1. General

- 1.1. Introduction
- 1.2. Brief history
- 1.3. Reporting bugs

## 2. Author and copyright

## 3. Downloading and installation

- 3.1. Source distribution
- 3.2. Linux precompiled distribution
- 3.3. RPM package
- 3.4. Debian package
- 3.5. OpenBSD package
- 3.6. Windows precompiled distribution
- 3.7. Binary distributions with ncurses [new 1.5.1]
- 3.8. Other formats
- 3.9. "What if I don't have root privileges on my machine?"

## 4. Basic nap usage

- 4.1 Starting nap
- 4.2. Simple searches and downloads
- 4.3. The download/upload screen [new 1.5.0]
- 4.4. Browsing another user's files
- 4.5. Where your music files go
- 4.6. Navigating the main screen [updated 1.5.0]
- 4.7. Quitting nap
- 4.8. Napster vs. OpenNap
- 4.9. News about new releases
- 4.10. If you are behind a firewall

## 5. More on searching and downloading

- 5.1. Advanced searches [updated 1.5.1]
- 5.2. Pings
- 5.3. Advanced navigation of the search result screen
- 5.4. Shortcut searches [new 1.5.0]
- 5.5. Incomplete downloads and turds
- 5.6. Upload and download limits and queueing [updated 1.5.0]
- 5.7. Purging and retrying failed items [updated 1.5.0]
- 5.8. Limiting bandwidth
- 5.9. Direct browsing
- 5.10. Sharing non-music files
- 5.11. Managing uploads and downloads from the main screen [updated 1.5.0]

## 6. Messages, channels, and hotlists

- 6.1. Private messages
- 6.2. Napster channels
- 6.3. Creating your own channel
- 6.4. IRC channels
- 6.5. The hotlist

## 7. Configuration and user variables

- 7.1. The configuration files
- 7.2. User variables [updated 1.5.1]
- 7.3. Meta-servers
- 7.4. Http proxies [new 1.5.0]
- 7.5. Building your library
- 7.6. "Some files in my upload directory don't show up on napster."

## 8. Advanced features

- 8.1. User defined commands and handlers
- 8.2. Daemon mode
- 8.3. Running nap as a nohup process

## 9. Obsolete features

- 9.1. Creating a new napster account

## 10. Summary of command line options [updated 1.5.1]

## 11. Summary of nap commands [updated 1.5.0]

## 1. General

#### 1.1. Introduction

Nap is a console napster client for linux and other operating systems, written by Kevin Sullivan. This user guide summarizes some of its most important features, from a user's point of view. Additions and corrections are welcome.

#### 1.2. Brief history

Nap, written by Kevin Sullivan sometime in 1999, was one of the first napster clients besides Shawn Fanning's original Windows client. It was also the first client that ran on Linux. Kevin learned much about the inner workings of the napster protocol by collaborating with Jordan Ritter, who was one of the co-founders of Napster and its chief server architect at the time.

After a period of inactivity, development of nap resumed in early 2001, when I took over the project. Since then, nap has been polished, and many new features have been added, while the original "look and feel" has been preserved as much as possible. Today, nap is one of the most reliable and stable napster clients. Nap has been packaged for a variety of popular platforms, and it is shipped with distributions of some operating systems such as Debian Linux and OpenBSD.

#### 1.3. Reporting bugs

Nap has a sourceforge project page. You are encouraged to use sourceforge's facilities for bug reports, feature requests etc. You can also send me bug reports by email. When you report a bug, please be as specific as you can about what happened and what you were doing when the bug occurred.

## 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://nap.sourceforge.net/. 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-XXX.linux-i386.tar.gz`. Install nap as follows:

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

If you are running Linux on a different architecture, such as Alpha, just substitute "alpha" for "i386" in the above instructions.

Napping is a helper application for nap which can be safely installed suid (with permissions 4755). For more on napping, see 5.2. Pings.

#### 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 section 3.9.

#### 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. Windows precompiled distribution

Instructions: download the file `nap-XXX.cygwin32.zip`. Unpack it with

            pkunzip nap-XXX.cygwin32.zip

(Note: pkunzip is a relatively dumb program. My version of it, which came with Windows 98, does not understand long filenames, and you may have to type something of the form "pkunzip nap-1.~1.zip". Instead of creating a directory, it may decide to dump the files in the current working directory, and it may rename them. Use "unzip" instead of "pkunzip" if it is available.) Among the unpacked files, you will find an executable file nap.exe and two DLL's (dynamically linked libraries): cygncurses5.dll and cygwin1.dll. You need to put these DLL's in a place where Windows can find them, before running nap.exe. One way to do this is to copy the two "*.dll" files to a location (such as C:\WINDOWS) where Windows looks for DLL's. Another way is to amend your PATH environment variable, by adding something like the following line to C:\AUTOEXEC.BAT:

            PATH=%PATH%;C:\DIRECTORY\WHERE\DLLS\ARE

Special care is needed with nap for Windows regarding the location of the configuration files. Nap normally looks for its configuration files in a directory called ".nap" in the user's home directory. Under Windows, there is no such thing as a user's home directory, and nap will by default look for the .nap directory in the current working directory. You can change this behavior by defining an environment variable HOME. I do this by something like the line

            set HOME=C:\SOME\DIRECTORY

in the file C:\AUTOEXEC.BAT. This will cause nap to look for (and create) its configuration files in the directory C:\SOME\DIRECTORY\.nap.

See also the file README.win which comes with the distribution.

#### 3.7. Binary distributions with ncurses [new 1.5.1]

Some binary distributions for operating systems which do not normally ship with the ncurses library, such as Solaris, come with a file `ncurses.so.5` or similar. If nap complains that it cannot find this file, you need to put it somewhere where the dynamic linker can find it. You need to do one of two things:

- put the file `ncurses.so.5` in a standard directory where dynamically linked libraries are kept, typically `/usr/lib` or `/usr/local/lib`, or
- set the `LD_LIBRARY_PATH` environment variable to contain a path to the directory which contains the `ncurses.so.5` file. Suppose the file `ncurses.so.5` is in a directory path. Then you need to issue one of the following two commands, depending on the shell that you use:

         export LD_LIBRARY_PATH="$LD_LIBRARY_PATH:path"  (for sh and bash)
         setenv LD_LIBRARY_PATH "$LD_LIBRARY_PATH:path"  (for csh and tcsh)

  Note that this must be done every time you run nap. You might want to put the above lines in your `.bashrc` or `.tcshrc` file.

Important: the ncurses.so.5 file distributed with nap assumes that your `terminfo` database is located at `/usr/share/lib/terminfo`. If it is in a different location, you must set the `TERMINFO` environment variable to the location, e.g.

       export TERMINFO=/usr/share/terminfo

#### 3.8. 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.

#### 3.9. "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:

            setenv 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 three screens. This should be enough to get you started. Later sections of this userguide will cover these and other features in more detail.

#### 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.5.1]

         _.-------._
        |\          /|
       /| \_.----._/ |\                                  __
      .$:            :$.    _____  ____   _____  _____  / /__ ___   ____
     |$$:  ___  ___  :$$|  / __  // _  `// _   //  ___//  __// _ \ / ___/
      "$: \___\/___/ :$"  / / / // /_/ // /_/ /(__   )/  /_ /  __// /
        |     __     |   /_/ /_/ \__,_// ____//_____/ \___/ \___//_/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 (or, if available, in increasing order of ping response). 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 left and right arrow keys. If you press "h", a help message is displayed at the bottom of the screen, which can also be scrolled via the left and right arrow keys.

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

#### 4.3. The download/upload screen [new 1.5.0]

If you press "tab" while viewing search results, you will be taken to a third screen which displays all current downloads and uploads in a split-screen format (downloads above, uploads below), and their progress. Typically, this screen might look as follows:

                                     Downloads (7)
     1. Bobby Bones - Yucky.mp3                    | user77     | *Complete*
     2. Leo the Lion - Roaring On.mp3              | nickomat   | 55% (27.50 k/s)
     3. Savage Girls - Dig Your Well.ogg           | nickomat   | Queued
     4. Savage Girls - Gallow Song.ogg             | nickomat   | Waiting
     5. Savage Girls - Ghostly Night.ogg           | nickomat   | Waiting
     6. The Yucky Family - My Brother.mp3          | superguy   | Connecting
     7. Knots and Bones - Knotted.mp3              | 5668hello  | Failed

                                      Uploads (5)
     1. Cloned Sheep - Baah.mp3                    | macky      | 13% (0.53 k/s)
     2. Fried Thunder - Yesterday Morning.ogg      | sonicman   | Interrupted
     3. Fried Thunder - The Angel.ogg              | sonicman   | *Complete*
     4. Sunny Days - Happy again.mp3               | sonicman   | 77% (18.40 k/s)
     5. Sunny Days - Me and the sun.mp3            | sonicman   | 94% (22.53 k/s)

    Use F1 or 'q' to return to the main screen. 'h' for help.

You can scroll through the tasks via the up and down arrow keys, or "PgUp" and "PgDn". You can switch between the download and upload sections by pressing 'o', or "Alt-up" and "Alt-down". There are a number of keystrokes available to manipulate the displayed tasks: 'd' to delete the task under the cursor, 'r' to retry a failed/incomplete download, 'R' to retry all failed tasks, 'f' to force an immediate download, and 'P' to purge stopped tasks from the current section. You can also type 'h' for help and left/right to scroll help, as on the results screen.

Press "tab" to go back to search results, or type "q" from either screen to return to the main screen. You can also switch between the three screens (main screen, search result screen, download/upload screen) by using the function keys "F1" thru "F3", or "Alt-1" thru "Alt-3".

#### 4.4. 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. If the remote user's client supports it, you can also directly browse that user's files, without going via the napster server. To do this, use the command `/browse2` instead of `/browse`. This can be useful if the server limits the number of browse results that you can see. See also 5.9. Direct browsing.

#### 4.5. Where your music files go

When you start nap for the first time, it prompts you to enter three directories: Your "upload", "download" and "incomplete" directories.

The "upload" directory contains files that you want to share. Do not use nap to share any copyrighted material. Files that are currently being downloaded are kept in the "incomplete" directory. Completed downloads are moved to the "download" directory.

You can specify the location of these 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. If you do not specify an upload directory, nap will be unable to share any files. It is possible to specify more than one upload directories; multiple directories are separated by semicolons.

If an incomplete download results in a file of 100000 bytes or less, the file will be considered a "turd" and removed. Larger incomplete files will be kept in the "incomplete" directory. You can change this behavior; see 5.5. Incompete downloads and turds.

#### 4.6. Navigating the main screen [updated 1.5.0]

The text of the main screen can be scrolled up and down by using the "PgUp" and "PgDn" keys. This allows you to see stuff that has disappeared off the top of the screen. If you prefer, you can use the alternative keybindings "Ctrl-P" and "Ctrl-N" or "Ctrl-V" for the same purpose.

To switch between screens, use the keys "F1" thru "F3", or "Alt-1" thru "Alt-3". In addition, the commands `/results` and `/dlul` will take you to the search results or the download/upload list from the main screen.

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).

When entering a command, a number of standard keybindings are available. "Ctrl-U" deletes the current line, while "Ctrl-K" truncates the input, and "Ctrl-W" deletes everything from the current word to the end of the line. "Ctrl-D" or "delete" deletes the current character. "Backspace" deletes the previous character and "Alt-backspace" deletes the previous word. You can use "Ctrl-A" or "home" to move to the beginning of the line, and "Ctrl-E" or "end" to move to the end of the current line. "Ctrl-L" refreshes the screen.

The "up" and "down" keys provide a history of previously typed commands scroll through a history list of previous commands. This can save you time when using the same commands repeatedly. You can also use the "tab" key for completing partially typed commands. For instance, `/res[tab]` will yield `/results`.

#### 4.7. 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.8. Napster vs. OpenNap

Since June 2001, Napster Inc. has modified their servers to use a new client authentification scheme, and nap users can no longer connect to Napster Inc.'s servers. Thus, nap is configured to connect to the OpenNap servers by default. The OpenNap system is a network of napster servers that are independently owned (not run by Napster, the company). When starting up, nap will automatically download a list of servers from www.napigator.com, and it will connect to the first available one. You can change this behavior if you want; see 7.3. Meta-servers.

#### 4.9. News about new releases

At startup, 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, as a gentle reminder to upgrade. If you never want 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`.

#### 4.10. If you are behind a firewall

Most firewalls allow only outgoing connections, not incoming ones. The napster protocol can compensate for this to a certain extent, by arranging things so that firewalled clients initiate connections to non-firewalled clients, and not the other way around. In this way, both uploads and downloads are possible between a firewalled and a non-firewalled client. However, between two clients that are both firewalled, neither uploads nor downloads are possible.

If you are behind a firewall, then nap needs to know about it, in order to be able to compensate for it. However, nap can't find this out on its own. The way to tell nap that you are behind a firewall is to set `dataport = 0` in your configuration file (see 7. Configuration and user variables).

If you are behind a firewall, you may also need to set up an http proxy so that nap can read its server list; see 7.4. Http proxies.

## 5. More on searching and downloading

#### 5.1. Advanced searches [updated 1.5.1]

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              toggle sending 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 and slavanap only).

            -d=duration, -s<duration, -s>duration
                            duration equal to, at most, or at least
                            duration, in seconds (opennap and slavanap only).
    			[new 1.5.1]

    	-x keyword exclude results that match keyword (opennap and
    			slavanap only). Multiple -x options are possible.
    			[new 1.5.1]

            -t filetype search for the specified filetype, which must
    	                be one of: audio, video, text, image,
    	                application, mp3, any.
    			[new 1.5.1]

The "-s" option only works on OpenNap servers; it has no effect on Napster.

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. Pings

Pings are test packages that are sent to other clients to see how "far away" they are in the internet. A ping result is the time, in milliseconds, that it took the package to travel to the other client and back. Normally, nap will try to collect ping results with each search request. You can switch off pinging by giving the "-p" option to the `/search` command, or by setting the user variable `noping` to 1.

Nap implements pings via a separate helper application called "napping". The reason is that sending and receiving ping packets requires raw network protocol access, which usually requires root privileges on Linux. However, it would be dangerous to run nap with root privileges. The program "napping", written by Sebastian Zagrodzki, solves this problem. Napping is a very small program which is called by nap to handle pings. Napping, unlike nap, can be run "suid", i.e., with root privileges. This is safe because napping drops root privileges immediately after opening the network socket, which is in fact the first thing it does.

For napping to work, it must be installed somewhere in your $PATH, it must be owned by root, and it must have "suid" permissions. Thus, the permissions of napping should look like this:

            -rwsr-xr-x    1 root     root        48417 Aug 29 17:54 napping*

The "s" in the permissions is called the "suid" bit, and it means that napping will be run with the effective user id of root, rather than that of the user who actually runs it. You can set the right ownership and permissions with the following commands (assuming that napping is installed in /usr/local/bin):

            chown root:root /usr/local/bin/napping
    	chmod 4755 /usr/local/bin/napping

You can specify an alternative name for the napping program by setting the `napping` user variable. You can also use this to specify an absolute filename, which is useful in case napping is installed outside your $PATH (see 7.2. User variables).

#### 5.3. 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, and "D" to sort by directory name. Sorting by directory name is useful if there are many files whose names start with "01", "02", and so on. 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.

If you prefer an appearance of the search result screen different from the default appearance, you can set the `sdefaults` user variable to a string of key strokes executed when that screen is initialized. The default is "blsp". You can set it, for instance, to "lspmm" if you don't want to see the bitrate, but instead the file size in bytes. You can also set it to something like "blspN" if you like your results sorted by name, rather than by connection speed. Note that ping results will only be displayed if they are actually available, and connection speeds will not be displayed for browse results.

#### 5.4. Shortcut searches [new 1.5.0]

A convenience features allows you to enter a new search directly from the search result screen or download/upload screen. Just type "space", and an input window will open in the status line with the prefix "/search " entered for you. You can also type '/' to take you back to the main screen and start a new command (a shortcut for 'q', '/').

#### 5.5. 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.

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.

If you try to download two files with identical names, nap will automatically rename one of the files before saving them.

#### 5.6. Upload and download limits and queueing [updated 1.5.0]

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`. You can limit the maximal number of simultaneous uploads and downloads, both globally and for each remote user. To limit the number of simultaneous uploads or downloads, set the user variables `maxuploads` and `maxdownloads` to the desired number. To limit the number of simultaneous uploads or downloads from each user, use the user variables `maxupuser` and `maxdownuser`. By default, there are no limits.

When the download limit is reached, nap will queue any additional downloads, and it will start them as soon as space is available. Queued downloads will be listed along with all other downloads on the download/upload screen. If you want to force a queued download to be started immediately, you can do so by pressing 'f' on the download/upload screen.

#### 5.7. Purging and retrying failed items [updated 1.5.0]

By default, items which are stopped (finished, interrupted, timed out, or failed) are not automatically removed from the download list. They remain on the list until you remove them explicitly. Individual items can be removed from the download screen by pressing 'd'. You can also press 'P' to purge all stopped items in the current section (i.e., all uploads or all downloads).

If you prefer stopped items to be automatically purged, you can set the user variable `autopurge` to 0. You can also set `autopurge` to a positive number, if you want items to be purged after this many seconds. The variables `autopurgeup` and `autopurgedown` allow you to set these parameters for uploads and downloads separately.

A download which has been interruped, or which has timed out or failed, can be retried by pressing 'r' on the item on the download screen. You can also retry all such items with a single keystroke by pressing 'R'.

#### 5.8. Limiting bandwidth

It is possible to limit the bandwidth of up- and downloads. It is possible to set a limit on the bandwidth per connection, and to set an overall limit on the total bandwidth taken by all connections. This is done separately for uploads and downloads. Up- and download bandwidth limits are given in kilobytes per second, and they are set via the user variables `bandwidthup`, `bandwidthup1`, `bandwidthdown`, `bandwidthdown1`. See 7.2. User variables.

It is possible to change the bandwidth limits at any time. Such changes will immediately take effect, even for transfers that are already in progress. Note that bandwidth limits for downloads only affect the rate at which nap reads data, not the rate at which data arrives from the network. If data arrives on the network at a higher rate than nap reads it, then the operating system will usually buffer such data. Thus, the actual network bandwidth may not go down until the buffer is full.

If you plan to limit your upload bandwidth, please be sure to claim an appropriate connection speed. This is out of fairness to other users. For instance, if you limit your bandwidth to 10k/s, you should probably set your connection speed to 56k, even if you are really on a T3 connection. To some extent, nap will try to enforce this kind of etiquette.

#### 5.9. Direct browsing

Nap supports direct browsing, also known as client-to-client browsing. This is implemented through a new command, `/browse2`, which works essentially the same way as `/browse`, except it gets the file list directly from the other client, rather than from the server. Nap supports both outgoing direct browsing connections (you browsing another client's files) and incoming ones (another client browsing your files).

Direct browsing can be useful if the server limits the number of browse results that it returns. However, there are several caveats which limit the usefulness of direct browsing. The most important is that not many other clients support it. So you will be out of luck if you are trying to directly browse a client that does not support it - most likely, your browse request will time out after 30 seconds. Nufsi, who implemented direct browsing support for nap, writes: "Of the Napster-branded clients, only BETA 8 and BETA 9 support it, but even those clients don't support directly browsing a firewalled remote client. I think the only other client I found that supports direct browsing is Lopster."

Another caveat is that if your direct browsing request leads to an error of some kind, there is no way to stop it, and you will not be able to perform another search until the direct browsing request times out after 30 seconds. This is because, due to a bug in OpenNap, nap has no way of differentiating between an error due to a direct browsing request and any other kind of error.

#### 5.10. Sharing non-music files

By default, nap will only share files that it can validate as music files. Currently, this means files in the mp3 or Ogg Vorbis formats. Nap will generally refuse to share mp3 or ogg files that it recognizes as broken.

Since nap version 1.4.7, it is also possible to share non-music files. You have a certain amount of control over which types of files are shared through the `sharetypes` user variable. This variable contains a semicolon-separated list of case insensitive filename extensions, for example "jpg;jpeg;gif". The default is empty. Nap will share any files in your upload path which match one of these extensions. This is in addition to mp3 and ogg files, which nap will always share. Thus, there is no need to include "mp3" or "ogg" explicitly in the variable `sharetypes`. The extension "*" is special, as it matches all files.

Please note that whether a file is shared or not is decided at the time the library is built, not at the time the file is requested. Thus, any changes to `sharetypes` and `upload` do not take effect until you rebuild your library. You can use the `/update` or `/rebuild` commands to rebuild the library at any time. See also 7.5. Building your library.

#### 5.11. Managing uploads and downloads from the main screen [updated 1.5.0]

Prior to nap version 1.5.0, the download/upload screen did not exist. Instead there were a number of commands for managing uploads and downloads directly from the main screen. It is no longer really necessary to use these commands, but they are still available so we summarize them here.

To see the download list on the main screen, type `/pdown`. To delete the third download from the list, type

            /ddown 3

The corresponding commands for uploads are `/pup` and `/dup`. The command `/retry` can be used to retry a specific failed download, and the command `/retryall` can be used to retry all of them. To force a queued or stopped download to be (re)started immediately, use `/force`.

Stopped downloads or uploads can be purged from the lists with the commands `/purgedown` and `/purgeup`, or use `/purge` to clean up both the download and upload lists with a single command.

You can also limit the output of the `/pdown` command to certain classes of downloads. Just type

            /pdown [filter]

where filter is any combinations of the letters "d", "q", "s", "f". These stand respectively for "downloading", "queued", "succeeded", and "failed". If a filter is given, then only the respective downloads will be displayed.

## 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

You will no longer see that user's messages or files. If you have regrets later, you can also `/unignore` a user. To see a list of users you are currently ignoring, just type `/ignore` without any arguments.

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 channel). 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 channel

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, just type `/notify` without argument. `/hotlist` and `/unhotlist` are alternative names for `/notify` and `/unnotify`.

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 files

Nap uses a configuration file, by default `~/.nap/napconf`, to store information about your default settings. If the configuration file does not already exist, nap will prompt you for the relevant information and create a new configuration file. It is possible to edit this file if you want to change your default settings. The format of the configuration file looks something like this (except that the actual file is rather longer):

    # nap config file. Note: for boolean options, 1=true, 0=false

    # your napster username
    user=yourname

    # your napster password - optional
    pass=yourpasswd

    # your napster email address
    email=anon@napster.com

    # list of upload directories, separated by semicolon
    upload=/home/yourname/music

    # your download directory
    download=/home/yourname/download

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

    # 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

    # maximal number of simultaneous uploads allowed
    #maxuploads=

    # maximum number of simultaneous uploads per user
    #maxupuser=

    # maximum number of simultaneous downloads allowed
    #maxdownloads=

    # maximum number of simultaneous downloads per user
    #maxdownuser=

    # list of servers, separated by semicolon (note: this is now ignored
    # and overwritten unless nometa is set)
    #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 alternative 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.

There is also the possibility to read a global configuration file, usually called `/etc/naprc`. This file, which follows the same format as the user configuration file discussed above, is only read if it exists, and it is read after the user's configuration file. However, any options previously set will not be overwritten, so in effect, the user's configuration file takes precedence over the global one. It is even possible to change the location of the global configuration file by defining the variable `globalconfigfile` in the user's configuration file.

#### 7.2. User variables [updated 1.5.1]

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

            /set variable value
    and     /unset variable

to set a variable to a value, or to unset a variable. If you just type

            /set variable

then the current value of this variable will be displayed. Finally, if you just type `/set`, a list of all currently set variables and their values will be displayed.

Here is an alphabetical list of most user variables that have a special meaning.

- `announcepongs`: If this variable is set to 1, nap will announce when it receives a PONG packet from the server. I am not sure why this feature is useful, but it once used to be the default behavior, so I kept this in case someone needs it.
- `autopurge`: If this variable is set to a number, stopped item (i.e., failed, finished, incomplete, timed out) will be automatically deleted from the download list after this many seconds. If not set or set to -1, stopped items will remain in the download items indefinitely, until you explicitly remove them.
- `autopurgedown`: Like `autopurge`, but for downloads only.
- `autopurgeup`: Like `autopurge`, but for uploads only.
- `autoreply`: If this variable is set, it represents a string which will be sent as an automatic reply to any user who sends you a private message. This might be handy if you are running nap non-interactively, and you don't want to appear rude by not replying.
- `autorestart`: If this variable is set to 1, we attempt to automatically reconnect to a server when the connection to the server is lost. Same as the command line option of the same name.
- `bandwidthdown`: global limit on the bandwidth for downloads, in kB/s.
- `bandwidthdown1`: limit on the bandwidth of a single download, in kB/s.
- `bandwidthup`: global limit on the bandwidth for uploads, in kB/s.
- `bandwidthup1`: limit on the bandwidth of a single upload, in kB/s.
- `configfile`: Predictably, this is the name of your configuration file. I'm not sure why you would want to change it in the middle of a session, but you can.
- `connection`: Your connection speed. This is a number from 0 to 10. See the chart in the sample configuration file above.
- `connecttimeout`: The number of seconds until nap times out while making a connection to any one server. The default is 5 seconds. When set to 0, there is no timeout at all (which can cause nap to hang indefinitely when trying to connect to a non-responsive server).
- `cursorfollowsscreen`: If set to 1, the behavior of the "PgUp" and "PgDn" keys on the search result screen will be "cursor follows screen", else "screen follows cursor". In case you care.
- `dataport`: The port on your local machine which remote clients will connect to. It is advisable to give a range or ports, for instance, 6699-6799, in case your chosen port is already taken by another program. You should set this to 0 if you are behind a firewall.
- `debug`: This is the same as the debug level set with the "-d" option, or with the command `/debug`.
- `download`: Your download directory, i.e., where you want complete downloaded files to go. Incomplete files will go to the incomplete directory.
- `email`: Your email address, as sent to the server. It is perfectly acceptable to leave this blank. You can also set email addresses for different usernames by defining variables of the form `email.user`.
- `globalconfigfile`: The name of a global configuration file (default `/etc/naprc`) which is read after the user's configuration file, but in a special mode where no values that are already set are overwritten. This file is only read on startup.
- `hash`: If set, calculate MD5 hashes of shared files. This used to be the default until 1.5.0. But since most servers don't use the hashes anyway, by default, we don't calculate hashes any more. [new 1.5.1]
- `incomplete`: Your incomplete directory, i.e., where you want incomplete files to go. Completed downloads are moved to the download directory.
- `incompletesuffix`: The suffix added to the filenames of incomplete files. Default is ".incomplete".
- `libraryfile`: The location of your library file. The default is `~/.nap/shared` in your home directory.
- `logallfile`: If set, this is the name of a file to which everything that appears on the main screen will be logged.
- `logfile`: If set, this is the name of a file to which a record of all transfers (up- and downloads) will be logged.
- `maxdownloads`: limits the number of simultaneous downloads.
- `maxdownuser`: limits the number of simultaneous downloads for any one user.
- `maxuploads`: limits the number of simultaneous uploads.
- `maxupuser`: limits the number of simultaneous uploads for any one user.
- `metaserver`: the URL of a napigator-style metaserver to retrieve a server list from. The default is http://www.napigator.com/servers.php.
- `metatimeout`: If non-zero, this specifies the maximum number of seconds nap will spend trying to connect to the metaserver. The default is 5 seconds.
- `napping`: The name of the "napping" program to use. This can also be an absolute filename. The default is "napping" and is searched for in your $PATH. See also 5.2. Pings.
- `newstimeout`: If non-zero, this specifies the maximum number of seconds nap will spend looking for news about new releases while starting up. The default is 5 seconds.
- `noechosets`: If this is set to "1", then the `/set` command will not echo back its values to you.
- `nomasq`: Set this to "1" to disable filename masquerading. By default, nap hides the absolute pathnames of your upload directories from the server and other clients. For instance, if your upload directory is /home/username/music, and you are sharing a file /home/username/music/classical/Beethoven.mp3, then this will be reported to the server as /1/classical/Beethoven.mp3. Corresponding download requests will be converted to the original pathnames. [new 1.5.1]
- `nometa`: If set to "1", prevents nap from contacting the meta-server on startup. This is useful if you would like to specify your own "servers" variable in your config file.
- `nonews`: If set to "1", nap will not attempt to look for news about new releases while starting up.
- `noresultscreen`: If this is set to "1", search results will be listed on the main screen, and not on a special search results screen. You can then download files with the `/get` or `/g` command.
- `noscroll`: If this is set to "1", then the main screen does not automatically scroll to the bottom on output.
- `pass`: your napster password. You can also set passwords for different users by defining variables of the form `email.user`.
- `proxy`: if you are behind a firewall and need to use an http proxy to be able to access the world-wide web, then set `proxy` to the URL of your proxy server, e.g. `http://proxy.mydomain.com/`.
- `savechannels`: If set to "1" while quitting, nap will save your open channels to the file `~/.nap/channels-username`. If set to "1" while starting, load and join channels from that file.
- `savepass`: If this is set to "1", nap considers it okay to store your password in your configuration file. By default, nap will only store a "?", which means you will be promted for the password next time you start nap.
- `scrollsize`: If set, this defines a limit on the number of lines that are saved on the main screen. The default is 10000. If you set this to 0, there will be no limit.
- `sdefaults`: A string which determines the default layout of the search results screen. This is essentially a sequence of keystrokes which will be executed when the result screen is initialized, at the time the search results arrive. The default is "blsp". Use e.g. "ummU" to display only the user name, file size in bytes, and to sort by user names. Note: ping results and connection speeds are automatically turned off if that information is unavailable, so you may safely add them to your defaults.
- `servers`: A list of servers to connect to, separated by semicolons. This list is created automatically by connecting to www.napigator.com (see the `metaserver` user variable). Thus, whatever you specify in your config file will be overwritten, unless you set `nometa` to 1.
- `sharetypes`: A semicolon-separated, case-insensitive list of filename extensions to share in addition to mp3 and Ogg Vorbis files. The extension "*" is special and matches any file.
- `showtoomanyuploads`: If this is set to "1", display a message each time a remote client requests an upload but our upload limit is reached. Otherwise, handle it silently.
- `turdsize`: The size of the largest file which nap will consider a turd. Incomplete files of this or smaller size will be deleted.
- `upload`: A list of your upload directories (directories that contain files that you want to share). These have to be separated by semicolons.
- `user`: Your user name on napster.

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 `~/.nap/napconf`).

#### 7.3. Meta-servers

Normally, when starting up, nap downloads a list of available servers from http://www.napigator.com/servers.php. This list will be stored in the "servers" user variable and can be used for later `/reconnect` commands.

If you want the server list to be refreshed while you are already logged into nap, use the `/getservers` command. This will reset the "servers" user variable to the current list of available servers. If you want to leave the server that you are currently on and connect to the next available server on the list, type `/reconnect`. To see which server you are currently connected to, type `/server`. To connect to a specific server, type

            /server IP:port

To see the current list of servers, type `/set servers`.

The URL to look for a server list can be customized by setting the "metaserver" user variable to the desired URL. Note that the format of the servers file must be that used by napigator. The timeout for the connection to the metaserver can be set with the "metatimeout" variable. The default is 5 seconds. If you would like to define your own "servers" variable in you config file and do not want it to be overwritten on startup, add "nometa=1" to your config file.

It is still possible to specify a particular server to connect to on the command line. Whenever you specify a "-s" option on the command line, nap will respect this and not get a server list from the metaserver.

#### 7.4. Http proxies [new 1.5.0]

Nap uses the http protocol (the same protocol that is used by web browsers) to read the server list from napigator.com, and to check for news about new releases. If you are behind a firewall, you may need to use an http proxy to access the world-wide web. In this case, set the user variable `proxy` to the URL of your proxy server, for instance `http://proxy.mydomain.com/`. See 7.2. User variables.

#### 7.5. 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.6. "Some files in my upload directory don't show up on napster."

There are two common reasons why some of your files may not show up on the server. The first reason is that some napster servers attempt to block copyrighted content. In doing so, they often end up blocking non-copyrighted content as well.

The other reason some files do not show up is that nap does a basic sanity check on your music files before it adds them to your shared library. Nap will refuse to share music files that it considers broken, because such files would only pollute the network. Please consider repairing such files before you share them. 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 audible problems with mp3 files.

If you want to share non-music files, see 5.10. Sharing non-music files.

## 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".

To see a list of aliases currently defined, just type `/alias` without any arguments. To undefine an alias, use the `/unalias` command. 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. Warning: Handler code is not debugged very well and may cause program crashes.

The basic syntax for handlers is

            /handler code commands

where `code` is the napster message code in decimal. As with aliases, you can use "$1", "$3-5", "$2-" and so on to stand for selected parts of the incoming message. See napster.txt for the napster protocol specification.

The details of the syntax and semantics of aliases and handlers is a bit obscure, and to my knowledge they have not been documented anywhere. This part of the code is definitely very buggy. If you ever have any serious use for them (other than defining a shortcut for a command), 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.

You can also get nap to reconnect by sending it a SIGUSR1 signal:

            kill -USR1 process-id

This works both in daemon mode and in interactive mode. When nap receives this signal, it executes the /reconnect command.

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.

## 9. Obsolete features

#### 9.1. Creating a new napster account

This section is obsolete, since nap can no longer connect to the "official" Napster servers, and accounts do not need to be created on OpenNap servers. Thus, the "-m" option is now pretty much useless. That said, here is a description of what it does:

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.

## 10. 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 shared files 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 new account on server (obsolete)
    -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 title bar (fixes messed-up displays)
    -l, --nxterm           - try using a terminal which is compatible with most
                             systems (fixes some messed-up displays)
    -T, --transparent      - use terminal's default background instead of black
    -n, --noserver         - start up without connecting to a server [new 1.5.1]
    -f, --config fn        - config file to use (default $HOME/.nap/napconf)
    -x, --log fn           - log all transfers to a specific filename
    -g, --logall fn        - log everything to a specific filename
    -s, --server sv:port   - select a specific server (multiple -s opts possible)
    -d, --debug n          - set debug level
    -u, --user str         - specify napster username
    -p, --pass str         - specify user's password
    -e, --email str        - specify user's email address
    -U, --upload dir       - specify upload directory (multiple -U opts possible)
    -D, --download dir     - specify download directory
    -I, --incomplete dir   - specify directory for incomplete files
    -P, --dataport n-m     - specify port(s) to use for incoming upload requests
    -C, --connection n     - specify connection speed number (see README)
    -M, --maxuploads n     - specify maximum number of simultaneous uploads
    -o, --option var=value - set user variable

## 11. Summary of nap commands [updated 1.5.0]

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             browse2            cban
    cbanlist           chupload           clear              clearalias
    clearhandler       clist              clist2             cloak
    conf               cunban             ddown              dec
    debug              disconnect         dlul               dns
    done               dtimer             dup                echo
    eval               exec               fdown              finger
    force              fup                g                  get
    getservers         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             repeat             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 - Shows credits
/alias [name] [args] - Creates an alias, or lists current aliases
/aliaslist - Shows current list of aliases
/announce msg - Broadcasts a message to all users
/ban [user/IP] - Bans the specified user or IP, or lists banned users
/banlist - Prints a list of the current bans on the server
/block [IP] [reason] - Blocks the specified IP, or lists blocked users
/blocklist - Gives a list of current blocked users
/break - Breaks out of a loop
/browse user - Browses user's files
/browse2 user - Directly browses user's files
/cban [user] [reason] - Bans a user from a channel, or lists banned users
/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 config-string - Request a change in server configuration variables
/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 level - Sets debug level
/disconnect - Disconnects you from the server
/dlul - Switches to the download/upload monitor screen
/dns host/IP - Attempts to resolve the specified address
/done - Ends an alias
/dtimer [num] - Delete the timed event with the given number
/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
/fdown number or range - Gets information on the user as returned from /pdown
/finger user - Gets information on the specified user
/force number or range - Forces download of queued items, overriding download limit
/fup number or range - Gets information on the user as returned from /pup
/g number or range - Gets files by number as returned from /search
/get number or range - Gets files by number as returned from /search
/getservers - Read server list from napigator-style metaserver
/gusers - Gets a global list of users
/handler [code] [args] - Adds a handler, or lists current handlers
/handlerlist - Returns a list of handlers created
/help command - Returns help on the specified command
/hotlist [user] - Adds a user to your hotlist, or shows current hotlist
/if (val op val) cmd - Compares two values
/ignore [user] - Ignores a user, or lists all ignored users
/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, or lists all channels
/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] - Adds a user to your hotlist, or shows current 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 [dqsf] - Gives a listing of your current downloads. Optional flags select downloading, queued, succeeded, failed items.
/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 next available server on the list
/reloadconfig-variable - Resets server configuration parameter to its default value
/reloadm - Reloads the user command module (only if supported)
/repeat [min:sec] [cmd] - Initiates a timed event which repeats every interval
/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>speed] [-r>freq] [-s>size] [-d>duration] [-x exclude]... [-t filetype] [-mmaxresults] [-l] [-p] [-f] query - Searches the napster database
/serv [IP:port] - Connects to the specificed server and port, or shows current server and port
/server [IP:port] - Connects to the specificed server and port, or shows current server and port
/set [name] [value] - Sets a user variable, or prints current values
/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 type string - Send raw command to the server
/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
/unhotlist user - Removes a user from your hotlist
/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