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 listen
       ing 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, options -q, -s, and -P will be ignored.  If
       the pattern represents an absolute  path,  the  -d  optoin
       will also be ignored.

       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 (parsing files to find it)
	   %q	     Sequence number (starting from zero)
	   %Nq	     Sequence number (starting from number N)
	   %%	     Percent sign

       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  con
       trol  how  many clients are allowed to simultaneously con
       nect.  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 avail

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

       -a [file]
	      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
       [file], a timestamped filename will automatically be used.

       -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     Overwrite tracks in complete directory

       When streamripper rips tracks they are first in the incom
       plete 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.

       -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, how
       ever, 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 streamrip
       per 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 (begin
       ning with 0001).	 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.

       -P prefix
	      Add prefix to each ripped file

       This  prepends  the  prefix string to the filename of each
       individual track file created by streamripper.

       -i     Don't add ID3V1 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,  but  you  can choose not to include the
       ID3V1 header if you like.

       -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 connec
       tion.  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  frag
       ments.	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.

       -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 discon
       nected, but they aren't sending any data.  When this  hap
       pens, if you used the -m flag, streamripper will shut down
       the stream and reconnect after <timeout> seconds of  inac
       tivity.

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

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

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 clicking 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  incom
       plete  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 listen 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  detec
       tion  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 capabili
       ties  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_off
       set, 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

       or

	 streamripper URL --xs_offset=5000 --xs_padding=0:5000

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



			   25 June 2005		  STREAMRIPPER(1)
