s t r e a m r i p p e r  - v 1.60.X

by Jon Clegg

Introduction
~~~~~~~~~~~~
This readme is the official documentation for streamripper. If you
have any additional questions, please check out the following web
sites.  Linked to the streamripper home page is a forum that might 
can be used to chat and ask questions.

Streamripper home page:
http://streamripper.sourceforge.net/

Sourceforge project page:
http://sourceforge.net/projects/streamripper

Shoutcast: www.shoutcast.com
Icecast: www.icecast.org
ShoutClub: www.shoutclub.com

About Streamripper
~~~~~~~~~~~~~~~~~~
Streamripper records shoutcast compatible streams. Shoutcast style
streams contain "meta data" or track separation data, it uses that as
a marker for where the track should be separated, next the MP3 data is
decoded and scanned for a silent point which is where tracks will be
created. Finally, tracks are placed nicely on your hard drive with
appropriate names and separation.

Installation
~~~~~~~~~~~~
download the latest version from
ftp://streamripper.sourceforge.net/pub/streamripper and extract the
archive, then type in the following commands

./configure
make
make install

this works on FreeBSD 4.5, Linux 2.4 and OSX. If it doesn't work on
your setup let me know, I'll see what i can do.

Usage
~~~~~
The easiest way to get started is to find the URL of a stream you want
to rip, usually I find the URL by loading it up in winamp or xmms and
querying for the source URL. (right clicking on the playlist) 
Once you have the URL you can begin ripping.

streamripper http://205.188.245.132:8038

This would rip Monkey Radio (as of 1/10/2001), it places the tracks
into two directory's one called "Monkey Radio" and a sub-directory
"Monkey Radio/incomplete" the incomplete directory is for tracks that
streamripper does not know the begging or end of. the first and last
tracks your rip for instance, would be in incomplete.

also you can listen to the stream by creating a relay server..

streamripper http://205.188.245.132:8038 -r

When the program starts it will display what port it's relaying the
stream on, it defaults to 8000 but you can choose another port. To
listen to your relay server open up XMMS or Winamp and enter your
machine name with the port as you would any other stream.

Command line parameters
~~~~~~~~~~~~~~~~~~~~~~~
-a <file>      - Optional: Rip to single file

The default mode of operation is to separate the each track into a 
separate file.  But sometimes this is not what you want.  Sometimes you 
want the stream recorded to a single (big) file without splitting 
into tracks.  The -a option does this.  If you use -a without including 
the <file>, a timestamped filename will automatically be used.

-d <dir>       - Optional: The destination directory

Select a different base directory for ripping. just in case you don't
want to dump tons of mp3's into whatever directory your at.

-s             - Optional: Don't create a directory for each stream

I don't know why you wouldn't want this. Normally streamripper will
make a directory with the same name as the stream to place the tracks
into, this disables that.

-r <base port> - Optional: Create a relay server on base port,
                           defaults to port 8000 

Creates a relay server on base port. if base port is not specified it
defaults to 8000, otherwise whatever you entered for base port. NOTE:
without the -z option, it will keep trying higher ports if the port is
unavailable.

-z             - Optional: Don't scan for free ports if base port is not avail

Disables the "scan for free port" feature. use it if your paranoid. or
don't like ports being open.

-p <url>       - Optional: Use HTTP proxy server at <url>

If your behind a proxy server, enter it here. This hasn't been tested
in over 6 months. but it should still work. Please till me if it
doesn't.

-o             - Optional: Overwrite tracks in complete

When streamripper rips tracks they are first in the incomplete
directory. if the tracks finishes properly it moves over to the main
directory, but if they track is already there it doesn't. this make
streamripper copy over tracks that already exist in the main
directory. I didn't make this default because if your ripping a stream
for a long time (trying to get the whole thing) it helps to see the
incomplete directory fill up with tracks you already have. One the
incomplete directory is as large (or larger) then your main directory
you can be pretty sure you've got the whole stream.

-t             - Optional: Don't overwrite tracks in incomplete

Normally streamripper writes the files in the incomplete directory, and
then moves it to the base directory (the complete directory) when it
is done.  If the file with the name of the track already exists in 
incomplete, it will overwrite the old track.  When you use the -t
flag, however, this will tell streamripper to backup the existing file
in incomplete (appending a version number), and then create the new file.

This is useful for streams that don't have meta-data.  Because these
streams only have a single file, reconnects will cause overwriting the
existing file, which is not desired.

-c             - Optional: Don't auto-reconnect

Once again, not sure why you wouldn't want this. Normally streamripper
will be very aggressive and try to re-connect to a dropped stream,
this disables that.

-v             - Optional: Print version info and quit

Not surpisingly, this option will print the version number and quit.

-l <seconds>   - Optional: Number of seconds to run, otherwise runs forever

Usually, streamripper runs until it crashes.  Or rather, I meant to
say that it runs until you kill it, yes, I'm sure that's what I meant.  
But you can instead tell streamripper to run for a certain length of 
time, and then exit using this flag.

-q             - Optional: Add sequence number to output file

When the files are copied from incomplete to complete, the filename 
can be prepended with a sequence number (beginning with 0001).  This can
be used to, for example, show the order that the files were created.

-i             - Optional: Don't add ID3V1 Tags to output file

Mp3 files have two different kinds of header information which describe
the contents of the file: ID3V1 and ID3V2.  By default, both are included
in the mp3 files generated by streamripper, but you can choose not to 
include the ID3V1 header if you like.

-u <useragent> - Optional: Use a different UserAgent than "Streamripper"

In the http request, streamripper includes a string that identifies 
what kind of program is requesting the connection.  Be default it is 
the string "Streamripper/1.x".  Here you can decide to identify 
yourself as a different agent if you like.

-f <dstring>   - Optional: Don't create new track if metainfo 
                           contains <dstring>

Some streams change the meta data within a song.  Usually this is 
a thank-you notice or possibly an advertisement for an upcoming show.
When this happens, the current track will become split into fragments.
To prevent this, you can tell streamripper to ignore track changes
which contain <dstring> as a substring.

--xs           - Optional: Various options for fine-tuning track splitting.

Streamripper automatically splits tracks based on detection of a
silent near the meta interval where the track changes. However, this
method is imperfect, and sometimes the track splitting occurs is too
early or too late.  These options will fine tune the track 
splitting capabilities for streams that use cross-fading,
which causes streamripper's automatic silence detection routine to
fail.  

Various flags can be used to add an offset for streams that have a
meta interval that comes too early or too late, to add extra padding
to the beginning and end of each song, and to decide where the length
of the search window and silence window.  See readme_xfade.txt for details.

Bugs
~~~~
* Track separation is not an exact science, it will fail retardedly at
times. Sometimes streamripper hasn't buffered enough back to ever hear
the previous track, other times the track has a pockets of silence in
he beginning and end, hopefully it works well 95% of the time.
