.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.TH "STREAMRIPPER" "1" "10 April 2005" "" ""

.SH NAME
streamripper \- rip shoutcast radio streams to mp3 files
.SH SYNOPSIS
.PP
\fBstreamripper\fR URL [options]
.SH "DESCRIPTION"
.PP
Streamripper records shoutcast and icecast compatible streams.  It uses
meta data within a shoutcast stream to determine the beginning and
end of each song, and stores the songs on your hard disk
as individual mp3 files.  In addition, streamripper includes
a relay server for listening to the station while you are recording.
.SH "OPTIONS"
.TP
\fB-h\fR
Print help and exit.
.TP
\fB-v\fR
Print version info and quit.
.TP
\fB-d dir\fR
The destination directory.
.PP
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.
.TP
\fB-s\fR
Don't create a directory for each stream.
.PP
Normally streamripper will
make a directory with the same name as the stream to place the tracks
into, this disables that.
.TP
\fB-r [base port]\fR
Create a relay server on base port, defaults to port 8000
.PP
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
that if the -z option is not used, it will keep trying higher
ports if the port is unavailable.
.TP
\fB-R num_conn\fR
Maximum connections to relay stream.
.PP
In addition to creating a relay server, you can also control how many
clients are allowed to simultaneously connect.  The default is 1 client,
but if you specify the -R option you can increase this number
to <num_conn> clients.  If <num_conn> is set to 0, the number of connections
is limited only by your processor and network speed.  The -R option has
no effect if -r was not used to create a relay stream.
.TP
\fB-z\fR
Don't scan for free ports if base port is not avail
.PP
Disables the "scan for free port" feature. use it if your paranoid. or
don't like ports being open.
.TP
\fB-p url\fR
Use HTTP proxy server at <url>
.PP
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.
.TP
\fB-a [file]\fR
Rip to single file.
.PP
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.
.TP
\fB-A\fR
Don't create individual tracks.
.PP
The default mode of operation is to create one file for each track.
But sometimes you don't want these files.  For example, you might
prefer a single file (using the -a option), or you want to use
streamripper as a relay (using the -r option), without creating
these files.  Using the -A option, the individual files for each
track are not created.
.TP
\fB-o\fR
Overwrite tracks in complete directory.
.PP
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.
.TP
\fB-t\fR
Don't overwrite tracks in incomplete directory.
.PP
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.
.PP
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.
.TP
\fB-T\fR
Truncate completed tracks in incomplete directory.
.PP
When you are not overwriting files in the complete folder, the
duplicate files will normally stay in the incomplete folder.  This
option tells streamripper to truncate the files to zero bytes
in the incomplete folder if they are a duplicate.
.TP
\fB-c\fR
Don't auto-reconnect.
.PP
Normally streamripper will be very aggressive and try to re-connect
to a dropped stream.  This option disables this behavior.
.TP
\fB-l seconds\fR
Run for a predetermined length of time, in seconds.
.PP
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.
.TP
\fB-M megabytes\fR
Stop ripping after this many megabytes.
.PP
Use this flag to tell streamripper to rip a certain number of
megabytes, then stop.
.TP
\fB-q\fR
Add sequence number to output filenames.
.PP
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.
.TP
\fB-P prefix\fR
Add prefix to each ripped file.
.PP
This prepends the prefix string to the filename of each individual
track file created by streamripper.
.TP
\fB-i\fR
Don't add ID3V1 Tags to output file.
.PP
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.
.TP
\fB-u useragent\fR
Use a different UserAgent than "Streamripper".
.PP
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.
.TP
\fB-w parse_file\fR
Use customized parsing rules.
.PP
This tells streamripper to use custom meta-data parsing rules.
Without this flag, streamripper will use its built-in parsing rules.
.PP
There are two cases where you want to do this.  In the first case,
you are using a stream that changes 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 meta-data.
.PP
The second case you might want to use this is if the artist and title
information is sent in an unusual format.  For example, they might be
separated by a comma instead of a hyphen, or there might be an
extra advertisement attached to the end of the meta-data string.
In this case, you can tell streamripper how it should identify the
title, artist, album and track from the metadata string using
regular expressions.
.PP
See the file parse_rules.txt, which is included in your distribution,
for examples of the parse rules.
.TP
\fB-k count\fR
Skip over <count> tracks before starting to rip.
.PP
Sometimes the first few tracks generated by a stream are not useful,
because they are advertisements, the station intro, broken songs, etc.
Use this option and these tracks won't be saved.
.TP
\fB-m timeout\fR
Timeout to restart connection.
.PP
Some streams will "hang", which means they haven't disconnected, but
they aren't sending any data.  When this happens, if you used the -m flag,
streamripper will shut down the stream and reconnect after <timeout>
seconds of inactivity.
.TP
\fB--debug\fR
Save debugging log.
.PP
This creates a file called "gcs.txt" that contains all sorts of
debugging information.
.TP
\fB--quiet\fR
Don't write any text to the console, except error messages.
.TP
\fB--xs_silence_length=num\fR
The volume must be less than xsd_min_volume for a period
of time greater than this.
.TP
\fB--xs_search_window=num:num\fR
This is how long to search for the silence.  1st number
is # msec before nominal center, 2nd number is # msecs after
nominal track change position.
.TP
\fB--xs_offset=num\fR
Offset from center of silence window.
.TP
\fB--xs_padding=num:num\fR
Amount to pad before and after splitpoint.
.SH "GETTING STARTED"
.PP
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.

