Name

pyradio - a curses Internet radio player.

Synopsis

pyradio [OPTIONS]

Description

pyradio is a command line Internet Radio Player based on curses, that uses external media players to perform the actual playback.

It currently supports the following players: MPV, MPlayer and VLC.

Options

General options:

-c CONFIG_DIR, --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 [STATION_NUMBER], --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 PLAYER, --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 sonfig.

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

Playlist selection:

-ls, --list-playlists

List of available playlists in config dir.

-s PLAYLIST, --stations PLAYLIST

Load the specified playlist instead of the default one.

-tlp, --toggle-load-last-playlist

Toggle autoload last opened playlist.

Themes:

-t THEME, --theme THEME

Use specified theme.

--show-themes

Show Internal and System Themes names.

--no-themes

Disable themes (use default theme).

--write-theme IN_THEME OUT_THEME,

Write an Internal or System Theme to themes directory.

Terminal 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 that the argument is at the end of the command line, for example: --terminal-param "-p 3 -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 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 PNG_FILE, --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_IPORT

Start in headless mode. IP_AND_IPORT 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).

The following options can also be set in pyradio’s configuration file:

Controls

Up/Down/PgUp/PgDown

Change station selection

j/k

Change station selection (vi-like)

Enter/Right/l

Play selected station

r

Select and play a random station

Space/Left/h

Stop/start playing selected station

P

Jump to playing station

H M L

Jump to top / middle / bottom of screen

g

Jump to the start of the playlist

<n>G

Jump to the end of the playlist
If <n> (line number) was entered, jump to it

-/+ or ,/.

Change volume

m

Mute

v

Save volume (MPV and MPlayer only)

o s R

Open / Save / Reload playlist

a A

Add / append a new station

e

Edit current station

E

Change current station's encoding

DEL,x

Delete selected station

O

Open RadioBrowser

< / >

Browse the Stations history list

J

Create a Jump tag

<n>^U,<n>^D

Move current station up / down
If <n> (line number) was entered, or a Jump tag has been defined, move the station there

t

Open the Theme Selection window

T

Toggle background transparency

c

Open the Configuration window

' \\y

Get into Registers, Extra Commands, Yank mode, respectively

z

Toggle "Force http connections"

Z

Display the "Extra Player Parameters" window.

?

Show keys help

Esc/q

Quit

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:

PyRadio's Modes

pyradio has the following primary modes:

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

The functions availabe through the secondary modes are content dependant, so you can see what command is available by pressing "?" while within such a mode. Pressing any other key will exit the secondary mode.

Tiling manager modes

Config File

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 user config file

About Playlist Files

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 eighth column defines the Volume value to be used (more on this at Station volume).

-

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

The following table presents the Station's fields and the current level of support.

pyradio will by default load the user's stations file (e.g. ~/.config/pyradio/stations.csv). If this file is not found, it will be created and populated with a default set of stations.

Tip:

If you already have a custom stations.csv file, but want to update it with pyradio's default one, you just rename it, run pyradio (so that the default one get created) and then merge the two files.

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.

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:

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.

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

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

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

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.

Examples:

To load a playlist called "blues.csv", one would use the command:

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:

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

Finally, opening another playlist is also possible. Just press "o" and you will be presented with a list of saved playists 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 choise 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 taked on March 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.

Stations history

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

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.

Line Editor

pyradio "Search function" and "Station editor" use a Line editor to permit typing and editing stations' data.

The Line editor works both on Python 2 and Python 3, but does not provide the same functionality for both versions:

One can always display help by pressing "?", but that pauses a drawback; one cannot actually have a "?" withing the string.

To do that, one would have to use the backslash key "\" and then press "?".

To sum it all up:

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 [1], as described on CJK Unified Ideographs (Unicode block) [2], also known as URO, abbreviation of Unified Repertoire and Ordering. These characters, although encoded as a single code-poin (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:

https://members.hellug.gr/sng/pyradio/pyradio-editor.jpg

[1] https://en.wikipedia.org/wiki/CJK_Unified_Ideographs

[2] https://en.wikipedia.org/wiki/CJK_Unified_Ideographs_(Unicode_block)

Moving Stations Around

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:

Specifying Stations' Encoding

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,

This way we add an empty encoding, forcing

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.

Finding The Right Encoding

A valid encoding list can be found at:

https://docs.python.org/2.7/library/codecs.html#standard-encodings

replacing 2.7 with specific version: 3.0 up to current python version.

Player Detection / Selection

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.

Note

The default player to use can also be set in pyradio’s configuration file, parameter player (default value is mpv, mplayer, vlc).

Changing player mid-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:

Note

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

Extra Player Parameters

All three supported players can accept a significant number of "command line parameters", 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:

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 parameter, or the "Configuration Window" (under "Player:").

This way, 10 sets of parameters can be inserted and made available for selection.

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.

[pyradio-player-selection.jpg](https://members.hellug.gr/sng/pyradio/pyradio-player-selection.jpg)

Each of the supported players can have up to 11 sets of extra parameters (the first one is the default).

The user can add ("a") a new parameter, edit ("e") an existing set and delete ("x" or "DEL") one.

Player Connection Protocol

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

Player Default Volume Level

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 accompliced using the "softvol=1" and "softvol-max=300" lines above. The user may choose to remove these lines from the config (to activate system-wide volume adjustment) or add them to the config (in case the profile was created by an older pyradio version).

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

Displaying Station Info

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 bitrate, for example, but some may ommit 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 be seen here: https://members.hellug.gr/sng/pyradio/pyradio-station-info.jpg . 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

pyradio takes the concept of registers from ivim (https://www.vim.org), 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 "\u".

To copy a station to a register one would press "y" and:

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:

Favorites playlist

Pressing "*" 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

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.

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.

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

Configuration

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

PyRadio Themes

pyradio comes with 6 preconfigured (hard coded) themes:

Furthermore, a number of System Themes (these are actual files saved in the themes installation directory) are also available:

Contrary to the old styling method, which was terminal and palette dependent, a new styling method has been implemented; actual CSS colors can now be defined.

Pressing "t" will bring up the Theme selection window, which can be used to activate a theme and set the default one.

Note

If the theme selected in the Theme selection window, (or requested using the "-t" command line option), is in any way invalid, or is of the old format, pyradio will fall-back to the "dark" theme and will display a relevant message.

The window will display the current state of the Use transparency and Force transparency configuration options in its bottom right corner:

Note

the options indication will not be visible when the window is opened withing the pyradio’s “Configuration Window”.

One can get more info about these options in the “Using Transparency” section, bellow.

The Theme selection window will remain open after activating a theme, so that the user can inspect the visual result and easily change it, if desired. Then, when he is satisfied with the activated theme, the window will have to be manually closed (by pressing "q" or any other relevant key - pressing "?" will bring up its help).

Pressing "SPACE", will apply the theme and make it default, and pressing "c" will apply the theme and make it default and start a file watch function on the file, so that if the file changes, pyradio will automatically update itself.

Alternative Main Window border color

Virtual terminal restrictions

CSS color themes restrictions

Secondary windows background

Mouse Support

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:

Note:

The Wheel can be configured to adjust the player's volume instead of its default scrolling function through the Reverse wheel configuration option. Then, Shift-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

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 works independantly from the "ebug" function, is actually a Rotating File Handler (https://docs.python.org/3/library/logging.handlers.html#logging.handlers.RotatingFileHandler), 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:

The titles are written in a file called pyradio-titles.log which is saved at pyradio configuration directory.

Log file sample:

Tagging a title

An extra functionality is made possible because of "titles' logging": tagging a title (something like liking a song).

The idea is that the user plays a station and hears a song he likes and want to look it up later. With this functionality, he can tag the song (make a note in the log file), so he can refer to it at a later time.

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

Then, if titles's logging is already enabled, the log file will have an entry similar to the one shown below:

If title's logging is not enabled, it will be turned on, the song will be tagged and logging will be turned off again:

Online Radio Directory Services

pyradio supports the following Online Radio Directory services:

RadioBrowser - https://www.radio-browser.info/

This is a community driven effort (like wikipedia) with the aim of collecting as many internet radio and TV stations as possible.

For more information please refer to the relevant man page: pyradio_rb(1).

To access supported services, just press "O" at the program's main window.

Desktop Notifications

pyradio can provide Desktop Notifications when a notification daemon is already present (on Linux and BSD).

The behavior and presentation of notifications greatly depends on the daemon/service and command line utility used to trigger a notification.

If enabled, pyradio will display:

Configuration

On Linux

On MacOS

Desktop File

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

Specifying pyradio parameters

Session Locking

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

Update Notification

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

Cleaning Up

pyradio will uninstall all previously installed versions when updated (using the -U command line parameter), so no extra steps are needed any more to house keep your system.

Playing a station in the terminal

A user request Shortcut to quit pyradio and launch standalone player (e.g. mpv) with currently selected station (https://github.com/coderholic/pyradio/issues/252) 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.

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.

Debug Mode

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 in github at <https://github.com/coderholic/pyradio/issues>

Reporting Bugs

When a bug is found, please do report it by opening an issue at github at <https://github.com/coderholic/pyradio/issues>, 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.

Acknowlegement

pyradio uses code from the following projects:

Files

/usr/share/doc/pyradio/README.html

/usr/share/doc/pyradio/build.html

/usr/share/doc/pyradio/radio-browser.html

/usr/share/doc/pyradio/windows.html

/usr/share/doc/pyradio/windows-mplayer.html

/usr/share/licenses/pyradio/LICENSE

Note:

On Mac OS, these file may be installed in /usr/local/share/doc/pyradio, depending on whether or not SIP is enabled.

Authors

Ben Dowling <https://github.com/coderholic>, (Origianl author)

Kirill Klenov <https://github.com/klen>, (2012)

Laurent Stacul <https://github.com/stac47>, (2013)

Peter Stevenson (2E0PGS) <https://github.com/2E0PGS>, (2018)

Spiros Georgaras <https://github.com/s-n-g>, (2018-2024)

You can see a complete list of contributors at
https://github.com/coderholic/pyradio/graphs/contributors

Special thanks

1.

edunfelt (https://github.com/edunfelt), for her wonderful work on base16 themes (https://github.com/edunfelt/base16-pyradio), and ideas regarding theming and such.

2.

amano-kenji (https://github.com/amano-kenji), for his valuable suggestions and bug reports.

3.

Scary-Guy (https://github.com/Scary-Guy), for his suggestions on improving user experience.

See also

pyradio_rb(1)

RadioBrowser Implementation

pyradio_rec(1)

Recording stations

pyradio_server(1)

Remote Control Server

pyradio-client(1)

Remote Control Client