pyradio.1

.\" Copyright (C) 2011 Ben Dowling <http://www.coderholic.com/pyradio>
.\" This manual is freely distributable under the terms of the GPL.
.\"
.TH pyradio 1 "May 2022" PyRadio

.SH Name
.PP
pyradio \- a curses Internet radio player.

.SH Synopsis
.PP
\fBpyradio\fR\ [\fIOPTIONS\fR]

.SH Description
.PP
.B PyRadio
is a command line Internet Radio Player based on curses, that uses external media players to perform the actual playback.
.PP
It currently supports the following players: \fIMPV\fR, \fIMPlayer\fR and \fIVLC\fR.

.SH Options

.IP \fB-s\fR,\fB\ \--stations\ \fR[\fISTATIONS\fR]
Use specified station CSV file.
.IP \fB-p\fR,\fB\ \--play\ \fR\<\fIPLAY\fR\>
Play station number \fR\<\fIPLAY\fR\>. Select randome station if \fR\<\fIPLAY\fR\> not specified.
.IP \fB-u\fR,\fB\ \--use-player\ \fR[\fIUSE_PLAYER\fR]
Specify which player to use (\fImpv\fR,\ \fImplayer\fR\ or\ \fIvlc\fR). A comma-separated list of players can be givven, thus specifying detection order.
.IP \fB-a\fR,\fB\ \--add
Add station to list.
.IP \fB-ls\fR,\fB\ \--list-playlists
List of available playlists in config dir.
.IP \fB-l\fR,\fB\ \--list
List of available stations in a playlist.
.IP \fB-t\fR\ \fITHEME\fR,\ \fB--theme\fR\ \fITHEME\fR
Use specified \fITHEME\fR.
.IP \fB-tlp\fR,\ \fB--toggle-load-last-playlist
Toggle autoload last opened playlist.
.IP \fB-scd\fR,\fB--show-config-dir\fR
Print config directory (\fI[CONFIG DIR]\fR) location and exit.
.IP \fB-ocd\fR,\fB--open-config-dir\fR
Open config directory (\fI[CONFIG DIR]\fR) with default file manager.
.IP \fB-ep\ \fIEXTRA_PLAYER_PARAMETERS\fR,\ \fB--extra_player_parameters\ \fIEXTRA_PLAYER_PARAMETERS\fR
Provide extra player parameters as a string. For more information, refer to the \fBEXTRA PLAYER PARAMETERS\fR section.
.IP \fB-ap\fR\ \fIACTIVE_PLAYER_PARAM_ID\fR,\ \fB--active-player-param-id\fR\ \fIACTIVE_PLAYER_PARAM_ID\fR
Specify the extra player parameter set to be used with the default player. \fIACTIVE_PLAYER_PARAM_ID\fR is 1-11.
.IP \fB-lp
List extra players parameters.
.IP \fB-U
Update \fBPyRadio\fR.
.IP \fB--user
Install only for current user (linux only).
.IP \fB-R
Uninstall \fBPyRadio\fR.
.IP \fB--unlock
Remove sessions' lock file.
.IP \fB-d\fR,\fB\ \--debug
Enable \fBDEBUG MODE\fR.
.IP \fB-h\fR,\fB\ \--help
Show usage information and exit.

.RE
.PP
The following options can also be set in \fBPyRadio\fR’s configuration file:

.IP \fB-s\fR
parameter \fIdefault_playlist\fR (default value: \fBstations\fR)
.IP \fB-p\fR
parameter \fIdefault_station\fR (default value: \fB-1\fR)
.IP \fB-u\fR
parameter \fIplayer\fR (default value: \fBmpv, mplayer, vlc\fR)

.SH Controls

.IP \fBUp\fR/\fBDown\fR/\fBPgUp\fR/\fBPgDown
Change station selection
.IP \fBj\fR/\fBk
Change station selection (vi-like)
.IP \fBEnter\fR/\fBRight\fR/\fBl
Play selected station
.IP \fBr
Select and play a random station
.IP \fBSpace\fR/\fBLeft\fR/\fBh
Stop/start playing selected station
.IP \fBP\fR
Jump to playing station
.IP \fBH\ M\ L
Jump to top / middle / bottom of screen
.IP \fBg
Jump to the start of the playlist
.IP \fI<n>\fBG
Jump to the end of the playlist
.br
If \fI<n>\fR (line number) was entered, jump to it
.IP \fB-\fR/\fB+\fR\ or\ \fB,\fR/\fB.
Change volume
.IP \fBm
Mute
.IP \fBv
Save volume (\fIMPV\fR and \fIMPlayer\fR only)
.IP \fBo\ s\ R
\fBO\fIpen\fR / \fBS\fIave\fR / \fBR\fIeload\fR playlist
.IP \fBa\ A\fR
Add / append a new station
.IP \fBe\fR
Edit current station
.IP \fBE\fR
Change current station's encoding
.IP \fBDEL\fR,\fBx
Delete selected station
.IP \fBJ
Create a \fIJump tag
.IP \fI<n>\fB^U\fR,\fI<n>\fB^D
Move current station up / down
.br
If \fI<n>\fR (line number) was entered, or a \fIJump tag\fR has been defined, move the station there
.IP \fBt
Open the \fITheme Selection\fR window
.IP \fBT
Toggle background transparency
.IP \fBc
Open the \fIConfiguration window
.IP \fB'\ \\\\\ y\fR
Get into \fIRegisters\fR, \fIExtra Commands\fR, \fIYank\fR mode, respectively
.IP \fBz\fR
Toggle "Force http connections"
.IP \fBZ\fR
Display the "Extra Player Parameters" window.
.IP \fB?
Show keys help
.IP \fBEsc\fR/\fBq
Quit

