pyradio(1)

📦 version 0.9.3.9, in opensuse-leap 16.0

pyradio(1) — General Commands Manual 💅

💖 NAME 💖

pyradio — a curses Internet radio player. That’s the whole vibe: terminal radio, but make it cute. 🎀

🌈 SYNOPSIS 🌈

pyradio [OPTIONS]

✨ DESCRIPTION ✨

Okay so bestie, pyradio is a command line Internet Radio Player based on curses, and it uses external media players to perform the actual playback. Periodt. 💅

It currently supports these players: MPV, MPlayer and VLC. Yes, those exact names, slay. 👑

🎀 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.
  • -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.
  • -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 (yes, the page says “sonfig”; I’m just the messenger 😭).
  • -d, --debug — start PyRadio in debug mode.
  • -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 TERMINAL_PARAM — use this as PyRadio parameter in the Desktop File. Please replace hyphens with underscores when passing the parameter, for example: --terminal-param "_p 3 _t light" (which will result to "pyradio -p 3 -t light").

🦋 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 (their spelling, not mine 🫶). 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:

-s     parameter default_playlist (default value: stations)
-p     parameter default_station (default value: -1)
-u     parameter player (default value: mpv, mplayer, vlc)

🎮 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:

  • +/- and ,/. — adjust volume.
  • m — mute player.
  • v — save volume.
  • T — toggle transparency.
  • W — toggle title logging.
  • w — like a station.
  • ^N/^P [1] [2] — play next / previous station.
  • </> [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. No cap. ✨

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.

🌸 Pyradio's Modes 🌸

okay bestie, pyradio has these primary modes — think of them as the main-character states of the app:

  1. The Main mode — this is what you get when you open the program: a list of stations (a playlist) that you can play and edit. That’s why it’s also called the editing mode. All the other modes come from this one, and it’s the mode you have to get back to in order to terminate the program. 👑
  2. The Playlist mode — open it by pressing "o". From there you can open, create, paste a station, etc. ✨
  3. The Registers mode — identical to the Playlist mode, but instead of displaying playlists it displays register. Enter it by pressing '' (two single quotes) and exit with Esc or q. You can also press ' (single quote) to get to the Playlist mode and back. 🎀
  4. The Register Main mode — identical to the Main mode, except it displays the content of a named register. 💅
  5. The Listening mode — made for when you just want pyradio to play your favorite station and not take up too much space. It’s ideal for tilling window manager use, because 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 actions available. To get pyradio back to normal operation, you just resize its window to a reasonable size (7 lines vertically, or more). 🦋

A set of secondary modes is also available — and yes, a secondary mode works within a primary one:

  1. The Extra Commands mode — gives you access to extra commands. Enter it by pressing \ (backslash). Then a backslash is displayed at the bottom right corner of the window. ⭐
  2. The Yank (Copy) mode — used to copy stations to registers. Enter it by pressing y. Then a y is displayed at the bottom right corner of the window. 💖
  3. The Open Register mode — used to open a register or get into the Registers or Register Main mode. Enter it by pressing ' (single quote). Then a single quote is displayed at the bottom right corner of the window. 🌈
  4. The Paste mode — available in the Station editor window only. It’s designed to help you 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 containing 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 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 🧚

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

  1. The Limited Width mode — automatically enabled when the window width get below certain limits:
    • a. 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). 🌸
    • b. When the width gets below 20 columns, the Limited display will be activated. ✨

🎀 Config File 🎀

when pyradio runs, it first reads its package configuration file and then tries to read the user configuration file. If an error occurs while parsing it, an error message will be displayed and pyradio will terminate. no cap, that’s the rule. 😌

📦 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, so it can be used as a template in order to manually create the user configuration file. 💖

