FreeRadio — NVDA Add-on

FreeRadio is an internet radio add-on for the NVDA screen reader. Its primary goal is to give users easy access to thousands of internet radio stations. The entire interface and all features have been designed with full accessibility for NVDA in mind.

Radio Browser Directory

FreeRadio uses the Radio Browser open database for its station catalogue. Radio Browser is a community-managed, free directory hosting more than 50,000 internet radio stations from around the world. No registration or account is required and its API is open to everyone. Each station includes address, country, genre, language and bitrate information; stations are ranked by user votes. FreeRadio connects to this API through mirror servers located in Germany, the Netherlands and Austria; if one server is unreachable, it automatically switches to the next.

Adding a Station to Radio Browser

If a station you are looking for is not in the Radio Browser directory, you can submit it yourself at https://www.radio-browser.info/add. No account or registration is needed.

Fill in the form on that page:

• Stream URL (required) — the direct URL of the audio stream, ending in .mp3, .aac, .ogg or similar. This is not the station website address; it is the raw stream address you would paste into a media player. Most stations publish their stream URL on their website or in their "Listen live" section.
• Station name (required) — the name of the station as it should appear in the directory.
• Homepage — the station's website address.
• Country and language — select the country and the broadcast language from the dropdown lists.
• Tags — genre or topic keywords separated by commas, for example news, jazz, classical. These are used for searching and filtering.
• Logo URL — a direct link to the station's logo image, if available.

After submitting, the station is reviewed and added to the public directory. Once accepted it will appear in FreeRadio's search and country listings automatically, since the directory is refreshed from the live API.

Requirements

• NVDA 2024.1 or later
• Windows 10 or later
• Internet connection

Installation

Download the .nvda-addon file, press Enter on it and restart NVDA when prompted.

Keyboard Shortcuts

All shortcuts can be reassigned from NVDA Menu → Preferences → Input Gestures → FreeRadio. These shortcuts work from anywhere, regardless of which window has focus.

Next / previous shortcuts only navigate the favourites list; they do not work with the all stations list. When a list is focused in the browser window, the left and right arrow keys serve the same purpose — see In-Dialog Shortcuts.

Station Browser

FreeRadio also adds a FreeRadio submenu to the NVDA Tools menu. From there you can directly open the Station Browser and FreeRadio Settings.

The window opened with Ctrl+Win+R contains five tabs: All Stations, Favourites, Recording, Timer, and Liked Songs. You can navigate between tabs with Ctrl+Tab.

When the All Stations tab opens, the top 1,000 most-voted stations are automatically loaded from Radio Browser. Selecting a country from the dropdown updates the list to show that country's stations. Typing in the search field instantly performs a full search across the entire Radio Browser database simultaneously by name, country and genre.

The Output Device dropdown at the bottom of the browser window — outside the tabs — lists all BASS-recognised audio output devices. Selecting a device immediately redirects audio output to it and saves the choice permanently; the same device is used automatically in the next session. If the selected device is not connected, the add-on falls back to the system default automatically. This control is only functional when the BASS backend is active.

The Volume (0–200) and Effects controls in the same area can be adjusted at any time while the window is open. From the Effects list, Chorus, Compressor, Distortion, Echo, Flanger, Gargle, Reverb, EQ: Bass Boost, EQ: Treble Boost and EQ: Vocal Boost can be enabled simultaneously; changes are applied to the active stream instantly. These controls are fully functional only when the BASS backend is active.

When one or more EQ effects are enabled, a gain control appears for each active band. The gain can be set between −15 dB and +15 dB; the default values are Bass +9 dB, Treble +9 dB, and Vocal +6 dB. The gain controls are shown only for the EQ bands that are currently checked, and are hidden automatically when an EQ effect is unchecked. Gain values are saved globally and restored on the next session.

The Play/Pause button is also located at the bottom of the window. If no station is playing it starts the selected station; if a station is already playing it pauses playback.

When a station is selected in the list, the Station Details button displays information such as country, language, genre, format, bitrate, website and stream URL in a separate dialog. Each field appears in its own read-only text box; you can move between fields with Tab and copy all information to the clipboard at once with the Copy all to clipboard button. This button is available in both the All Stations and Favourites tabs.

