Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

       streamripper - rip shoutcast radio streams to mp3 files

       streamripper URL	[options]

       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.

	   Print help and exit

	   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.

	   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

       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.

	   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.

	   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.

	   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.

	   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.

	   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.

	   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.

	   Add ID3V1 tags to output file

	   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

       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

       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, which is
       included	in your	distribution.

	   Save	debugging log
       This creates a file called "gcs.txt" that contains all sorts of
       debugging information.

	   Quiet operation
       Don't write any text to the console, except error messages

	   Write output	to stderr instead of stdout

	   Set silence duration
       The volume must be less than xsd_min_volume for a period	of time
       greater than this.

	   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

	   Set offset from center of silence window

	   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.

	   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.

	   Use capisce's new algorithm (Apr 2008) for silence detection.

	   Tells streamripper what codeset to use for the file names when it
	   writes to your hard drive.

	   Tells streamripper what codeset to use for the id3 information.

	   Tells streamripper what codeset is being used for metadata in the
	   stream coming from the network.

	   Tells streamripper what codeset to use for metadata that it sends
	   to your player on the relay stream.

       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:


       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.

       You can listen to the stream while you are ripping by creating a	relay
       server. This is done by using the -r option.

	     streamripper -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:


       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.


       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.


       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.

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

		 xs_offset |
		       ts\ |
		 |-------+-|---------| *search_win
		  pre_sw |   post_sw
		     |---+---| *silence_win
	   /ntb		 |	   /pte
		 prepad	   postpad

       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

	     streamripper URL -d /my/music/stream1 -s

       Rip the stream, creating	a single file and don't	create individual

	     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

       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

	     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

       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



       Copyright (C) 2000-2002 Jon Clegg, (C) 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		       STREAMRIPPER(1)


Want to link to this manual page? Use this URL:

home | help