User Guide To RadioLover 1.4

RadioLover is an Internet radio recorder for Mac OS X.

With RadioLover you can record your favourite MP3 radio streams as separate songs. You can record radio shows and listen to them on your iPod or other MP3 device. If you like using iTunes, you will love RadioLover!

With RadioLover you can:

Users can record Internet radio so that they can listen to broadcasts when it is convenient for them. This is called time-shifting. It's the same principle as recording television broadcasts with a video recorder. Time-shifting with TiVos, VCRS and software such as RadioLover are giving users the freedom to listen or watch whatever they want, whenever they want. Now there's no excuse not to walk the dog!

Ever listened to a song on the radio, wanted to buy it, but not know the name of it? Many Internet radio stations send track and playlist information along with the broadcast, making it possible for RadioLover to divide recordings into songs. This makes it easy for users to learn about new music and find tracks in the iTunes music store or local record stores.

There are many audio formats in use today on the Internet. RadioLover supports one of the most popular audio formats called MP3.

RadioLover does not support other audio formats such as RealAudio or WindowsMedia. If you want to record these and other streams, you can do so with our other software iRecordMusic. It's free to download and test, so give it a spin!

RadioLover can be downloaded from the Bitcartel web-site.

RadioLover is distributed as a disk image. A disk image is a standard Mac OS X file.

RadioLover will run on any Apple Mac with:

Users running older versions of Mac OS X, such as OSX 10.1.5 (Puma) users should use StreamRipperX 1 .05

	Note
	Before releasing RadioLover, the author released StreamRipperX. RadioLover is a complete re-write from the ground up, designed for Mac OS X, with significant improvements. Note that RadioLover does not use any code from StreamRipperX, which was based on top of an open-source Unix tool called StreamRipper.

Note that there are no versions of RadioLover planned for either MacOS 9, or for the Windows platform.

From the download page, click the download link to download the latest version of RadioLo ver. The file you are downloading is a standard Mac OS X disk image. With Safari, the disk image should automatically mount and open a window in Finder.

Figure 2.1. Mounted Disk Image Window In Finder

If this does not happen, use the Finder to drag the downloaded file to Disk Copy, located in the Utilities folder of the Applications folder.

Once the disk image has mounted, a Finder window will appear that contains an icon for the RadioLover application. Simply drag this icon to your Applications folder, or wherever you like to keep your software. This copies the application from the temporary disk image onto your hard disk. The software is now installed and you can now eject the mounted RadioLover volume.

If you are upgrading from an earlier version, first remove the old version of the software from your system by deleting it, or moving it to the Trash, and then follow the installation instructions as above. It is not recommended that you simply drag'n'drop a new version over the old version.

If you would like to remove RadioLover completely from your system, remove the main application file, and also delete the following files depending on your version.

1.3 and up

HOME/Library/Application Support/RadioLover
HOME/Library/Preferences/com.bitcartel.radiolover.plist

Earlier than 1.3

HOME/Library/Preferences/RadioLover Preferences
HOME/Library/Preferences/org.bitcartel.radiolover.plist

That's it, you've finished the quick start guide to RadioLover - it really is that easy! So far we've only touched upon a few of the basic features, so read on to learn much more.

Internet radio stations are found with an Internet web address, commonly called a URL. This web address points to an audio stream which you can listen to with iTunes, and record with RadioLover. iTunes has a built-in radio tuner which lists many radio stations, but there are many more out there listed on websites. We'll list some sites later for you.

	Tip
	A web address for a radio station may change from week to week. One rule of thumb is that commercial radio stations to keep the same web address. In contrast, smaller Internet only stations, tend to change their web address frequently.

Open iTunes Radio Tuner and click on the genres to display some radio stations.

Figure 4.1. iTunes Radio Tuner

Open radio stations in iTunes by clicking the music genre's disclosure triangle

To transfer these radio stations to RadioLover, select the import menu on the toolbar. Selecting this option, you will import every radio station that is currently on display in the iTunes Radio Tuner. This takes a few seconds. Note that it is currently not possible to organise the imported stations by genre.

From the toolbar, you can manually add radio streams, create folders to organise them, and delete streams you don't like. Currently there is no undo feature. Each stream you record can be recorded differently, based on a recording style which you can customise. If you delete a stream, the recording style is still preserved.

The stream table lets you get an overview of the current state of RadioLover - whether there are any active or pending recordings, and which stream you are listening to.

Figure 5.1. The Table Of Radio Streams

Click the column headers to sort the column alphanumerically. You can sort streams by name, comment or bitrate.

The toolbar allows you to control recording, organise your favourite radio station, and set up scheduled recordings.

