pyradio

PyRadio is a feature-rich command line radio player with the following capabilities:

• Navigation & Controls: vi-like key bindings (including station registers), customizable key bindings, and mouse support.
• Station Management: Station editor (add/edit) with CJK character support, search function (including fuzzy search), and multiple playlist support (including M3U).
• Connectivity & Integration: RadioBrowser support, Remote Control Server, and OS media controls integration (MPRIS, SMTC, Now Playing).
• Customization: Theming support and a configuration editor.
• Platform Support: Runs on Linux, macOS, and Windows.

PyRadio includes specialized modes for users of tiling window managers, which trigger automatically based on window dimensions:

• Limited Height mode: Automatically enabled when the window height is below 8 lines. It shows a Limited display where only playback status and volume controls are visible.
• Limited Width mode:
  • Below 40 columns: All windows close, and only the Main window (stations, playlists, or registers) is visible.
  • Below 20 columns: The Limited display is activated.

Note: These automatic modes are not supported on Windows (7 or 10) because the console window does not reliably notify PyRadio of size changes.

Starting with version 0.9.2.6, PyRadio moved toward using virtual environments (via pipx) to avoid breaking system-wide Python installations.

Modern Linux distributions (like Ubuntu 23.04 and newer) implement PEP 668, marking the Python base environment as "externally managed". This prevents pip from installing packages system-wide, which could conflict with the distribution's own tools.

Using pipx isolates PyRadio in its own virtual environment, ensuring it does not interfere with the system's Python installation.

Groups allow you to organize stations within a large playlist. A Group Header is created by adding a station entry where the URL field is a hyphen (-).

Example Group Entry: Blues,-

Group Headers cannot be played directly but can be moved, copied, or deleted like any other entry.

Navigation Commands:

• ^E: Go to next Group
• ^Y: Go to previous Group
• ^G: Display a list of existing Groups to select from
• a: Add a new Group Header (fill in name and use - for URL)

The tts_context setting determines the depth of auditory feedback provided by the system:

• limited: Provides essential information only, such as system messages, errors, and station data.
• window: Provides extended feedback, including window text and interface elements.
• all: Provides comprehensive feedback, speaking all available text and information.

Note on Configuration Windows: When navigating through Configuration menus and windows, the TTS system temporarily overrides the tts_context setting to provide full auditory feedback for all interface elements, ensuring accessibility during setup.

PyRadio implements station recording using two distinct components to handle the stream:

1. Recorder: The component that connects to the station stream, receives data (including song titles/metadata), and writes it to a file. It is responsible for the actual data capture.
2. Monitor: The component that plays back the file being written by the recorder so the user can hear the recording in real-time. The monitor only knows about the file content and does not receive station metadata like song titles.

This dual-component approach allows PyRadio to facilitate the pause and resume playback feature.

You can define a preferred player for individual stations directly within your playlist file. When a station with a preferred player is played, PyRadio will automatically attempt to use that player. If the specified player is not installed, PyRadio falls back to the default player.

Note: A station with a defined player will always use that player, overriding any session-wide player changes or defaults.

When using MPV as the media player, recording has the following behavior:

• Simultaneous Playback/Recording: MPV can play and record a stream at the same time. This is highly convenient as you can listen to the station while it is being recorded.
• Experimental Status: Stream recording is considered an experimental feature by MPV developers, though it is stable for common codecs like mp3, aac, and flac.
• Volume Control: Adjusting the player volume or muting the player does not affect the quality or volume of the recorded stream.
• Pausing: If you pause playback, the player stops playing audio but continues to record the stream. Song titles will stop updating while paused but will sync correctly once playback resumes.

PyRadio can be run in a "headless" mode on Linux, BSD, or Pi systems by using the --headless command line option. In this mode, PyRadio starts an integrated web server that allows remote control via a terminal (using wget or curl) or a web browser.

Key behaviors in headless mode:

• Loads the default "dark" theme to save memory.
• Restricts access to themes and the configuration window.
• Does not create a standard session lock file (allowing normal terminal instances to run simultaneously).
• Creates a server-headless.txt lock file containing the server's IP and port.

Accessing the server:

• Text interface: http://<ip>:<port>
• HTML interface: http://<ip>:<port>/html

To find the current server address, run: pyradio --addr

pyradio --headless auto

Because PyRadio streams live radio rather than local files, certain media actions have specific behaviors:

• Playback Actions: Supports Play, Stop, Next station, and Previous station.
• Pause Behavior: Since live streams cannot be paused, the Pause action typically behaves like Stop.
• Artwork: PyRadio attempts to retrieve station-provided icons. If unavailable, it falls back to the default PyRadio icon.
• Metadata: The OS will display the Station name, Station title, Playlist name, Artwork, and Playback status (Playing/Stopped) if provided by the station.

When installing PyRadio via the script, you must choose between two modes:

1. Fully isolated installation (install.py -i): Installs all dependencies inside a virtual environment. This prevents cluttering your system's Python installation but carries a higher risk of dependency installation failures.

2. System dependent installation (install.py): Requires all PyRadio dependencies to be installed globally via your system's package manager (e.g., apt, dnf, zypper). This is more stable if the distribution provides the necessary packages.