You can also get the configuration file with the active parameter values (i.e. after being 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 from the one set in the package configuration file. 🎀

You can easily edit it manually, though. The best practice is to execute pyradio with the -ocd command line option, which will open the configuration directory in your file manager, and then edit (or create 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 🌸

Okay bestie, so pyradio reads the stations it's gonna play from a CSV file. Each line has two columns: column one is the station name, column two is the stream URL. Simple, iconic, no cap.

Optionally, you can add a third column that says what encoding the station uses — more on that at Specifying Stations' Encoding. And optionally, two more columns can be used.

So the whole lineup is: the third column defines the encoding used by the station (again, more at Specifying Stations' Encoding), and the fourth column sets an Icon URL, which gets used when displaying Desktop Notifications. 💖

By default, pyradio loads the user's stations file, like ~/.config/pyradio/stations.csv. If that file isn't found, it gets created and populated with a default set of stations. Slay.

Tip: If you already have a custom stations.csv file but wanna update it with pyradio's default one, just rename your file, run pyradio so the default one gets created, and then merge the two files. Easy.
Note: Older versions used to use ~/.pyradio as the default stations file. If that file is found, it will be copied to the user's config directory (e.g. ~/.config/pyradio) and renamed to stations.csv — or, if that file already exists, to pyradio.csv. In this case, this file will be the default one.

✨ Defining and using Groups ✨

To organize stations inside a big playlist, pyradio supports Groups. A Group is defined as a normal "station" entry whose URL field is a hyphen (-). For example, this defines a Group Header for a Group called Blues:

Blues,-

A Group Header entry does not define a station, so it cannot start a playback session. Other than that, it can be moved, copied, deleted, etc. just like any other playlist entry. Main character energy, honestly.

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

You can navigate among Groups with:

  • ^E / ^Y — go to the next / previous Group.
  • ^G — display a list of existing Groups to select from.

🌈 Integrating new stations 🌈

When the package's stations.csv file gets updated, those changes do not automatically appear in the user's stations file. Rude, but true.

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

Either way, the user can always manually update their stations file by issuing this 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, this 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) 🎀

Normally, pyradio loads its default playlist file, as described above, when it starts. A different file can be loaded when the -s command line option is used.

The -s option accepts:

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

Examples, because we love a demonstration:

To load a playlist called blues.csv, you'd use:

pyradio -s /path/to/blues.csv

If that file was saved inside pyradio's configuration directory, you could use:

pyradio -s blues

To use the playlist number, you'd execute:

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     │ 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: Python 2 output is much simpler, but the functionality is the same.
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 normally loads its default playlist (called stations) on startup. This behavior can be changed in two ways:

  1. Changing the default playlist. This is done using the Def. playlist configuration option (optionally along with the Def. station option).
  2. Always loading the last used playlist at startup. This is done using the Open last playlist configuration option. In this case, the last used playlist will be opened the next time pyradio is executed, trying to restore the previously selected station or starting playback. This option takes precedence before the Def. playlist configuration option (if it's used) and the -s (--stations) command line option.
Note: When the Open last playlist configuration option is set, all playlist operations will be performed on 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 loaded, you can perform a bunch of actions on the current playlist and on the set of playlists saved in its configuration directory. Currently, the following actions are available:

Pressing a or A lets you add a new station (either below the currently selected station or at the end of the list), while e edits the currently selected station. All of these actions open the "Station editor".

If you just wanna change the encoding of the selected station, press E. If the station is currently playing, playback will be restarted so the encoding change takes effect (hopefully correctly displaying the station/song title). Fingers crossed, bestie.

Then, when that's 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 when Ctrl+C is pressed).

One thing you may also wanna do is remove a station from a playlist — e.g. when you find it no longer works. You can do that by pressing DEL or x.

Finally, opening another playlist is also possible. Just press o and you'll 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 into its configuration directory, 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 March 11, 2019 at 13:35:47).

⭐ Playlist History ⭐

pyradio keeps a history of all the playlists opened (within a given session), so navigating between them is easy. To go back to the previous playlist, you just press \\ (double backslash). To get to the first playlist, \] (backslash - closing square bracket) can be used.

Going forward in history is not supported. We don't do that here. 💀

🎧 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 that 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 reset with every search that is performed. 🦋

🔍 SEARCH FUNCTION 🔍

Okay bestie, listen: any window that’s showing you a list of things — stations, playlists, themes — has a search function, and you open it by pressing /. 💅

The Search Window supports normal and extend editing and in session history. You can always get help by pressing the ? key.

After a search term has been successfully found — and yes, search is case insensitive — you get the next occurrence with n and the previous occurrence with N. Iconic. ✨

✨ LINE EDITOR ✨

pyradio’s “Search function” and “Station editor” use a Line editor so you can type and edit stations’ data. It works on both Python 2 and Python 3, but it does not give you the same functionality on both versions:

  • In Python 2, only ASCII characters can be inserted.
  • In Python 3, no such restriction exists. Furthermore, using CJK characters is also supported.

You can always display help by pressing ?, but that causes a drawback: you cannot actually have a ? within the string. To do that, you 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.

Paste mode is designed to directly accept the ? and \ characters — which are normally used as command 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-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:

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

🔀 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 — the target. 🎯

There are three ways 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 🧬

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, everything would be okay, 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 they come from). The result in pyradio would be that a song title would be incorrectly displayed, not displayed at all, or trying to display 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 adding the encoding to each and every affected station, you just set it globally. Slay. ✨

🔎 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 finally 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 🔄

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.

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 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"
A note of caution — If such a file has been created for a station, please do not rename the station in the playlist manually; the “link” to the referer file will be lost. Rename the station using pyradio rename functionality and save the playlist instead; the referer file will be renamed as well.
Note — 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

🌸 EXTRA PLAYER PARAMETERS 🌸

Ok so bestie, plot twist: all three supported players can accept a significant number of "command line parameters" — and they're all well documented and accessible through man pages (on linux and macOS) or the documentation (on Windows). Iconic of them honestly.

pyradio uses some of these parameters to execute and communicate with the players. In particular, the following parameters are in use by default:

  • mpv — --no-video, --quiet, --input-ipc-server, --input-unix-socket, --playlist, --profile
  • mplayer — -vo, -quiet, -playlist, -profile
  • vlc — -Irc, -vv. On 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. Like, do not touch, bestie, it's giving "handle with care". 💀

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

💅 Using The Configuration Window

When the user uses the configuration window (screenshot in the docs: pyradio-player-selection.jpg), they're presented with an interface which will permit them to select the player to use with pyradio and edit its extra parameters.

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

The user can add (a) a new parameter, edit (e) an existing set and delete (x or DEL) one. So simple, so clean. ✨

🔌 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. It's giving "it's complicated" 😭

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. Two different girls, bestie, don't mix them up. 🙈

🌈 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 can be seen in the screenshot http-force.jpg in the docs.

The z in parenthesis is just a hint to remind the user that they 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. Shy little thing. 🦋

🔊 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 they may have already set the volume to a desired level, the playback starts at the player's default level. Annoying? Lowkey yes. 😭

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

🎧 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 that will be saved is in a file called vlc.conf and resides within the data directory, inside pyradio's configuration folder. Cute little file, doing its thing. 🎀

🧺 BUFFERING 🧺

When a station is slow (or the internet connection is slow), one might get to a situation where the connection timeout will run out before the connection with the station can be established. Even worse, pyradio will connect to the station, but the sound will be choppy and crackling. Absolutely not the vibe. 💀

The solution is to use a large enough buffer to connect to the station; this will effectively make pyradio connect to the station and start receiving data, but will not start playback until the buffer is full.

All pyradio supported players support buffering, using a number of command line parameters to actually set it up. pyradio will remove all this complexity by making it as simple as inserting a single value into the "Buffering" window (screenshot in the docs: pyradio-buffering-win.jpg).

The window opens by pressing \B while in the Main mode.

It will display the current buffer size (0 means no buffering), and will permit adjusting it, or using the previously used value (pressing r).

In any case, one can enable or disable the use of buffering by pressing \b (using either the default value or the one set in the "Buffering" window).

🛠️ Parameters used

The following list shows the command line parameters used by pyradio when the "Buffering" window is used to set up buffering.

  • mpv (X in seconds)
    • --demuxer-readahead-secs=X-1
    • --demuxer-cache-wait=yes
    • --cache=yes
    • --cache-secs=X
    • --cache-on-disk=yes/no *
      • * disabled if more than 500KB of memory is free
  • mplayer (X in KBytes)
    • -cache X
    • -cache-min 80
  • vlc (X in seconds)
    • --network-cachin X * 1000

🎀 Customizing the buffering behaviour

In case one wants to use a different set of parameters (when using mpv or mplayer, but not vlc), one would just not use the integrated solution; one would just use a profile.

Please refer to the players' documentation on profiles and the "Player default volume level" section in this man page.

As long as the word cache is contained in the profile's name, pyradio will understand this is a buffering profile and act accordingly. But it's up to the user to make sure this presupposition is honored. No cap, that part is on you bestie. 🫶

👑 How it works

When buffering is enabled, and a connection to a station initializes, pyradio will display a [B] at the top left corner of the window, and display Buffering: and the name of the station in the status bar, until it gets a token that the buffering has stopped.

Screenshot in the docs: pyradio-b.jpg — an example is shown there.

Now, this behaviour depends on the station, and the data it sends (or does not send) while it is buffering. For example, an ICY title may be received while buffering, which will be displayed in the status bar.

It should be noted that no volume adjustment can be performed while buffering. Like, the volume slider is just not taking calls right now. 😭

🕵️‍♀️ 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. Main character data honestly. ⭐

Now, not all stations send the whole set of data; most send their name, website, genre and bitrate, 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 be seen at pyradio-station-info.jpg in the docs). 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). Mystery solved, Nancy Drew ate. 🔥

