STREAMRIPPER(1)

📦 version 1.64.6, in debian bookworm, debian trixie, nixos 26.05, nixpkgs unstable, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

🎀 STREAMRIPPER(1) 🎀

okay bestie, sit down, we are reading STREAMRIPPER(1) today and honestly? it's a whole moment ✨

✨ NAME ✨

streamripper — rip shoutcast radio streams to mp3 files 💖

🦋 SYNOPSIS 🦋

streamripper URL [options]

🌸 DESCRIPTION 🌸

Streamripper records shoutcast and icecast compatible streams, and it saves them in their native format. the formats it supports are, in order: mp3, nsv, aac, and ogg 🎧

the way it works is iconic, ngl — it reads the meta data inside the stream to figure out where each song begins and ends, and then it stores those songs on your hard disk as individual files. and if that wasn't enough, streamripper also comes with a relay server so you can listen to the station while you're recording it. multitasking queen 👑

💅 OPTIONS 💅

-h — print help and then exit. that's it, that's the whole thing 🫶
-v — print version info and quit.
-d dir — set the destination directory. pick a different base directory for ripping, for when you simply do not want to dump tons of mp3's into whatever directory you happen to be standing in 🙈
-s — don't create a directory for each stream. normally streamripper makes a directory with the same name as the stream and drops the tracks in there. this flag disables that entirely.
-D pattern — use a pattern to format the output file names. this option tells streamripper how to form the filenames. heads up though: if -D is used, the options -s and -P get ignored. and if the pattern represents an absolute path, then the -d option also gets ignored. oh and if you specify both -D and -q, then -q will only be used to set the start count if a %q token is included.

by default the output files go in a directory with the same name as the stream, and the files are formed from the artist and title. but you can override this behavior and create the output files however you like 💅

the output file names are generated by substituting tokens with values that depend on the stream, the track, or the environment. these are the tokens you can substitute:

%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 gets consumed by the shell. so you'd put "%%S/%%A/%%T" instead of "%S/%A/%T". noted, bestie.

the extension (like .mp3) is appended automatically.

the tokens %D and %d are different 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 are different because %q tries to figure out the correct sequence number from the existing files, whereas %Nq does not. the N is your starting number. so like, %32q means start numbering at 32 🔢

-r [base port] — create a relay server on the base port, defaults to port 8000. creates a relay server on the base port. if the base port isn't specified it defaults to 8000, otherwise it uses 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. determined 💪
-R num_conn — maximum connections to the relay stream. on top of making a relay server, you can also control how many clients are allowed to connect at the same time. the default is 1 client, but if you specify the -R option you can bump that number up 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 the base port isn't available. disables the "scan for free port" feature. use it if you're paranoid, or if you just don't like ports being open. valid tbh 🙈
-p url — use the HTTP proxy server at <url>. if you're 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 a single file. the default mode of operation splits every track into its own file. but sometimes that is simply not the vibe. sometimes you want the stream recorded to one big file with no track splitting at all. the -a option does exactly that. if you use -a without including the [pattern], a timestamped filename is used automatically.

the pattern can be used in a way similar to the -D flag, but generally only %S, %q and %d are useful here.

-A — don't create individual tracks. the default mode of operation creates one file per track. but sometimes you don't want those files at all. for example, maybe you'd rather have a single file (using the -a option), or you want to use streamripper as a relay (using the -r option) without creating those files. using the -A option, the individual files for each track are not created.
-o (always | never | larger | version) — overwrite tracks in the complete directory. when streamripper rips tracks, they get put into the incomplete directory until they're finished. normally they're then moved into the complete directory. but when the track is already there, you can use this option to tell streamripper what you want to do about it. 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 versions through 1.63.4, and -o version starting with 1.64.5. 👑

if you use the -o never option, that tells streamripper to never overwrite any existing file in the complete directory.

if you use the -o always option, that tells streamripper to always overwrite any existing file in the complete directory.

if you use the -o larger option, that tells streamripper to overwrite an existing file in the complete directory if the newer file is larger.

if you use the -o version option, that tells streamripper to keep both versions, renaming the existing file.

