STREAMRIPPER(1) | STREAMRIPPER(1) |
NAME¶
streamripper - rip shoutcast radio streams to mp3 filesSYNOPSIS¶
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¶
-hPrint 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.
%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
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.
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.
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.
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.
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.
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
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
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.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)./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)./mi | |-----------| xs_offset | | ts\ | |-------+-|---------| *search_win pre_sw | post_sw | |---+---| *silence_win | /ntb | /pte |-------------|---------| prepad postpad
USAGE EXAMPLES¶
Rip from a stream:streamripper URL
streamripper URL -l 3600
streamripper URL -d /my/music/stream1 -s
streamripper URL -a -A
streamripper URL -r 9000
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
streamripper URL --xs_offset=-5000
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: Sourceforge project page Shoutcast IcecastCOPYING¶
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 |