💖 Copying And Pasting - Registers 💖

okay so 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, bestie.

There are 36 named registers (a-z, 0-9) and one unnamed register.

🎀 Named registers 🎀

  • a-z, 0-9 — these 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. That last bit means 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, you’d rename it to a normal playlist file.

🦋 The unnamed register 🦋

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, press y and:

  • one of a-z, 0-9 — add it to the corresponding named register. The unnamed register is also populated.
  • ENTER — add it to the unnamed register.

To open a named register, press ' (single quote) and:

  • one of a-z, 0-9 — open the corresponding register.
  • ' (single quote) — open the Registers window, so that a register can be selected.

To rename a named register, press \r either in the Registers window or while editing the register.

To clear a named register, press \c either in the Registers window or while editing the register.

To clear all registers, 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, press:

  • p while editing a playlist or register.
  • \p while editing a playlist or register. This opens the Paste selection window.
  • \p in the Playlist Selection or the Registers window.

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

🎨 Pyradio Themes 🎨

pyradio comes with 6 preconfigured (hard coded) themes:

  • dark (8 color theme) — This is the appearance pyradio has always had. Enabled by default.
  • light (8 color theme) — A theme for light terminal background settings.
  • dark_16_colors (16 color theme) — dark theme alternative.
  • light_16_colors (16 color theme) — light theme alternative.
  • white_on_black or wob (256 color b&w theme) — A theme for dark terminal background settings.
  • black_on_white or bow (256 color b&w theme) — A theme for light terminal background settings.

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:

  • A [T] means that the Use transparency option is enabled.
  • A [F] means that the Force transparency option is enabled.
  • A [TF] means that both options are enabled.
Note the options indication will not be visible when the window is opened within pyradio’s Configuration Window.

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

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 🌈

It is also possible to change the Main Window border color. This is a feature that has been requested and implemented, but not used by default.

To provide an alternative border color, one would just add the following to a theme file:

# Border color for the Main Window
# (background color will come from Stations)
Border              #69a9a7
Note This color will be used only when the terminal supports more than 16 colors. This is because pyradio already uses colors 0-15, and this border color will be declared as color No 16.

🧚 Virtual terminal restrictions 🧚

After introducing CSS color themes, it has come to my attention that pyradio will not display colors correctly when executed within specific terminals, konsole, yakuake, deepin-teminal, qterminal and terminology, just to name a few.

Now, I do not know whether this is because of the terminals themselves, python curses implementation or whatever, but that’s that.

pyradio will try to detect these terminals and disable themes (after displaying a relative message). Then the default theme will be used.

Some of the terminals that work ok, are: gnome-terminal, mate-terminal, xfce4-terminal, lxterminal, terminator, termite, kitty, alacritty, sakura, roxterm, tilix, lilyterm, st, xst, rxvt, urxvt, uxterm, xterm.

If you want to make pyradio start in one of these terminal, just follow the instructions given at Desktop File: Specifying the terminal to use.

💀 CSS color themes restrictions 💀

Using CSS colors imposes a couple of restrictions on the type of terminals pyradio will be able to run:

  1. The TERM variable must be set (Linux and MacOs only). pyradio will set it to "xterm-256color" if not set. Furthermore, if TERM is set to anything like "xterm*", "screen*" or "tmux*", pyradio will set it to "xterm-256color" as well.
  2. Terminals that do not support at least 16 colors will not be able to display any of the new themes. The same goes for terminals that do not support changing their colors (through the curses library). These terminals will default to either the "dark" or the "light" theme (determined by the configuration parameter console_theme), displaying whatever colors the active palette dictates.
  3. There are a couple of terminals (that I know of) which will permit changing their colors but will not be able to present the changed color on the fly. This means that, in order for a theme change to take full effect, pyradio will have to be restarted.

🍓 Secondary windows background 🍓

Secondary windows (such as messages, questions, the Theme Selection window, the Encoding Selection window, etc.) originally use the same background color as the Main window.

It is now possible to use a different background color for these windows, to get better visual result.

There are two ways to do that:

  1. Defined in a theme
  2. Using a calculated color

🎀 Theme defined secondary windows color 🎀

Themes have the following entry:

# Message window border foreground and background.
# The background color can be left unset.
# Please refer to the following link for more info
# https://github.com/coderholic/pyradio#secondary-windows-
# background
#
Messages Border     #a3b367

It's also possible to define a background color too, like this:

Messages Border     #a3b367 #F5DBDE

When you do that, this color becomes the Secondary Windows background color. 💅

You can technically use literally any color here, but for the best visual result it's highly recommended you follow these guidelines:

  1. The color should be 1–20% lighter or darker than the "Stations Background" color setting of your theme. 🎨

You can use this page http://www.workwithcolor.com/hsl-color-picker-01.htm (or one like it) to drop in the base color and then adjust the L component until it's cute. A terminal alternative is pastel (https://github.com/sharkdp/pastel), which you can use like this:

pastel color '#fbf1f2'         # show color info
pastel lighten .1 '#fbf1f2'    # color lightened by 10%
pastel darken .1 '#fbf1f2'     # color darkened by 10%
  1. If the Stations Background color is dark, make a lighter version of it. If it's light, make a darker version. 🌗

Ngl though, this is just a recommendation — honestly just grab a color that combines well with the existing ones (border foreground, stations foreground and active station). 🫶

This info is technically about creating a new pyradio theme, but it's super important to understand how the calculated background color works. iykyk. ✨

🎀 Calculated secondary windows color 🎀

By default, pyradio uses the same background color for all windows — that's the case as long as the theme you're using doesn't define a Messages Border background color.

So if you want a Messages Border background color that's different from the Stations background color, and the selected theme doesn't define one, there's a config option for you: "Calculated color". 💖

This config option takes a value between 0 and 0.2.

  • If it's 0, no color change happens at all.
  • Otherwise, the value acts as a percentage (a factor) telling pyradio how much the luminance of the Stations background color should change to produce the new background color. 🌈

Here's how that actually works: pyradio calculates the Stations background color's perceived brightness, which tells it whether the color is dark or light. Then, depending on that, it adds or subtracts factor percent from its luminance value.

Finally, it checks whether this new color is too close to the Messages Border foreground color, and re-adjusts it as possible. 🧚

💜 Optional Calculated Color in a Theme 💜

Another way to get a different background color for secondary windows is to just provide one right in the theme file itself. Like so:

# Luminance Color Factor
# The factor to lighten or darken Stations background
# color, to get a calculated color used as background
# for secondary windows
# Valid values: 0 - 0.2
Color Factor        0.05

In this case, the value you provide (i.e. 0.05) gets used exactly the same way as the config option "Calculated color".

And fr fr, if both a theme factor value and a config factor value are provided, the value from the theme wins. 👑

