Command line internet radio player.
Ben Dowling - https://github.com/coderholic
PyRadio provides the following features:
and much more…
2022-12-09 s-n-g
* version 0.8.9.32 (0.9-beta29)
* Making it possible to disable the no themes start
up notification
* Fixing Config Window scrolling
* Fixing ping for python2 and the BSDs (again)
* Desktop Notification will stop when player is muted
* RadioBrowser config will be centered on screen
* RadioBrowser config will return to Config Window
* Started working on remote controlling PyRadio
2022-11-25 s-n-g
* version 0.8.9.31 (0.9-beta28)
* fixing icon installation and discovery
* fixing config window not showing last entry
2022-11-25 s-n-g
* version 0.8.9.30 (0.9-beta27)
* Adding a Desktop File
* Adding Desktop Notifications
* Adding --terminal and --terminal-param command line options
* Adding --no-themes command line option
* Fixing Windows uninstallation script
* Fixing opening registers by name
* Fixing ping command for BSD
* The installation will fail if pip not found
* Trying to restore windows title on exit (not for Windows)
* URL will not overlap the title
2022-09-27 s-n-g
* version 0.8.9.28 (0.9-beta25)
* adding play next/previous station to global functions
* fixing Connection Type window colors
* fixing line editor blobal function handler
* fixing a couple of stations history bugs
* fixing station listing for CJL characters
* updating docs
2022-09-18 s-n-g
* version 0.8.9.27 (0.9-beta24)
* Implementing Stations History as per #161
* Station encoding will be checked before used
* Fixing several crashes
* Fixing several Python 2 errors
* Fixing station paste to playlist
* Fixing RadioBrowser columns when CJK characters are
present, on Windows
2022-08-28 s-n-g
* version 0.8.9.26 (0.9-beta23)
* adding calculated messages windows color
* adding "Calculated Color" config option
* Windows installation will try to install 7-Zip, if not
already installed
2022-08-14 s-n-g
* version 0.8.9.25 (0.9-beta22)
* fixing global shorcuts inside RadioBrowser search window
(as per #164)
2022-08-12 s-n-g
* version 0.8.9.24 (0.9-beta21)
* fixing several theme issues (exchanging cursors background color
and making borders visible for theme.sh themes, when border
color is equal to background color)
* fixing a crash when requests fails to download a base16 theme
* transparency changes will now be consistent with theme transparency
* updating docs, including info on theme-sh-pyradio repo
2022-08-03 s-n-g
* version 0.8.9.23 (0.9-beta20)
* pyradio can now sync with themes created by base16, pywal and theme.sh
* if session is locked, the theme selection window will not be available
* if session is locked, do not create / download (watched) theme; wait
for main instance to do it instead, then just load it
* docs updated
2022-07-03 s-n-g
* version 0.8.9.22 (0.9-beta19)
* themes can declare transparency hint
* theme auto update implemented
* themes updated (1 added)
* updating docs
2022-06-26 s-n-g
* version 0.8.9.21 (0.9-beta18)
* Theme Selection window partly rewritten
* Converting themes to using CSS colors
* Themes updated and new themes added
* Updated docs
2022-05-22 s-n-g
* version 0.8.9.20 (0.9-beta17)
* going back to history will ask to save a modified playlist
* fixing #157 (python2 only)
* other minor changes
2022-05-19 s-n-g
* version 0.8.9.19 (0.9-beta16)
* fixing main window galobal shortcuts ( #156 )
* fixing RadioBrowser Search Window global shortcuts
2022-05-18 s-n-g
* version 0.8.9.18 (0.9-beta15)
* changing shortcut w and ^W to e and ^E on the RadioBrowser
Search Window
* implementing global functions
* fixing a couple of bugs and crashes
* updating docs
2022-04-29 s-n-g
* version 0.8.9.17 (0.9-beta14)
* adding Title's Log
* changing versioning
* fixing user installation in build_install_pyradio
* fixing python2 main.py crash (#153)
* updating docs
2022-03-18 s-n-g (0.9-beta13)
* version 0.8.9.16 (0.9-beta13)
* fixing install.py script
* installing Start Menu Shortcut on Windows
2022-03-15 s-n-g
* version 0.8.9.15 (0.9-beta12)
* fixing "0" and "$" insertion on RadioBrowser search window
* macOS installation method updated to pip
* fixing a macOS RadioBrowser interface breakage
* Windows installation method updated to pip
* adding F7, F8, F9, F10 functionality for Windows
* updating docs
2022-02-14 s-n-g
* version 0.8.9.14 (0.9-beta11)
* fixing typo in player.py
2022-02-13 s-n-g
* version 0.8.9.13 (0.9-beta10)
* fixing #148
* fixing a potential psutil crash
2022-01-26 s-n-g
* version 0.8.9.12 (0.9-beta9)
* Fixing install.py
2022-01-25 s-n-g
* version 0.8.9.11 (0.9-beta8)
* Fixing (#147): Cannot type "t" in RadioBrowser Search window
* Trying to fix install.py crash
* Adding MPV support on Windows
2022-01-17 s-n-g
* version 0.8.9.10 (0.9-beta7)
* RadioBrowser config window almost finished
* RadioBrowser search window shortcuts changes
* save config before entering config window, when theme is changed
* fixing compiling/build error for arch linux (#146)
* fixing Windows installation as per (#145)
* adding check for -p parameter (int)
* keep looking for a station after playback failure when random is on
* trying to better VLC start of playback detection
* trying to eliminate crashes when window width gets small
(like in tilling managers)
* show correct help page when in online browser
* disabling theme editing per (#141)
* adding last opened playlist support as per (#138)
* HTML help can be displayed using \h
* Fixing installation of HTML files for all platforms and modes
* Incorporating the Changelog into README.html (offline help)
* install.py will always use the requested python version
* install.py will use special indication per command line
(-sng for --sng-master and -sng-dev for --sng-devel)
* Adding --git option to install.py
* Windows installation will fail if a dependency fails to install
* mplayer on Windows: do not fail to start a station
after astop/start command
* Updating docs
2021-08-31 s-n-g
* Version 0.8.9.9 (0.9-beta6)
* Search history navigation will work with normal keys
in addition to Control-key combinations (when a line
editor does not have the focus)
* When navigating to a new search term, in the RadioBrowser
Search Window, the two main check boxes will always get
the focus (makes it easier to navigate using normal keys)
* Docs Updated
2021-08-22 s-n-g
* Version 0.8.9.8 (0.9-beta5)
* Fixing RadioBrowser save pop up window
* Interchanging ^T and ^Y in the RadioBrowser Search Window
* Addinf FULL_SCREEN_MODES for farter rendering
2021-08-20 s-n-g
* Version 0.8.9.7 (0.9-beta4)
* RadioBrowser: closing with "q" or "Escape"
* RadioBrowser: do not close if network fails
* RadioBrowser: added hidebroken to all queries
* RadioBrowser: if limit=0, disable result limit
* RadioBrowser: finalized config save / read function
* RadioBrowser: All Search Window movement keys (^N, ^P, ^Y)
will add a new history item (if possible)
* RadioBrowser: ^B does not save history to file
* RadioBrowser: Better navigation in the Search Window
* Fixed a couple of python 2 crashes
* Updated docs
2021-08-15
* Version 0.8.9.6 (0.9-beta3)
* RadioBrowser History Management finalized
* Fields' placement fixed in RadioBrowser Search Window
* RadioBrowser man page added
* Docs updated
2021-08-11 s-n-g
* Version 0.8.9.5 (0.9-beta2)
* Fixed a crash that would occur when searching for name only in
RadioBrowser Search Window
* Do not display the Theme Selection Window when pressing "t" in a
RadioBrowser Line Editor
* Updated History legend aread
* Updated docs
2021-08-11 s-n-g
* Version 0.8.9.4 (0.9-beta1)
* Radio Browser implementation is now usable (but still not complete)
* Implemented ^N,^P to play next/previous station as per (#135)
* Several python2 fixes
* Updating docs
2021-07-13 s-n-g
* Version 0.8.9.3
This is an "internal" release testing (#135)
2021-05-11 s-n-g
* Version 0.8.9.2
* Screen flickering when moving within the stations' list eliminated
* VLC player is available again (disabled by unreported bug)
* Advancing Radio Browser support
* Fixing python 2 return from Radio Browser TUI breakage
* Adding dnspython module availability check
2021-04-14 s-n-g
* Version 0.8.9.1
* Implemented the so called "Listening" mode, in which PyRadio TUI
can be reduced down to a single line (the "Status Bar"). Requested
for tilling WM use (#128)[https://github.com/coderholic/pyradio/issues/128]
2021-04-03 s-n-g
* Version 0.8.9
* Implemented a simplified method to install, update, uninstall.
* PyRadio will detect its player abnormal termination.
* Player's connection timeout can now be disabled. Once a player is
started, it will be considered to be connected immediately.
* stations.csv changes can now be integrated into user's stations.csv
* mplayer "pyradio" profile will use the internal mixer to adjust volume
* BUG FIX: Active players parameter list is always synchronized to saved.
* BUG FIX: Clicking on empty space (past last station) will not crash pyradio.
2021-02-27 s-n-g
* Version 0.8.8.5 (BUG FIX release)
* Fixing -ap value not activated by player
* Commenting out excessive error log messages
2021-02-27 s-n-g
* Version 0.8.8.4 (BUG FIX release)
* Fixing double click behavior (while in playback
double clicking to a different station will start it.
* vcl will not start muted (volume = 0)
2021-02-26 s-n-g
* Version 0.8.8.3
* Basic mouse support implemented
* Config option to enable mouse support added
* Implementing players extra parameters set.
* Player selection Config window redesigned.
* Adding -ep. -ap, -lp command line parameters.
* Fixing a bug which would lead to a crash when "r"
would be pressed in the config window.
* Playback will be restarted when vital parameters are
changes (encoding, connection type, player parameters).
* When restarting playback, play the correct station
not the selected one.
* adding autostart BAT file on Windows to
prevent session locking when Windows
terminate while PyRadio is still running
* pyradio will always use a profile
* Fixing several minor bugs.
2020-12-21 s-n-g
* Theme selection window will not crash when resizing
* After editing a station, restart playback only if the
encoding of the station that's playing has been changed
2020-12-18 s-n-g
* Version 0.8.8.2
* Gracefully exit when the terminal is closed
2020-12-14 s-n-g
* Version 0.8.8.1
* Fixing (?) vlc terminataion on Windows
* Restarting radio-browser.info implementation
2020-12-10 s-n-g
* Starting 0.8.8
* Implementing "Paste to playlist" (\p) command
* Implementing "Create Playlist" (\n)
* Addind \u (show Unnamed Register) command
* Fixing volume display for MPV on python3 before a
valid Title has been received
* Revert to stations playlist if default one (set by
config) does not exist
* Second level config windows will not be displayed
when main window shows "Window too small" message
* When opening a playlist/register from register mode,
continue playing active station (if found in opened
playlist/register)
* Do not show "'" when opening a playlist/register
from register mode
* "Title: (null)" will not appear any more (vlc)
2020-11-23 s-n-g
* Version 0.8.8-beta6
* Fixing playback for m3u8 (vlc)
* Fixing "-u" functionality on Windows
* Fixing "no player" messages
* Stopping runaway threads from displaying messages
after the player is stopped
2020-11-23 s-n-g
* Version 0.8.8-beta5
* Adding VLC support on Windows
2020-11-17 s-n-g
* Version 0.8.8-beta4
* Adding the "Force http connections" configuration
option (#113)
* Fixed a couple of bugs
* Installation script will use Python 3 by default
2020-10-30 s-n-g
* Version 0.8.8-beta3
* Re-implementing status bar output function
* Connection timeout counter will be visible at 70% of timeout value
* Player will be aware of mid-session connection timeout changes
* Changing numbers presentation (adding "G" and "J" suffixes)
* Adding a program termination speed up
* Changing new version detection function
No update notification will be displayed due to this change
* Fixing TUI breaks due to multi-threading
2020-10-13 s-n-g
This is a long-overdue update!
This is a called a beta release in the sense that some
of the intended features have not been implemented yet.
* Version 0.8.7.3 (0.8.8-beta2)
* Adding PASTE MODE in editing windows
* Finalizing alternative modes (registers, register mode,
extra commands, yank i.e. copy) - implementation
started in 0.8.8-beta1
* Toggling transparency enabled in theme selection window
* Pyradio respects global encoding
* Info window gets updated as data are read
* Display message when fallback theme is used (#99)
* Fixing info window highlight and encoding issues
* Making Station editor window size aware
* Fixing -a command line parameter functionality
* Build script accepts --user (for user only installation) on linux
* Build script will clean up previous installation files
* Fixing volume saving on Windows (mplayer)
Implemented in 0.8.8-beta1
* Connection timeout counter
* Station info window
* Main help window has 3 pages now
* Fixing playback restart when encoding changed
Not implemented yet
* \p - Select playlist/register to paste station
* \n - Create new playlist
2020-03-16 s-n-g
* Version 0.8.7.2
* Fixing macOS Catalina installation
2020-01-31 s-n-g
* Version 0.8.7.1
* Fixing mpv playlist option (for mpv 0.32.0)
2020-01-26 s-n-g
* 0.8.8-beta1
* Adding connection timeout counter
* Adding station info window
* Adding registers add, remove station, clear
* Adding paste station to current playlist
* g prefixed by a number jumps to it (same as G)
* Dead keys (alternative mode and jump number) are
now displayed at the bottom right corner of the window
* Main help window has 3 pages now
* Fixing playback restart when encoding changed
* Replacing widechar.py with cjkwrap.py and adding its
update script in devel/
2019-12-23 s-n-g
* Version 0.8.7
* Fixing volume issue with mpv
* mpv on python3 uses socket communication only; no stdout parsing
done anymore, as it is still done on python2, due to title
(icy-title) encoding problems.
* socat is no longer needed to use mpv
2019-12-14 s-n-g
* Version 0.8.6
* Adding playlist history (for local playlists)
* https URLs will be converted to http before connecting
* Fixing station moving when appending station
* Config / Default station: pading fixed
* WINDOWS: Volume will be saved when mplayer is installed in %APPDATA%\pyradio
2019-11-15 s-n-g
* PyRadio will not crush with mpv 0.30.0
Changing mpv's volume is still possible, but no info will be
presented on the Status Bar.
Furthermore, saving mpv's volume will not be possible
( mpv issue #7153: https://github.com/mpv-player/mpv/issues/7153 )
2019-11-12 s-n-g
* When default played is changed in the config, a message to restart
the application is presented to the user
* Config / Default station: pading fixed
2019-11-10 s-n-g
* Fixing vlc returned volume parsing (due to locales decimal separator)
2019-10-29 s-n-g
* FIX: Playlists flagged as changed when adding a station
* Handling CJK presentation on station and playlist view
* Preparing for online stations browser
2019-10-23 s-n-g
* Handling CJK presentation on station and playlist window
2019-10-20 s-n-g
* Version 0.8.2
* Fixing chars H,L,M rejected by line editor
* Fixing station editor rejecting "\?"
* Updating station's editor help messages
2019-10-19 s-n-g
* Version 0.8.1
* CJK Unified Ideographs supported by the line editor
* On python 2, trying to edit a station whose name contains
non-ASCII characters is prohibited and will end up in
displaying a relevant message
* Line editor: using backslash to insert "?" and "\"
* Search term will not be lost when resizing the window
* Fixing issues with presenting search history
* Themes now have a "Edit Cursor" field
2019-09-08 s-n-g
* Version 0.8.0
* Adding station editor ("a" and "A" to add a station, "e" to edit)
* Line editor supports unlimited string length
* Main help window separated to two pages (navigation with "n" / "p")
* Changing "e" to "E" to change a station's encoding
* Changing "p" to "P" to jump to playing station / loaded playlist
* Adding H, L to jump to top / bottom of screen
* Changing M to jump to middle of screen
* Changing volume, saving volume and muting is now available on most
windows (pop up and questions)
* Manipulating volume (keys m,v) on a help window, will close it
if player not playing
* Adding ^U, ^D to move station up, down
* Search string will not be lost after displaying help
* PyRadio runs on Windows (finally). Added an installation BAT file,
icons, program shortcut and help (windows.md - windows.html)
* Minor bug fixes
2019-07-15 s-n-g
* Searching is now available on any window presenting a list of items
* Transparency indication presentation always reflects setting
* A locked session is indicated next to PyRadio version
* Adding "Top" link to html files
* Docs updated
2019-07-08 s-n-g
* Version 0.7.8
* fixing playlist recovery message presentation
* fixed foreign playlist management
* fixed exiting when playlist is modified
* when applying a them which is not supported, using "light"
if "light" or "light_16_colors" is default
* fixing update notification message "Will check again in 0 days"
* update notification will clean files in all cases
* adding "M" to config station selection
* updating help for playlist and config station selection
* heavy refactoring; using window stack and redisplay list
2019-06-26 s-n-g
* Version 0.7.7
* mpv now uses a dedicated socket file. This way multiple instances of
PyRadio can be executed.
* Introducing session locking.
* Added the "--unlock" command line parameter, to force sessions' unlock.
* Added "M" command, which will jump to the middle of the list.
* PyRadio can load external theme files.
* Three more themes added. These are system themes (actual files).
* Theme selection window reworked - themes are separated by location,
theme selection is remembered when resizing, and loading default or
saved theme (in config window).
* PyRadio will report reverting to default theme.
* PyRadio will check and report when a new release is available.
* Added good bye message.
* Theme editor implementation started (disabled for this release).
* Minor other fixes.
2019-06-06 s-n-g
* Verion 0.7.6.2
This is a BUG FIX release, fixing config status (indicating whether
config is modified or not)
2019-06-02 s-n-g
* Version 0.7.6.1
This is a BUG FIX release, fixing regression: config not saved when
changing themes
2019-06-01 s-n-g
* Version 0.7.6
* Added "e" option to change station's encoding.
* Implemented playlist backup and recovery, to address saving errors.
* Inform user when playlist not found and of playlist recovery result.
* Parameter -s - Check if file is supported (ends with .csv)
2019-04-18 s-n-g
* Version 0.7.5
* Minimum python version supported changed. Now it's 2.7+/3.5+
* Added configuration window (opens with "c").
* Canceling theme selection (not in config) will restore saved theme.
* Done a bit of refactoring.
2019-02-14 s-n-g
* Version 0.7.4
* Fixing p command for playlists view.
* Selected station / playlist will be visible when resizing the terminal.
* Calculating initial loaded playlist position in window.
* Implemented dynamic list padding.
* Correctly display failed station when returning to stations mode.
* Help window gets redisplayed when the terminal is resized.
* Updating docs
2019-02-04 s-n-g
* Version 0.7.3
* Added "p" command to jump to playing station / loaded playlist.
* Added two more themes (dark_16_colors and light_16_colors)
* Improved black_on_white theme.
* On a 8 color terminal, the fall-back theme will be "light",
if "light_16_colors" is default.
* Exiting if terminal cannot display colors.
* Fixed player selection error screen.
* Fixed a regression which might appear when loading a playlist
2019-02-02 s-n-g
* Version 0.7.2
* Themes support added (4 hardcoded themes).
* Command line option -t (--theme) THEME added.
* Config option "theme" added.
* Key "t" will open the "Theme Selection Window".
* Key "T" will toggle transparency / use terminal's background color.
* Alt keyboard combinations will not be considered as ESCAPE char.
* Help / message windows use multiple colors.
* Fixing a couple of minor bugs.
2019-02-10 s-n-g
* Version 0.7.1
* Avoiding curses layout breakage due to BROKEN PIPE errors
* Start of playback detection implemented. This is done by
detecting the players audio decoder info, which actually mean
that playback is on. If not detected within a timeout value,
failure to connect is presumed
* Volume adjustment, saving and muting is inhibited before start
of playback is detected
* Playing a station in random order will not stop until a
working station is acquired or another action is taken (e.g
pressing a key)
* Stations name is limited to window width
* Station title is validated before displayed
2019-01-21 s-n-g
* Version 0.7.0
* added command line options -ls, -scd, -ocd
* make sure config dir exists before doing anything with it
* make sure the playlist is valid (-s option)
* Option -s accepts playlist name only, if it exists in config dir, or
playlist number as reported by the -ls command line option
* -a command line option works in combination with -s
* -l command line option prints a tabular list
* started implementing playlist management. Now we can open another
playlist, remove a station from a playlist and save a playlist.
TODO: rename playlist, copy playlist, add station, edit station
* added configuration file (~/.config/pyradio/config)
TODO: edit configuration file within PyRadio
* Input encoding can now de set either in a station by
station mode or globally
* ESCAPE now works for exit/cancel
* ESCDELAY set to 25ms. Refer to https://stackoverflow.com/questions/27372068/why-does-the-escape-key-have-a-delay-in-python-curses for more info
* "Foreign" playlist handing added. A playlist that does not reside in
PyRadio's config dir (called a "foreign playlist") can now be copyied
there, making it available for opening from within PyRadio.
* '/' win no longer display help ('?' is still valid)
* minor errors fixed
* error_code renamed to operation_mode
* build script working on macOS
2018-12-02 s-n-g
* Version 0.6.0
* PyRadio will not crash when no player found.
* PyRadio will only display station name and icy-title (if received)
* PyRadio version will include git revision when not on a git tag
(i.e.not on a release tag)
* Added '-u' option to specify player to use (or detection order)
* A help message can be displayed (shortcut '?' or '/')
* vlc will unmute on exit
* Volume value is displayed while changing
* Volume can be saved for mpv and mplayer (shortcut 'v')
* pyradio.log is always saved in home directory
* Both mpv and socat must be installed for mpv to be used as player
* Added man page, thanks to AUR package pyradio-git (not installed
by default; it's up to the packagers to do it)
2013-04-03 stac47
* Version 0.5.1
* Fixed regression on bottom panel not updated in Python 3
* Support of VLC as the underlying player
* Probing the multimedia player available on the host system
2013-03-16 stac47
* Version 0.5.0
* Fix compatibility issue with Python 3
2012-08-31 klen
* Version 0.4.2
* Add '-p' option
2012-08-30 klen
* Version 0.4.1
* Fix user stations loading
2012-08-29 klen
* Version 0.4.0
* Add console interface
* Published on pypi
The best way to install PyRadio is via a distribution package, if one exists (e.g. Arch Linux and derivatives can install any of these packages from the AUR).
In any other case, and since PyRadio is currently not available via pip, you will have to build it from source.
$ pyradio -h
usage: pyradio [-h] [-s STATIONS] [-p [PLAY]] [-u USE_PLAYER] [-a] [-ls] [-l]
[-t THEME] [--show-themes] [--no-themes]
[--write-theme IN_THEME OUT_THEME,] [--terminal TERMINAL]
[--terminal-param TERMINAL_PARAM] [-tlp] [-scd] [-ocd]
[-ep EXTRA_PLAYER_PARAMETERS] [-ap ACTIVE_PLAYER_PARAM_ID]
[-lp] [-U] [--user] [-R] [--unlock] [-lt] [-d] [-V]
Curses based Internet radio player
options:
-h, --help show this help message and exit
-s STATIONS, --stations STATIONS
Use specified station CSV file.
-p [PLAY], --play [PLAY]
Start and play.The value is num station or empty for
random.
-u USE_PLAYER, --use-player USE_PLAYER
Use specified player. A comma-separated list can be
used to specify detection order. Supported players:
mpv, mplayer, vlc.
-a, --add Add station to list.
-ls, --list-playlists
List of available playlists in config dir.
-l, --list List of available stations in a playlist.
-t THEME, --theme THEME
Use specified theme.
--show-themes Show Internal and System Themes names.
--no-themes Disable themes (use default theme).
--write-theme IN_THEME OUT_THEME,
Write an Internal or System Theme to themes directory.
--terminal TERMINAL Use this terminal for Desktop file instead of the
auto-detected one. Use "none" to reset to the default
terminal or "auto" to reset to the auto-detected one.
--terminal-param TERMINAL_PARAM
Use this as PyRadio parameter in the Desktop File.
Please replace hyphens with underscores when passing
the parameter, for example: --terminal-param "_p 3 _t
light" (which will result to "pyradio -p 3 -t light").
-tlp, --toggle-load-last-playlist
Toggle autoload last opened playlist.
-scd, --show-config-dir
Print config directory [CONFIG DIR] location and exit.
-ocd, --open-config-dir
Open config directory [CONFIG DIR] with default file
manager.
-ep EXTRA_PLAYER_PARAMETERS, --extra-player_parameters EXTRA_PLAYER_PARAMETERS
Provide extra player parameters as a string. The
parameter is saved in the configuration file and is
activated for the current session. The string's format
is [player_name:parameters]. player_name can be 'mpv',
'mplayer' or 'vlc'. Alternative format to pass a
profile: [player_name:profile:profile_name]. In this
case, the profile_name must be a valid profile defined
in the player's config file (not for VLC).
-ap ACTIVE_PLAYER_PARAM_ID, --active-player-param-id ACTIVE_PLAYER_PARAM_ID
Specify the extra player parameter set to be used with
the default player. ACTIVE_PLAYER_PARAM_ID is 1-11
(refer to the output of the -lp option)
-lp, --list-player-parameters
List extra players parameters.
-U, --update Update PyRadio.
--user Install only for current user (not on Windows).
-R, --uninstall Uninstall PyRadio.
--unlock Remove sessions' lock file.
-lt, --log-titles Log titles to file.
-d, --debug Start pyradio in debug mode.
-V, --version Display version information.
The following options can also be set in PyRadio’s configuration file:
Main window Playlists window Themes window
-------------------------------------------------------------------------------------------------------------------------------------
Up/Down/j/k/
PgUp/PgDown Change station selection Change station playlist Change station theme
g Jump to first station Jump to first playlist Jump to first theme
<n>G Jump to n-th / last station Jump to n-th / last playlist Jump to n-th / last theme
H M L Jump to the top / middle bottom of the list [Valid] -
P Jump to playing station Jump to playing playlist -
Enter/Right/l Play selected station Open selected playlist Apply selected theme
^N / ^P Play next/previous station - -
r Select and play a random station Re-read playlists from disk -
Space/Left/h Stop/start playing selected station - -
Space - - Apply theme and make it default
-/+ or ,/. Change volume [Valid] [Valid]
m Mute / unmute player [Valid] [Valid]
v Save volume (not applicable for vlc) [Valid] [Valid]
o s R Open / Save / Reload playlist - -
a A Add / append a new station - -
e Edit current station - -
E Change station's encoding - -
DEL,x Delete selected station - -
O Open RadioBrowser - -
< > Browse the Stations history list - -
t T Load theme / Toggle transparency [Valid] [Valid]
c Open Configuration window. - -
/ n N Search, go to next / previous result [Valid] [Valid]
J Create a jump tag
<n>^U <n>^D Move station up / down. - -
' \ y Get into Registers, Extra Commands y (yank) is not applicable -
and Yank modes, respectively
z Toggle "Force http connections" - -
Z Display the "Extra Player Parameter" window - -
? Show keys help [Valid] [Valid]
# Redraw window [Valid] [Valid]
Esc/q Quit - -
Esc/q/Left/h - Cancel / close window Cancel / close window
The same logic applies to all PyRadio windows.
Note: When inserting numbers (either to jump to a station or to move a station), the number will be displayed at the right bottom corner of the window, suffixed by a “G”, i.e. pressing 35 will display [35G].
Note: When tagging a station position for a move action (by pressing “J”), the position will be displayed at the right bottom corner of the window, suffixed by a “J”, i.e. pressing “J” on position 35 will display [35J].
Some of the functions provided by PyRadio will always be available to the user. These functions are:
| Shortcut | Function | Shortcut | Function |
|---|---|---|---|
| + / - and , / . | adjust volume | W | toggle titles logging |
| m | mute player | w | like a station |
| v | save volume | ^N / ^P [1] [2] | play next / previous station |
| T | toggle transparency | < / > [1] | play next / previous station history entry |
Every window in PyRadio will respect these shortcuts, even the ones with a “Press any key to…” message.
When focus is on a “Line editor”, all shortcuts will work when preceded by a “\”.
Notes
[1] Function not available when in Playlist and Registers mode. More info on PyRadio’s modes below.
[2] Function not available in the Radio Browser Search window.
While in PyRadio main window, one can open the HTML (offline) help using “\h”.
This is just a helper function for windows users who cannot use the man pages, but is still available for all platforms.
PyRadio has the following primary modes:
The Main mode, which is the one you get when you open the program, showing you a list of stations (a playlist), that you can play and edit; this is why it is also called the editing mode. All other modes derive from this one, and it’s the mode you have to get to in order to terminate the program.
The Playlist mode, which you can open by pressing “o”. Then you can open, create, paste a station, etc.
The Registers mode. This is identical to the “Playlist” mode, but instead of displaying playlists, it displays register. You can enter this mode by pressing “’’” (two single quotes) and exit from it by pressing “Esc” or “q”. You can also press “’” (single quote) to get to the Playlist mode and back.
The Register Main mode, which is identical to the “Main” mode, except it displays the content of a named register.
The Listening mode, which is intended to be used when you want PyRadio to just play your favorite station and not take up too much space. It is ideal for tilling window manager use, as the whole TUI can be reduced all the way down to a single line (displaying the “Status Bar”). In this mode, adjusting, muting and saving the volume are the only action available. To get PyRadio back to normal operation one would just resize its window to a reasonable size (7 lines vertically, or more).
A set of secondary modes is also available (a secondary mode works within a primary one):
The Extra Commands mode, which gives you access to extra commands. You can enter this mode by pressing “\” (backslash). Then a backslash is displayed at the bottom right corner of the window.
The Yank (Copy) mode, which is used to copy stations to registers. You can enter this mode by pressing “y”. Then a “y” is displayed at the bottom right corner of the window.
The Open Register mode, which is used to open a register or get into the Registers mode. You can enter this mode by pressing “’” (single quote). Then a single quote is displayed at the bottom right corner of the window.
The Paste mode, which is available in the Station editor window only. It is designed to help the user paste a URL (and optionally a station’s name). Why you might ask… Well, the Station editor normally treats the “?” and “\” characters as special characters (actually commands). So, if a URL which contains these characters (more frequently the “?” character) is pasted it will be corrupted unless the Paste mode is enabled.
The functions available through the secondary modes are content dependent, so you can see what command is available by pressing “?” while within a secondary mode. Pressing any other key will exit the secondary mode.
These modes are specifically designed to be used with tiling window managers, trying to face a rapid reduction of window height or width (or both).
The Limited Height mode, which is automatically enabled when the window height gets below 8 lines.
The Limited Width mode, which is automatically enabled when the window width get bellow certain limits:
When the width gets bellow 40 columns, all windows will be closed and the main window will be the only visible one (either displaying stations, playlists or registers).
When the width gets bellow 20 columns, the Limited display will be activated.
Note: These two modes do not work on Windows, either 7 or 10. The “Console”window will shrink as desired, but will not always notify PyRadio about it, so results will vary.
PyRadio upon its execution tries to read its configuration file (i.e. ~/.config/pyradio/config). If this file is not found, it will be created. If an error occurs while parsing it, an error message will be displayed and PyRadio will terminate.
The file contains parameters such as the player to use, the playlist to load etc. It is heavily commented (as you can see here), so that manual editing is really easy. The best practice to manually edit this file is executing PyRadio with the -ocd command line option, which will open the configuration directory in your file manager, and then edit it using your preferable text editor.
The file can also be altered while PyRadio is running by pressing “c”, which will open the “Configuration window”. This window presents all PyRadio options and provide the way to change them and finally save them by pressing “s”.
In any case, PyRadio will save the file before exiting (or in case Ctrl-C is pressed) if needed (e.g. if a config parameter has been changed during its execution).
If saving the configuration file fails, PyRadio will create a back up file and terminate. When restarted, PyRadio will try to restore previously used settings from the said back up file.
PyRadio reads the stations to use from a CSV file, where each line contains two columns, the first being the station name and the second being the stream URL.
Optionally, a third column can be inserted, stating the encoding used by the station (more on this at Specifying stations’ encoding).
PyRadio will by default load the user’s stations file (e.g. ~/.config/pyradio/stations.csv) to read the stations from. If this file is not found, it will be created and populated with a default set of stations.
Note: Older versions used to use ~/.pyradio as default stations file. If this file is found, it will be copied to use’s config directory (e.g. ~/.config/pyradio) and renamed to stations.csv or if this file exists, to pyradio.csv. In this case, this file will be the default one.
When the package’s “stations.csv” files is updated, the changes it has will not automatically appear in the user’s stations file.
What PyRadio will do is inform the user that these changes do exist and give him a chance to integrate these changes to his stations file, by appending the new stations to the file.
When this is done, the first added station will be selected so that the user can inspect the changes and decide to keep or delete the new stations.
PyRadio will only add stations to the user’s stations file; no station will be deleted as a result of this procedure.
PyRadio will normally load its default playlist file, as described above, upon its execution. A different file can be loaded when the -s command line option is used.
The -s option will accept:
Examples:
To load a playlist called “blues.csv”, one would use the command:
pyradio -s /path/to/blues.csv
If this file was saved inside PyRadio’s configuration directory, one could use the following command:
pyradio -s blues
To use the playlist number, one would execute the commands:
$ pyradio -ls Playlists found in "/home/user/.config/pyradio" 1. hip-hop 2. party 3. stations 4. huge 5. blues 6. rock 7. pop $ pyradio -s 5
Note: The default playlist to load can also be set in PyRadio’s configuration file, parameter default_playlist (default value is stations).
As already stated, PyRadio will normally load its default playlist (called “stations”) upon startup.
This behavior can be then changed in two ways:
Changing the default playlist.
This is accomplished using the “Def. playlist” configuration option (optionally along with the “Def. station” option).
Always loading the last used playlist at startup.
This is accomplished using the “Open last playlist” configuration option.
In this case, the last used playlist will be opened the next time PyRadio will be executed, trying to restore the previously selected station or starting playback.
This option will take precedence before the “Def. playlist” configuration option (if it is used) and the “-s” (“–stations”) command line option.
Note: When the “Open last playlist” configuration option is set, all playlist operations will be performed to the last opened playlist. In order to use the “-a” (“–add”) or “-l” (“–list”) command line options along with the “-s” (“–stations”) command line option, the “-tlp” (“–toggle-load-last-playlist”) option can be used to temporarily deactivate autoloading.
Once PyRadio has been loaded, one can perform a series of actions on the current playlist and set of playlists saved in its configuration directory.
Currently, the following actions are available:
Pressing “a” or “A” will enable you to add a new station (either below the currently selected station or at the end of the list), while “e” will edit the currently selected station. All of these actions will open the “Station editor”.
If you just want to change the encoding of the selected station, just press “E”. If the station is currently playing, playback will be restarted so that the encoding’s change takes effect (hopefully correctly displaying the station/song title).
Then, when this is done, you can either save the modified playlist, by pressing “s”, or reload the playlist from disk, by pressing “R”. A modified playlist will automatically be saved when PyRadio exits (or Ctrl-C is pressed).
One thing you may also want to do is remove a station from a playlist, e.g. when found that it not longer works. You can do that by pressing “DEL” or “x”. The deleted station is copied to the unnamed register (refer to section Copying and pasting - Registers for more information).
Finally, opening another playlist is also possible. Just press “o” and you will be presented with a list of saved playlists to choose from. These playlists must be saved beforehand in PyRadio’s configuration directory.
While executing any of the previous actions, you may get confirmation messages (when opening a playlist while the current one is modified but not saved, for example) or error messages (when an action fails). Just follow the on screen information, keeping in mind that a capital letter as an answer will save this answer in PyRadio’s configuration file for future reference.
A playlist that does not reside within the program’s configuration directory is considered a “foreign” playlist. This playlist can only be opened by the “-s” command line option.
When this happens, PyRadio will offer you the choice to copy the playlist in its configuration directory, thus making it available for manipulation within the program.
If a playlist of the same name already exists in the configuration directory, the “foreign” playlist will be time-stamped. For example, if a “foreign” playlist is named “stations.csv”, it will be named “2019-01-11_13-35-47_stations.csv” (provided that the action was taken on January 11, 2019 at 13:35:47).
PyRadio will keep a history of all the playlists opened (within a given session), so that navigating between them is made easy.
In order to go back to the previous playlist, the user just has to press “\\” (double backslash). To get to the first playlist “\]” (backslash - closing square bracket) can be used.
Going forward in history is not supported.
Playing several stations, sometimes among different playlists, and returning to them is sometimes a tedious operation.
This problem is addressed with the “Station history” functionality, which is actually a list of stations which have been played back.
The user can go back and forth in this list using the “<” and “>” keys.
The list is not saved between sessions (restarting the program will lead to an empty list). When an “online service is used (e.g. Radio Browser) the list is reseted with every search that is performed.
On any window presenting a list of items (stations, playlists, themes) a search function is available by pressing “/”.
The Search Window supports normal and extend editing and in session history.
One can always get help by pressing the “?” key.
After a search term has been successfully found (search is case insensitive), next occurrence can be obtained using the “n” key and previous occurrence can be obtained using the “N” key.
PyRadio “Search function” and “Station editor” use a Line editor to permit typing and editing stations’ data.
The Line editor works both on Python 2 and Python 3, but does not provide the same functionality for both versions:
One can always display help by pressing “?”, but that pauses a drawback; one cannot actually have a “?” withing the string.
To do that, one would have to use the backslash key “\” and then press “?”.
To sum it all up:
When in Station editor, the Line editor recognizes an extra mode: Paste mode.
This mode is enabled by pressing “\p” and gets automatically disabled when the focus moves off the line editors.
This mode is designed to directly accept the “?” and “\” characters (which are normally used as commands indicators). This makes it possible to easily paste a station’s name and URL, especially when the “?” and “\” characters exist in them; it is very common to have them in URLs.
The Line editor supports the insertion of CJK Unified Ideographs, as described on CJK Unified Ideographs (Unicode block) also known as URO, abbreviation of Unified Repertoire and Ordering. These characters, although encoded as a single code-point (character), actually take up a 2-character space, when rendered on the terminal.
A depiction of the editor’s behavior can be seen at this image:
Rearranging the order of the stations in the playlist is another feature PyRadio offers.
All you have to do is specify the source station (the station to be moved) and the position it will be moved to (target).
There are three way to do that:
Normally, stations provide information about their status (including the title of the song playing, which PyRadio displays) in Unicode (utf-8 encoded). Therefore, PyRadio will use utf-8 to decode such data, by default.
In an ideal world that would be the case for all stations and everything would be ok and as far as PyRadio is concerned, songs’ titles would be correctly displayed. Unfortunately, this is not the case.
A lot of stations encode and transmit data in a different encoding (typically the encoding used at the region the come from). The result in PyRadio would be that a song title would be incorrectly displayed, not displayed at all, or trying to displaying it might even break PyRadio’s layout.
Note: vlc will not work in this case; it presumably tries to decode the said data beforehand, probably using utf-8 by default, and when it fails, it provides a “(null)” string, instead of the actual data. So, you’d better not use vlc if such stations are in your playlists.
PyRadio addresses this issue by allowing the user to declare the encoding to use either in a station by station mode or globally.
As previously stated, a PyRadio’s playlist can optionally contain a third column (in addition to the station name and station URL columns), which declares the station’s encoding.
So, when a non-utf-8 encoded station is inserted in a playlist, its encoding can also be declared along with its other data. The drawback of this feature is that an encoding must be declared for all stations (so that the CSV file structure remains valid). To put it simple, since one station comprises the third column, all stations must do so as well.
This may seem intimidating (and difficult to achieve), but it’s actually really simple; just add a “,” character at the end of the line of each station that uses the default encoding. In this way, all stations comprise the third column (either by declaring an actual encoding or leaving it empty).
Example:
Suppose we have a playlist with one utf-8 encoded station:
Station1,Station1_URL
Now we want to add “Station2” which is iso-8859-7 (Greek) encoded.
Since we know all stations must comprise the third (encoding) column, we add it to the existing station:
Station1,Station1_URL,
Finally, we insert the new station to the playlist:
Station1,Station1_URL, Station2,Station2_URL,iso-8859-7
Note: Using the -a command line option will save you all this trouble, as it will automatically take care of creating a valid CSV file. Alternatively, you can change the selected station’s encoding by pressing “E” while in PyRadio.
PyRadio’s configuration file contains the parameter default_encoding, which by default is set to utf-8.
Setting this parameter to a different encoding, will permit PyRadio to successfully decode such stations.
This would be useful in the case where most of your stations do not use utf-8. Instead of editing the playlist and add the encoding to each and every affected station, you just set it globally.
PyRadio is basically built around the existence of a valid media player it can use. Thus, it will auto detect the existence of its supported players upon its execution.
Currently, it supports MPV, MPlayer and VLC, and it will look for them in that order. If none of them is found, the program will terminate with an error.
Users can alter this default behavior by using the -u command line option. This option will permit the user either to specify the player to use, or change the detection order.
Example:
pyradio -u vlc
will instruct PyRadio to use VLC; if it is not found, the program will terminate with an error.
pyradio -u vlc,mplayer,mpv
will instruct PyRadio to look for VLC, then MPlayer and finaly for MPV and use whichever it finds first; if none is found, the program will terminate with an error.
The default player to use can also be set in PyRadio’s configuration file, parameter player (default value is mpv, mplayer, vlc), using the “Configuration Window”, through which extra player parameters can be set.
All three supported players can accept a significant number of “command line options”, which are well documented and accessible through man pages (on linux and macOs) or the documentation (on Windows).
PyRadio uses some of these parameters in order to execute and communicate with the players. In particular, the following parameters are in use by default:
| Player | Parameters |
|---|---|
| mpv | –no-video, –quiet, –input-ipc-server, –input-unix-socket, –playlist, –profile |
| mplayer | -vo, -quiet, -playlist, -profile |
| vlc | -Irc, -vv Windows only: –rc-host, –file-logging, –logmode, –log-verbose, –logfile |
Note: The user should not use or change the above player parameters. Failing to do so, may render the player unusable.
PyRadio provides a way for the user to add extra parameters to the player, either by a command line option, or the “Configuration Window” (under “Player:”).
This way, 10 sets of parameters can be inserted and made available for selection.
When the command line option (-ep or –extra_player_parameters) is used, the parameters specified must be of a specific format, and will be added to the list of parameters and made default for the player for the current session.
The format of the parameter is the following: [player_name:parameters]
Where:
Example:
pyradio -ep "vlc:--force-dolby-surround 2"
Note: When a parameter is passed to “mpv” or “mplayer”, PyRadio” will use the default player profile (called “pyradio”).
For “mpv” and “mplayer” a profile can be specified (“vlc” does not support profiles). In this case the format of the parameters part of the command line is: profile:profile_name.
Where:
Example:
pyradio -ep "mpv:profile:second_sound_card"
When the user uses the configuration window (shown in the following image), he is presented with an interface which will permit him to select the player to use with PyRadio and edit its extra parameters.
Each of the supported players can have up to 11 sets of extra parameters (the first one is the default).
The user can add (“a”) a new parameter, edit (“e”) an existing set and delete (“x” or “DEL”) one.
When all desired parameter sets are already defined, using the -ap (–active-player-param-id) command line option can activate the set that corresponds to the number specified. The number to use for any given set can be retrieved using the -lp (–list-player-parameters) command line option.
While PyRadio is running, the user can change the parameters set used by the player using the “Player Extra Parameters” window, by pressing “Z”.
If playback is on, changing the player’s parameters will make the player restart the playback so that the new parameters get used.
Note: Any changes made this way will not be saved but will be in effect until PyRadio terminates.
Most radio stations use plain old http protocol to broadcast, but some of them use https.
Experience has shown that playing a https radio station depends on the combination of the station’s configuration and the player used.
If such a station fails to play, one might as well try to use http protocol to connect to it.
PyRadio provides a way to instruct the player used to do so; the “Force http connections” configuration parameter. If it is False (the default), the player will use whatever protocol the station proposes (either http or https). When changed to True, all connections will use the http protocol.
When the selected player is initialized (at program startup), it reads this configuration parameter and acts accordingly.
If the parameter has to be changed mid-session (without restarting the program), one would press “z” to display the “Connection Type” window, where the parameter’s value can be set as desired.
Note: Changes made using the “Connection Type” window are not stored; next time the program is executed, it will use whatever value the configuration parameter holds. Furthermore, changing the configuration stored value, will not affect the “working” value of the parameter.
MPV and MPlayer, when started, use their saved (or default) volume level to play any multimedia content. Fortunately, this is not the case with VLC.
This introduces a problem to PyRadio: every time a user plays a station (i.e restarts playback), even though he may have already set the volume to a desired level, the playback starts at the player’s default level.
The way to come around it, is to save the desired volume level in a way that it will be used by the player whenever it is restarted.
This is done by typing “v” right after setting a desired volume level.
MPV uses profiles to customize its behavior.
PyRadio defines a profile called “[pyradio]” in MPV’s configuration file (e.g. ~/.config/mpv/mpv.conf). This profile will be used every time playback is started.
Example:
volume=100 [pyradio] volume=50
MPlayer uses profiles to customize its behavior as well.
PyRadio defines a profile called “[pyradio]” in MPV’s configuration file (e.g. ~/.mplayer/config). This profile will be used every time playback is started.
Example:
volume=100 [pyradio] softvol=1 softvol-max=300 volstep=1 volume=50
Note: Starting with PyRadio v. 0.8.9, mplayer’s default profile will use its internal mixer to adjust its volume; this is accompliced using the “softvol=1” and “softvol-max=300” lines above. The user may choose to remove these lines from the config (to activate system-wide volume adjustment) or add them to the config (in case the profile was created by an older PyRadio version).
When a connection to a radio station has been established, the station starts sending audio data for the user to listen to.
Well, that’s obvious, right?
Yes, but this is just half of the story.
The station actually also sends identification data, audio format data, notifications, etc. Part of this non-audio data transmitted by a station is the title of the song currently playing; this is why we can have this data displayed at the bottom of the screen.
Now, not all stations send the whole set of data; most send their name, website, genre and bit rate, for example, but some may omit the website or the genre.
PyRadio can receive, decode and display this data, and even help the user to identify an unknown station. This is the way to do it:
After a connection to a station has been established (after playback has started), just press “i” to display the station’s info.
The window that appears includes the “Playlist Name” (the station name we have in the playlist) and the “Reported Name” (the name the station transmitted to us) among other fields; an example can bee seen here:
If these two names are not identical, the user can press “r” to rename the station in the playlist using the “Reported Name”. This way an unknown station (when only the URL is known) can be correctly identified (after being inserted in a playlist with a dummy station name).
PyRadio takes the concept of registers from vim, and adapts their function to its own needs. So this is how it all works.
There are 36 named registers (name is a-z, 0-9) and one unnamed register.
Named registers are actually files that contain stations and can be opened and edited as regular playlist files. There are some differences in handling them: they are accessible either individually or using a special window, they are automatically saved, and writing errors are ignored. The later means that registers should not be regarded as normal playlist files that can be safely saved and used forever; this is true as long as there’s no problem with writing to them; if a writing error occurs they may get overwritten or emptied. To permanently save a register, on would rename it to a normal playlist file.
The unnamed register holds just one station (the one that has been copied or added to a register or deleted from a playlist), and it is the one used when pasting to a register or a playlist. One can see its contents by pressing “**“.
To copy a station to a register one would press “y” and:
one of “a-z”, “0-9” to add it to the corresponding named register. The unnamed register is also populated.
ENTER to add it to the unnamed register.
To open a named register, one would press “’” (single quote) and:
one of “a-z”, “0-9” to open the corresponding register.
“’” (single quote) to open the “Registers window”, so that a register can be selected.
To rename a named register, one would press “\r” either in the “Registers window” or while editing the register.
To clear a named register, one would press “\c” either in the “Registers window” or while editing the register.
To clear all registers, one would press “\C” either in the “Registers window” or while editing a playlist or a register.
To paste the unnamed register to a playlist or register, one would press:
“p” while editing a playlist or register.
“\p” while editing a playlist or register. This would open the “Paste selection” window.
“\p” in the “Playlist Selection or the”Registers” window.
PyRadio comes with 6 preconfigured (hard coded) themes:
Furthermore, a number of themes (these are actual files saved in the themes installation directory) are also available:
Contrary to the old styling method, which was terminal and palette dependent, a new styling method has been implemented; actual CSS colors can now be defined.
Theme sample / template:
# Main foreground and background Stations #8b8198 #fbf1f2 # Playing station text color # (background color will come from Stations) Active Station #d57e85 # Status bar foreground and background Status Bar #fbf1f2 #d57e85 # Normal cursor foreground and background Normal Cursor #fbf1f2 #dcb16c # Cursor foreground and background # when cursor on playing station Active Cursor #fbf1f2 #d57e85 # Cursor foreground and background # This is the Line Editor cursor Edit Cursor #fbf1f2 #bfb9c6 # Text color for extra function indication # and jump numbers within the status bar # (background color will come from Stations) Extra Func #69a9a7 # Text color for URL # (background color will come from Stations) PyRadio URL #a3b367 # Message window border foreground and background. # The background color can be left unset. # Please refer to the following link for more info # https://github.com/coderholic/pyradio#secondary-windows-background # Messages Border #a3b367 # Theme Transparency # Values are: # 0: No transparency (default) # 1: Theme is transparent # 2: Obey config setting transparency 0
Pressing “t” will bring up the Theme selection window, which can be used to activate a theme and set the default one.
Note: If the theme selected in the “Theme selection window”, (or requested using the “-t” command line option), is in any way invalid, or is of the old format, PyRadio will fall-back to the “dark” theme and will display a relevant message.
The “Theme selection window” will remain open after activating a theme, so that the user can inspect the visual result and easily change it, if desired. Then, when he is satisfied with the activated theme, the window will have to be manually closed (by pressing “q” or any other relevant key - pressing “?” will bring up its help).
Pressing “SPACE”, will apply the theme and make it default, and pressing “c” will apply the theme and make it default and start a file watch function on the file, so that if the file changes, PyRadio will automatically update itself.
After introducing CSS color themes, it has come to my attention that PyRadio will not display colors correctly when executed within specific terminals, konsole, yakuake, deepin-teminal, qterminal and terminology, just to name a few.
Now, I do not know whether this is because of the terminals themselves, python curses implementation or whatever, but that’s that.
PyRadio will try to detect these terminals and disable themes (after displaying a relative message). Then the default theme will be used.
Some of the terminals that work ok, are: gnome-terminal, mate-terminal, xfce4-terminal, lxterminal, terminator, termite, kitty, alacritty, sakura, roxterm, tilix, lilyterm, st, xst, rxvt, urxvt, uxterm, xterm.
If you want to make PyRadio start in one of these terminal, just follow the instructions given at Desktop File: Specifying the terminal to use.
Using CSS colors imposes a couple of restrictions on the type of terminals PyRadio will be able to run:
The TERM variable must be set (Linux and MacOs only).
PyRadio will set it to “xterm-256color” if not set.
Furthermore, if TERM is set to anything like “xterm”, “screen” or “tmux”, PyRadio will set it to “xterm-256color” as well.
Terminals that do not support at least 16 colors will not be able to display any of the new themes. The same goes for terminals that do not support changing their colors (through the curses library).
These terminal will default to the old “dark” theme, displaying whatever colors the active palette dictates.
There are a couple of terminals (that I know of) which will permit changing their colors but will not be able to present the changed color on the fly.
This means that, in order for a theme change to take full effect, PyRadio will have to be restarted.
Secondary windows (such as messages, questions, the “Theme Selection window” the “Encoding Selection window”, etc.) originally use the same background color as the “Main window”.
It is now possible to use a different background color for these windows, to get better visual result.
There are two way to do that:
Defined in a theme
Using a calculated color
Themes have the following entry
# Message window border foreground and background. # The background color can be left unset. # Please refer to the following link for more info # https://github.com/coderholic/pyradio#secondary-windows-background # Messages Border #a3b367
It is possible to define a background color as well, like so
Messages Border #a3b367 #F5DBDE
In this case, this color will be used as the Secondary Windows background color.
Although one can use any color here, it is recommended to follow these guidelines for best visual result:
pastel color '#fbf1f2' # show color info pastel lighten .1 '#fbf1f2' # color lightened by 10% pastel darken .1 '#fbf1f2' # color darkened by 10%
This information is actually relevant to creating a new PyRadio theme, but it’s very important in order to understand how the calculated background color works.
PyRadio will use the same background color for all windows by default, provided that the theme used does not define a “Messages Border” background color.
In order to use a “Messages Border” background color different than the “Stations background” color, when “Messages Border” background color is not defined in the selected theme, a config option is available; “Calculated color”.
This config option takes a value that’s between 0 and 0.2.
If it is 0, no color change will occur.
Otherwise, the value acts as a percentage (a factor), which indicates how much the luminance of the “Stations background” color will change to produce the new background color.
This is how this works: PyRadio will calculate the “Stations background” color perceived brightness, which will indicate whether the color is dark or light. Then depending on that, will add or subtract factor percent from its luminance value.
Finally, a check will be made to see if this color is close to “Messages Border” foreground color, and re-adjusted as possible.
Note: When a calculated background color is used, pressing “~” (tilde) will toggle it on and off. This setting will be valid until PyRadio terminates, or a new theme is loaded.
Users can easiliy create their own themes, using for example CSS color names as a resource, and
Save the theme provided as a template above in their themes folder using any (short) file name and a “.pyradio-theme” file extension.
For this reason, a folder called “themes” will probably have to be created in PyRadio config directory (~/.config/pyradio or %APPDATA%\pyradio on Windows)
Customize it as desired
Load it from the “Theme selection window” (it will be found under “User Themes”).
An old theme (using the old format) can be asily converted to the new format, using the script found at this gist.
Note: In order to get the color intended to be used, the same palette as the one used when the original theme was created, must be used.
For PyRadio, transparency means that a theme’s background actually disappears, effectively making it to display whatever is on the terminal (color/picture/transparency). The visual result depends on terminal settings and whether a compositor is running.
Not all themes look good when transparency is ON, so themes can now declare whether they want to use transparency or not. This is the “transparency” variable of the theme, which can have these values:
Please notice that this is just a hint; themes will obey the rules above, but transparency can still be toggled using “T” (capital “t”).
When the “Theme selection window” is visible, a “[T]” string displayed at its bottom right corner will indicate that transparency is on.
Terminal users have been using all kind of software to change / update / adapt their terminal colors and palettes, such as bASE16, pywal, wpgtk, theme.sh, to name a few.
PyRadio is now able to “watch” a given theme for changes and update its colors whenever the theme changes.
To set up a theme for auto update, one would just open the “Theme Selection” window, navigate to a theme under “User Themes” and press “c”. To create a user theme just follow the procedure described in section User themes.
Consecuently, the default theme name will be preceded by:
PyRadio is able to use (and watch) the output of certain projects that modify terminal colors.
PyRadio will detect theses projects (programs installed and initialized), and will add them under the “Ext. Themes Projects” section of the “Themes Selection Window.”
If loading any of these themes fails, the default dark theme will be loaded, but contrary to a local theme being invalid, the selection will persist (so that the theme gets loaded wheneve it is available).
Currently, the following projects are supported:
Thanks to the wonderful work by user edunfelt, there is now a PyRadio base16 template in place, and themes have been produced based on the project (there are more than 900 themes available).
This implementation will add four entries in the theme selection menu (with alternative and variant forms of the main theme).
Then, any of the themes can either be activated or watched; in which case PyRadio will download and apply the corresponding theme.
In case one wants to use any of these themes, but not install or use base16, one can get them from this repo, and use the “cycle_themes.py” and “install_themes.py” scripts to inspect and install them.
For Windows users, this is the only way to use any of these “Project Themes”, since their generation works on non-windows platforms only.
When detected, two themes will be added to the menu; the main and the alternative form.
Since these themes are generated on the fly, as the wallpaper changes, there is no way to use them if pywal is not in use.
Note: If pywal themes are activated but not watched, the theme will be corrupted when the wallpaper changes, and will have to be manually reloaded. So, it’s better to just always watch these themes.
When detected, four themes will be added to the menu; the main and the alternative forms (there are 400 plus themes available, which makes a stuggering number of around 1800 themes for PyRadio!)
In case one wants to use any of these themes, but not install or use theme.sh, one can download this repo, and use the “create_themes.py” script to create the themes, and “cycle_themes.py” and “install_themes.py” scripts to inspect and install them.
For Windows users, this is the only way to use any of these “Project Themes”, since their generation works on non-windows platforms only.
Being a console application, PyRadio was never intended to work with a mouse.
Furthermore, when using the mouse on a console application, the result is highly dependent on the terminal used and the way it implements mouse support.
Having said that, and since the question of using the mouse with PyRadio has been risen, basic mouse support has been implemented; starting, stopping and muting the player, scrolling within the playlist and adjusting the player’s volume is now possible using the mouse.
All one has to do is enable mouse support in the “Config Window” (mouse support is disabled by default) and restart PyRadio for the change to take effect.
Then, the mouse can be used as follows:
| Action | Result |
|---|---|
| Click | Change selection |
| Double click | Start / stop the player |
| Middle click | Toggle player muting (does not work with all terminals) |
| Wheel | Scroll up / down |
| Shift-Wheel | Adjust volume (does not work with all terminals) |
Version 0.8.9.17 adds to PyRadio the ability to log the titles displayed at the bottom of its window, in a log file, for refference.
The logger, which works independantly from the “degub” function, is actually a Rotating File Handler, configured to write up to 5 files of around 50KB each (parameters maxBytes=50000 and backupCount=5).
The way this works, according to the documenataion, is that one “can use the maxBytes and backupCount values to allow the file to rollover at a predetermined size. When the size is about to be exceeded, the file is closed and a new file is silently opened for output. Rollover occurs whenever the current log file is nearly maxBytes in length… When backupCount is non-zero, the system will save old log files by appending the extensions ‘.1’, ‘.2’ etc., to the filename. For example, with a backupCount of 5 and a base file name of app.log, you would get app.log, app.log.1, app.log.2, up to app.log.5. The file being written to is always app.log. When this file is filled, it is closed and renamed to app.log.1, and if files app.log.1, app.log.2, etc. exist, then they are renamed to app.log.2, app.log.3 etc. respectively.
The function can be enabled:
The titles are written in a file called pyradio-titles.log which is saved at PyRadio configuration directory.
Log file sample:
Apr 18 (Mon) 13:12 | >>> Station: Lounge (Illinois Street Lounge - SomaFM) Apr 18 (Mon) 13:12 | Jack Costanzo - La Cumparsa, Harlem Nocturne Apr 18 (Mon) 13:14 | Don Baker Trio - Third Man Theme Apr 18 (Mon) 13:16 | Gillian Hills - Un Petit Baiser
An extra functionality is made possible because of “titles’s logging”: tagging a title (something like liking a song).
The idea is that the user plays a station and hears a song he likes and want to look it up later. With this functionality, he can tag the song (make a note in the log file), so he can refer to it at a later time.
To tag a title, one has to press the “w” key.
Then, if titles’s logging is already enabled, the log file will have an entry similar to the one shown below:
Apr 18 (Mon) 13:39 | Tom Russell - Bus Station Apr 18 (Mon) 13:40 | Tom Russell - Bus Station (LIKED)
If title’s logging is not enabled, it will be turned on, the song will be tagged and logging will be turned off again:
Apr 18 (Mon) 15:38 | === Logging started Apr 18 (Mon) 15:38 | >>> Station: Folk (Folk Forward - SomaFM) Apr 18 (Mon) 15:38 | Lord Huron - Lullaby Apr 18 (Mon) 15:38 | Lord Huron - Lullaby (LIKED) Apr 18 (Mon) 15:38 | === Logging stopped
PyRadio supports the following Online radio directory services:
This is a community driven effort (like wikipedia) with the aim of collecting as many internet radio and TV stations as possible.
Read more at PyRadio RadioBrowser Implementation
To access supported services, just press “O” (capital “o”) at the program’s main window.
PyRadio can provide Desktop Notifications when a notification daemon is already present (on Linux and BSD), or throught Windows Notification Service (WNS).
If enabled, PyRadio will display:
To find out more about configuring this feature, please refer to Desktop Notification.
PyRadio will install a Desktop File under ~/.local/share/applications.
Note: The system wide Desktop File will probably be under /usr/share/applications or /usr/local/share/applications.
By default, this Desktop File will add a “PyRadio” entry under the “Internet” category (or menu), and will execute PyRadio no matter if the directory it resides in is the PATH or not, using the default terminal that the system uses.
In case of a local installation, when a system wide installation also exists, the entry will display “PyRadio - Local” to distinguish itself from the system wide “PyRadio” one.
Note: If the TERMINAL variable is set, the Desktop File will use that instead.
If a specific terminal has to be used, using the –terminal command line option is the way to go:
pyradio --terminal kitty
This command will set the terminal in the Desktop file, so that:
Exec=kitty -e pyradio
To have PyRadio try to find a suitable terminal, execute:
pyradio --terminal auto
To restore the original functionality (specifying no terminal):
pyradio --terminal none
If a PyRadio parameter has to be present in the Desktop File, use the –terminal-param command line option:
pyradio --terminal none --terminal-param "_p 2"
This command will use no specific terminal and will pass the “-p 2” (play station No 2 automatically) parameter to PyRadio. To pass such a parameter, substitute all hyphens with underscores.
PyRadio uses session locking, which actually means that only the first instance executed within a given session will be able to write to the configuration file.
Subsequent instances will be “locked”. This means that the user can still play stations, load and edit playlists, load and test themes, but any changes will not be recorded in the configuration file.
If for any reason PyRadio always starts in “locked mode”, one can unlock the session, using the “–unlock” command line option.
PyRadio will periodically (once every 10 days) check whether a new version has been released.
If so, a notification message will be displayed, informing the user about it and asking to proceed with updating the program (provided this is not a distribution package).
First thing you do is get the installation script. Open a terminal and type:
cd wget https://raw.githubusercontent.com/coderholic/pyradio/master/pyradio/install.py
or using curl:
cd curl -L https://raw.githubusercontent.com/coderholic/pyradio/master/pyradio/install.py -o install.py
Note: If you have neither wget or curl installed, or you are on Windows, just right click on this link and use your browser “Save link as” menu entry to save the file in your home folder.
Finally, execute the command:
python install.py --force
PyRadio will uninstall all previously installed versions when updated (using the -U command line option), so no extra steps are needed any more to house keep your system.
Adding the “-d” option to the command line will instruct PyRadio to enter Debug mode, which means that it will print debug messages to a file. This file will always reside in the user’s home directory and will be named pyradio.log.
In case of a bug or a glitch, please include this file to the issue you will open at github.
When a bug is found, please do report it by opening an issue at github, as already stated above.
In you report you should, at the very least, state your pyradio version, python version and method of installation (built from source, AUR, snap, whatever).
It would be really useful to include ~/pyradio.log in your report.
To create it, enter the following commands in a terminal:
$ rm ~/pyradio.log $ pyradio -d
Then try to reproduce the bug and exit pyradio.
Finally, include the file produced in your report.
If you are a packager and would like to produce a package for your distribution please do follow this mini guide.
First of all, make sure you declare the pacakges’s requirements to the relevant section of your manifest (or whatever) file. These are:
After that, you will have to modify some files, because PyRadio is able to update and uninstall itself, when installed from source. This is something you do not want to be happening when your package is used; PyRadio should be updated and uninstalled using the distro package manager.
In order to accomplice that, you just have to change the distro configuration parameter in the config file. PyRadio will read this parameter and will disable updating and uninstalling, when set to anything other than “None”. So, here’s how you do that:
Once you are in the sources top level directory (typically “pyradio”), you execute the command:
sed -i 's/distro = None/distro = YOUR DISTRO NAME/' pyradio/config
Then you go on to produce the package as you would normally do.
For example, an Arch Linux packager would use this command:
sed -i 's/distro = None/distro = Arch Linux/' pyradio/config
The distro name you insert here will appear in PyRadio’s “Configuration Window”. In addition to that it will appear in the log file, so that I know where the package came from while debugging.
Having said that, if you are not packaging for a specific distribution, please do use something meaningful (for example, using “xxx” will do the job, but provides no useful information).
Then, if you want to enable Desktop Notifications, do a
sed -i 's/enable_notifications = -1/enable_notifications = 0/' pyradio/config
or
sed -i 's/enable_notifications = -1/enable_notifications = 60/' pyradio/config
to have notifications every 60 seconds, for example. You can use any value here, starting from 30 to 300 (meaning every 30 seconds up to 5 minutes), using a step of 30.
Finally, make sure you install:
PyRadio uses code from the following projects:
CJKwrap by Florent Gallaire - A library for wrapping and filling UTF-8 CJK text.
ranger - A console file manager with VI key bindings.
Vifm - A file manager with curses interface, which provides a Vi[m]-like environment.