1STREAMRIPPER(1) STREAMRIPPER(1)
2
3
4
5NAME
6 streamripper - rip shoutcast radio streams to mp3 files
7
8SYNOPSIS
9 streamripper URL [options]
10
11
12DESCRIPTION
13 Streamripper records shoutcast and icecast compatible streams, in their
14 native format. The following formats are supported: mp3, nsv, aac, and
15 ogg. The meta data within the stream are interpreted to determine the
16 beginning and end of each song, and stores the songs on your hard disk
17 as individual files. In addition, streamripper includes a relay server
18 for listening to the station while you are recording.
19
20
21OPTIONS
22 -h
23 Print help and exit
24
25 -v
26 Print version info and quit
27
28 -d dir
29 The destination directory
30 Select a different base directory for ripping, just in case you dont
31 want to dump tons of mp3s into whatever directory your at.
32
33 -s
34 Dont create a directory for each stream
35 Normally streamripper will make a directory with the same name as the
36 stream to place the tracks into, this disables that.
37
38 -D pattern
39 Use a pattern to format the output file names
40 This option tells streamripper how to form the filenames. If -D is
41 used, the options -s and -P will be ignored. If the pattern represents
42 an absolute path, the -d option will also be ignored. If both -D and -q
43 are specified, -q will only be used to set the start count if a %q
44 token is included.
45
46 By default the output files are put in a directory that has the same
47 name as the stream, and files are formed from the artist and title. But
48 you can override this behavior and create the output files as you like.
49 The output file names are generated by substituting tokens with values
50 that depend on the stream, track, or environment. The following tokens
51 can be used for substitution.
52
53
54 %S Stream
55 %A Artist
56 %T Title
57 %a Album
58 %D Date and time (per song)
59 %d Date and time (per execution)
60 %q Sequence number (automatic detection)
61 %Nq Sequence number (starting from number N)
62 %% Percent sign
63
64 Note
65 On windows you may be required to supply an extra % because the symbol
66 is consumed by the shell. Therefore, you would put "%%S/%%A/%%T"
67 instead of "%S/%A/%T".
68
69
70 The extension (such as .mp3) is appended automatically.
71
72 The tokens %D and %d differ because %D gives a unique timestamp for
73 each song, whereas %d gives a unique timestamp each time streamripper
74 is run.
75
76 The tokens %q and %Nq differ because %q tries to figure out the correct
77 sequence number from the existing files, wherease %Nq does not. The N
78 is your starting number. For example %32q means start numbering at 32.
79
80 -r [base port]
81 Create a relay server on base port, defaults to port 8000
82 Creates a relay server on base port. if base port is not specified it
83 defaults to 8000, otherwise whatever you entered for base port. Note
84 that if the -z option is not used, it will keep trying higher ports if
85 the port is unavailable.
86
87 -R num_conn
88 Maximum connections to relay stream
89 In addition to creating a relay server, you can also control how many
90 clients are allowed to simultaneously connect. The default is 1 client,
91 but if you specify the -R option you can increase this number to
92 <num_conn> clients. If <num_conn> is set to 0, the number of
93 connections is limited only by your processor and network speed. The -R
94 option has no effect if -r was not used to create a relay stream.
95
96 -z
97 Dont scan for free ports if base port is not available
98 Disables the "scan for free port" feature. Use it if your paranoid, or
99 dont like ports being open.
100
101 -p url
102 Use HTTP proxy server at <url>
103 If you are behind a proxy server, use the -p flag to specify its url.
104 You can also use the http_proxy environment variable to specify your
105 proxy server.
106
107 -a [pattern]
108 Rip to single file
109 The default mode of operation is to separate the each track into a
110 separate file. But sometimes this is not what you want. Sometimes you
111 want the stream recorded to a single (big) file without splitting into
112 tracks. The -a option does this. If you use -a without including the
113 [pattern], a timestamped filename will automatically be used.
114
115 The pattern can be used in a manner similar to the -D flag, but
116 generally only %S, %q and %d are useful.
117
118 -A
119 Dont create individual tracks
120 The default mode of operation is to create one file for each track. But
121 sometimes you dont want these files. For example, you might prefer a
122 single file (using the -a option), or you want to use streamripper as a
123 relay (using the -r option), without creating these files. Using the -A
124 option, the individual files for each track are not created.
125
126 -o (always | never | larger | version)
127 Overwrite tracks in complete directory
128 When streamripper rips tracks they are put into the incomplete
129 directory until they are finished. Normally, they are then moved into
130 the complete directory. However, when the track is already there, can
131 use this option to tell streamripper what you want to do. There are
132 three choices: always, never, and larger. If you dont include any of
133 the -o options on the command line, the default is "-o larger" for
134 version through 1.63.4, and "-o version" starting with 1.64.5.
135
136 If you use the "-o never" option, this tells streamripper to never
137 overwrite any existing file in the complete directory.
138
139 If you use the "-o always" option, this tells streamripper to always
140 overwrite any existing file in the complete directory.
141
142 If you use the "-o larger" option, this tells streamripper to overwrite
143 an existing file in the complete directory if the newer file is larger.
144
145 If you use the "-o version" option, this tells streamripper to keep
146 both versions, renaming the existing file.
147
148 -t
149 Dont overwrite tracks in incomplete directory
150 Normally streamripper writes the files in the incomplete directory, and
151 then moves it to the base directory (the complete directory) when it is
152 done. If the file with the name of the track already exists in
153 incomplete, it will overwrite the old track. When you use the -t flag,
154 however, this will tell streamripper to backup the existing file in
155 incomplete (appending a version number), and then create the new file.
156
157 This is useful for streams that dont have meta-data. Because these
158 streams only have a single file, reconnects will cause overwriting the
159 existing file, which is not desired.
160
161 -T
162 Truncate completed tracks in incomplete directory
163 When you are not overwriting files in the complete folder, the
164 duplicate files will normally stay in the incomplete folder. This
165 option tells streamripper to truncate the files to zero bytes in the
166 incomplete folder if they are a duplicate.
167
168 -c
169 Dont auto-reconnect
170 Normally streamripper will be very aggressive and try to re-connect to
171 a dropped stream. This option disables this behavior.
172
173 -l seconds
174 Run for a predetermined length of time, in seconds
175 Usually, streamripper runs until it crashes. Or rather, I meant to say
176 that it runs until you kill it, yes, Im sure thats what I meant. But
177 you can instead tell streamripper to run for a certain length of time,
178 and then exit using this flag.
179
180 -M megabytes
181 Stop ripping after this many megabytes
182 Use this flag to tell streamripper to rip a certain number of
183 megabytes, then stop. As of version 1.64.5, megabytes are defined as
184 2^20 bytes.
185
186 -q [start]
187 Add sequence number to output filenames
188 When the files are copied from incomplete to complete, the filename can
189 be prepended with a sequence number (beginning with 0000). This can be
190 used to, for example, show the order that the files were created. If
191 desired, a starting count can be used with -q to begin the sequence at
192 any number you like.
193
194 -i
195 Dont add ID3 tags to output file
196 Mp3 files have two different kinds of header information which describe
197 the contents of the file: ID3V1 and ID3V2. By default, only ID3V2 is
198 included in the mp3 files generated by streamripper. If you use the
199 option, then neither are included.
200
201 --with-id3v1
202 Add ID3V1 tags to output file
203
204 --without-id3v2
205 Dont add ID3V2 tags to output file
206
207 -k count
208 Specify the number of files to leave in the incomplete directory.
209 Usually you start ripping in the middle of the song, so the default is
210 to leave one file in the incomplete. But sometimes you want to discard
211 extra tracks generated by a stream, because they are advertisements,
212 the station intro, broken songs, etc. Conversely, some streams always
213 start you at the beginning of a complete song. In this case, you could
214 specify "-k 0" to save the first song.
215
216 -m timeout
217 Timeout to restart connection
218 Some streams will "hang", which means they havent disconnected, but
219 they arent sending any data. When this happens, if you used the -m
220 flag, streamripper will shut down the stream and reconnect after
221 <timeout> seconds of inactivity.
222
223 -u useragent
224 Use a different UserAgent than "Streamripper"
225 In the http request, streamripper includes a string that identifies
226 what kind of program is requesting the connection. By default it is the
227 string "Streamripper/1.x". Here you can decide to identify yourself as
228 a different agent if you like.
229
230 -w parse_file
231 Use customized parsing rules
232 This tells streamripper to use custom meta-data parsing rules. Without
233 this flag, streamripper will use its built-in parsing rules.
234
235 There are two cases where you want to do this. In the first case, you
236 are using a stream that changes the meta data within a song. Usually
237 this is a thank-you notice or possibly an advertisement for an upcoming
238 show. When this happens, the current track will become split into
239 fragments. To prevent this, you can tell streamripper to ignore
240 meta-data.
241
242 The second case you might want to use this is if the artist and title
243 information is sent in an unusual format. For example, they might be
244 separated by a comma instead of a hyphen, or there might be an extra
245 advertisement attached to the end of the meta-data string. In this
246 case, you can tell streamripper how it should identify the title,
247 artist, album and track from the metadata string using regular
248 expressions.
249
250 See the file parse_rules.txt, which is included in your distribution,
251 for examples of the parse rules.
252
253 -E external_command
254 Use external command to get track information
255 Some streams do not send artist or title information using metadata,
256 but instead send this information using other means. For example, some
257 streams update the current artist and title using html or xml. Another
258 example is icecast 1.x, which sends metadata through a UDP socket.
259
260 Streamripper can get artist and title information from these kinds of
261 streams using a helper application, specified using the -E option. The
262 helper application works by finding the title and artist, and writing
263 it to stdout. Streamripper reads the output of the helper program, and
264 splits the tracks accordingly.
265
266 To help you in creating external commands to use with streamripper,
267 please look at the example file fetch_external_metadata.pl, which is
268 included in your distribution.
269
270 --debug
271 Save debugging log
272 This creates a file called "gcs.txt" that contains all sorts of
273 debugging information.
274
275 --quiet
276 Quiet operation
277 Dont write any text to the console, except error messages
278
279 --stderr
280 Write output to stderr instead of stdout
281
282 --xs_silence_length=num
283 Set silence duration
284 The volume must be less than xsd_min_volume for a period of time
285 greater than this.
286
287 --xs_search_window=num:num
288 Set search window duration
289 This is how long to search for the silence. 1st number is msec before
290 nominal center, 2nd number is msecs after nominal track change
291 position.
292
293 --xs_offset=num
294 Set offset from center of silence window
295
296 --xs_padding=num:num
297 Set amount to pad before and after splitpoint. The 1st number is
298 the number of msec to add to the end of each song. The 2nd number
299 is the number of msec to add to the beginning of each song.
300
301 --xs-none
302 Dont search for silent spot
303 This is a shorthand for the following combination of options:
304 --xs-search-window=0:0 --xs-silence-lenghth=0 --xs-offset=0
305 --xs-padding=0:0. Note, however, that streamripper will still decode
306 the stream in the region near the meta-data change, in order to split
307 at an exact mp3 frame boundary.
308
309 --xs2
310 Use capisces new algorithm (Apr 2008) for silence detection.
311
312 --codeset-filesys=codeset
313 Tells streamripper what codeset to use for the file names when it
314 writes to your hard drive.
315
316 --codeset-id3=codeset
317 Tells streamripper what codeset to use for the id3 information.
318
319 --codeset-metadata=codeset
320 Tells streamripper what codeset is being used for metadata in the
321 stream coming from the network.
322
323 --codeset-relay=codeset
324 Tells streamripper what codeset to use for metadata that it sends
325 to your player on the relay stream.
326
327GETTING STARTED
328 The easiest way to get started is to find the URL of a stream you want
329 to rip, usually I find the URL by loading it up in winamp or xmms and
330 querying for the source URL (right click on the playlist). Once you
331 have the URL you can begin ripping. For example:
332
333
334 streamripper http://205.188.245.132:8038
335
336 This would rip Monkey Radio (as of 1/10/2001), it places the tracks
337 into two directorys one called "Monkey Radio" and a sub-directory
338 "Monkey Radio/incomplete" the incomplete directory is for tracks that
339 streamripper does not know the begging or end of. The first and last
340 tracks your rip for instance, would be in incomplete.
341
342
343LISTENING TO THE RELAY
344 You can listen to the stream while you are ripping by creating a relay
345 server. This is done by using the -r option.
346
347
348 streamripper http://205.188.245.132:8038 -r
349
350 When streamripper starts it will display what port its relaying the
351 stream on. It defaults to 8000 but you can choose another port. To
352 listen to your relay server, open up XMMS or Winamp and enter your
353 machine name with the port as you would any other stream. For example,
354 if you are using the default relay stream, you would want to open up
355 this URL:
356
357
358 http://localhost:8000
359
360 However, if you are ripping an ogg stream, you usually need to tell the
361 player that the stream is ogg, which can be done by appending ".ogg" to
362 the stream URL.
363
364
365 http://localhost:8000/.ogg
366
367 Similarly, if you want to watch an nsv stream while you rip, you need
368 to tell the player that the stream is nsv, which can be done by
369 appending ";stream.nsv" to the URL.
370
371
372 http://localhost:8000/;stream.nsv
373
374SPLITPOINT DETECTION
375 Streamripper automatically splits tracks based on detection of a silent
376 near the meta interval where the track changes. However, this method is
377 imperfect, and sometimes the track splitting occurs is too early or too
378 late. These options will fine tune the track splitting capabilities for
379 streams that use cross-fading, which causes streamrippers automatic
380 silence detection routine to fail.
381
382 Various --xs flags can be used to add an offset for streams that have a
383 meta interval that comes too early or too late, to add extra padding to
384 the beginning and end of each song, and to decide where the length of
385 the search window and silence window.
386
387
388 Default splitting
389 The default spitting algorithm is used when no silent point can be
390 found. Suppose you have a meta-int with track change information at the
391 time "mi" (see figure below).
392
393 If the xs_offset is positive, the track separation point "ts" is later
394 the "mi" point. If xs_offset is negative, "ts" is earlier than "mi".
395 Once "ts" is determined, a user-defined "prepad" and "postpad" are used
396 to determine where the next track begins "ntb", and where the previous
397 track ends "pte". The interval between "ntb" and "pte" will be copied
398 to both songs.
399
400
401 /mi
402 |
403 | /ts
404 |-----------|
405 xs_offset |
406 |
407 |
408 /ntb | /pte
409 |---------|---------|
410 prepad postpad
411
412 Silence separation
413 Splitting based on silence separation is similar to default splitting,
414 only slightly more complex. Again, suppose you have a meta-int with
415 track change information at the time "mi" (see figure below).
416
417 A search window "search_win" is determined by the xs_offset, pre_sw,
418 and post_sw field. The beginning of the search window is at: mi
419 xs_offset - pre_sw and the end of the search window is at: mi xs_offset
420 + post_sw.
421
422 If there is a silent interval of length "silence_win" within the
423 "search_win", the center of "silence_win" is selected as the track
424 separation point "ts".
425
426 Once "ts" is determined, a user-defined "prepad" and "postpad" are used
427 to determine where the next track begins "ntb", and where the previous
428 track ends "pte". The interval between "ntb" and "pte" will be copied
429 to both songs.
430
431
432 /mi
433 |
434 |-----------|
435 xs_offset |
436 |
437 ts\ |
438 |-------+-|---------| *search_win
439 pre_sw | post_sw
440 |
441 |---+---| *silence_win
442 |
443 /ntb | /pte
444 |-------------|---------|
445 prepad postpad
446
447USAGE EXAMPLES
448 Rip from a stream:
449
450
451 streamripper URL
452
453 Rip from a stream for one hour:
454
455
456 streamripper URL -l 3600
457
458 Rip the stream, putting the mp3 files into the directory
459 /my/music/stream1:
460
461
462 streamripper URL -d /my/music/stream1 -s
463
464 Rip the stream, creating a single file and dont create individual
465 tracks:
466
467
468 streamripper URL -a -A
469
470 Rip from a stream and create a relay stream at port 9000:
471
472
473 streamripper URL -r 9000
474
475 Rip from a stream, creating a relay stream at port 8000, and allowing
476 twenty clients to connect:
477
478
479 streamripper URL -r -R 20
480
481SPLITPOINT USAGE EXAMPLES
482 Each of my songs contain about 5 seconds of the previous song. How can
483 I fix this?
484
485
486 streamripper URL --xs_offset=5000
487
488 Each of my songs contain about 5 seconds of the next song. How can I
489 fix?
490
491
492 streamripper URL --xs_offset=-5000
493
494 Each of my songs contain between 5 and 10 seconds of the previous song,
495 but it depends on the song. How can I include all of this zone within
496 both songs, and edit them later?
497
498
499 streamripper URL --xs_offset=7500 --xs_padding=2500:2500
500
501RESOURCES
502 Please check out the following web sites. Linked to the streamripper
503 home page is a forum that can can be used to chat and ask questions.
504
505 Streamripper home page:
506
507 http://streamripper.sourceforge.net/
508
509 Sourceforge project page
510
511 http://sourceforge.net/projects/streamripper
512
513 Shoutcast
514
515 http://www.shoutcast.com
516
517 Icecast
518
519 http://www.icecast.org
520
521COPYING
522 Copyright 2000-2002 Jon Clegg, 2004-2009 Gregory C. Sharp. Free use
523 of this software is granted under the terms of the GNU General Public
524 License (GPL).
525
526
527
528
529 03/08/2009 STREAMRIPPER(1)
530