PyRadio Documentation

# PyRadio

Command line internet radio player.

## Table of Contents Top

- Features
- Requirements
- Changelog
- Installation
- Command line options
- Controls
  - Global shortcuts
  - Customizing key bindings
- HTML help
- PyRadio Modes
  - Secondary Modes
  - Tiling manager modes
- Config file
  - The package config file
  - The user config file
- About Playlist files
  - Defining and using Groups
  - Integrating new stations
  - Specifying a playlist to load (command line)
  - Autoloading playlists
  - Managing playlists (within PyRadio)
  - Managing foreign playlists
  - Playlist history
  - Playlist validation support
- Stations history
- Search function
  - Fuzzy Search
- Line editor
  - CJK characters support
- Moving stations around
- Specifying stations’ encoding
  - Station by station encoding declaration
  - Global encoding declaration
- Player detection / selection
  - Changing player mid-session
    - Specifying a station’s preferred player
  - Specifying a station’s Referer URL
    - Note about MPlayer
    - Referer support in the playlist
  - Extra Player Parameters
    - Using the Configuration Window
- Player connection protocol
  - Visual reminder
- Player default volume level
  - MPV
  - MPlayer
  - VLC
- Station volume
  - How it Works
- Buffering
- Displaying Station Info
- Copying and pasting - Registers
- Favorites playlist
- Displaying the Current Time
  - Configuration
- PyRadio Themes
- Recording stations
- Mouse support
- Title logging
  - Tagging a title
- Online radio directory services
- Desktop Notifications
- Desktop File
  - Specifying the terminal to use
    - Specifying PyRadio parameters
- Session Locking
  - Session unlocking
- Update notification
- OS Media Controls integration
- Remote Control Server
  - Remote Control Client
- Playing a station in the terminal
- Text-to-Speech Support
- Debug mode
- Reporting bugs
- Packaging PyRadio

## Features Top

PyRadio provides the following features:

- vi like keys in addition to arrows and special keys
- RadioBrowser support
- Remote Control Server
- OS media controls (MPRIS, SMTC, Now Playing)
- Multiple playlist support
- M3U playlist support
- vi like station registers
- Theming support
- Station editor (add/edit) with CJK characters support
- Configuration editor
- Search function
- Customizable key bindings
- Playlist validation support
- Easy installation / updating
- Runs on Linux, macOS and Windows

and much more…

## Requirements Top

- python 3.8+
  - setuptools
  - wheel
  - requests
  - dnspython
  - psutil
  - rich
  - python-dateutil
  - netifaces
- dbus-next on linux, required to enable MPRIS
- MPV, MPlayer or VLC installed and in your path
- MKVToolNix (cli files) to insert tags, chapters and cover to recordings (optional, if MPV or VLC is to be used, but mandatory in the case of MPlayer)

Linux users will have to install a resource opener package, a utility to open directories, html pages, etc. PyRadio will look for xdg-open, gio, mimeopen, mimeo or handlr, in that order of detection. If a different resource opener is used, one can declare it in the Configuration Window.