-t — don't overwrite tracks in the incomplete directory. normally streamripper writes the files into the incomplete directory, and then moves them to the base directory (the complete directory) once it's done. if a file with the name of the track already exists in incomplete, it will overwrite the old track. but when you use the -t flag, it tells streamripper to back up the existing file in incomplete (by appending a version number), and then create the new file.

this is useful for streams that don't have meta-data. because those streams only have a single file, reconnects would cause the existing file to be overwritten, which is not what you want 😭

-T — truncate completed tracks in the incomplete directory. when you're not overwriting files in the complete folder, the duplicate files will normally just stay in the incomplete folder. this option tells streamripper to truncate the files to zero bytes in the incomplete folder if they're a duplicate.
-c — don't auto-reconnect. normally streamripper is very aggressive and will try to re-connect to a dropped stream. this option disables that behavior entirely.
-l seconds — run for a predetermined length of time, in seconds. usually streamripper runs until it crashes. or rather — i meant to say 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 a 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 you want, a starting count can be used with -q to begin the sequence at any number you like 🔢
-i — don't add ID3 tags to the 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 this option, then neither is included.
--with-id3v1 — add ID3V1 tags to the output file.
--without-id3v2 — don't add ID3V2 tags to the output file.
-k count — specify the number of files to leave in the incomplete directory. usually you start ripping in the middle of a song, so the default is to leave one file in incomplete. but sometimes you want to discard extra tracks that the stream generates, because they're advertisements, the station intro, broken songs, etc. conversely, some streams always start you at the beginning of a complete song. in that case you could specify -k 0 to save the first song 💖
-m timeout — timeout to restart the connection. some streams will "hang", which means they haven't disconnected, but they aren't sending any data either. when that 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's the string "Streamripper/1.x". here you can decide to identify yourself as a different agent if you like. main character energy, choose your own name 💅
-w parse_file — use customized parsing rules. this tells streamripper to use custom meta-data parsing rules. without this flag, streamripper uses its built-in parsing rules.

there are two cases where you'd want to do this. in the first case, you're using a stream that changes the meta data within a song. usually this is a thank-you notice or maybe an advertisement for an upcoming show. when that happens, the current track gets 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 an external command to get track information. some streams don't 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.

okay so streamripper can also scoop the artist + title info out of these kinds of streams using a little helper app — you tell it which one with the -E option. The helper does its thing by finding the title and artist and writing it to stdout. Streamripper reads whatever the helper spits out and splits the tracks accordingly. ✨

And to help you build your own external commands to use with streamripper, please go look at the example file fetch_external_metadata.pl, which is included in your distribution. It's literally right there bestie, go check it 💖

--debug — save a 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. That's it, that's the whole vibe.
--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 the amount to pad before and after the 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 the 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. (And yes, copy that line exactly as written, no edits, ok? 💅)

--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 wanna 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, bestie 👑). 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), and it places the tracks into two directories — one called Monkey Radio and a sub-directory Monkey Radio/incomplete. The incomplete directory is for tracks that streamripper does not know the beginning or end of. So like, the first and last tracks of your rip, for instance, would be in incomplete. Periodt. 💅

🌈 LISTENING TO THE RELAY 🌈

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

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, just like you would any other stream. For example, if you're using the default relay stream, you'd want to open up this URL:

http://localhost:8000

However, if you're 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 silence near the meta interval where the track changes. However — and this is the tea 😭 — this method is imperfect, and sometimes the track splitting occurs 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 go.

Default splitting

The default splitting 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 than 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. (yes, go hang out, iykyk 🫶)

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 👑

and that's the whole page bestie!! this one's STREAMRIPPER(1) from the streamripper source, dated 03/08/2009 — go forth and rip, slay, and remember to read the docs fr fr 💅✨🦋

📦 where this page comes from

debian bookworm: streamripper 1.64.6-1+b2
debian trixie: streamripper 1.64.6-2 · GPL-2.0-only
nixos 26.05: streamripper 1.64.6
nixpkgs unstable: streamripper 1.64.6
ubuntu jammy: streamripper 1.64.6-1build1
ubuntu noble: streamripper 1.64.6-1build3
ubuntu resolute: streamripper 1.64.6-3 · GPL-2.0-only
ubuntu stonking: streamripper 1.64.6-4ubuntu1 · GPL-2.0-only
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms