Provided by: streamripper_1.64.6-1_amd64 bug

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

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

       The pattern can be used in a manner similar to the -D flag, but generally 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 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.

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

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

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

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

       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 appending ";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
       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_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.

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