We will now describe the toolbar from left to right. The toolbar controls can be divided into three main groups, depending on their use. These groups are recording controls, stream management and stream recording options.

Recording styles were introduced in RadioLover v1.3. A recording style determines how a stream will be recorded, from how it will be split up, to whether or not recordings are added to iTunes. You can assign recording styles to streams, and if you remove the stream, the recording style can still be used again.

Select a stream in the table and click the Recording Style. A drawer will open, where you can select the recording style from the pull-down menu, and click open to edit a recording style. By default, the standard recording style is selected.

Figure 6.1. Recording Style Drawer

Assign and edit recording styles

On opening the recording style editor, you will see a window with pull-down menus. These menus allow you to save changes, delete and rename existing recording styles.

Figure 6.2. Recording Style Menus

Current selected recording style, and current set of options on display

Note that it is not possible to change the default Standard recording style. Any changes should be saved with the Save As menu option.

Figure 6.3. Save, Rename And Delete Recording Styles

Save, rename and delete recording styles

This section will explain options to split streams by song, by time, or by size.

Figure 6.4. Splitting Options

Splitting options let you split by song name, or by time or size of recording.

Before you start recording, you can select some options to ensure your recordings turn out exactly the way you want them. Want to break up long DJ mixes into 3 minute segments for easy iPod navigation? Or record 74 minute segments for easy burning to CD? Read on!

Most radio streams send track (or song) information with their broadcasts. This makes it possible for RadioLover to try and judge the point in time when one song ends, and another begins.

RadioLover will automatically look for the track data, and split recordings into individual tracks.

Some radio streams don't send track data at exactly the right time. Some song recordings may be split too late e.g. at the start of a song, so you have a few seconds of the previous song. For each RadioStream, you can tell RadioLover to split songs a few seconds earlier than normal, or later than normal.

If radio streams don't send any track information, it is not possible to record by song or track. In this case, RadioLover shifts to manual control:

It is sometimes useful to select the option "Ignore Track Information" to tell RadioLover not to automatically split a recording by song or track. Instead, the manul recording options are used. For example, if you are recording a 30 minute radio show, and you don't want the recording to be split into individual songs and jingles.

Split by time records based on the time limit you set. Note that the length of time is in calculated in real-time. It is not based on how much data should have been sent in a period of time, as often data is lost due to network congestion.

This section explains how to use tagging options to alter the information recorded with your MP3s.

Figure 6.5. Tagging Options

Tagging options affect how information such as artist, album, song name and genre are recorded in your MP3s.

Tagging helps you to organise and identify the recordings you make.

You can tell RadioLover to organise recordings by adding a sequence number to the start of filenames.

You can use these sequence numbers in the MP3 tags as the "track number". This is great for listening to the recording in the exact order as broadcast. Very useful for DJ mixes.

Sometimes you will see that there are missing track numbers in a sequence. This can happen for a number of reasons. The recording may have been very small, say a jingle, and may have been removed based on your settings in Preferences. Or the network connection may have been done, or the station disconnected you, resulting in a missing file or partial file.

If a radio stream only sends "Artist - Title" information, you can append an album name by using the radio station name instead.

The genre of recordings can be set to match the genre of the stream being recorded. You can change this to use a custom genre name if you wish.

This section shows you how to organise RadioLover recordings in iTunes.

Figure 6.6. iTunes Playlist Options

Recordings can be added to iTunes playlists automatically

If you decided to add recordings to iTunes, you should check to see if iTunes is currently set to copy files into its own music library when songs are added. You can check this in the iTunes Preferences. If so, you might want to select an option in RadioLover's Preferences to delete recordings once they have been added to iTunes, thus saving disk space.

You can select the default playlist RadioLover, or you can select one based on the stream name. Note that the stream name can be edited in the main table. Alternatively, if in your preferences you have set the stream name to be set based on the Radio Station's server, the playlist name will be based on this information. You can also choose to have a playlist named by genre. Genre information is sent by the radiostation, so a playlist might be named RadioLover - Jazz. Finally, you can enter your own playlist name.

If you use the scheduler, you might want to organise recordings by the date and time of the recording. So if you record from a stream manually and via the scheduler, you can distinguish the recordings based on the playlist name.

This section shows you how to tell RadioLover to interpret track information sent by a radio station.

Figure 6.7. Track Information Options

RadioLover has many options to customise track information interpretation.

Standard Options

A common pattern for MP3 streams is "Artist - Title". If the radio stream broadcasts in a different pattern, you can select another one from the pull-down menu.

Most information is separated by a separator character such as a hypen '-', but sometimes you might need to change this a comma or an underscore.

For radio stations that send song information in a different language encoding, you can select the language type from the pull-down menu. Changes take effect the next time you start recording.

