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

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

	 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 append-
       ing ";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	 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-2007 Gregory C. Sharp.  Free
       use of this software is granted under the terms of the GNU General Pub-
       lic License (GPL).



				  19 May 2007		       STREAMRIPPER(1)
