STREAMRIPPER(1)						       STREAMRIPPER(1)



NAME
       streamripper - rip shoutcast radio streams to mp3 files

SYNOPSIS
       streamripper URL [options]

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

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 %q differ because %Q tries to figure out the  correct
       sequence	 number from the existing files, wherease %q does not.	The %q
       token takes an optional 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 con-
       nections 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 sep-
       arate  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	gener-
       ally 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  pre-
       fer  a single file (using the -a option), or you want to use streamrip-
       per as a relay (using the -r option),  without  creating	 these	files.
       Using  the  -A option, the individual files for each track are not cre-
       ated.

       -o (always | never | larger)
	      Overwrite tracks in complete directory

       When streamripper rips tracks they are put into the  incomplete	direc-
       tory  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 "-o larger" strategy is used.

       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.

       -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 incom-
       plete, it will overwrite the old track.	When you use the -t flag, how-
       ever, this will tell streamripper to backup the existing file in incom-
       plete (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	dupli-
       cate  files  will  normally stay in the incomplete folder.  This option
       tells streamripper to truncate the files to zero bytes  in  the	incom-
       plete 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.

       -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, both are
       included in the mp3 files generated by streamripper.  If	 you  use  the
       option, then neither are included.

       -k count
	      Skip over <count> tracks before starting to rip

       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.

       -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 <time-
       out> 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	 your-
       self 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  expres-
       sions.

       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 debug-
       ging information.

       --quiet
	      Quiet operation

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

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

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.

	 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 lis-
       ten  to your relay server open up XMMS or Winamp and enter your machine
       name with the port as you would any other stream.

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	 auto-
       matic 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_off-
       set + 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 sep-
       aration 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-2006 Gregory C. Sharp.  Free
       use of this software is granted under the terms of the GNU General Pub-
       lic License (GPL).



				13 August 2006		       STREAMRIPPER(1)