NAME
streamripper - rip shoutcast radio streams to mp3 files
SYNOPSIS
streamripper URL [options]
DESCRIPTION
Streamripper records shoutcast and icecast compatible streams, in their
native format. The following formats are supported: mp3, nsv, aac, and
ogg. The meta data within the stream are interpreted to determine the
beginning and end of each song, and stores the songs on your hard disk
as individual files. In addition, streamripper includes a relay server
for listening to the station while you are recording.
OPTIONS
-h
Print help and exit
-v
Print version info and quit
-d dir
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
Don´t create a directory for each stream
Normally streamripper will make a directory with the same name as the
stream to place the tracks into, this disables that.
-D pattern
Use a pattern to format the output file names
This option tells streamripper how to form the filenames. If -D is
used, the options -s and -P will be ignored. If the pattern represents
an absolute path, the -d option will also be ignored. If both -D and -q
are specified, -q will only be used to set the start count if a %q
token is included.
By default the output files are put in a directory that has the same
name as the stream, and files are formed from the artist and title. But
you can override this behavior and create the output files as you like.
The output file names are generated by substituting tokens with values
that depend on the stream, track, or environment. The following tokens
can be used for substitution.
%S Stream
%A Artist
%T Title
%a Album
%D Date and time (per song)
%d Date and time (per execution)
%q Sequence number (automatic detection)
%Nq Sequence number (starting from number N)
%% Percent sign
Note
On windows you may be required to supply an extra % because the symbol
is consumed by the shell. Therefore, you would put "%%S/%%A/%%T"
instead of "%S/%A/%T".
The extension (such as .mp3) is appended automatically.
The tokens %D and %d differ because %D gives a unique timestamp for
each song, whereas %d gives a unique timestamp each time streamripper
is run.
The tokens %q and %Nq differ because %q tries to figure out the correct
sequence number from the existing files, wherease %Nq does not. The N
is your starting number. For example %32q means start numbering at 32.
-r [base port]
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
that if the -z option is not used, it will keep trying higher ports if
the port is unavailable.
-R num_conn
Maximum connections to relay stream
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.
-z
Don´t scan for free ports if base port is not available
Disables the "scan for free port" feature. Use it if your paranoid, or
don´t like ports being open.
-p url
Use HTTP proxy server at <url>
If you are behind a proxy server, use the -p flag to specify its url.
You can also use the http_proxy environment variable to specify your
proxy server.
-a [pattern]
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
[pattern], a timestamped filename will automatically be used.
The pattern can be used in a manner similar to the -D flag, but
generally only %S, %q and %d are useful.
-A
Don´t create individual tracks
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.
-o (always | never | larger | version)
Overwrite tracks in complete directory
When streamripper rips tracks they are put into the incomplete
directory until they are finished. Normally, they are then moved into
the complete directory. However, when the track is already there, can
use this option to tell streamripper what you want to do. There are
three choices: always, never, and larger. If you don´t include any of
the -o options on the command line, the default is "-o larger" for
version through 1.63.4, and "-o version" starting with 1.64.5.
If you use the "-o never" option, this tells streamripper to never
overwrite any existing file in the complete directory.
If you use the "-o always" option, this tells streamripper to always
overwrite any existing file in the complete directory.
If you use the "-o larger" option, this tells streamripper to overwrite
an existing file in the complete directory if the newer file is larger.
If you use the "-o version" option, this tells streamripper to keep
both versions, renaming the existing file.
-t
Don´t overwrite tracks in incomplete directory
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.
-T
Truncate completed tracks in incomplete directory
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.
-c
Don´t auto-reconnect
Normally streamripper will be very aggressive and try to re-connect to
a dropped stream. This option disables this behavior.
-l seconds
Run for a predetermined length of time, in seconds
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.
-M megabytes
Stop ripping after this many megabytes
Use this flag to tell streamripper to rip a certain number of
megabytes, then stop. As of version 1.64.5, megabytes are defined as
2^20 bytes.
-q [start]
Add sequence number to output filenames
When the files are copied from incomplete to complete, the filename can
be prepended with a sequence number (beginning with 0000). This can be
used to, for example, show the order that the files were created. If
desired, a starting count can be used with -q to begin the sequence at
any number you like.
-i
Don´t add ID3 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, only ID3V2 is
included in the mp3 files generated by streamripper. If you use the
option, then neither are included.
--with-id3v1
Add ID3V1 tags to output file
--without-id3v2
Don´t add ID3V2 tags to output file
-k count
Specify the number of files to leave in the incomplete directory.
Usually you start ripping in the middle of the song, so the default is
to leave one file in the incomplete. But sometimes you want to discard
extra tracks generated by a stream, because they are advertisements,
the station intro, broken songs, etc. Conversely, some streams always
start you at the beginning of a complete song. In this case, you could
specify "-k 0" to save the first song.
-m timeout
Timeout to restart connection
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.
-u useragent
Use a different UserAgent than "Streamripper"
In the http request, streamripper includes a string that identifies
what kind of program is requesting the connection. By default it is the
string "Streamripper/1.x". Here you can decide to identify yourself as
a different agent if you like.
-w parse_file
Use customized parsing rules
This tells streamripper to use custom meta-data parsing rules. Without
this flag, streamripper will use its built-in parsing rules.
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.
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.
See the file parse_rules.txt, which is included in your distribution,
for examples of the parse rules.
-E external_command
Use external command to get track information
Some streams do not send artist or title information using metadata,
but instead send this information using other means. For example, some
streams update the current artist and title using html or xml. Another
example is icecast 1.x, which sends metadata through a UDP socket.
Streamripper can get artist and title information from these kinds of
streams using a helper application, specified using the -E option. The
helper application works by finding the title and artist, and writing
it to stdout. Streamripper reads the output of the helper program, and
splits the tracks accordingly.
To help you in creating external commands to use with streamripper,
please look at the example file fetch_external_metadata.pl, which is
included in your distribution.
--debug
Save debugging log
This creates a file called "gcs.txt" that contains all sorts of
debugging information.
--quiet
Quiet operation
Don´t write any text to the console, except error messages
--stderr
Write output to stderr instead of stdout
--xs_silence_length=num
Set silence duration
The volume must be less than xsd_min_volume for a period of time
greater than this.
--xs_search_window=num:num
Set search window duration
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.
--xs_offset=num
Set offset from center of silence window
--xs_padding=num:num
Set amount to pad before and after splitpoint. The 1st number is
the number of msec to add to the end of each song. The 2nd number
is the number of msec to add to the beginning of each song.
--xs-none
Don´t search for silent spot
This is a shorthand for the following combination of options:
--xs-search-window=0:0 --xs-silence-lenghth=0 --xs-offset=0
--xs-padding=0:0. Note, however, that streamripper will still decode
the stream in the region near the meta-data change, in order to split
at an exact mp3 frame boundary.
--xs2
Use capisce´s new algorithm (Apr 2008) for silence detection.
--codeset-filesys=codeset
Tells streamripper what codeset to use for the file names when it
writes to your hard drive.
--codeset-id3=codeset
Tells streamripper what codeset to use for the id3 information.
--codeset-metadata=codeset
Tells streamripper what codeset is being used for metadata in the
stream coming from the network.
--codeset-relay=codeset
Tells streamripper what codeset to use for metadata that it sends
to your player on the relay stream.
GETTING STARTED
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 click on the playlist). Once you
have the URL you can begin ripping. For example:
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.
LISTENING TO THE RELAY
You can listen to the stream while you are ripping by creating a relay
server. This is done by using the -r option.
streamripper http://205.188.245.132:8038 -r
When streamripper 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. For example,
if you are using the default relay stream, you would want to open up
this URL:
http://localhost:8000
However, if you are ripping an ogg stream, you usually need to tell the
player that the stream is ogg, which can be done by appending ".ogg" to
the stream URL.
http://localhost:8000/.ogg
Similarly, if you want to watch an nsv stream while you rip, you need
to tell the player that the stream is nsv, which can be done by
appending ";stream.nsv" to the URL.
http://localhost:8000/;stream.nsv
SPLITPOINT DETECTION
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 --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.
Default splitting
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).
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.
/mi
|
| /ts
|-----------|
xs_offset |
|
|
/ntb | /pte
|---------|---------|
prepad postpad
Silence separation
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).
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.
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".
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.
/mi
|
|-----------|
xs_offset |
|
ts\ |
|-------+-|---------| *search_win
pre_sw | post_sw
|
|---+---| *silence_win
|
/ntb | /pte
|-------------|---------|
prepad postpad
USAGE EXAMPLES
Rip from a stream:
streamripper URL
Rip from a stream for one hour:
streamripper URL -l 3600
Rip the stream, putting the mp3 files into the directory
/my/music/stream1:
streamripper URL -d /my/music/stream1 -s
Rip the stream, creating a single file and don´t create individual
tracks:
streamripper URL -a -A
Rip from a stream and create a relay stream at port 9000:
streamripper URL -r 9000
Rip from a stream, creating a relay stream at port 8000, and allowing
twenty clients to connect:
streamripper URL -r -R 20
SPLITPOINT USAGE EXAMPLES
Each of my songs contain about 5 seconds of the previous song. How can
I fix this?
streamripper URL --xs_offset=5000
Each of my songs contain about 5 seconds of the next song. How can I
fix?
streamripper URL --xs_offset=-5000
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?
streamripper URL --xs_offset=7500 --xs_padding=2500:2500
RESOURCES
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.
Streamripper home page:
http://streamripper.sourceforge.net/
Sourceforge project page
http://sourceforge.net/projects/streamripper
Shoutcast
http://www.shoutcast.com
Icecast
http://www.icecast.org
COPYING
Copyright © 2000-2002 Jon Clegg, © 2004-2009 Gregory C. Sharp. Free use
of this software is granted under the terms of the GNU General Public
License (GPL).
03/08/2009