## Changelog Top

    2026-05-04 s-n-g
        * version 0.9.3.11.31 - 0.9.3.12-beta31
        * adding Group Selection ability to the main and Keyboard
          configuration windows
        * adding a Fuzzy Finder for station ans playlist windows, based on
            feat: add fuzzyfinding for station (hotkey f) #327
        * implementing config window item help TTS messages
        * adding TTS message for even more windows
        * adding the update_window_title config parameter for
          [FEAT] Option to disable terminal title modification #328
        * fixing RadioBrowser config dirty token color
        * fixing a couple of CJK rendering issues
        * updating documentation

    2026-04-23 s-n-g
        * version 0.9.3.11.30 - 0.9.3.12-beta30
        * implementing a workaround for: Do not check if the package
          is a path in the current working directory -
            https://github.com/pypa/pipx/issues/1778
        * enabling TTS help messages
        * implementing dialog TTS messages for
          - the Remote Control Server window
          - the Connection Type window
          - the Player Extra Parameters window
          - the Switch Media Player window
          - the Open Directory window
        * fixing a couple of minor bugs and crashes
        * updating documentation
        * updating Windows MPV download link

    2026-03-28 s-n-g
        * version 0.9.3.11.29 - 0.9.3.12-beta29
        * PyRadio will properly terminate when terminal closed (#325)
        * fixing Remote Control Web interface when RadioBrowser is toggled
        * adding the "Auto update stations" config parameter
          the user can now disable stations.csv update detection

    2026-03-13 s-n-g
        * version 0.9.3.11.28 - 0.9.3.12-beta28
        * adding 6 more System Themes by lee2sman
        * adding OS media controls support
          - MPRIS on Linux
          - SMTC on Windows
          - "Now Playing" on macOS
        * adding the "Enable OS Media Controls" configuration option
        * adding the --mpris command line parameter
          (for linux pipx isolated installations)
        * adding the "Speak start too" TTS configuration parameter
        * macOS enhancement: PyRadio will appear in both the Applications
          panel and the Spotlight
        * fixing a --show-dirs crash
        * fixing a couple of minor bugs
        * updating documentation
        * updating Windows MPV download link

    2026-02-07 s-n-g
        * version 0.9.3.11.27 - 0.9.3.12-beta27
        * fixing #322 - pyradio dont start

    2026-02-06 s-n-g
        * version 0.9.3.11.26 - 0.9.3.12-beta26
        * fixing #321 - stations update crash
        * TTS will concert \" \' to " '
        * updating documentation
        * updating MPV Windows download link

    2026-01-21 s-n-g
        * version 0.9.3.11.25 - 0.9.3.12-beta25
        * fixing #320 - pyradio-client unusable
        * updating MPV Windows download link

    2026-01-16 s-n-g
        * version 0.9.3.11.24 - 0.9.3.12-beta24
        * fixing playlist open regression
        * fixing playlist display name removes "." regression

    2026-01-15 s-n-g
        * version 0.9.3.11.23 - 0.9.3.12-beta23
        * the -s (--stations) commamd line parameter will open M3U files as well
        * fixing the importlib_resources dependency problem for Python 3.8
        * fixing a typo that would crash the program
        * implementing pylint suggestion
        * updating MPV Windows download link
        * updating documentation

    2026-01-04 s-n-g
        * version 0.9.3.11.22 - 0.9.3.12-beta22
        * fixing ##317 - Not starting fresh install on fresh fedora 43
        * fixing #316 - remote control crash
        * working on TTS - updating tts.md
        * refactoring based on pylint and ruff
        * updating MPV Windows download link

    2025-11-09 s-n-g
        * version 0.9.3.11.21 - 0.9.3.12-beta21
        * fixing #312 - VLC crashes PyRadio after the radio station starts playing
        * fixing several minor bugs
        * adding basic TTS support (enabled from config or the toggle option \T)

    2025-10-23 s-n-g
        * version 0.9.3.11.20 - 0.9.3.12-beta20
        * adding error messages for charset-normalizer module not found (#305)
        * fixing #307 - [BUG] TypeError: string indices must be integers, not 'str'
        * fixing a bug that would lead to a crash when trying to display the
          "Player Extra Parameters" (def. key "Z")
        * updating docs including "update title logging directory info in
          pyradio.1" #308
        * fixing [BUG] Inconsistency with RadioBrowser Config's vertical
          navigation keybindings (j/k) - #309
        * localized keyboard setting is actually being saved
        * localized keyboard now works on Windows
        * enabling include-package-data and setuptools-scm in pyproject.toml
        * fix(resources): support running from zip/wheel via importlib.resources
          This makes PyRadio fully functional even when distributed as a wheel/zip
        * updating mpv windows download link

    2025-09-19 s-n-g
        * version 0.9.3.11.19 - 0.9.3.12-beta19
        * fixing #303 - Crash on adding a station
        * updating build_install_pyradio so that it detects pipx even if it
          is not provided as a module (executable only)
        * updating pyproject.toml
        * renaming setup.py to seyup.py.legacy so that it does not interfere
          with the modern build chain but keeping a legacy way to build the
          package if needed
        * updating mpv windows download link

    2025-09-12 s-n-g
        * version 0.9.3.11.18 - 0.9.3.12-beta18
        * both mpv and mplayer will honor the profile set by config
        * using \m to change the default player will actually keep the new value

    2025-09-09 s-n-g
        * version 0.9.3.11.17 - 0.9.3.12-beta17
        * adding playlist validation (CSV and M3U)
        * adding charset-normalizer to the required modules - fixing Debian bug
        * fixing #301 - SyntaxError: f-string expression part cannot include a backslash
        * fixing #302 - Windows installation script
        * updating mpv windows download link
        * updating docs

    2025-09-02 s-n-g
        * version 0.9.3.11.16 - 0.9.3.12-beta16
        * heavy refactoring - expect bugs!
        * adding player field (optional) to station's definition
        * adding M3U playlist support
        * fixing #300 - General Options player select param bug
        * fixing a potential Remote Control Server crash
        * fixing a couple of minor bugs
        * updating mpv download link for windows
        * updating docs

    2025-06-18 s-n-g
        * version 0.9.3.11.15 - 0.9.3.12-beta15
        * fixing #295 - crash when no localized keys present

    2025-06-17 s-n-g
        * version 0.9.3.11.14 - 0.9.3.12-beta14
        * added a confirmation dialog to the Configuration Window, to
          inform the user that the changes will be lost
        * fixing a crash that would occur when trying to use the external
          player before playing a station for the first time
        * fixing #294 Keypresses shows up as characters in the Pyradio window
        * the "Open Directory" window now inclues options to open the config
          directories of the installed players
        * fixing a bug occurring when saving the volume of a station; the
          profle would not be found, resulting in creating duplicate profile
          entries.

          Users are strongly encouraged to open the players' config file and
          manually remove any duplicate profiles

    2025-05-19 s-n-g
        * version 0.9.3.11.13 - 0.9.3.13-beta13
        * fixing #289 - sing < or > results in UnboundLocalError
        * updating MPV download link for Windows

    2025-05-15 s-n-g
        * version 0.9.3.11.12 - 0.9.3.12-beta12
        * implementing #291 - Don't stop playback when entering another
          playlist a config option (Continuous playback) has been added
          to help realize this feature
        * fixing #286 - Sorting Error
        * fixing #287 - Header Error
        * fixing build license warning
        * mpv reply will not stop being parsed when title found

    2025-05-10 s-n-g
        * version 0.9.3.11.11 - 0.9.3.12-beta11
        * fixing a dict Key error that will make some stations fail - #284
        * fixing an error that would render all player unusable on Windows - #282
        * fixing Windows getting stuck to "PyRadio still running" message - #283

    2025-05-06 s-n-g
        * version 0.9.3.11.10 - 0.9.3.12-beta10
        * redesigning the Station Editor
            - adding Volume, Buffering, Force http, Profile and Referrer fields
            - grouping URL, Icon and Referrer fields
        * station encoding can now get a "Default" value, to leave the station's
          encoding empty. This will make it use the default (config) encoding.
        * all players will use the new station fields
        * \V will toggle the use of station volume (revert to profile volume)
        * fixing a couple of minor bugs
        * updating mpv download link (Windows)
        * - updating docs

    2025-03-21 s-n-g
        * version 0.9.3.11.9 - 0.9.3.12-beta9
        * fixing default station selection in the config window
        * adding search support for both the config window and the shortcuts window

    2025-03-19 s-n-g
        * version 0.9.3.11.8 - 0.9.3.12-beta8
        * fixing #281 - Favourite list becomes corrupted after adding station
        * adding buffering config parameters: buffering and mplayer_save_br
        * pressing \b will toggle global buffering for the session
        * the Buffering Window will change station buffering value instead of config
        * station volume will be saved (\v by default) and the playlist will
          be silently saved - station volume will work for VLC only
        * saveCurrentPlaylist: trailling commas will be eliminated
        * updating Windows MPV download link
        * adding bufferring.md and pyradio_buf man page
        * updating docs

    2025-03-13 s-n-g
        * version 0.9.3.11.7 - 0.9.3.12-beta7
        * fixing #280 - Removing station and saving removes
          all URLs from stations.csv file

    2025-03-10 s-n-g
        * version 0.9.3.11.6 - 0.9.3.12-beta6
        * fixing #279 - The list of favorite stations is reset when added
        * fixing #278 - Typos 'RyRadio' when updating
        * updating docs

    2025-02-27 s-n-g
        * version 0.9.3.11.5 - 0.9.3.12-beta5
        * fixing the installation script
        * playlist format change: adding profile, buffering, http, volume
          and referer fields (support for these fields not implemented yet)
        * referer files will be integrated to playlists
        * config option added to invert the mouse wheel action (#272)
        * fixing #276 : mouse support will always be on
            - if disabled, mouse keys will be ignored
            - toggling the config option does not require a program restart any more
        * fixing #277: installation fails when username contains a space character
        * removing not working stations from stations.csv
        * updating docs

    2025-01-18 s-n-g
        * version 0.9.3.11.4 - 0.9.3.12-beta4
        * adding a clock displayed at the beginning of the Status Line
        * adding a new system theme: lambda_by_amski1
        * all players will try to catch (and display) HTTP errors (403, 404,
          503, etc) and player errors through Crash detection
        * rearranging options in the Config Window
        * the remote control server will be cleanly terminated when the terminal closes
        * titles log: fixing a bug that would disallow writing the station name to the log
        * when the External Player is used, pyradio will not exit; it will reload the tui
          and continue from where it left off
        * keep working on keyboard.py
        * started working on localized shortcuts
        * updating mpv player link on Windows
        * fixing issues reported by pylint
        * removing more python 2 code
        * updating docs

    2024-12-05 s-n-g
        * version 0.9.3.11.3 - 0.9.3.12-beta3
        * fixing a crash when opening RadioBrowser Config
        * all config windows will display distro info (if applicable)

    2024-12-05 s-n-g
        * version 0.9.3.11.2 - 0.9.3.12-beta2
        * Implementing the Shortcuts Window, making it possible to customize
          PyRadio's key bindings
        * fixing install.py (#262)
        * implementing #252

    2024-10-17 s-n-g
        * version 0.9.3.11.1 (BUG FIX) - 0.9.3.12-beta1
        * adding -sdd (--show_dirs) command line parameter
        * fixing a couple of bugs (some reported by pylint /ruff)
        * integrating suggestions by pylint / ruff
        * adding a Everforest based system theme
        * all keybindings are now customizable (interface not implemented yet)

    2024-08-30 s-n-g
        * version 0.9.3.11 (BUG FIX)
        * recovering from regression after addressing #249
        * updating docs

    2024-08-30 s-n-g
        * version 0.9.3.10
        * do not enable xdg compliant if user_config_dir is specified
        * do not create the default recording directory until it is
          actually needed (to save data in it)
        * when saving players' extra parameters reduce the list by removing
          the unused porifles from the list
        * Fixing player_params_file and schedule_file location when XDG
          compliance is ON
        * fixing a pyradio-client crash when no command is specified
        * fixing: MPV Volume resets to 0% when trying to increase
          beyond maximum #251
        * fixing a help crash: adding H_CONFIG_PLAYER help key
        * added a gruvbox variation system theme
        * updating docs and fixing broken links

    2024-06-04 s-n-g
        * version 0.9.3.9
        * fixing a crash when adding a station to favorites

    2024-06-04 s-n-g
        * version 0.9.3.8
        * pressing "*" will add the selected station to favorites
        * adding the possibility to declare a "Referer URL" for a station
        * pyradio-client: /title will actually report the song title
        * pyradio-client: beautifying output
        * removing more python 2 code
        * updating docs

    2024-05-24 s-n-g
        * version 0.9.3.7
        * introducing the pyradio-client program
        * adding three more System Themes
        * do not allow to change the Recording Directory while recording
          is on either in this instance or a headless instance
        * fix PyRadioOpenDir: always open dir
        * PyRadioRecordingDir: adding key 'd' to revert to deault
        * fixing default opener detection
        * if a linux opener is enetered but config not saved, and opener
          window is opened again, display the one entered instead of the
          saved opener
        * fix stop mkvmerge recursive execution
        * Remote Control Server: adding a warning to the info response,
          if PyRadio is not in Main Mode
        * Remote Control Server: introducing the /reconfig command
        * Desktop Notifications: stations icons are now being cached
        * config: adding parameter remove_station_icons, to remove
          downloaded files on program exit

    2024-05-10 s-n-g
        * version 0.9.3.6
        * fixing #241 - pyradio-recordings folder keeps showing in home directory
        * When XDG compliance is forced due to both XDG_DATA_HOME and XDG_STATE_HOME
          directories already exist, update the local Desktop file, so that the
          Icon point to its new location
        * fixing typos

    2024-05-06 s-n-g
        * version 0.9.3.5
        * Config Window changes:
            * when r / d (revert to saved / default params) is typed,
              correctly load the corresponding theme
            * do not use hardcoded values when loading default params
            * do not toggle transparency when repeatedly pressing r / d
            * do not change transparency settings when themes are not being used
            * fixing cursor positioning for PgDn
        * XDD compliant operation changes:
            * if both XDG_DATA_HOME and XDG_STATE_HOME directories already exist,
              xdg_compliant will be set to True, even if not set in the
              configuration file (it means an XDG migration has been performed
              in the past; using the non-XDG dirs will lead to data loss)
            * suppress list of files moved when migrating to XDG dirs
        * Theming changes:
            * preserve theming config options when a terminal that does not
              support color change is used and config is saved
            * adding "Color Factor" parameter to themes
        * Linux Vistual Console
            * adding config option console_theme; this way either the dark
              or the light theme can be used when on the console
            * detect execution on the Virtual Console
            * do not open HTML help
            * display list of directories when \o is pressed
            * do not issue desktop notifications
            * clear console at exit
        * fixing #240 - AttributeError: NoneType object has no attribute page
        * actually open playlists list ('o') or RabioBrowser ('O'), after a
          dirty palylist save query has been performed
        * updating Windows Media Players links
        * updating docs

    2024-04-23 s-n-g
        * version 0.9.3.4 (BUG FIX)
        * adding --no-video command line parameter for vlc
        * removing more python 2 code
        * updating macOS installation instructions (based on Ventura)
        * fixing #239 - PyRadio doesn't remember warning message was already shown
        * fixing loading saved and default config options in Config Window,
          Recording Dir is excluded from change
        * updating docs

    2024-04-18 s-n-g
        * version 0.9.3.3 (BUG FIX)
        * adding a resource opener parameter for linux installations
        * fixing issues #236 and #237
        * fixing several minor bugs

    2024-04-08 s-n-g
        * version 0.9.3.2 (BUG FIX)
        * fixing #233 (move .registers to state dir)
        * fixing stations.csv (from erroneous PR #227)
        * updating headless.md

    2024-04-06 s-n-g
        * version 0.9.3.1 (BUG FIX)
        * fixing #231 - [BUG] pyradio-0.9.3 cannot be executed
        * closing #232 - [BUG] self.xdg.xdg_compliant = False

    2024-04-05 s-n-g
        * version 0.9.3
        * user config file will not be automatically created; it will be
          created only when some parameter value is different to the one
          set in the package config file
        * adding -pc (--print-config) command line option
        * adding the xdg_compliant config option (packagers option)
          if set to True, config dir contents will be moved to XDG Base
          dir (https://wiki.archlinux.org/title/XDG_Base_Directory)
        * RadioBrowser: present next previous result pages
        * RadioBrowser: adding Icon to station DB info
        * Remote Control Server: adding commands relevant to RadioBrowser results
          page navigation (text interface) and relevant web interface buttons
        * Remote Control Server: adding REC button to web interface
        * Remote Control Server: the output of the /info command will report
          headless operation and if RadioBrowser is active, search term used and
          page number
        * introducing the Messaging System; most messages displayed to the user
          have been transfered to messages_system.py
        * moving PyRadio cache contents to ~/.cache (not on Windows)
        * moving the recordings directory to home folder and renaming it to
          "pyradio-recordings".
        * adding recording_dir config parameter and window to customize it
        * titles log files will be saved in the recordings directory
        * if netifaces module is not installed, headless operation will be aborted
        * fixing #229: Crash when $HOME/.mplayer directory does not exist
        * fixing escaped chars in window title and litles log file
        * adding a Windows python 3.12 workaround to the "curses silently exits" bug
        * adding two Serbian stations in station.csv - PR #227
        * updating documentation

    2024-02-24 s-n-g
        * version 0.9.2.25
        * dropping python 2 - PyRadio will only run on python 3
        * fixing #228

    2024-01-12 s-n-g
        * version 0.9.2.24 (BUG FIX)
        * fixing mpv title parsing (once again)
        * fixing "Genre" field wrapping on Station Info window

    2024-01-11 s-n-g
        * version 0.9.2.23 (BUG FIX)
        * fixing issue #224 - crash when "artist", "album", "year"
          string in received data

    2024-01-05 s-n-g
        * version 0.9.2.22 (BUG FIX)
        * fixing bug #222 - Appending a radio station with A in a playlist
          leads to a crash (when number stations is less than window height)
        * fixing a crash that would occur when pressing ENTER on the Cancel
          button of the "rename playlist" and "new playlist" window

    2024-01-04 s-n-g
        * version 0.9.2.21
        * adding --headless command line parameter and functionality
        * adding the --address command line parameter
        * recorded files will always be saved in the recordings folder
          If mkvtoolnix is present, a tmp_ prefix will be used to record
          the raw file, which will be removed after chapters integration
        * the message to indicate failure to connect to RadioBrowser will
          be displayed for 2 seconds (instead of requiring a key press)
        * mpv will read the "artist" and "title" fields from station response (#217)
        * remote control server: adding functionality for RadioBrowser
        * remote control server: do not disable individual buttons
        * remote control server: will restart if crashed
        * remote control server: can now accept real IPs (config option)
        * introducing "remote control server lock" files
        * trying to fix "pipx not found" on MacOS again
        * fixing config window rendering bug (#215)
        * fixing cover insertion to mkv files
        * fixing escape character warnings for python 3.12
        * fixing lock refresh issues
        * working on scheduler (not available yet)
        * updating win mplayer link
        * creating issues templates
        * updating documentation

    2023-11-23 s-n-g
        * version 0.9.2.20
        * Creating the docs folder and moving files there
        * Updating pyproject.toml and setup.py for the latest
          Installation method changes
        * Working on scheduler (not applicable yet)
        * Updating docs

    2023-11-06 s-n-g
        * version 0.9.2.19 (BUG FIX release)
        * cover.png updated
        * make sure cover.png is in the data folder
        * fix "No chapters found" message when recorded file has
          less than 3 chapter markers

    2023-11-03 s-n-g
        * version 0.9.2.18
        * fixing a crash on mkvtoolnix.py

    2023-11-03 s-n-g
        * version 0.9.2.17
        * Recorded MKV files will have a cover image by default
          (when MKVToolNix is installed)
        * Adding -mkv, -scv, -srt, -ach and -lr command line parameters
          (applicable when MKVToolNix is installed)
        * Rearranging and grouping options in the program's help screen
        * Working on scheduler (not applicable yet)
        * Updating docs

    2023-10-15 s-n-g
        * version 0.9.2.16
        * install.py: will terminate if python not in PATH
        * recorded files will have tags inserted in them if mkvmerge
          is detected. Chapters will also be added if the station
          provides ICY Titles
        * opening the config folder while recording will actually open the
          recording folder
        * buffering can now be disabled (in 0.9.2.15, once buffering was
          enabled, it could not be disabled until program termination)
        * fixing a couple of race conditions (threading lock files not being
          released) that would lead to a freeze
        * fixing players crash detection routines
        * fixing config players parsing
        * on Windows, downloaded recording files in the data directory
          will be deleted at startup, when recording is not active
        * adding recording man page
        * Updating docs

    2023-10-05 s-n-g
        * version 0.9.2.15 (BUG FIX)
        * fixing mplayer and vlc recording
        * mplayer buffering min changed to 250KB
        * fixing updateRecordingStatus not exiting when asked
        * buffer size cannot be 0

    2023-10-04 s-n-g
        * version 0.9.2.14
        * adding players buffering
        * [B] will be displayed at top left corner of the window
          when player is buffering
        * adding "Force transparency" config option (as per #201)
        * redesigning players' extra parameters window
        * removing command line parameters -ep, -ap, lp
          and changing -ocd etc.
        * Windows: MPV installation will check CPU flags to
          download V3 or normal mpv release
        * fix_pyradio_desktop_file: parameters will be placed
          after terminal name (before -e)
        * fixing mpv parameter which might throw a warning
          which would break the TUI
        * fixing mplayer volume parsing error
        * fixing a couple of python2 crashes
        * updating build_install_pyradio (as per #203)
        * updating docs

    2023-07-15 s-n-g
        * version 0.9.2.13
        * all search widgets will save up to 20 of their last search terms
        * VLC will now save its default volume
        * adding --record command line parameter
        * \l will toggle the "Open last playlist" config setting
        * updating docs

    2023-07-01 s-n-g
        * version 0.9.2.12
        * Implementing VLC recorder (not for Windows)
        * MPlayer recorder will display volume level
        * MPlayer on Windows 7 will not use profiles
        * Trying different recorded file limit to start monitor
        * updating docs

    2023-06-20 s-n-g
        * version 0.9.2.11
        * implementing station recording for MPlayer media player
        * players' config file will be backed up on Windows
        * fixing a couple of potential crashes

    2023-06-14 s-n-g
        * version 0.9.2.10
        * all PyRadio threads will terminate when Alt-F4 or the
          close button is used to close the program
        * adding a message about dateutil module missing
        * fixing a Windows error that has made PyRadio unusable
          on Windows

    2023-06-13 s-n-g
        * version 0.9.2.9
        * fixing: Remote Control Server does not terminate when
          PyRadio is closed with Alt-F4 or using the close button

    2023-06-13 s-n-g
        * version 0.9.2.8
        * \o will open the config directory in a file manager
        * implementing station recording for MPV media player
        * implementing playback pause for MPV media player, when
          player in recording mode
        * fixing Windows installayion scripts

    2023-06-05 s-n-g
        * version 0.9.2.7
        * fixing a couple of install.py potential crashes
        * fixing a theme download potential crash
        * theme transparency will always be honored, in contrast
          to global (config transparency setting)

    2023-05-08 s-n-g
        * version 0.9.2.6
        * using pipx for installation on "externally-managed"
          python installations
        * adding cache for pipx installation (and command line
          parameters to handle it)
        * --list will indicate Group Headers
        * started working on scheduling
        * updating docs

    2023-04-07 s-n-g
        * version 0.9.2.5
        * Desktop Notifications will display the image
          provided by the station (jpg or png).
        * adding config option "Use station icon"
        * adding a fourth optional column for pyradio playlists.
          This column will define a station icon url.
        * adding CJK chars support for Group Headers
        * fixing a potential crash when randomly playing stations.
        * trying to limit duplicate Desktop Notifications.
        * adding a system theme: blue_by_boxer
        * updating docs

    2023-04-01 s-n-g
        * version 0.9.2.4
        * do not crash when we have a small number of Groups
        * get a minimum size so that we don't get stuck
        * position all windows relevant to parent

    2023-04-01 s-n-g
        * version 0.9.2.3
        * fixing search function for Group Selection window (pressing
          "n" or "N" will now work)
        * random playback will not stop on a Group Header
        * do not put new selection in the middle of window if already
          visible (Group Selection window)

    2023-03-31 s-n-g
        * version 0.9.2.2
        * adding support for Groups in playlists
        * making sure that the stations update thread terminates timely

    2023-03-24 s-n-g
        * version 0.9.2.1
        * do not ask to update stations when first installing pyradio
          or when stations.csv has been copied from package
        * perform a more thorough check when updating a station

    2023-03-23 s-n-g
        * version 0.9.2
        * implementing "player change" (key: \m)
        * working on stations deletion, do not delete stations
          when session is locked
        * changing the way stations.csv updates are done
        * adding --update-stations (-us) command line option
        * adding indication to denote forced http connection mode
        * adding Catppuccin themes - https://github.com/catppuccin
        * using rich to add color to console messages as per #174
          (python 3 only)
        * "Press ? for help" message will not show up when overlapping
          normal messages
        * working on MPV auto-installation on first install on Windows
        * moving last-playlist file in data dir
        * fixing pyradio not terminating when answering no to save a
          modified playlist
        * fixing a theme save crash
        * removing some curses.ungetch calls
        * updating docs

    2023-02-20 s-n-g
        * version 0.9.1
        * adding pyproject.toml (as per pep-0518)
        * adding the --config-dir (-c) command line argument
          (as per #187) - Not available on Windows
        * adding icons directory to distribution
        * adding the /set_volume (/sv) text only RC command
        * adding the /volume (/v) text only RC command
        * adding WNYC station to stations.csv
        * working on Windows MPV installation procedure
          (making it less cumbersome and transparent)
        * fixing system themes main border color
        * fixing typos (thanks to @Wikinaut)

    2023-01-28 s-n-g
        * version 0.9.0
        * finalizing RadioBrowser service (adding config
          search term navigation), closing #93 and partially
          closing #80
        * adding search function to all stations/playlists
          lists
        * when terminal cannot change colors, always ask to
          not display the warning message
        * window title will not be resetted randomly
        * fixing python2 config dirty indication

    2023-01-16 s-n-g
        * version 0.8.9.36 (0.9-beta33)
        * fixing config win left ("h") key: will not exit when should be
          decreasing a number
        * fixing notification settings (pull request #175 from
          RaeedAhmed/bugfix/notifications)
        * moving execution data to "data" folder
        * fixing Desktop file installation (linux)
        * fixing pyradio_server man paget to installation

    2023-01-10 s-n-g
        * version 0.8.9.35 (0.9-beta32)
        * fixing call to fix_pyradio_desktop_file during installation

    2023-01-10 s-n-g
        * version 0.8.9.34 (0.9-beta31)
        * fixing a line editor crash
        * adding \s to help (page 5)

    2023-01-10 s-n-g
        * version 0.8.9.33 (0.9-beta30)
        * adding Remote Control Server
        * mpv volume will not go from zero to max when decreasing
        * all file read/write will be utf-8 encoded
          (python2 not affected)
        * fixing Windows lnk installation
        * editing gruvbox themes
        * adding "Border" parameter to themes as per #173
          (not used by default in any of the existing themes)
        * updating docs, creating pyradio_server man page

    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)
        * RadioBrowser 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 RadioBrowser support
        * Fixing python 2 return from RadioBrowser 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

## Installation Top

The best way to install PyRadio is via a distribution package, if one exists (Arch Linux and derivatives can install any of these packages from the AUR, FreeBSD users will find it in the ports, etc.).

In any other case you will have to build it from source.

Note: Please avoid installing PyRadio via pip. I (user s-n-g @ github) am not the creator of this project, nor do I maintain it on The Python Package Index (PyPI). As a result, the version available there is outdated and I cannot provide any support for it.
Furthermore, please refrain from using any third-party packaging methods, such as Snap or AppImage. I am not affiliated with these services or projects, and I cannot guarantee the functionality or version of PyRadio provided through them. Additionally, I am unable to offer support for any issues related to these packaging methods.

## Command line options Top

    # pyradio -h
    Usage: pyradio [-h] [-c CONFIG_DIR] [-p [STATION_NUMBER]] [-x] [-u PLAYER]
                   [-l] [-lt] [-sds] [-sd] [-od] [-pc] [-d]
                   [--d-player-input D_PLAYER_INPUT] [-ul] [-us] [-U] [-R] [-V]
                   [--mpris] [-ls] [-s PLAYLIST] [-tlp] [-t THEME] [--show-themes]
                   [--no-themes] [--write-theme IN_THEME OUT_THEME,]
                   [--terminal TERMINAL] [--terminal-param ...] [-oc] [-sc] [-cc]
                   [-gc] [-r] [-or] [-lr] [-mkv MKV_FILE] [-scv PNG_FILE] [-srt]
                   [-ach] [--headless IP_AND_PORT] [--address] [-fd]
                   [-cvt CONVERT] [--validate [{mark,drop}]] [--threads THREADS]
                   [--timeout TIMEOUT] [--max-per-host MAX_PER_HOST] [--with-date]
                   [--no-color] [--quiet] [-o OUTPUT] [-y] [-lm LIMIT]

    Curses based Internet Radio Player

    General options:
      -h, --help            Show this help message and exit
      -c, --config-dir CONFIG_DIR
                            Use specified configuration directory instead of the
                            default one. PyRadio will try to create it, if it does
                            not exist. Not available on Windows.
      -p, --play [STATION_NUMBER]
                            Start and play.The value is num station or empty for
                            random.
      -x, --external-player
                            Play station in external player. Can be combined with
                            --play.
      -u, --use-player PLAYER
                            Use specified player. A comma-separated list can be
                            used to specify detection order. Supported players:
                            mpv, mplayer, vlc.
      -l, --list            List of available stations in a playlist.
      -lt, --log-titles     Log titles to file.
      -sds, --show-dirs     Print all the directories used by PyRadio and exit.
      -sd, --show-config-dir
                            Print config directory [CONFIG DIR] location and exit.
      -od, --open-config-dir
                            Open config directory [CONFIG DIR] with default file
                            manager.
      -pc, --print-config   Print PyRadio config.
      -d, --debug           Start PyRadio in debug mode.
      --d-player-input D_PLAYER_INPUT
                            When -d is used, this option will not log player input
                            (value = 0), log accepted input (value = 1) or raw
                            input (value = 2).
      -ul, --unlock         Remove sessions' lock file.
      -us, --update-stations
                            Update "stations.csv" (if needed).
      -U, --update          Update PyRadio.
      -R, --uninstall       Uninstall PyRadio.
      -V, --version         Display version information.

    Isolated environment:
      --mpris               Install "dbus-next" in the isolated environment and
                            ensure it remains available after updates. This is
                            required for MPRIS support.

    Playlist selection:
      -ls, --list-playlists
                            List of available playlists in config dir.
      -s, --stations PLAYLIST
                            Load the specified playlist instead of the default
                            one. PLAYLIST can be the path to a CSV or an M3U file,
                            the name (without extension) of a CSV or an M3U file
                            which is in the station's folder, or the number which
                            corresponds to a file presented at the output of the
                            -ls command line parameter.
      -tlp, --toggle-load-last-playlist
                            Toggle autoload last opened playlist.

    Themes:
      -t, --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 selection:
      --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 ...  Use this as PyRadio parameter in the Desktop File.
                            Please make sure the parameters are at the end of the
                            command line. For example: pyradio --terminal kitty
                            --terminal-param "-p3 -t light".

    Cache:
      -oc, --open-cache     Open the Cache folder.
      -sc, --show-cache     Show Cache contents.
      -cc, --clear-cache    Clear Cache contents.
      -gc, --get-cache      Download source code, keep it in the cache and exit.

    Recording stations:
      -r, --record          Turn recording on (not available for VLC player on
                            Windows).
      -or, --open-recordings
                            Open the Recordings folder.
      -lr, --list-recordings
                            List recorded files.
      -mkv, --mkv-file MKV_FILE
                            Specify a previously recorded MKV file to be used with
                            one of the following options. The MKV_FILE can either
                            be an absolute or a relative path, or a number
                            provided by the -lr command line paremater. If it is a
                            relative path, it should be found in the current or in
                            the Recordings directory.
      -scv, --set-mkv-cover PNG_FILE
                            Add or change the cover image of a previously recorded
                            MKV file. PNG_FILE can either be an absolute or a
                            relative path. If relative, it should be found in the
                            current or in the Recordings directory.
      -srt, --export-srt    Export a previously recorded MKV file chapters to an
                            SRT file. The file produced will have the name of the
                            input file with the "mkv" extension replaced by "srt".
      -ach, --add-chapters  Add (or replace) chapter markers to a previously
                            recorded MKV file. The chapters file will be a SRT
                            file, much like the one produced by the previous
                            command line parameter.

    Headless operation:
      --headless IP_AND_PORT
                            Start in headless mode. IP_AND_PORT can be a) auto
                            (use localhost:11111), b) localhost:XXXXX (access the
                            web server through localhost), c) lan:XXXXX (access
                            the web server through the LAN) or d) IP_ADDRESS:XXXX
                            (the IP_ADDRESS must be already assigned to one of the
                            network interfaces). XXXXX can be any port number
                            above 1025. Please make sure it is different than the
                            one set in the configuration file.
      --address             Show remote control server address.
      -fd, --free-dead-headless-server
                            Use this if your headless server has terminated
                            unexpectedly, and you cannot start a new one (you get
                            a message that it is already running).

    m3u playlist handling:
      -cvt, --convert CONVERT
                            Convert CSV (PyRadio playlist) to M3U and vise-versa,
                            based on the file extension of CONVERT. If there's no
                            file extension, .csv is assumed. Accepts -y, -o, -lm
                            (general options). With -o: provides the output file
                            for the CSV to M3U conversion. If not specified, the
                            same path (including the name) as the CONVERT
                            parameter is used, replacing .csv with .m3u. The file
                            extension .m3u will be automatically added if not
                            specified. With -lm: specify maximum number of
                            stations in an M3U file (default is 10,000, 0 disables
                            it, effectively accepting any number of entries).

    Playlist validation:
      Validate playlists given with --convert. Requires a CSV file or an M3U
      file or URL as input.

      --validate [{mark,drop}]
                            Validate a playlist (CSV or M3U). If no value is
                            given, defaults to "mark". Options: mark: mark failed
                            stations with [X], drop: save working and failed
                            stations separately
      --threads THREADS     Number of parallel threads to use when checking
                            stations (default: 5).
      --timeout TIMEOUT     Timeout in seconds for each station request (default:
                            5).
      --max-per-host MAX_PER_HOST
                            Maximum concurrent requests per host (default: 2).
                            Prevents server banning by throttling requests to the
                            same host.
      --with-date           Add timestamp to output filenames. Useful for
                            scheduled checks to preserve history.
      --no-color            Disable colored output. Useful for logging or when
                            running in non-interactive environments.
      --quiet               Reduce verbosity (suppress per-station output). Only
                            show summary and errors.

    General options:
      -o, --output OUTPUT   Output file path (see specific commands for default
                            behavior).
      -y, --yes, --force    Assume yes to all prompts (dangerous: overwrites files
                            without confirmation, etc.).
      -lm, --limit LIMIT    Use LIMIT as a maximim value of accected items.

## Controls Top

The following list shows a default key bindings list used within the program.

                      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]
    *                 Add station to favorites                         -                                  -
    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.                       -                                  -
    | (vertical       Enable / disable recording
       line or
       pipe symbol)
    / n N             Search, go to next / previous result             [Valid]                            [Valid]
    f                 Open Fuzzy Search                                [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].

### Global shortcuts

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 title 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 RadioBrowser Search window.

### Customizing key bindings

PyRadio provides the possibility to customize the key bindings above.

Just open the configuration window and navigate to Keyboard Shortcuts. Please do read the help screen provided therein (press “*?” to get to it).

## HTML help Top

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 Modes Top

PyRadio has the following primary modes:

1. 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.

2. The Playlist mode, which you can open by pressing “o”. Then you can open, create, paste a station, etc.

3. 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.

4. The Register Main mode, which is identical to the “Main” mode, except it displays the content of a named register.

5. 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).

### Secondary Modes

A set of secondary modes is also available (a secondary mode works within a primary one):

1. 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.

2. 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.

3. 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.

4. 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.

### Tiling manager modes

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).

1. The Limited Height mode, which is automatically enabled when the window height gets below 8 lines.

   - In this mode, only a limited information is visible and if playback is on, the volume is the only thing that can be adjusted (or muted) and saved. This is the Limited display.

2. The Limited Width mode, which is automatically enabled when the window width get below certain limits:

   - When the width gets below 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 below 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.

## Config file Top

PyRadio upon its execution will first read its package configuration file and then will try to read the user configuration file. If an error occurs while parsing it, an error message will be displayed and PyRadio will terminate.

### The package config file

The package configuration file contains the program’s default parameters. These are the player to use, the playlist to load etc.

It is heavily commented (as you can see here), so that it can be used as a template in order to manual create the user configuration file.

One can also get the configuration file with the active parameter values (i.e. after changed by the user config file), by executing the command:

    pyradio -pc

### The user config file

This file (typically ~/.config/pyradio/config) is created by PyRadio when needed.

It will contain only the parameters whose value is different to the one set in the package configuration file.

One can easily edit it manually, though. The best practice to do so is by executing PyRadio with the -ocd command line option, which will open the configuration directory in your file manager, and then edit (or create it) it using your preferable text editor. Don’t forget you can get the list of parameters by executing pyradio -pc.

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.

## About Playlist files Top

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 number of more columns can be used.

- The third column will define the Encoding used by the station (more on this at Specifying stations’ encoding).

- The fourth column will set an Icon URL, to be used when displaying Desktop Notifications.

- The fifth column is the Profile to be used with this station.
  If a profile is set for the station, a “[P]” will be displayed at the left top corner of the window when the station starts playing.

- The sixth column will determine whether Buffering will be used (more on this at Buffering).

- The seventh column will determine whether the station will be forced to be using http instead of https (more on this at Player connection protocol).

- The eight column defines the Volume value to be used (more on this at Station volume).

- The ninth column will define the Referer to be used (more on this at Specifying a station’s Referer URL).

- The last column will define the Player to be used (more on this at Specifying a station’s preferred station).

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.

### Defining and using Groups

In order to better organize stations within a (large) playlist, PyRadio supports Groups.

A Group is defined as a normal “station” entry, whose URL field is a hyphen (“-”). For example, the following will define a Group Header for a Group called Blues.

    Blues,-

A Group Header entry does not define a station, and subsequently cannot stat a playback session. Other that that, it can be moved, copied, deleted, etc, just like any other playlist entry.

To add a Group Header, just press “a”, fill in the name and type a “-” in the URL field.

Navigation among Groups can be achieved by:

Key | Description
--- | ---
^E / ^Y | Go to next / previous Group
^G | Display a list of existing Groups to select from

### Integrating new stations

When the package’s “stations.csv” files is updated, the changes it has will not automatically appear in the user’s stations file.

PyRadio will display a message asking the user to either update the file, ignore the changes for this version or postpone his decision for the next time PyRadio will be executed.

This update can be disabled permanently by setting the configuration option “auto_update_stations” to False in the user’s configuration file.

Either way, the user can always manually update his stations file, by issuing the following command:

    pyradio -us

If changes have been applied, a message resembling the following will appear:

    Reading config...
    Updating "stations.csv"
    Last updated version: 0.9.2
     Last synced version: None
      From version: 0.9.2
        +/- updating: "Reggae Dancehall (Ragga Kings)"
        +++   adding: "Groove Salad Classic (Early 2000s Ambient)"
        +++   adding: "n5MD Radio (Ambient and Experimental)"
        +++   adding: "Vaporwaves [SomaFM]"
        +++   adding: "The Trip: [SomaFM]"
        +++   adding: "Heavyweight Reggae"
        +++   adding: "Metal Detector"
        +++   adding: "Synphaera Radio (Space Music)"

    Summary
        +++ added   :  7
        +/- updated :  1
        --- deleted :  0

If the file is already up to date, the following message will be displayed:

    Reading config...
    Updating "stations.csv"
    Last updated version: 0.9.2
     Last synced version: 0.9.2
    Already synced: "stations.csv"

### Specifying a playlist to load (command line)

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:

- a relative or absolute file name.
- the name of a playlist file which is already in its configuration directory.
- the number of a playlist file, as provided by the -ls command line option.

Note: PyRadio can also open an M3U file using this option; the program will actually convert the M3U file to a CSV and load this file instead. One can use its absolute path, its name or its playlist number as described bellow.

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"
           ┏━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┓
           ┃  # ┃ Name       ┃    Size ┃ Date                     ┃
           ┡━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━┩
           │  1 │ hip-hop    │ 6.41 KB │ Mon Nov  7 18:17:47 2022 │
           │  2 │ party      │ 1.94 KB │ Fri Nov 29 10:49:39 2021 │
           │  3 │ stations   │ 5.30 KB │ Sat Jul 18 23:32:04 2022 │
           │  4 │ huge       │ 1.94 MB │ Wed Oct 23 11:05:09 2019 │
           │  5 │ blues      │ 5.30 KB │ Thu Jul 16 16:30:51 2020 │
           │  6 │ rock (m3u) │ 2.56 KB │ Fri Jan 10 00:20:07 2023 │
           │  7 │ pop        │ 1.01 KB │ Fri Sep 18 00:06:51 2020 │
           └────┴────────────┴─────────┴──────────────────────────┘

    $ 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).

### Autoloading playlists

As already stated, PyRadio will normally load its default playlist (called “stations”) upon startup.

This behavior can be then changed in two ways:

1. Changing the default playlist.

   This is accomplished using the “Def. playlist” configuration option (optionally along with the “Def. station” option).

2. 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.

### Managing playlists (within PyRadio)

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.

### Managing foreign playlists

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).

### Playlist history

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.

### Playlist validation support

PyRadio provides a powerful playlist validation system, with multi-threading support and host-aware throttling for both CSV and M3U playlists.

More info: PyRadio Playlist Validation Guide

## Stations history Top

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. RadioBrowser) the list is reseted with every search that is performed.

