"Search, bookmark, and stream internet radio stations directly from your terminal."

Xradios is a terminal tool to discover and streaming radio stations worldwide.

• Search: Find radio stations by name, genre, country, language or other criteria.
• Stream: Play radio stations directly in your terminal.
• Interactive Interface: Navigate and control playback with keyboard shortcuts.
• Bookmarks: Save stations for quick access. (TODO)

• Python 3.8 or higher
• mpv or libmpv for audio playback

pipx install xradios

pip install --user xradios

You can run xradios in two modes:

If you want to launch the interactive interface and automatically start the server (if not already running), just run:

xradios

By default, it connects to 127.0.0.1:10000. You can override this by specifying the address and port:

xradios --host 192.168.0.10 --port 9000

If the host is local (127.0.0.1 or 0.0.0.0), xradios will try to start the server automatically.

You can manually start the server and then connect to it using the client.

xradiosd

Or with custom host and port:

xradiosd --host 0.0.0.0 --port 9000

Then, start the client and connect to the server:

xradios --host 192.168.0.10 --port 9000

• Open command line: Press :
• Navigate: Use Ctrl + UP/Ctrl + DOWN to move focus.
• Search for stations: search tag=rock limit=100 order=votes
• Play a station: Select a station with UP/DOWN and press ENTER.
• Exit: Press Ctrl + q

Press ? to see a complete list of shortcuts and commands.

1. Clone the repository and navigate into project directory:

git clone git@github.com:andreztz/xradios.git
cd xradios

2. Install development dependencies using the following command:

uv sync --dev
uv pip install -e .

3. Start the xradios server by running:

xradiosd

4. Open a new terminal, and run textual console to monitor log messsages:

textual console

5. In another terminal run xradios application in development mode:

textual run --dev xradios

6. Run tests:

pytest

Contributions are welcome! Please open an issue or submit a pull request.
See CONTRIBUTING.md for guidelines.

• No audio? Ensure mpv or libmpv is installed and accessible in you PATH.

André P. Santos – @ztzandre – andreztz@gmail.com

Distributed under the MIT license. See LICENSE for details.

GitHub: https://github.com/andreztz/xradios