In-Dialog Shortcuts

The following keys work only while the Station Browser window is active.

F Keys

List and Navigation Shortcuts

Volume Shortcuts

Alt Key Shortcuts

Favourites

The favourites list is a personal station collection stored permanently. To add a station, select it in the list and press the Add to Favourites button or use the Alt+V shortcut. The same shortcut removes a station that is already in the list when it is selected.

Favourites can be played with Ctrl+Win+→ and Ctrl+Win+←; these shortcuts work even when the browser window is not open.

To delete a station from the favourites list, select it and press the Delete Station button or the Delete key. After deletion, focus and selection automatically move to the next station in the list. If the deleted station was the last one, focus moves to the previous station. If the list becomes empty, focus moves to the Play button.

Exporting and Importing Favourites

The Favourites tab includes two buttons for backing up and restoring your station list:

Export Favourites… — saves your entire favourites list to a file. A save dialog lets you choose between two formats: - JSON (.json) — a complete backup that preserves station names, stream URLs, and all metadata. Recommended for restoring your list later or moving it to another computer. - M3U playlist (.m3u) — a standard playlist format compatible with most media players and radio apps. Note that M3U does not store all station metadata, so restoring from M3U may result in less detail than a JSON backup.

Import Favourites… — loads stations from a previously exported JSON or M3U file. After selecting the file, you are asked how to add the stations: - Yes (Merge) — adds the imported stations to your existing list without removing any current favourites. Duplicate stations are not added twice. - No (Replace) — clears your current favourites list entirely and replaces it with the contents of the imported file. - Cancel — returns to the browser without making any changes.

After a successful import, the favourites list, scheduled-recording station list, and timer station list are all refreshed automatically.

Reordering Favourites

With a station selected in the Favourites tab, press comma to enter move mode — you will hear a beep. Navigate to the target position with the arrow keys, then press comma again. The station is placed at the chosen position and the new order is saved immediately. Pressing comma again at the same position cancels the move.

Direct Keyboard Shortcuts for Favourite Stations

Every station in your favourites list is registered as a separate script in NVDA's Input Gestures dialog, under the FreeRadio Stations category. You can assign any keyboard shortcut to any station and press it from anywhere — no need to open the browser window first.

To assign a shortcut:

1. Open NVDA Menu → Preferences → Input Gestures.
2. Expand the FreeRadio Stations category.
3. Find the station by name, select it, and press Add.
4. Press the desired key combination and confirm.

The shortcut activates the station immediately. If the station is later removed from your favourites, its entry disappears from the category and any shortcut assigned to it is automatically cleared by NVDA. When a new station is added to favourites, it appears in the category straight away — the Input Gestures dialog does not need to be reopened.

Adding a Custom Station

To add a station that is not in Radio Browser, use the Add Custom Station button. In the dialog that appears, enter the station name and stream URL to add it directly to your favourites. Custom stations can be played and reordered just like any other favourite.

Station Audio Profile

The Favourites tab includes two buttons for managing per-station audio settings:

Save Audio Profile for This Station — saves the current volume level, active effects (chorus, EQ, etc.), and EQ gain values as a profile tied to that specific station. Whenever that station starts playing, its saved volume, effects and gain settings are automatically applied, overriding the global defaults.

Clear Audio Profile — removes the saved audio profile from the selected station. After clearing, the station reverts to the global volume, effects and EQ gain settings. This button is only active when the selected station already has a saved profile.

Both buttons are located below the favourites list and are only enabled when a station in the list is selected.

Music Recognition

Pressing Ctrl+Win+I three times triggers Shazam-based music recognition for the currently playing stream. Recognition only starts when no ICY metadata (track info broadcast by the station) is available; if metadata is present, it is copied to the clipboard instead.

Recognition works as follows: a short audio sample is captured from the stream using ffmpeg, the Shazam fingerprinting algorithm is applied, and the result is sent to Shazam's servers. If recognition succeeds, the track title, artist, album and release year are announced by NVDA and automatically copied to the clipboard. If the Save liked songs to a text file option is enabled, the recognition result is also appended to likedSongs.txt.

Audio feedback: Two rising beeps sound when recognition starts, and two falling beeps when it ends. A short beep plays every 2 seconds while the process is running.

Requirement: ffmpeg.exe is required. An ffmpeg.exe placed in the add-on folder is used automatically; if it is in a different location, the path can be set in Settings. Download ffmpeg from ffmpeg.org.

Audio Mirror

The Ctrl+Win+M shortcut mirrors the currently playing stream to a second audio output device simultaneously. This is useful for listening on two different devices at the same time, such as speakers and headphones.

On first press, a selection dialog listing the available output devices appears. Once a device is chosen, mirroring begins and main playback continues uninterrupted. Pressing the shortcut again stops mirroring.

Use cases: - Speakers + headphones — Let a guest follow the same broadcast on headphones while you listen through the computer speakers. - Recording setup — Route the main output to speakers and the second output to an external recorder or audio interface for external capture. - Multi-room — Play through a Bluetooth speaker and the built-in speaker simultaneously; no extra software needed to carry audio to another room. - Remote monitoring — In a screen-sharing or remote desktop session, both the local and remote sides can hear the same stream simultaneously.

Note: Audio mirroring is only available when the BASS backend is active. If the volume is changed while mirroring is active, both outputs are updated simultaneously.

Recording

Recordings are saved to Documents\FreeRadio Recordings\ by default. The filename includes the station name (or song title, in song recording mode) and the recording start time. The recordings folder can be changed at any time from NVDA Menu → Preferences → Settings → FreeRadio → Recordings folder. Because the recording engine connects directly to the stream, the audio is written to disk as received — no processing or re-encoding is applied; recording quality is identical to the broadcast quality.

Instant recording: While a station is playing, press Ctrl+Win+E once. Press again to stop. Playback continues uninterrupted throughout.

Song recording: Press Ctrl+Win+E twice in quick succession while a station that broadcasts ICY metadata is playing. The recording starts immediately and is named after the current track title. When the track changes, the recording stops automatically and NVDA announces the saved filename. If you want to end the recording early before the track finishes, press Ctrl+Win+E twice again. If the current station does not broadcast ICY metadata, song recording is not available and NVDA will inform you.

Scheduled recording: Open the Recording tab in the browser. Select a station from your favourites, enter the start time in HH:MM format and the duration in minutes, select one or more active days, then choose a recurrence mode and a recording mode:

Active days: Check one or more days of the week. In single-recording mode, a separate entry is created for each selected day, each placed on the next upcoming occurrence of that day. In recurring mode, the recording repeats only on the checked days. If no days are checked, the recording is not restricted to specific days.

Recurrence: - Record once — records a single time on each selected day. Each entry is placed on the next upcoming occurrence of that day; if the selected time has already passed today, the entry moves to the same day next week automatically. - Repeat weekly — repeats every week on the selected active days until removed from the schedule list.

Recording mode: - Record while listening — plays and records simultaneously. A playback backend is started using the BASS → VLC → PotPlayer → Windows Media Player priority order. - Record only — records silently in the background without any audio output; the recording engine connects directly to the stream.

NVDA announces when a recording starts and when it finishes. If NVDA is restarted while a scheduled recording is active, the recording resumes automatically on startup.

Time-Shift (Rewind Live Radio)

Time-shift lets you rewind the station you're currently listening to, like a DVR or a cassette tape — pause the moment, go back a few minutes, and catch up to live again whenever you want. Playback never has to stop for this: rewinding and fast-forwarding both happen instantly on the same audio stream.

This feature is disabled by default. Enable it from NVDA Menu → Preferences → Settings → FreeRadio → Enable time-shift buffer (rewind live radio, ~10 minutes), or toggle it instantly at any time with Ctrl+Win+T.

How It Works

Once enabled, FreeRadio continuously captures the currently playing station into a rolling local buffer in the background, independently of normal playback. The buffer holds roughly the last 10 minutes of audio; older audio is automatically discarded from the front as new audio arrives, so the buffer always represents "the recent past" relative to the live edge.

• Ctrl+Win+J — Rewind 15 seconds. The first press switches you from live playback into time-shifted playback, starting 15 seconds behind the live edge. Each further press moves another 15 seconds further back, up to the buffer limit.
• Ctrl+Win+K — Fast-forward 15 seconds while time-shifted. Once you reach the live edge, playback automatically switches back to the live stream and NVDA announces "Back to live" — you don't need to do anything extra to resume normal listening.
• Ctrl+Win+T — Turns the whole feature on or off. Turning it off while time-shifted immediately returns you to live playback and stops the background capture for the current station.

Background capture keeps running the entire time you're time-shifted, so the live edge keeps moving forward even while you're listening to something a few minutes old — exactly like a real DVR.

Enabling and Buffer Warm-Up

The buffer starts filling as soon as a station starts playing (once the feature is enabled) or the moment you enable the feature while already listening to a station. Because of this, rewinding is only possible once a few seconds of audio have actually been captured — if you press Ctrl+Win+J immediately after switching stations, NVDA will let you know there isn't enough buffered audio yet. Simply wait a few seconds and try again.

Switching to a different station always restarts the buffer for the new station; the previous station's buffered audio is discarded.

Supported Streams

Time-shift works with the same range of streams FreeRadio already supports:

• Plain HTTP/HTTPS streams (MP3, AAC, OGG, etc.), including Shoutcast/Icecast-style servers.
• HLS (.m3u8) streams — FreeRadio resolves the station's master playlist, follows the media playlist, and downloads segments in the background to keep the buffer filled, the same way it works for plain streams.

In the rare case that a station's playlist cannot be read at all (for example, a broken or unreachable .m3u8 manifest), NVDA will tell you rewinding isn't available for that particular station.

Requirements and Limitations

• Requires the BASS backend. Time-shift is not available when BASS is disabled and playback falls back to VLC, PotPlayer, or Windows Media Player.
• The buffer is approximately 10 minutes; you cannot rewind further back than that.
• The buffer is per-station: switching stations, stopping playback, or restarting NVDA clears it and starts fresh.
• Time-shifted playback uses its own local buffer file and does not produce a saved recording — if you want to keep the audio permanently, use Instant Recording (Ctrl+Win+E) as well.

Timer

Open the Timer tab in the station browser (Alt+4). Two types of timer can be added:

Alarm — start radio: Automatically starts playing a selected station from your favourites at the specified time. Choose a station and enter the time in HH:MM format.

Sleep — stop radio: Stops playback at the specified time. When the timer fires, volume is gradually reduced over 60 seconds before playback stops. No station selection is needed; just enter the time.

For both types, if the entered time has already passed the action is scheduled for the following day. Adding a timer is blocked if another timer — of any type — already exists at the same time; a message informs you of the conflict and prompts you to remove the existing entry first. Pending timers are listed in the tab; select one and press the Remove Selected Timer button to cancel it.

Settings

The following options can be configured from NVDA Menu → Preferences → Settings → FreeRadio:

Mute Notifications

When Mute notifications is enabled in Settings, NVDA silences the following automatic announcements:

• Station name when a new station starts playing
• Playback state changes: play, pause, stop
• Recording events: started, stopped, finished (instant, song and scheduled recordings)
• ICY track change announcements, even when Auto-announce track changes is also enabled

The following announcements are intentionally not affected: error messages, favourites feedback (added / already in list), music recognition results, and update notifications.

The setting can be toggled from NVDA Menu → Preferences → Settings → FreeRadio, or instantly at any time via an unassigned input gesture (assign one from NVDA Menu → Preferences → Input Gestures → FreeRadio). When toggled, NVDA announces "Notifications muted" or "Notifications unmuted" once to confirm the change.

Auto-announce Track Changes

When the Auto-announce track changes option is enabled in Settings, FreeRadio checks the active station's ICY metadata stream in the background approximately every 5 seconds. When the track changes, the new title is automatically read by NVDA — no keypress required.

When switching to a new station, the first track info is announced as soon as the connection is established. If you switch to a station that does not broadcast ICY metadata, the system stays silent and the previous station's track info is not repeated.

This feature is disabled by default and can be toggled from NVDA Menu → Preferences → Settings → FreeRadio.

Liked Songs

When the Save liked songs to a text file option is enabled, track info copied to the clipboard by pressing Ctrl+Win+I three times is also appended line by line to Documents\FreeRadio Recordings\likedSongs.txt.

On stations that broadcast ICY metadata, the track title and artist are saved directly. On stations without ICY metadata, the Shazam recognition result is saved to the same file — both sources share the same list. The file is created automatically if it does not exist; each entry is appended to the end of the file and previous entries are never deleted.

Liked Songs Tab

The Liked Songs tab in the station browser displays all tracks saved in likedSongs.txt. The list is automatically reloaded from the file each time the tab is opened.

A Filter field above the list lets you narrow the displayed tracks in real time. Type any part of a song title or artist name and the list updates instantly on every keystroke. NVDA announces the number of matching results after each change. Press the Down arrow from the filter field to move focus directly into the list.

Selecting a track from the list enables the following actions:

• Play on Spotify: Tries to open the Spotify desktop app directly. If the app is not installed, falls back to the Spotify website and automatically starts playing the first result.
• Play on YouTube (Alt+O): Searches YouTube for the selected track and opens the results in the default browser.
• Show Lyrics: Fetches and displays the lyrics for the selected track. Lyrics are retrieved from lrclib.net (free, no account required). A short "Fetching lyrics…" message is announced while the search runs in the background. If lyrics are found, they open in a read-only dialog where you can read them with NVDA and copy them to the clipboard. If no lyrics are found, NVDA announces this. The button is temporarily disabled while a fetch is in progress to prevent duplicate requests.
• Remove (Alt+M): Deletes the selected track from likedSongs.txt and updates the list. The Delete key also triggers this button when the list is focused.
• Refresh (Alt+E): Reloads the list from the file.

The Spotify, YouTube, Show Lyrics, and Remove buttons are only enabled when a real track is selected in the list.

Lyrics Service

FreeRadio uses lrclib.net to fetch lyrics — a free, open database that requires no API key or account. The lookup process parses the track string stored in likedSongs.txt and tries progressively looser queries until lyrics are found:

1. Exact match using the full artist name and cleaned title (noise suffixes such as "Remastered", "Live", or year tags are stripped before searching).
2. Exact match using the full artist name and the original title (if cleaning changed it).
3. Exact match using only the first artist name and the cleaned title (for multi-artist strings such as "Artist A & Artist B").
4. Fuzzy search using the first artist name and the cleaned title.
5. Fuzzy search using the raw track string as a last resort.

When plain lyrics are available they are shown as-is. When only time-synced LRC lyrics are available, the timestamps are stripped and the plain text is shown. Instrumental tracks are reported as not found.

Playback

The add-on selects a playback backend using the following priority order:

1. BASS — the default and primary backend. No separate installation is required; it is bundled with the add-on. BASS sends audio directly to the Windows audio stack and appears in the Windows volume mixer as an independent audio source named "pythonw.exe", separate from NVDA. This means FreeRadio audio flows on a completely separate channel from NVDA speech: the radio does not cut out, mix with, or get affected by NVDA's own audio settings while NVDA is speaking. The user can adjust the radio volume independently from NVDA in the Windows Volume Mixer. Supports HTTP, HTTPS and most embedded stream formats. Audio mirroring is only available with this backend.
2. VLC — takes over if BASS fails. Searched automatically in common installation locations, user profile folders and the system PATH.
3. PotPlayer — tried if VLC is not found. Searched automatically in common installation locations.
4. Windows Media Player — used as a last resort; requires the WMP component to be installed on the system.

Update Check

FreeRadio automatically checks for new versions via GitHub.

Automatic check: Runs silently in the background 15 seconds after NVDA starts. If a new version is found, you are notified; if none is found, no message is shown.

Manual check: Can be triggered on demand from NVDA Tools → FreeRadio → Check for Updates…. When started this way, the result is announced even if the version is up to date.

When an update is found: A dialog opens showing the version number and your installed version.

• If a directly downloadable .nvda-addon file is available on the GitHub release, a Download and Install button is shown. Once confirmed, the file is downloaded in the background, NVDA announces when the download starts, and NVDA's own installation screen opens automatically.
• If no direct download link is available, an Open Page button is shown and the GitHub release page opens in the default browser.

To disable automatic checks: Turn off the Check for updates automatically option from NVDA Menu → Preferences → Settings → FreeRadio.

License

GPL v2