.P
The same logic applies to all \fBPyRadio\fR windows.

.IP \fBNote:
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 "\fIG\fR", i.e. pressing \fI35\fR will display \fI[35G]\fR.

.IP \fBNote:
When tagging a station position for a move action (by pressing "\fBJ\fR"), the position will be displayed at the right bottom corner of the window, suffixed by a "\fIJ\fR", i.e. pressing "\fIJ\fR" on position \fI35\fR will display \fI[35J]\fR.

.IP \fBGlobal\ shortcuts\fR

Some of the functions provided by \fBpyradio\fR will always be available to the user. These functions are:


.RS 10

.IP \fB+\fR/\fB-\fR\ and\ \fB,\fR/\fB.\fR
adjust volume
.IP \fBm\fR
mute player
.IP \fBv\fR
save volume
.IP \fBT\fR
toggle transparency
.IP \fBW\fR
toggle titles logging
.IP \fBw\fR
like a station

.RE
.RS 7
Every window in \fBpyradio\fR will respect these shotrcuts, even the ones with a “\fIPress any key to…\fR” message.

When focus is on a \fBLine editor\fR, all shortcuts will work when preceded by a "\fI\\\fR".

.SH Pyradio's Modes

\fBPyRadio\fR has the following primary modes:

.RS 5
.IP 1. 3
The \fBMain\fR 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 \fBediting mode\fR. All other modes derive from this one, and it's the mode you have to get to in order to terminate the program.

.IP 2. 3
The \fBPlaylist\fR mode, which you can open by pressing "\fBo\fR". Then you can open, create, paste a station, etc.

.IP 3. 3
The \fBRegisters\fR mode. This is identical to the "\fIPlaylist\fR" mode, but instead of displaying playlists, it displays register. You can enter this mode by pressing "\fB''\fR" (two single quotes) and exit from it by pressing "\fBEsc\fR" or "\fBq\fR". You can also press "\fB'\fR" (single quote) to get to the "\fIPlaylist\fR" mode and back.

.IP 4. 3
The \fBRegister Main\fR mode, which is identical to the "\fIMain\fR" mode, except it displays the content of a \fBnamed\fR register.

.IP 5. 3
The \fBListening\fR mode, which is intended to be used when you want \fBPyRadio\fR 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 "\fIStatus Bar\fR"). In this mode, adjusting, muting and saving the volume are the only actions available. To get \fBPyRadio\fR back to normal operation one would just resize its window to a reasonable size (7 lines vertically, or more).

.RE


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

.RE
.RS 5
.IP 1. 3
The \fBExtra Commands\fR mode, which gives you access to extra commands. You can enter this mode by pressing "\fB\\\fR" (backslash). Then a backslash is displayed at the bottom right corner of the window.

.IP 2. 3
The \fBYank (Copy)\fR mode, which is used to copy stations to \fBregisters\fR. You can enter this mode by pressing "\fBy\fR". Then a "\fIy\fR" is displayed at the bottom right corner of the window.

.IP 3. 3
The \fBOpen Register\fR mode, which is used to open a register or get into the \fIRegisters\fR or \fIRegister Main\fR mode. You can enter this mode by pressing "\fB'\fR" (single quote). Then a single quote is displayed at the bottom right corner of the window.

.IP 4. 3
The \fBPaste\fR mode, which is available in the \fIStation editor\fR window only. It is designed to help the user paste a URL (and optionally a station's name). Why you might ask... Well, the \fIStation editor\fR normally treats the "\fI?\fR" and "\fI\\\fR" characters as special characters (actually commands). So, if a URL which contains these characters (more frequently the "\fI?\fR" character) is pasted it will be corrupted unless the \fBPaste\fR mode is enabled.

.RE

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

\fBTiling manager modes\fR

.RS 5

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

.IP 1. 3
The \fBLimited Height\fR mode, which is automatically enabled when the window height gets \fIbelow 8 lines\fR.

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 \fBLimited display\fR.

.IP 2. 3
The \fBLimited Width\fR mode, which is automatically enabled when the window width get bellow certain limits:

.RE
.RS 8
.IP a. 3
When the width gets \fIbellow 40 columns\fR, all windows will be closed and the main window will be the only visible one (either displaying stations, playlists or registers).

.IP b. 3
When the width gets \fIbellow 20 columns\fR, the \fBLimited display\fR will be activated.

.SH Config File
\fBPyRadio\fR upon its execution tries to read its configuration file (i.e. \fI~/.config/pyradio/config\fR). If this file is not found, it will be created. If an error occurs while parsing it, an error message will be displayed and \fBPyRadio\fR will terminate.

The file contains parameters such as the player to use, the playlist to load etc. It is heavily commented, so that manual editing is really easy. The best practice to manually edit this file is executing \fBPyRadio\fR with the \fB-ocd\fR command line option, which will open the configuration directory in your file manager, and then edit it using your preferable text editor.

The file can also be altered while \fBPyRadio\fR is running, by pressing "\fIc\fR", which will open the "\fIConfiguration window\fR". This window presents all \fBPyRadio\fR options and provide the way to change them and finally save them by pressing "\fIs\fR".

In any case, \fBPyRadio\fR 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, \fBPyRadio\fR will create a back up file and terminate. When restarted, \fBPyRadio\fR will try to restore previously used settings from the said back up file.

.SH About Playlist Files
.PP
\fBPyRadio\fR 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.
.PP
Optionally, a third column can be inserted, stating the encoding used by the station (more on this at \fBSpecifying Stations' Encoding\fR).
.PP
\fBPyRadio\fR will by default load the user's stations file (e.g. \fI~/.config/pyradio/stations.csv\fR). If this file is not found, it will be created and populated with a default set of stations.

.IP \fBTip:
If you already have a custom \fIstations.csv\fR file, but want to update it with \fBPyRadio\fR's default one, you just rename it, run \fBPyRadio\fR (so that the default one get created) and then merge the two files.

.IP \fBNote:
Older versions used to use \fI~/.pyradio\fR as default stations file. If this file is found, it will be copied to use's config directory (e.g. \fI~/.config/pyradio\fR) and renamed to \fIstations.csv\fR or if this file exists, to \fIpyradio.csv\fR. In this case, this file will be the default one.

.PP
.B
Specifying a playlist to load (command line)

.PP
\fBPyRadio\fR will normally load its default playlist file, as described above, upon its execution. A different file can be loaded when the \fI-s\fR command line option is used.

.PP
The \fI-s\fR option will accept:

.HP

\fI*\fR a relative or absolute file name.

\fI*\fR the name of a playlist file which is already in its configuration directory.

\fI*\fR the number of a playlist file, as provided by the \fI-ls\fR command line option.

.PP
\fBExamples:\fR

.HP
To load a playlist called "\fIblues.csv\fR", one would use the command:

.RS 5
\fBpyradio -s /path/to/\fIblues.csv\fR

.RE
If this file was saved inside \fBPyRadio\fR's configuration directory, one could use the following command:

.RS 5
\fBpyradio -s \fIblues\fR

.RE
To use the playlist number, one would execute the commands:

.RS 5

\fBpyradio -ls\fI

Playlists found in "/home/user/.config/pyradio"
  1. hip-hop
  2. party
  3. stations
  4. huge
  \fB5. blues\fI
  6. rock
  7. pop

\fBpyradio -s \fI5\fR


.IP \fBNote\fR
The default playlist to load can also be set in \fBPyRadio\fR’s configuration file, parameter \fIdefault_playlist\fR (default value is \fIstations\fR).



.RE
.PP
.B
Autoloading playlists

As already stated, \fBPyRadio\fR will normally load its default playlist (called "\fBstations\fR") upon startup.

This behavior can be then changed in two ways:

.RS 5
.IP 1. 3
Changing the default playlist.

This is accomplished using the "\fBDef. playlist\fR" configuration option (optionally along with the "\fBDef. station\fR" option).

.IP 2. 3
Always loading the last used playlist at startup.

This is accomplished using the "\fBOpen last playlist\fR" configuration option.

In this case, the last used playlist will be opened the next time \fBPyRadio\fR will be executed, trying to restore the previously selected station or starting playback.

This option will take precedence before the "\fBDef. playlist\fR" configuration option (if it is used) and the "\fI-s\fR" ("\fI--stations\fR") command line option.

.RS 3
.IP \fBNote:\fR
When the "\fBOpen last playlist\fR" configuration option is set, all playlist operations will be performed to the last opened playlist. In order to use the "\fI-a\fR" ("\fI--add\fR") or "\fI-l\fR" ("\fI--list\fR") command line options along with the "\fI-s\fR" ("\fI--stations\fR") command line option, the "\fI-tlp\fR" "\fI--toggle-load-last-playlist\fR") option can be used to temporarily deactivate autoloading.
.RE
.RE

.PP
.B
Managing Playlists (within Pyradio)

Once \fBPyRadio\fR 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 "\fIa\fR" or "\fIA\fR" will enable you to add a new station (either below the currently selected station or at the end of the list), while "\fIe\fR" will edit the currently selected station. All of these actions will open the "\fIStation editor\fR".

If you just want to change the encoding of the selected station, just press "\fIE\fR". 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 "\fIs\fR", or reload the playlist from disk, by pressing "\fIR\fR". A modified playlist will \fIautomatically\fR be saved when \fBPyRadio\fR 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 "\fIDEL\fR" or "\fIx\fR".

Finally, opening another playlist is also possible. Just press "\fIo\fR" and you will be presented with a list of saved playists to choose from. These playlists must be saved beforehand in \fBPyRadio\fR'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 \fBPyRadio\fR's configuration file for future reference.

.PP
.B
Managing “Foreign” Playlists

A playlist that does not reside within the program’s configuration directory is considered a "\fIforeign\fR" playlist. This playlist can only be opened by the \fB-s\fR command line option.

When this happens, \fBPyRadio\fR 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 "\fIforeign\fR" playlist will be time-stamped. For example, if a "\fIforeign\fR" playlist is named "\fIstations.csv\fR", it will be named "\fI2019-01-11_13-35-47_stations.csv\fR" (provided that the action was taked on January 11, 2019 at 13:35:47).


.PP
.B
Playlist History

\fBPyRadio\fR 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 "\fI\\\\\fR" (double backslash). To get to the first playlist "\fI\\]\fR" (backslash - closing square bracket) can be used.

Going forward in history is not supported.

.SH Search Function

On any window presenting a list of items (stations, playlists, themes) a \fBsearch function\fR is available by pressing "\fI/\fR".

The \fISearch Window\fR supports normal and extend editing and in session history.

One can always get help by pressing the "\fI?\fR" key.

After a search term has been successfully found (search is case insensitive), next occurrence can be obtained using the "\fIn\fR" key and previous occurrence can be obtained using the "\fIN\fR" key.

.SH Line Editor

\fBPyRadio\fR "\fISearch function\fR" and "\fIStation editor\fR" use a \fILine editor\fR to permit typing and editing stations' data.

The \fILine editor\fR works both on \fBPython 2\fR and \fBPython 3\fR, but does not provide the same functionality for both versions:

.RS 5
.IP \fI*\fR 2
In \fBPython 2\fR, only ASCII characters can be inserted.
.IP \fI*\fR 2
In \fBPython 3\fR, no such restriction exists.  Furthermore, using CJK characters is also supported.

.RE

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

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

To sum it all up:

.IP
1. Press "\fI?\fR" to get help.
.IP
2. Press "\fI\\?\fR" to get a "\fI?\fR".
.IP
3. Press "\fI\\\\\fR" to get a "\fI\\\fR".

.PP
When in \fIStation editor\fR, the \fBLine editor\fR recognizes an extra mode: \fBPaste mode\fR.

This mode is enabled by pressing "\fB\\p\fR" and gets automatically disabled when the focus moves off the line editors.

This mode is designed to directly accept the "\fI?\fR" and "\fI\\\fR" characters (which are normally used as commands indicators). This makes it possible to easily paste a station's name and URL, especially when the "\fI?\fR" and "\fI\\\fR" characters exist in them; it is very common to have them in URLs.

.PP
\fBCJK Characters Support\fR

The \fILine editor\fR supports the insertion of \fICJK Unified Ideographs [1]\fR, as described on \fICJK Unified Ideographs (Unicode block) [2]\fR, 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:

\fIhttps://members.hellug.gr/sng/pyradio/pyradio-editor.jpg\fR

[1] \fIhttps://en.wikipedia.org/wiki/CJK_Unified_Ideographs\fR

[2] \fIhttps://en.wikipedia.org/wiki/CJK_Unified_Ideographs_(Unicode_block)\fR


.SH 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 \fIsource\fR station (the station to be moved) and the position it will be moved to (\fItarget\fR).

There are three way to do that:

.RS 5

.IP 1. 3
Press \fICtrl-U\fR or \fICtrl-D\fR to move the current station up or down.
.IP 2. 3
Type a station number and press \fICtrl-U\fR or \fICtrl-D\fR to move the current station there.
.IP 3. 3
Go to the position you want to move a station to, and press "\fIJ\fR". This will tag this position (making it the target of the move). Then go to the station you want to move and press \fICtrl-U\fR or \fICtrl-D\fR to move it there.


.SH Specifying Stations' Encoding

Normally, stations provide information about their status (including the title of the song playing, which \fBPyRadio\fR displays) in Unicode (\fIutf-8\fR encoded). Therefore, \fBPyRadio\fR will use \fIutf-8\fR 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 \fBPyRadio\fR 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 \fBPyRadio\fR would be that a song title would be incorrectly displayed, not displayed at all, or trying to displaying it might even break \fBPyRadio\fR's layout.

.IP \fBNote\fR
\fIvlc\fR will not work in this case; it presumably tries to decode the said data beforehand, probably using \fIutf-8\fR by default, and when it fails, it provides a "\fI(null)\fR" string, instead of the actual data. So, you'd better not use \fIvlc\fR if such stations are in your playlists.

.PP
\fBPyRadio\fR addresses this issue by allowing the user to declare the encoding to use either in a station by station mode or globally.

.PP
.B
Station By Station Encoding Declaration

As previously stated, a \fBPyRadio\fR'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 \fInon-utf-8\fR 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 \fBall stations\fR (so that the \fBCSV\fR 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 "\fI,\fR" 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 \fIutf-8\fR encoded station:

.HP

\fIStation1\fB,\fIStation1_URL

.PP
Now we want to add "\fIStation2\fR" which is \fIiso-8859-7\fR (Greek) encoded.

Since we know \fBall stations\fR must comprise the third (encoding) column, we add it to the existing station:


.HP

\fIStation1\fB,\fIStation1_URL\fB,

.PP
This way we add an empty encoding, forcing
.PP
Finally, we insert the new station to the playlist:

.HP

\fIStation1\fB,\fIStation1_URL\fB,\fI
.br
Station2\fB,\fIStation2_URL\fB,\fIiso-8859-7

.IP \fBNote\fR
Using the \fB-a\fR command line option will save you all this trouble, as it will automatically take care of creating a valid \fBCSV\fR file. Alternatively, you can change the selected station's encoding by pressing "\fIE\fR" while in \fBPyRadio\fR.


.PP
.B
Global Encoding Declaration

\fBPyRadio\fR's configuration file contains the parameter \fBdefault_encoding\fR, which by default is set to \fIutf-8\fR.

Setting this parameter to a different encoding, will permit \fBPyRadio\fR to successfully decode such stations.

This would be useful in the case where most of your stations do not use \fIutf-8\fR. Instead of editing the playlist and add the encoding to each and every affected station, you just set it globally.

.PP
.B
Finding The Right Encoding

A valid encoding list can be found at:

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

\fRreplacing \fI2.7\fR with specific version: \fI3.0\fR up to current python version.

.SH Player Detection / Selection
.PP
\fBPyRadio\fR 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.
.PP
Currently, it supports \fIMPV\fR, \fIMPlayer\fR and \fIVLC\fR, and it will look for them in that order. If none of them is found, the program will terminate with an error.
.PP
Users can alter this default behavior by using the \fB-u\fR command line option. This option will permit the user either to specify the player to use, or change the detection order.
.PP
Example:

.IP \fBpyradio\ -u\ vlc
will instruct \fBPyRadio\fR to use VLC; if it is not found, the program will terminate with an error.

.IP \fBpyradio\ -u\ vlc,mplayer,mpv
will instruct \fBPyRadio\fR 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.


.IP \fBNote\fR
The default player to use can also be set in \fBPyRadio\fR’s configuration file, parameter \fIplayer\fR (default value is \fImpv, mplayer, vlc\fR).

.SH
\fBExtra Player Parameters\fR

All three supported players can accept a significant number of "\fIcommand line parameters\fR", which are well documented and accessible through man pages (on linux and macOs) or the documentation (on Windows).

\fBPyRadio\fR uses some of these parameters in order to execute and communicate with the players. In particular, the following parameters are in use \fBby default\fR:

.RS 5
.IP \fBPlayer\fR 10
\fBParameters\fR
.IP \fBmpv\fR 10
--no-video, --quiet, --input-ipc-server, --input-unix-socket, --playlist, --profile
.IP \fBmplayer\fR 10
-vo, -quiet, -playlist, -profile
.IP \fBvlc\fR 10
-Irc, -vv. \fIOn Windows only:\fR --rc-host, --file-logging, --logmode, --log-verbose, --logfile
.RE

.IP \fBNote\fR
The user should not use or change the above player parameters. Failing to do so, may render the player \fBunusable\fR.

.P
\fBPyRadio\fR provides a way for the user to add extra parameters to the player, either by a command line parameter, or the "\fIConfiguration Window\fR" (under "\fIPlayer:\fR").

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

\fBUsing The Command Line\fR

When the command line parameter (\fB-epp\fR or \fB-extra_player_parameters\fR) is used, the parameters specified must be of a specific format, and will be added to the list of parameters and made default for the player for the current session.

The format of the parameter is the following: \fI[\fBplayer_name\fR:\fBparameters\fI]\fR.

Where:

.RS 5
.IP \fBplayer_name\fR
the name of the player (\fImpv\fR, \fImplayer\fR or \fIvlc\fR)
.IP \fBparameters\fR
the actual player parameters
.RE

.P
Example:

.HP

\fIpyradio -epp "vlc:--force-dolby-surround 2"\fR


.IP \fBNote\fR
When a parameter is passed to \fImpv\fR or \fImplayer\fR, \fBPyRadio\fR will use the default player profile (called \fBPyRadio\fR).

.P
For \fImpv\fR and \fImplayer\fR a profile can be specified (\fIvlc\fR does not support profiles). In this case the format of the \fBparameters\fR part of the command line is: \fI[\fBprofile\fR:\fBprofile_name\fI]\fR.

Where:
.RS 5
.IP \fBprofile
the word "\fIprofile\fR"
.IP \fBprofile_name
the name of a profile. The profile must be already defined in the player's configuration file.
.RE

.P
Example:

.HP

\fIpyradio -epp "mpv:profile:second_sound_card"


.P
\fBUsing The Configuration Window\fR

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 \fBPyRadio\fR 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 ("\fBa\fR") a new parameter, edit ("\fBe\fR") an existing set and delete ("\fBx\fR" or "\fBDEL\fR") one.

\fBChanging Parameters' Set\fR

.P
When all desired parameter sets are already defined, using the \fB-ap\fR (\fB--active-player-param-id\fR) command line parameter can activate the set that corresponds to the number specified. The number to use for any given set can be retrieved using the \fB-lp\fR (\fB--list-player-parameters\fR) command line parameter.

While \fBPyRadio\fR is running, the user can change the parameters' set used by the player using the "\fIPlayer Extra Parameters\fR" window, by pressing "\fBZ\fR".

If playback is on, changing the player's parameters will make the player restart the playback so that the new parameters is used.

.IP \fBNote\fR
Any changes made this way will not be saved but will be in effect until \fBPyRadio\fR terminates.

.SH 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 \fBhttps\fR 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 \fBhttp\fR protocol to connect to it.

\fBPyRadio\fR provides a way to instruct the player used to do so; the "\fIForce http connections\fR" configuration parameter. If it is \fIFalse\fR (the default), the player will use whatever protocol the station proposes (either \fBhttp\fR or \fBhttps\fR). When changed to \fBTrue\fR, all connections will use the \fBhttp\fR 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 "\fIz\fR" to display the "\fIConnection Type\fR" window, where the parameter's value can be set as desired.

.IP \fBNote\fR
Changes made using the "\fIConnection Type\fR" 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.

.SH Player Default Volume Level
.PP
\fIMPV\fR and \fIMPlayer\fR, when started, use their saved (or default) volume level to play any multimedia content. Fortunately, this is not the case with \fIVLC\fR.
.PP
This introduces a problem to \fBPyRadio\fR: 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.
.PP
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.
.PP
This is done by typing "\fIv\fR" right after setting a desired volume level.
.PP
\fBMPV\fR
.PP
\fIMPV\fR uses profiles to customize its behavior.
.PP
\fBPyRadio\fR defines a profile called "\fI[pyradio]\fR" in MPV's configuration file (e.g. \fI~/.config/mpv/mpv.conf\fR). This profile will be used every time playback is started.
.PP
Example:

.HP

\fIvolume=100

[pyradio]
.br
volume=50

.PP
\fBMPlayer\fR
.PP
\fIMPlayer\fR uses profiles to customize its behavior as well.
.PP
\fBPyRadio\fR defines a profile called "\fI[pyradio]\fR" in MPV's configuration file (e.g. \fI~/.mplayer/config\fR). This profile will be used every time playback is started.
.PP
Example:

.HP

\fIvolume=100

[pyradio]
.br
volstep=1
.br
softvol=1
.br
softvol-max=300
.br
volstep=1
.br
volume=50

.IP \fBNote:
Starting with \fBpyradioR v. 0.8.9\fR, \fImplayer\fR's default profile will use its internal mixer to adjust its volume; this is accompliced using the "\fIsoftvol=1\fR" and "\fIsoftvol-max=300\fR" 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 \fBPyRadio\fR version).

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

\fBPyRadio\fR 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 "\fIi\fR" to display the station's info.

The window that appears includes the "\fIPlaylist Name\fR" (the station name we have in the playlist) and the "\fIReported Name\fR" (the name the station transmitted to us) among other fields (an example can be seen here: \fIhttps://members.hellug.gr/sng/pyradio/pyradio-station-info.jpg\fR . If these two names are not identical, the user can press "\fIr\fR" to rename the station in the playlist using the "\fIReported Name\fR". 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).


.SH Copying And Pasting - Registers

\fBPyRadio\fR takes the concept of \fBregisters\fR from i\fIvim\fR (\fIhttps://www.vim.org\fR), and adapts their function to its own needs. So this is how it all works.

There are 36 named registers (name is \fBa-z\fR, \fB0-9\fR) and one unnamed register.

.IP \fBNamed\ registers\fR
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 \fBrename\fR it to a normal playlist file.

.IP The\ \fBunnamed\ register\fR
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 "\fB\\u\fR".


.P
To \fBcopy\fR a station to a register one would press "\fBy\fR" and:

.RS 5
.IP \fI*\fR 2
one of "\fBa-z\fR", "\fB0-9\fR" to add it to the corresponding \fInamed\fR register. The \fIunnamed\fR register is also populated.

.IP \fI*\fR 2
\fBENTER\fR to add it to the \fIunnamed\fR register.

.RE
To \fBopen\fR a \fInamed\fR register, one would press "\fB'\fR" (single quote) and:

.RS 5
.IP \fI*\fR 2
one of "\fBa-z\fR", "\fB0-9\fR" to open the corresponding register.

.IP \fI*\fR 2
"\fB'\fR" (single quote) to open the "\fIRegisters window\fR", so that a register can be selected.

.RE
To \fBrename\fR a \fInamed\fR register, one would press "\fB\\r\fR" either in the "\fIRegisters window\fR" or while editing the register.

To \fBclear a named register\fR, one would press "\fB\\c\fR" either in the "\fIRegisters window\fR" or while editing the register.

To \fBclear all registers\fR, one would press "\fB\\C\fR" either in the "\fIRegisters window\fR" or while editing a playlist or a register.

To \fBpaste\fR the \fIunnamed\fR register to a playlist or register, one would press:

.RS 5
.IP \fI*\fR 2
"\fBp\fR" while editing a playlist or register.

.IP \fI*\fR 2
"\fB\\p\fR" while editing a playlist or register. This would open the "\fIPaste selection\fR" window.

.IP \fI*\fR 2
"\fB\\p\fR" in the "\fIPlaylist Selection\fR or the "\fIRegisters\fR" window.

.RE

.SH Pyradio Themes
.PP

\fBPyRadio\fR comes with 6 preconfigured (hard coded) themes:

.IP \fBdark\fR\ (8\ color\ theme)
This is the appearance \fBPyRadio\fR has always had. Enabled by default.
.IP \fBlight\fR\ (8\ color\ theme)
A theme for light terminal background settings.
.IP \fBdark_16_colors\fR\ (16\ color\ theme)
\fIdark\fR theme alternative.
.IP \fBlight_16_colors\fR\ (16\ color\ theme)
\fIlight\fR theme alternative.
.IP \fBwhite_on_black\fR\ or\ \fBwob\fR\ (256\ color\ b&w\ theme)
A theme for dark terminal background settings.
.IP \fBblack_on_white\fR\ or\ \fBbow\fR\ (256\ color\ b&w\ theme)
A theme for light terminal background settings.

.PP
Furthermore, three 256-color system themes (these are actual files saved in the \fIthemes\fR installation directory) are also available: \fBbrown_by_sng\fR, \fBpink_by_sng\fR and \fBpurple_by_sng\fR.

.PP
The visual result of an applied theme greatly depends on the terminal settings (e.g. foreground and background color settings, palette used, number of colors supported, real or pseudo-transparency support, etc.)

Pressing "\fBt\fR" will bring up the \fITheme selection window\fR, which can be used to activate a theme and set the default one.

.IP \fBNote\fR
Themes that use more colors than those supported by the terminal in use, will not be present in the \fITheme selection window\fR. Furthermore, if a such a theme is set as default (or requested using the "\fB-t\fR" command line option), \fBPyRadio\fR will fall-back to the "\fBdark\fR" theme, (or the "\fBlight\fR" theme, if the terminal supports 8 colors and default theme is set to "\fIlight_16_colors\fR"), and will display a relevant messages at program startup.

.PP
The \fITheme selection window\fR 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 "\fBq\fR" or any other relevant key - pressing "\fB?\fR" will bring up its help).

The use of custom themes and theme editing is not implemented yet; theses are features for future releases.

.PP
\fBUsing Transparency\fR

\fBPyRadio\fR themes are able to be used with a transparent background.

Pressing "\fBT\fR"  will toggle the transparency setting (it is \fIoff\fR by default) and save this state in \fBPyRadio\fR's configuration file.

Setting transparency on, will actually force \fBPyRadio\fR to not use its own background color, effectively making it to display whatever is on the terminal (color/picture/transparency). The visual result depends on terminal settings and whether a compositor is running.

When the \fITheme selection window\fR is visible, a "\fI[T]\fR" string displayed at its bottom right corner will indicate that transparency is \fIon\fR.

.SH Mouse Support

Being a console application, \fBPyRadio\fR 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 \fBPyRadio\fR 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 "\fIConfig Window\fR" (mouse support is disabled by default) and restart \fBPyRadio\fR for the change to take effect.

Then, the mouse can be used as follows:

.RS 5

.IP \fBClick
Change selection

.IP \fBDouble\ click
Start / stop the player

.IP \fBMiddle\ click
Toggle player muting (does not work with all terminals)

.IP \fBWheel
Scroll up / down

.IP \fBShift-Wheel
Adjust volume (does not work with all terminals)

.RE

.SH Titles logging

Version \fB0.8.9.17\fR adds to \fBpyradio\fR the ability to log the titles displayed at the bottom of its window, in a log file, for refference.

The logger, which works independantly from the "\fIdegub\fR" function, is actually a \fIRotating File Handler\fR (\fIhttps://docs.python.org/3/library/logging.handlers.html#logging.handlers.RotatingFileHandler\fR), configured to write up to 5 files of around 50KB each (parameters \fBmaxBytes=50000\fR and \fBbackupCount=5\fR).

The way this works, according to the documenataion, is that one "can use the \fBmaxBytes\fR and \fBbackupCount\fR 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 \fBmaxBytes\fR in length… When \fBbackupCount\fR 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 \fBapp.log\fR, you would get \fIapp.log\fR, \fIapp.log.1\fR, \fIapp.log.2\fR, up to \fIapp.log.5\fR. The file being written to is always \fBapp.log\fR. When this file is filled, it is closed and renamed to \fIapp.log.1\fR, and if files \fIapp.log.1\fR, \fIapp.log.2\fR, etc. exist, then they are renamed to \fIapp.log.2\fR, \fIapp.log.3\fR etc. respectively.

The function can be enabled:

.RS 5
.IP 1. 3
using the \fI-lt\fR (\fI--log-titles\fR) command line parameter, or

.IP 2. 3
by pressing "\fBW\fR" while in the \fBMain\fR, the \fBPlaylist\fR or the \fBRegister\fR mode.

.RE

The titles are written in a file called \fIpyradio-titles.log\fR which is saved at \fBpyradio\fR configuration directory.

Log file sample:

.RS 5
\fIApr 18 (Mon) 13:12 | >>> Station: Lounge (Illinois Street Lounge - SomaFM)
.br
Apr 18 (Mon) 13:12 |     Jack Costanzo - La Cumparsa, Harlem Nocturne
.br
Apr 18 (Mon) 13:14 |     Don Baker Trio - Third Man Theme
.br
Apr 18 (Mon) 13:16 |     Gillian Hills - Un Petit Baiser
\fR
.RE

\fBTagging a title\fR

An extra functionality is made possible because of "\fItitles's logging\fR": 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 "\fBw\fR" key.

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

.RS 5
\fIApr 18 (Mon) 13:39 |     Tom Russell - Bus Station
.br
Apr 18 (Mon) 13:40 |     Tom Russell - Bus Station (LIKED)\fR
.RE

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

.RS 5
\fIApr 18 (Mon) 15:38 | === Logging started
.br
Apr 18 (Mon) 15:38 | >>> Station: Folk (Folk Forward - SomaFM)
.br
Apr 18 (Mon) 15:38 |     Lord Huron - Lullaby
.br
Apr 18 (Mon) 15:38 |     Lord Huron - Lullaby (LIKED)
.br
Apr 18 (Mon) 15:38 | === Logging stopped\fR
.RE

.SH Online Radio Directory Services

\fBPyRadio\fR supports the following \fIOnline Radio Directory services\fR:

.IP \fBRadioBrowser\ -\ \fIhttps://www.radio-browser.info/\fR

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: \fIpyradio_rb(1)\fR.

.PP
To access supported services, just press "\fIO\fR" at the program's main window.


.SH Session Locking

\fBPyRadio\fR 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 "\fIlocked\fR. This means that the user can still play stations, load and edit playlists, load and test themes, but any changes will \fBnot\fR be recorded in the configuration file.

\fBSession unlocking\fR

If for any reason \fBPyRadio\fR always starts in \fIlocked mode\fR, one can \fBunclock\fR the session, using the "\fB--unlock\fR" command line paremater.

.SH Update Notification
.PP
\fBPyRadio\fR 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).

.SH Cleaning Up

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

.SH Debug Mode
.PP
Adding the \fB-d\fR option to the command line will instruct \fBPyRadio\fR to enter \fBDebug mode\fR, 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 \fIpyradio.log\fR.
.PP
In case of a bug or a glitch, please include this file to the issue you will open in github  at \<\fIhttps://github.com/coderholic/pyradio/issues\fR\>

.SH Reporting Bugs
.PP
When a bug is found, please do report it by opening an issue at github at \<\fIhttps://github.com/coderholic/pyradio/issues\fR\>, as already stated above.

In you report you should, at the very least, state your \fIpyradio version\fR, \fIpython version\fR and \fImethod of installation\fR (built from source, AUR, snap, whatever).

It would be really useful to include \fB~/pyradio.log\fR in your report.

To create it, enter the following commands in a terminal:

.HP

\fI$\fR \fBrm ~/pyradio.log\fR
.br
\fI$\fR \fBpyradio -d\fR

.PP
Then try to reproduce the bug and exit pyradio.

Finally, include the file produced in your report.

.SH Acknowlegement

.PP
\fBPyRadio\fR uses code from the following projects:

.RS 5

.IP 1. 3
\fBCJKwrap\fR (\fIhttps://gitlab.com/fgallaire/cjkwrap\fR) by Florent Gallaire - A library for wrapping and filling UTF-8 CJK text.

.IP 2. 3
\fBranger\fR (\fIhttps://ranger.github.io/\fR) - A console file manager with VI key bindings.

.IP 3. 3
\fBVifm\fR (\fIhttps://vifm.info/\fR) -  A file manager with curses interface, which provides a Vi[m]-like environment.

.SH Files
.PP
.I /usr/share/doc/pyradio/README.html

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

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

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

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

.I /usr/share/licenses/pyradio/LICENSE

.IP \fBNote:
On \fBMac OS\fR, these file may be installed in \fI/usr/local/share/doc/pyradio\fR, depending on whether or not \fBSIP\fR is enabled.


.SH Authors
.PP
\fBBen Dowling\fR\ \<\fIhttps://github.com/coderholic\fR\>,\ (Origianl\ author)
.PP
\fBKirill Klenov\fR\ \<\fIhttps://github.com/klen\fR\>,\ (2012)
.PP
\fBLaurent Stacul\fR\ \<\fIhttps://github.com/stac47\fR\>,\ (2013)
.PP
\fBPeter Stevenson (2E0PGS)\fR\ \<\fIhttps://github.com/2E0PGS\fR\>,\ (2018)
.PP
\fBSpiros Georgaras\fR\ \<\fIhttps://github.com/s-n-g\fR\>,\ (2018-2021)
.PP
You can see a complete list of contributors at
  https://github.com/coderholic/pyradio/graphs/contributors

.SH See also

    pyradio_rb(1)