## Search function Top

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.

All search widgets provide a “search history” function; pressing the Up or Down arrow will cycle through previously used search terms (maximum number remembered is 20). Pressing ^X will remove an item from the history.

### Fuzzy Search

On any window presenting a list of stations or playlists pressing “f” (default key) will open the Fuzzy Search window. It displays a live-updating list of stations and narrows the results down as you type.

## Line editor Top

PyRadio “Search function” and “Station editor” use a Line editor to permit typing and editing stations’ data.

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:

1. Press “?” to get help.
2. Press “\?” to get a “?”.
3. Press “\\” to get a “\”.

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.

### CJK characters support

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:

## Moving stations around Top

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:

1. Press Ctrl-U or Ctrl-D to move the current station up or down.
2. Type a station number and press Ctrl-U or Ctrl-D to move the current station there.
3. Go to the position you want to move a station to, and press “J”. This will tag this position (making it the target of the move). Then go to the station you want to move and press Ctrl-U or Ctrl-D to move it there.

## Specifying stations’ encoding Top

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.

### Station by station encoding declaration

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.

### Global encoding declaration

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.

## Player detection / selection Top

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.

### Changing player mid-session

If the user faces a playback problem with a given station, chances are that a different player will successfully play it.

Pressing “\m” will bring up the “Switch Media Player” window, where a different player can be activated.

If recording is on while using the previously activated player, it will remain on with the newly activated one. This actually means that the recording will stop when the old player is stopped and resumed when the new player is activated (creating a new recorder file). There is just one exception to that; selecting VLC is not possible on Windows, since VLC does not support recording on this platform.

Note: The activated player will not be saved; PyRadio will still use the player defined at its config next time it is executed.

#### Specifying a station’s preferred player

Some stations may perform better —offering more stable playback, faster starts, or improved compatibility— when played with a specific audio player.

PyRadio allows you to define a preferred player for individual stations directly within the playlist file.

When such a preference is set, PyRadio will automatically activate the specified player and use it to start playback for that station. If the player in not installed, the default player will be used instead.

Note: A station with a defined player will always use that player, regardless of the session’s default player or any player changes made during the session.

### Specifying a station’s Referer URL

Although PyRadio is meant to be a radio station player, it can also be used to listen to video stations transmitting m3u8 playlists (HTTP Live Streaming or HLS).

The thing with these transmissions is that usually a Referer URL has to be provided so that the connection does not fail.

PyRadio now does support the declaration of a Referer URL for individual stations; it does it in an “anorthodox” way, but it is available and it works.

So, let us imagine that a station called “My video station” has been added to a playlist. The user tries to play it but it fails; the referer URL is missing.

