# Demo
### Features
- [x] Supports more than 40K stations !! :radio:
- [x] Record audio from live radio on demand :zap:
- [x] Get song information on run-time 🎶
- [x] Shazam identification of tracks
- [x] Saves last station information
- [x] Favorite stations :heart:
- [x] Selection menu for favorite stations
- [x] Supports user-added stations :wrench:
- [x] Looks minimal and user-friendly
- [x] Runs on Raspberry Pi
- [x] Finds nearby stations
- [x] Discovers stations by genre
- [x] Discovers stations by language
- [x] VLC, MPV player support
- [x] Default config file
- [x] Result limit (default 100)
- [x] Sleep Timer (pomodoro) ⏲️
- [x] History/Recently Played stations
- [x] Scheduled Recording
- [x] I'm feeling lucky! Play Random stations
> See my progress ➡️ [here](https://github.com/users/dpnkrpl/projects/5)
🎊🎊 For developer's guides and detailed architecture refer to this wiki: https://deepwiki.com/dpnkrpl/radio-active
[](https://deepwiki.com/dpnkrpl/radio-active)
### Why radioactive?
While there are various CLI-based radio players like [PyRadio](https://github.com/coderholic/pyradio) and [TERA](https://github.com/shinokada/tera), Radioactive stands out for its simplicity. It's designed to work seamlessly right from the start. You don't need to be a hardcore Linux or Vim expert to enjoy radio stations with Radioactive. The goal of Radioactive is to offer a straightforward user interface that's easy to grasp and comes preconfigured, without unnecessary complexities.
### In the Spotlight
The praise from YouTube channels and blogs underscores Radioactive's emergence as a top choice for radio enthusiasts. Its simple yet powerful features, make it a must-try application for radio lovers of all expertise levels. Discover the world of radio with ease – experience Radioactive today.
1. See DistroTube YouTube channel talks about my app: https://www.youtube.com/watch?v=H7sf1RDFXpU&pp=ygUYcmFkaW9hY3RpdmUgcGxheWVyIHJhZGlv
2. Ubunlog: https://ubunlog.com/en/radio-activate-an-application-to-listen-to-the-radio-from-the-terminal/
3. LinuxLinks: https://www.linuxlinks.com/radio-active-listen-radio-terminal/3/
4. Official entry in the RadioBrowser API: [https://www.radio-browser.info/users](https://www.radio-browser.info/users#:~:text=Sources-,radio%2Dactive,-Sources)
5. ThingsAndStuff: https://wiki.thingsandstuff.org/Streaming#:~:text=com/billniakas/bash_radio_gr-,radio%2Dactive,-https%3A//github.com
6. Awesome-stars: https://arbal.github.io/awesome-stars/#:~:text=dpnkrpl/radio%2Dactive%20%2D%20Play%20any%20radios%20around%20the%20globe%20right%20from%20the%20terminal%20%3Azap%3A
7. OpenSourceAgenda: https://www.opensourceagenda.com/projects/my-awesome-stars#:~:text=dpnkrpl/radio%2Dactive%20%2D%20Play%20any%20radios%20around%20the%20globe%20right%20from%20the%20terminal%20%3Azap%3A
### Install
Simply run: `pip3 install --upgrade radio-active`
I recommend installing it using `pipx install radio-active`
#### TODO:
- [ ] Create deb, rpm and exe packages
- [ ] Add it to various Linux distribution package repositories.
- [ ] Add to scoop, chocolately
### External Dependency
It needs [FFmpeg](https://ffmpeg.org/download.html) to be installed on your
system in order to record the audio
on Ubuntu-based system >= 20.04 Run
```
sudo apt update
sudo apt install ffmpeg
```
For other systems including Windows see the above link
#### Installing FFmpeg
FFmpeg is required for this program to work correctly. Install FFmpeg by following these steps:-
- On Linux -
- On Windows -
### Run
Search a station with `radio --search [STATION_NAME]` or simply `radio` :zap: to select from the favorite menu.
### Tips
1. Use a modern terminal emulator, otherwise the UI might break! (gets too ugly sometimes)
2. On Windows, instead of the default Command Prompt, use the new Windows Terminal or web-based emulators like Hyper, Cmdr, Terminus, etc. for better UI
3. Let the app run for at least 5 seconds (not a serious issue though, for better performance)
### Demo
#### Scheduled Recording
To schedule a recording:
`radio --record-at "18:30" --uuid "96444e20-0601-11e8-ae97-52543be04c81" --filename "evening_jazz" --duration 30`
This will countdown until 18:30, then record the station for 30 minutes, and exit.
### Demo
### Options
| Options | Note | Description | Default | Values |
| ------------------ | -------- | ---------------------------------------------- | ------------- | ---------------------- |
| (No Option) | Optional | Select a station from menu to play | False | |
| `--search`, `-S` | Optional | Station name | None | |
| `--play`, `-P` | Optional | A station from fav list or url for direct play | None | |
| `--country`, `-C` | Optional | Discover stations by country code | False | |
| `--state` | Optional | Discover stations by country state | False | |
| `--language` | optional | Discover stations by | False | |
| `--tag` | Optional | Discover stations by tags/genre | False | |
| `--uuid`, `-U` | Optional | ID of the station | None | |
| `--record` , `-R` | Optional | Record a station and save to file | False | |
| `--record-at` | Optional | Start recording at a specific time (HH:MM) | None | HH:MM (24h) |
| `--duration` | Optional | Duration of recording in minutes | None | Minutes |
| `--filename`, `-N` | Optional | Filename to used to save the recorded audio | None | |
| `--filepath` | Optional | Path to save the recordings | `~/radioactive/recordings` | |
| `--filetype`, `-T` | Optional | Format of the recording | mp3 | `mp3`,`auto` |
| `--last` | Optional | Play last played station | False | |
| `--random` | Optional | Play a random station from favorite list | False | |
| `--sort` | Optional | Sort the result page | votes | |
| `--filter` | Optional | Filter search results | None | |
| `--limit` | Optional | Limit the # of results in the Discover table | 100 | |
| `--volume` , `-V` | Optional | Change the volume passed into ffplay | 80 | [0-100] |
| `--favorite`, `-F` | Optional | Add current station to fav list | False | |
| `--add` , `-A` | Optional | Add an entry to fav list | False | |
| `--list`, `-W` | Optional | Show fav list | False | |
| `--remove` | Optional | Remove entries from favorite list | False | |
| `--flush` | Optional | Remove all the entries from fav list | False | |
| `--history` | Optional | Show recently played stations | False | |
| `--kill` , `-K` | Optional | Kill background radios. | False | |
| `--loglevel` | Optional | Log level of the program | Info | `info`, `warning`, `error`, `debug` |
| `--player` | Optional | Media player to use | ffplay | `vlc`, `mpv`, `ffplay` |
> [!NOTE]
> Once you save/play at least one station, invoking `radio` without any options will show a selection menu
> `--search`, `-S`: Search for a station online.
> `--play`, `-P`: You can pass an exact name from your favorite stations or alternatively pass any direct stream URL. This would bypass any user selection menu (useful when running from another script)
> `--uuid`,`-U`: When station names are too long or confusing (or multiple
> results for the same name) use the station's uuid to play. --uuid gets the
> greater priority than `--search`. Example: 96444e20-0601-11e8-ae97-52543be04c81. type `u` on the runtime command to get the UUID of a station.
> `--loglevel`,: Don't need to specify unless you are developing it. `info`, `warning`, `error`, `debug`
> `-F`: Add the current station to your favorite list. Example: `-F my_fav_1`
> `-A`: Add any stations to your list. You can add stations that are not currently available on our API. When adding a new station enter a name and direct URL to the audio stream.
> `--limit`: Specify how many search results should be displayed.
> `--filetype`: Specify the extension of the final recording file. default is `mp3`. you can provide `-T auto` to autodetect the codec and set file extension accordingly (in original form).
> `--record-at`: Schedule a recording to start at a specific local time (HH:MM 24-hour format). Requires `--uuid`, `--filename`, and `--duration` to be specified.
> `--duration`: Specify the recording duration in minutes. Required for scheduled recording.
### Runtime Commands
Radioactive features a modern, **Vim-style command bar** at the bottom of the screen. Instead of the old prompt, you now see a subtle `:` where you can type commands and search for stations.
#### Available Commands:
| Shortcut | Full Command | Description |
| :--- | :--- | :--- |
| `p` | `play/pause` | Toggle current station playback |
| `t` | `track` | Show current track info |
| `i` | `info` | Show station details |
| `r` | `record` | Start/Stop recording |
| `rf` | `recordfile` | Record with a specific filename |
| `f` | `fav` | Add current station to favorites |
| `l` | `list` | Open favorite station selection menu |
| `s` | `search` | Search for a new station online |
| `n` | `next` | Play next station (from search/favs) |
| `timer` | `sleep` | Set a sleep timer |
| `v` | `volume` | Set volume (e.g., `v 50`) |
| `sz` | `shazam` | Identify current song using Shazam |
| `b` | `background` | Run radioactive in the background |
| `q` | `quit` | Exit Radioactive |
#### Power Features:
* **Tab Completion**: Type a few letters and press `Tab` or `Right Arrow` to auto-complete commands and station names.
* **Instant Suggestions**: As you type, the bar shows descriptive hints (e.g., typing `p` shows `(play/pause)`).
* **Universal Fuzzy Search**: If your input doesn't match a command, Radioactive instantly searches your **Favorites** and **History**. Just type the name of a station and press `Enter` to play it immediately!
### Sort Parameters
you can sort the result page with these parameters:
- `name` (default)
- `votes` (based on user votes)
- `codec`
- `bitrate`
- `lastcheckok` (active stations)
- `lastchecktime` (recent active)
- `clickcount` (total play count)
- `clicktrend` (currently trending stations)
- `random`
### Filter Parameters
Filter search results with `--filter`. Some possible expressions are
- `--filter "name=shows"`
- `--filter "name=shows,talks,tv"`
- `--filter "name!=news,shows"`
- `--filter "country=in"`
- `--filter "language=bengali,nepali"`
- `--filter "bitrate>64"`
- `--filter "votes<500"`
- `--filter "codec=mp3"`
- `--filter "tags!=rock,pop"`
Allowed operators are:
- `=`
- `,`
- `!=`
- `>`
- `<`
- `&`
Allowed keys are: `name`, `country` (countrycode as value), `language`, `bitrate`, `votes`, `codec`, `tags`
Provide multiple filters at one go, use `&`
A complex filter example: `--filter "country!=CA&tags!=islamic,classical&votes>500"`
> [!NOTE]
> set `--limit` to a higher value while filtering results
### Default Configs
Default configuration file is located at ~/radioactive/config.ini
```bash
[AppConfig]
loglevel = info
limit = 100
sort = votes
filter = none
volume = 80
filepath = {home}/radioactive/recordings/
filetype = mp3
player = ffplay
```
### Feature Configuration
You can enable or disable specific features by editing `~/radioactive/features.conf`.
If the file does not exist, it will be automatically created on the first run.
```bash
MINIMAL_FEATURE=false
RECORDING_FEATURE=true
TRACK_FEATURE=true
SEARCH_FEATURE=true
CYCLE_FEATURE=true
INFO_FEATURE=true
TIMER_FEATURE=true
HISTORY_FEATURE=true
```
> Setting `MINIMAL_FEATURE=true` will override and disable all other optional features.
### Configuration Paths
All the data files are stored in a folder called `radioactive` under your user home directory.
- **Configuration**: `~/radioactive/config.ini`
- **Features**: `~/radioactive/features.conf`
- **Favorites**: `~/radioactive/alias_map`
- **Last Station**: `~/radioactive/last_station`
- **Recordings**: `~/radioactive/recordings`
Legacy configuration files are automatically migrated to this new location on the first run.
> [!WARNING]
> Do NOT modify the keys, only change the values.
### Bonus Tips
1. when using `rf`: you can force the recording to be in mp3 format by adding an extension to the file name. Example "talk-show.mp3". If you don't specify any extension it should auto-detect. Example "new_show"
2. You don't have to pass the exact option name, a portion of it will also work. for example `--sea` for `--search`, `--coun` for `--country`, `--lim` for `--limit`
3. It's better to leave the `--filetype` as mp3 when you need to record something quickly. The autocodec takes a few milliseconds extra to determine the codec.
### Changes
see [CHANGELOG](./CHANGELOG.md)
### Community
Share you favorite list with our community 🌐 ➡️ [Here](https://github.com/dpnkrpl/radio-active/discussions/10)
> Your favorite list `alias_map` is under `~/radioactive/` directory.
### Support
Visit my contribution page for more payment options.
### Acknowledgements
Happy Listening
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