Note — If the "Messages Border" theme option provides both a foreground and a background, both of the calculated values get ignored. 💀
Note — When a calculated background color is in use, pressing ~ (tilde) toggles it on and off. This setting stays valid until pyradio terminates, or until a new theme is loaded. 🔥

🦋 User themes 🦋

Bestie, you can easily make your own themes! Use CSS color names (https://www.cssportal.com/css3-color-names/) as a resource, then:

  1. Copy (and rename) one of the System Themes into the user's themes folder. This folder might not exist yet — you have to create it in the pyradio config directory (~/.config/pyradio). 🌸

To get access to the System Themes, run these commands:

cd `python -c 'import site; print(site.getusersitepackages())'`
cd pyradio/themes

(you may have to use python2 or python3 instead of plain python, depending on your OS and distribution).

  1. Customize it however you want. 🎨
  2. Load it from the Theme selection window — it'll show up under "User Themes". ✨

🌈 Converting old themes 🌈

An old theme (the old format, bestie) can be easily converted to the new format using the script found at this gist (https://gist.github.com/s-n-g/65aa6ae12e135481bf3a503ece4e92d2).

Note: To get the color that was actually intended, you must use the same palette that was used when the original theme was created. 🙈

💅 Using Transparency 💅

For pyradio, transparency means a theme's background actually disappears, effectively making it display whatever is on the terminal (color / picture / transparency). The visual result depends on your terminal settings and whether a compositor is running. ✨

Not every theme looks good with transparency ON, so themes can now declare whether they want to use transparency or not. This is the transparency variable of the theme, and it can have these values:

  • 0 — means the theme will be opaque (no transparency).
  • 1 — means the theme will be transparent.
  • 2 — 2 means the theme looks good either way (the default), and the global transparency setting value (defined in the pyradio config file) will be used. 🦋

Heads up: this behavior changed since v. 0.9.2.7 — theme transparency will always be honored, regardless of the global config value. 😭

Which means: a theme set to be transparent (by its creator) will always be transparent, no matter if global transparency is on or off. Same energy the other way — if a theme is set to be opaque, it stays opaque regardless of the global transparency value.

The only time global transparency comes into play is when the theme doesn't care about it (theme transparency set to 2 – Obey config setting). 👑

Since v. 0.9.2.14, you can also force the use of the Transparency setting — that's the "Force Transparency" configuration option. When enabled, it effectively makes all themes behave as if their transparency setting was set to 2 (Obey config setting). 🔥

⭐ Updating themes automatically ⭐

Terminal users have been using all kinds of software to change / update / adapt their terminal colors and palettes, like ibASE16 (https://github.com/chriskempson/base16), pywal (https://github.com/dylanaraps/pywal), wpgtk (https://github.com/deviantfero/wpgtk), theme.sh (https://github.com/lemnos/theme.sh), just to name a few. 💖

pyradio can now "watch" a given theme for changes and update its colors whenever the theme changes. 👀

To set a theme up for auto update, just open the Theme Selection window, navigate to a theme under User Themes and press c. To create a user theme, follow the procedure in section User themes. 🎀

Consequently, the default theme name will be preceded by:

  • * — if the theme is the default one (the way it's always been).
  • - — if the theme is the default one, and pyradio will watch it for changes. ✨

🧚 Using Project Themes 🧚

pyradio can use (and watch) the output of certain projects that modify terminal colors. 🌈

pyradio will detect these projects (programs installed and initialized) and add them under the Ext. Themes Projects section of the Themes Selection Window. 👑

If loading any of these themes fails, the default dark theme will be loaded — but unlike a local theme being invalid, the selection will persist (so the theme gets loaded whenever it becomes available). 💜

Currently, these are the supported projects:

  1. base16

Thanks to the wonderful work by user edunfelt (https://github.com/edunfelt), there's now a pyradio base16 (https://github.com/base16-project) template in place, and themes have been produced based on the project (there are more than 900 themes available). 🤯

This implementation adds four entries in the theme selection menu (with alternative and variant forms of the main theme).

Then any of those themes can either be activated or watched — in which case pyradio will download and apply the corresponding theme. 🔥

Using the themes without base16

In case you want to use any of these themes but not install or use base16 (https://github.com/base16-project), you can grab them from this repo (https://github.com/edunfelt/base16-pyradio), and use the cycle_themes.py and install_themes.py scripts to inspect and install them. 🫶

  1. pywal

When detected, two themes get added to the menu — the main one and the alternative form. ✨

Since these themes are generated on the fly as the wallpaper changes, there's no way to use them if pywal (https://github.com/dylanaraps/pywal) isn't in use. 😭

Note: If pywal themes are activated but not watched, the theme will be corrupted when the wallpaper changes, and will have to be manually reloaded. So, it’s better to just always watch these themes. 😭

3. theme.sh

When detected, four themes will be added to the menu; the main and the alternative forms (there are 400 plus themes available, which makes a stuggering number of around 1800 themes for pyradio!). 💅

Using the themes without theme.sh

In case one wants to use any of these themes, but not install or use theme.sh (https://github.com/lemnos/theme.sh), one can download this repo (https://github.com/s-n-g/theme-sh-pyradio), and use the create_themes.sh script to create the themes, and cycle_themes.py and install_themes.py scripts to inspect and install them. ✨

🖱️ MOUSE SUPPORT 🖱️

Okay so, bestie, being a console application, pyradio was never intended to work with a mouse. No cap.

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. It’s giving terminal main character energy, honestly.

Having said that, and since the question of using the mouse with pyradio has been risen, basic mouse support has been implemented; starting, stopping and muting the player, scrolling within the playlist and adjusting the player’s volume is now possible using the mouse. 🫶

All one has to do is enable mouse support in the “Config Window” (mouse support is disabled by default) and restart pyradio for the change to take effect.

Then, the mouse can be used as follows:

  • Click — Change selection.
  • Double click — Start / stop the player.
  • Middle click — Toggle player muting (does not work with all terminals).
  • Wheel — Scroll up / down.
  • Shift-Wheel — Adjust volume (does not work with all terminals).

📝 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 refference. Iconic, honestly.

The logger, which works independantly from the degub 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 documenataion, is that one “can use the maxBytes and backupCount values to allow the file to rollover at a predetermined size. When the size is about to be exceeded, the file is closed and a new file is silently opened for output. Rollover occurs whenever the current log file is nearly maxBytes in length… When backupCount is non-zero, the system will save old log files by appending the extensions ‘.1’, ‘.2’ etc., to the filename. For example, with a backupCount of 5 and a base file name of app.log, you would get app.log, app.log.1, app.log.2, up to app.log.5. The file being written to is always app.log. When this file is filled, it is closed and renamed to app.log.1, and if files app.log.1, app.log.2, etc. exist, then they are renamed to app.log.2, app.log.3 etc. respectively.”

The function can be enabled:

  1. using the -lt (--log-titles) command line parameter, 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 saved at pyradio configuration directory.

Log file sample:

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

Tagging a title

An extra functionality is made possible because of “titles’s logging”: tagging a title (something like liking a song). Obsessed with this little feature, fr fr. 💖

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

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

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

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

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

Apr 18 (Mon) 15:38 | === Logging started
Apr 18 (Mon) 15:38 | >>> Station: Folk (Folk Forward - SomaFM)
Apr 18 (Mon) 15:38 |     Lord Huron - Lullaby
Apr 18 (Mon) 15:38 |     Lord Huron - Lullaby (LIKED)
Apr 18 (Mon) 15:38 | === Logging stopped

🌐 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. Periodt. 👑

🔔 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:

  1. The playlist name, when playback starts.
  2. Song info (as provided by the radio station). That means that if the radio station does not provide any info, no notification will be issued.
  3. Connection failure messages.
  4. Player crash messages.

Configuration

Desktop Notifications are disabled by default. To enable them, go to pyradio config window and customize the “Enable notifications” option.

Available values are:

  • -1: disabled (deault)
  • 0: enabled (no repetition)
  • x: enabled and repeat every x seconds

pyradio supports notifications repetition, so that even when used with quake or yakuake and the like, you still have some info on what’s going on with it.

Notifications can be set to repeat every "x" seconds, with "x" ranging from 30 to 300 (30 seconds to 5 minutes), in 30 seconds steps.

Notification Icon

The icon that is displayed in the notification message is by default pyradio icon.

pyradio will search for this icon, named pyradio.png (or pyradio.ico on Windows) in the following locations:

  1. In the configuration directory, under data (or Help folder on Windows).
  2. In the distribution directory (under the icons folder). As a consequence, one could replace the icon found in the configuration directory (under data or Help) with a custom icon, preserving the icon name as appropriate (pyradio.png, or pyradio.ico on Windows).

If the station defines a Station Icon URL (either on a local playlist or an online service; RadioBrowser includes an icon for many stations, for example), pyradio will used this one instead, provided that it is of JPG or PNG format.

On Linux

On Linux (and the BSDs), pyradio uses the notification daemon that’s already present and whatever command line helper program it provides to send notifications to the daemon.

By default, pyradio uses the following command to issue notifications:

notify-send -i ICON TITLE MSG

This command will:

  • display the title "TITLE" and message "MSG".
  • display an icon (-i).

The "ICON", "TITLE" and "MSG" tokens are just placeholders; pyradio will replace them with real data when issuing the notification.

If that does not work for you, or you want to customize the output, this is what to do:

  1. put together a valid command that can be executed on a terminal and produce the desired notification.
  2. create a file called notification in pyradio configuration directory.
  3. write the above command in that file and put each field in a different line.

Example

I have this custom command:

notify-send -i ICON -t 6000 TITLE MSG

The file I wrote is ~/.config/pyradio/notification:

notify-send
-i
ICON
-t
6000
TITLE
MSG

On MacOS

MacOS Maverick (and later) provides a scripting service to issue notifications from the command line.

The command pyradio uses is:

osascript -e 'display notification "MSG" with title "TITLE"'

If that does not work for you, or you want to display the icon as well, just install terminal-notifier:

brew install terminal-notifier

After it is installed, write the following in ~/.config/pyradio/notification:

terminal-notifier
-message
MSG
-title
TITLE
-appIcon
ICON

and you are done! 🎀

🖥️ Desktop File 🖥️

okay so pyradio will install a Desktop File under ~/.local/share/applications. iconic behavior, honestly.

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. main character energy fr fr 💅

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. the way that’s actually thoughtful 😭

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:

pyraio --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 2"

This command will use no specific terminal and will pass the -p 2 (play station No 2 automatically) parameter to pyradio. To pass such a parameter, substitute all hyphens with underscores. lowkey a little spell, but it slays ✨

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

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. ngl, that’s the vibe: you can play, but the config file is not taking notes 💀

🔓 Session unlocking 🔓

If for any reason pyradio always starts in locked mode, one can unlock the session, using the --unlock command line parameter. bestie, that’s your escape hatch 🫶

🔔 Update Notification 🔔

pyradio will periodically (once every 10 days) check whether a new version has been released. lowkey attentive 👑

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

🧹 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. no cap, it’s giving self-cleaning icon ✨

🐞 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. meticulous queen 💅

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. fr fr, it helps so much.

🐛 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. don’t be shy, bestie 💖

In your report you should, at the very least, state your pyradio version, python version and method of installation (built from source, AUR, snap, whatever). the details matter, okay?

It would be really useful to include ~/pyradio.log in your report. literally the receipts.

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. slay the bug report process 🐛🔥

🫶 Acknowlegement 🫶

pyradio uses code from the following projects:

  1. CJKwrap (https://gitlab.com/fgallaire/cjkwrap) by Florent Gallaire — A library for wrapping and filling UTF-8 CJK text.
  2. ranger (https://ranger.github.io/) — A console file manager with VI key bindings.
  3. Vifm (https://vifm.info/) — A file manager with curses interface, which provides a Vi[m]-like environment.

not me being obsessed with the collaboration timeline 😭💜

📁 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 files may be installed in /usr/local/share/doc/pyradio, depending on whether or not SIP is enabled.

👑 Authors 👑

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

the whole squad ate 💅👑

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

genuinely iconic contributions, no notes 🎀

🔎 See also 🔎

💖 That’s the whole page, bestie! Source/version: pyradio · date: June 2024 · manual: pyradio(1) ✨📻

📦 where this page comes from