To rectify the situation, a file containing the referer URL would have to be saved in the config directory: its name must be the name of the station as it is in the playlist, followed by the “.referer.txt” extension.

In our example above, the file will have to be named:

“My video station.referer.txt”

#### Note about MPlayer

This will unfortunately not work with MPlayer.

It seems it will not use the Referer provided, as shown in the following part of the command execution output:

    [tcp @ 0x7f4a42c7fa60]Successfully connected to XX.XX.XXX.XX port 443
    [https @ 0x7f4a42c7fa60]request: GET /live/XXXXXXXX.m3u8 HTTP/1.1
    User-Agent: Lavf/60.16.100
    Accept: */*
    Range: bytes=0-
    Connection: close
    Host: XXXXXX-XXXXXXXXX.XXXXXX.XXX.XXX.XX
    Icy-MetaData: 1

    [https @ 0x7f4a42c7fa60]HTTP error 403 Forbidden

#### Referer support in the playlist

As of v. 0.9.3.11.5, support for the referer in the playilist has been implemented.

In this case, if a referer file is found for a station, PyRadio will:

1. update the station info in the playlist
2. mark the playlist as modified
3. remove the referer file
4. inform the user so that he saves the playlist

Note: At this point, inserting the referer from PyRadio TUI has not yet been implemented.
One can either use the referer file method described above, or just manually edit the playlist file and add it using the following format:

    Station Name,Station URL,,,,,,Referer URL

Please note the number of commas inserted after the Station URL.

### Extra Player Parameters

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:”).

#### Using the Configuration Window

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.

For each of the supported players the existing profiles (not for VLC) and existing extra parameters will be displayed.

The user can add (“a”) a new parameter, edit (“e”) an existing set and delete (“x” or “DEL”) one; profiles cannot be edited or deleted, though.

## Player connection protocol Top

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.

### Visual reminder

When this option is activated, either through the config or the keyboard, a “[http forced (z)]”message appears on the top right corner of the window, as shown in the following image.

The “z” in parenthesis is just a hint to remind the user that he can change the behavior by pressing “z”.

As the window shrinks in width, the message becomes a “[h]”; when it shrinks even more, it disappears completely.

## Player default volume level Top

All players, 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

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

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 accomplished 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).

### VLC

Although VLC can use a local configuration file, there seems to be no reliable way of defining the playback volume in it.

In the past, VLC would just use any volume setting it had saved from a previous execution, but now it is possible to save the volume it will use when executed by PyRadio.

This means that VLC will start and connect to a station, use whatever volume level it’s stored for it and then PyRadio will reset the volume to the desired one (as saved within PyRadio).

The volume will be saved is a file called vlc.conf and reside withing the data directory, inside PyRadio’s configuration folder.

## Station volume Top

Stations in a playlist can come from various sources, each with its own default volume level. This often results in inconsistent playback volume, forcing the user to adjust PyRadio’s volume every time a new station starts.

While using a volume normalization tool could solve this, it may not always be desirable or feasible.

PyRadio offers a better alternative: station volume.

With this feature, each station can have a specific volume value saved along with its name and URL. When the station is played, that volume is automatically applied.

Though the user needs to manually set and save the ideal volume for each station (based on their own audio setup), this provides a consistent and reliable solution over time.

To set a station’s volume, start playing it, adjust the volume to the desired level, and press “\v”. This will silently save the updated volume to the playlist on disk.

If you want to temporarily ignore all station volume settings, press “\V”. This will disable volume overrides for the current session only; the setting will reset the next time PyRadio is launched.

When a station’s volume setting is active, a “[V]” indicator appears in the top-left corner of the window. If station volume has been disabled, you’ll see “[v]” instead. This is illustrated in the image below:

### How it Works

Both MPV and MPlayer use profiles to configure playback options.

When station volume is enabled, PyRadio creates a temporary profile named pyradio-volume by copying the selected base profile. It then updates the volume field in this profile to match the station’s saved volume. This custom profile is then used to launch the player.

Naturally, this means the player’s user configuration file must be read, parsed, modified, and saved — which may introduce a slight delay, particularly on slower systems.

VLC, on the other hand, does not support profiles. In this case, PyRadio simply applies the station’s volume directly, overriding the global volume setting.

## Buffering Top

PyRadio provides stream buffering options for all supported players.

Please refer to this document for more info: PyRadio Buffering.

## Displaying Station Info Top

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).

## Copying and pasting - Registers Top

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.

## Favorites playlist Top

Pressing “*” (asterisk) in Main Mode will add the selected station to the favorites playlist.

If the station is already there, it will either be updated if its name has been changed, for example, or will be ignored, to avoid creating duplicate entries.

The favorites playlist, residing in the configuration folder, is a normal playlist in any other respect, which can be subsequently opened, edited, deleted even, as any other playlist.

## Displaying the Current Time Top

The Clock feature allows you to display the current time in the bottom left corner of the window. This can be helpful for keeping track of time while using the application.

You can easily toggle the clock display by pressing "\t".

### Configuration

The configuration window has a group labeled “Clock, which presents the following options:

- The “Display on startup” option determines whether the clock is displayed when the application starts. Set it to True to show the clock at startup, or leave it as False (the default) to hide it.

- You can choose how the time is displayed using the “Time format” option. Here are the available formats:

Value | Format Description
--- | ---
0 | 24-hour format, with seconds
1 | 24-hour format, no seconds (default)
2 | 12-hour format, with AM/PM and seconds
3 | 12-hour format, no AM/PM, with seconds
4 | 12-hour format, with AM/PM, no seconds
5 | 12-hour format, no AM/PM, no seconds

By default, the Clock is turned off, with the default format set to “HH:MM” (value 1). Enabling the clock will introduce a few additional threads, which may make PyRadio slightly heavier than usual.

## PyRadio Themes Top

PyRadio supports CSS themes; it comes with a number of predefined ones and can use external programs that can provide automatically created and updated themes.

To set a theme you just press “t” and

- select a theme and press the Right Arrow to activate it.

- when you have found a theme you like, press Space to make it the default one.

To get more info about using and creating a PyRadio theme, please refer to this page.

## Recording stations Top

PyRadio supports recording of stations, as much as this feature is provided by the players it supports.

Berfore you continue, read this!

Generally, recording a radio streaming broadcast is considered legit, if the recording is to be used for personal use only (i.e. to listen to the broadcast at a later time).

Distributing such a recording, is illegal. Broadcasting it is also illegal. Its reproduction before an audience is also illegal. In some countries/regions, it is also illegal to split or tag the songs in the recording.

Please make sure you are informed about this topic, about what the law considers illegal at your country/region, before using this feature!

You have been warned!

PyRadio, its creator and maintainers do not condone any behavior that involves online piracy or copyright violation. This feature is provided strictly for personal use, and to utilize another requested feature: pausing and resuming playback.

Please refer to this page to read more about his feature.

## Mouse support Top

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”.

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 or adjust volume
Shift-Wheel | Adjust volume (does not work with all terminals)

Note: The Wheel can be configured to adjust the player’s volume instead of its default scrolling function through the “Adjust volume” configuration option. Then, BShift-Wheel will scroll through the playlist. This is useful if Shift-Wheel does not work, or one is accustomed to using the wheel for volume control.

## Title logging Top

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 reference.

The logger, which is a special kind of debug logger, but works independently from the “debug” 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 documentation, 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:

1. using the -lt (--log-titles) command line option, or
2. by pressing “W” while in the Main, the Playlist or the Register mode.

The titles are written in a file called pyradio-titles.log which is located in the Recordings 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

### Tagging a title

An extra functionality is made possible because of “titles’ logging”: tagging a title (a kind of “liking” a song).

The idea is that when users play a station and hear a song, they may like and want to look it up later. With this functionality, they can tag the song (make a note in the log file) for later.

To tag a title, one has to press the “w” key.

Then, if title logging is already enabled, the log file will show up an entry like the example below:

    Apr 18 (Mon) 13:39 |     Tom Russell - Bus Station
    Apr 18 (Mon) 13:40 |     Tom Russell - Bus Station (LIKED)

If title logging is disabled, it will be temporarily turned on only for the tagging of that song:

    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

## Online radio directory services Top

PyRadio supports the following Online radio directory services:

- RadioBrowser

  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.

## Desktop Notifications Top

PyRadio can provide Desktop Notifications if a notification daemon is already present (on Linux and BSD), or via Windows Notification Service (WNS).

If enabled, PyRadio will display:

1. The playlist name, when playback starts.
2. Song info (as provided by the radio station).
3. Connection failure messages.
4. Player crash messages.

To find out more about configuring this feature, please refer to Desktop Notification.

## Desktop File Top

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.

### Specifying the terminal to use

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

#### Specifying PyRadio parameters

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 3"

This command will use no specific terminal and will pass the “-p 3” (play station No 3 automatically) parameter to PyRadio. Just make sure that the parameter is at the end of the command line.

## Session Locking Top

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.

### Session unlocking

If for any reason PyRadio always starts in “locked mode”, one can unlock the session, using the “–unlock” command line option.

## Update notification Top

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).

Note: Packages coming from a distribution repository will display no notification; it’s up to the distro to update / uninstall PyRadio, as stated in Packaging PyRadio.

## OS Media Controls integration Top

PyRadio can integrate with the operating system’s media control system.

For more information, please refer to the relevant page.

## Remote Control Server Top

PyRadio can be controlled remotely using normal http requests either form the command line (with curl for example) or from a browser.

For more information, please refer to the relevant page.

If you’d like to set up a “headless” PyRadio operation for your linux box, please refer to the Headless page.

### Remote Control Client

PyRadio comes with its own client, which will make it easier to communicate with the Remote Control Server.

For more information, please refer to the relevant page.

## Playing a station in the terminal Top

A user request Shortcut to quit pyradio and launch standalone player (e.g. mpv) with currently selected station lead to the possibility to use any player in the terminal.

This action will be triggered by pressing “X”.

After the player stops, PyRadio will stop as well.

Note: On Windows, mpv and VLC will open a new player window instead of executing in the terminal.

In addition, a command line parameter has been added “-x” (“–exteranl-player”) which when used in conjuction with the “-p” (“–play”) command line parameter, will instruct PyRadio to play a station and terminate after the playback stops.

## Text-to-Speech Support Top

PyRadio now features comprehensive Text-to-Speech (TTS) support, providing auditory feedback for an enhanced radio streaming experience. This intelligent system delivers contextual information about station navigation, playback status, and system events.

More info about the implementation and status at the relevant page.

## Debug mode Top

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.

## Reporting bugs Top

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.

## Packaging PyRadio Top

If you are a packager and would like to produce a package for your distribution please do follow this mini guide.