Figure 6.8. Language Encoding Menu

Pull-down menu with language encodings

To verify the language encoding is correct, check the song title in the bottom right of the main window. RadioLover uses ID3v2 tags to store this information in the recording file, and they will be visible in iTunes and an iPods.

Figure 6.9. Korean Language Song Title

Language encodings affect how song information is displayed and saved

There's no need to stay up all night to listen to broadcasts from the other side of the world. RadioLover's built-in scheduler lets you schedule recordings so you never miss your favourite radio show. Important: You need to keep RadioLover running if you have scheduled a recording - don't quit the application! (We hope to address this issue in the future and enable RadioLover to wake up a computer from deep sleep). Using the scheduler, you can set up a recording schedule, similar to that of a VCR. To access the scheduler, select a radio stream and click the schedule icon in the toolbar. A drawer will open with the scheduling options.

Figure 7.1. The Scheduler

The scheduler lets you set up recording events

Decide if the show is a one-off, or a recurring programme. Enter the start and stop time of the show. Times are entered in the 12 hr clock format, and you can toggle the AM/PM indicator. Also enter a name for the show. The name can be used as an iTunes playlist name, where recordings are added. Read the section on Recording Styles to find out more about this.

When done, click the add button. Your schedule will be active. You can disable a schedule by clicking the checkbox.

To modify a schedule, select the schedule in the table, make some changes and then click the modify button which is enabled.

If a schedule is active, you will see a clock icon appear next to the radio stream. When the timer kicks off your recording, the clock will change to a red icon (similar to a VCR)

If the recording is interrupted, such as by a change of network location, the application will try to restart the recording every few seconds. If you quit the application, the next time RadioLover is launched, the scheduled recording will continue if necessary.

To stop a scheduled recording from starting, either disable it by clicking the active checkbox, or remove the entry from the list of scheduled recordings. Clicking the "Stop" button on the toolbar will not work - this is in case you click it by accident.

If you need to, you can also modify existing scheduled recordings.

Figure 8.1. Downloading Options

Select where to download recordings

By default, recordings are saved in a user's home directory, under the "Music" folder. Under this folder, recording are organised by radio station name. There will be folders with the name "incomplete", which are working folders, and may contain incomplete recordings. You can delete the contents of this working folder.

	Caution
	Do not save recordings into the iTunes Music Library folder. This folder is for the use of iTunes only, and if recordings are saved there, the behaviour of recordings in iTunes is unpredictable.

You can ignore duplicate recordings if you wish. Duplicate recordings are based on whether the track information which was sent by the radio station already exists in the download history.

You can clean up your download directory by ignoring small files - often a result of radio adverts and jingles, or the last few seconds of a song.

Disk safetly lets you stops recording if your download folder is running out of space. The limit is set to 100MB, and is recommended if you are saving to your boot volume (the disk which OSX is on). As reported on MacFixIt, and from personal experience, if your boot volume is running low on disk space many applications such as Mail and Safari can crash, and corrupt their respective user preference files.

Figure 8.2. Listening To Streams

You can listen to streams in RadioLover or Audion

When recording a radio stream, RadioLover can re-broadcast the radio stream on a local port on your computer. A port is identified by its number. Think of a television channel. This is how iTunes listens to a stream which RadioLover is recording.

Note that the recent release of iTunes 4.6 is exhibiting some strange behaviour when connecting to streams. If a stream has not connected properly in RadioLover, it is advised to not try to listen to the stream. We are investigating this issue.

If you prefer to listen with Audion 3, you can select this option and then Audion will be used instead of iTunes for listening to streams.

Figure 8.3. Connection Options

You can select re-connection policy, and make use of proxy servers

You can select the number of seconds to wait before disconnecting a stream if there is no incoming data. This could be due to your network connection being down, or network congestion on the Internet.

You can choose to auto-reconnect if a connection is dropped, or the connection cannot be established in the first place, or if some error halts recording midway through a broadcast. You can select the number of seconds before re-connecting. The lower the number, the more aggressive the policy, and the more background processing. Setting the wait to 0 seconds will re-connect the fastest.

RadioLover normally connects to radio stations based on the Network settings in your system preferences. If you are using a proxy server in your System Preferences, it will also be by RadioLover. However, you can choose to ignore the system setting and use a custom proxy server.

Figure 8.4. Miscellaneour Options

Miscellaneous settings that don't affect recording behaviour

Select the Aqua interface option if you prefer the Aqua interface or if you are using an older Mac, and you want to avoid the CPU overhead of the brushed metal look.

You can turn automatic version checking on or off. We recommend you keep this on so that each time you start RadioLover, you can find out if there are new upgrades available.