.nf
  streamripper http://205.188.245.132:8038
.fi
.PP
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.
.PP
Also you can listen to the stream by creating a relay server..

.nf
  streamripper http://205.188.245.132:8038 -r
.fi
.PP
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.
.SH "SPLITPOINT DETECTION"
.PP
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.
.PP
Various --xs 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.
.SS "DEFAULT SPLITTING"
.PP
The default spitting algorithm is used when no silent point can be found.
Suppose you have a meta-int with track change information at the time "mi"
(see figure below).
.PP
If the xs_offset is positive, the track separation point "ts" is later
the "mi" point.  If xs_offset is negative, "ts" is earlier than "mi".
Once "ts" is determined, a user-defined "prepad" and "postpad"
are used to determine where the next track begins "ntb", and where
the previous track ends "pte".  The interval between "ntb" and "pte"
will be copied to both songs.
.sp
.RS

.nf
/mi
|
|           /ts
|-----------|
  xs_offset |
            |
            |
  /ntb      |         /pte
  |---------|---------|
    prepad    postpad
.fi
.RE
.SS "SILENCE SEPARATION"
.PP
Splitting based on silence separation is similar to default splitting,
only slightly more complex.  Again, suppose you have a meta-int
with track change information at the time "mi" (see figure below).
.PP
A search window "search_win" is determined by the xs_offset, pre_sw,
and post_sw field.  The beginning of the search window is at:
mi + xs_offset - pre_sw
and the end of the search window is at:
mi + xs_offset + post_sw.
.PP
If there is a silent interval of length "silence_win" within the
"search_win", the center of "silence_win" is selected as the
track separation point "ts".
.PP
Once "ts" is determined, a user-defined "prepad" and "postpad"
are used to determine where the next track begins "ntb", and where
the previous track ends "pte".  The interval between "ntb" and "pte"
will be copied to both songs.
.sp
.RS

.nf
    /mi
    |
    |-----------|
      xs_offset |
                |
            ts\\ |
      |-------+-|---------| *search_win
       pre_sw |   post_sw
              |
          |---+---| *silence_win
              |
/ntb          |         /pte
|-------------|---------|
      prepad    postpad
.fi
.RE
.SH "USAGE EXAMPLES"
.PP
Rip from a stream:

.nf
  streamripper URL
.fi
.PP
Rip from a stream for one hour:

.nf
  streamripper URL -l 3600
.fi
.PP
Rip the stream, putting the mp3 files into the directory /my/music/stream1:

.nf
  streamripper URL -d /my/music/stream1 -s
.fi
.PP
Rip the stream, creating a single file and don't create individual
tracks:

.nf
  streamripper URL -a -A
.fi
.PP
Rip from a stream and create a relay stream at port 9000:

.nf
  streamripper URL -r 9000
.fi
.PP
Rip from a stream, creating a relay stream at port 8000, and allowing
twenty clients to connect:

.nf
  streamripper URL -r -R 20
.fi
.SH "SPLITPOINT USAGE EXAMPLES"
.PP
Each of my songs contain about 5 seconds of the previous song.
How can I fix this?

.nf
  streamripper URL --xs_offset=5000
.fi
.PP
Each of my songs contain about 5 seconds of the next song.
How can I fix?

.nf
  streamripper URL --xs_offset=-5000
.fi
.PP
Each of my songs contain between 5 and 10 seconds of the previous
song, but it depends on the song.  How can I include all of this
zone within both songs, and edit them later?

.nf
  streamripper URL --xs_offset=7500 --xs_padding=2500:2500
.fi
.PP
or

.nf
  streamripper URL --xs_offset=5000 --xs_padding=0:5000
.fi
.SH "RESOURCES"
.PP
Please check out the following web
sites.  Linked to the streamripper home page is a forum that can
can be used to chat and ask questions.
.TP
\fBStreamripper home page:\fR
http://streamripper.sourceforge.net/
.TP
\fBSourceforge project page\fR
http://sourceforge.net/projects/streamripper
.TP
\fBShoutcast\fR
http://www.shoutcast.com
.TP
\fBIcecast\fR
http://www.icecast.org
.SH "COPYING"
.PP
Copyright (C) 2000-2002 Jon Clegg, (C) 2004-2005 Gregory C. Sharp.
Free use of this software is
granted under the terms of the GNU General Public License (GPL).