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