coderholic · s-n-g · Dec 5, 2018 · Nov 21, 2018 · Nov 21, 2018 · Nov 21, 2018
diff --git a/.gitignore b/.gitignore
@@ -6,3 +6,4 @@ dist
 build
 .vimrc
 *.log
+*.sh
diff --git a/Changelog b/Changelog
@@ -1,3 +1,20 @@
+2018-12-02  s-n-g
+
+	* Version 0.6.0
+	* PyRadio will not crash when no player found.
+	* PyRadio will only display station name and icy-title (if received)
+	* PyRadio version will include git revision when not on a git tag
+	  (i.e.not on a	release tag)
+	* Added '-u' option to specify player to use (or detection order)
+	* A help message can be displayed (shortcut '?' or '/')
+	* vlc will unmute on exit
+	* Volume value is displayed while changing
+	* Volume can be saved for mpv and mplayer (shortcut 'v')
+	* pyradio.log is always saved in home directory
+	* Both mpv and socat must be installed for mpv to be used as player
+	* Added man page, thanks to AUR package pyradio-git (not installed
+	  by default; it's up to the packagers to do it)
+
 2013-04-03  stac47
 
 	* Version 0.5.1

diff --git a/README.html b/README.html
@@ -0,0 +1,125 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
+<head>
+  <meta charset="utf-8" />
+  <meta name="generator" content="pandoc" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
+  <title>PyRadio README</title>
+  <style type="text/css">
+    html {margin: 2em;} 
+    h2 {margin-top: 2.5em; border-bottom:1px solid #D6D6D6;} 
+    h3 {margin-top: 2em;} 
+    dl {margin: 2em;} 
+    dd {margin: 1em;} 
+    dt {font-weight: bold;} 
+    pre { background-color: #F6F6F6; padding: 1.5em; border: 1px solid #E6E6E6;}
+      code{white-space: pre-wrap;}
+      span.smallcaps{font-variant: small-caps;}
+      span.underline{text-decoration: underline;}
+      div.column{display: inline-block; vertical-align: top; width: 50%;}
+  </style>
+  <!--[if lt IE 9]>
+    <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
+  <![endif]-->
+</head>
+<body>
+<header id="title-block-header">
+</header>
+<h1 id="pyradio">PyRadio</h1>
+<p>Command line internet radio player.</p>
+<p>Ben Dowling - <a href="https://github.com/coderholic">https://github.com/coderholic</a></p>
+<h2 id="table-of-contents">Table of contents</h2>
+<ul>
+<li><a href="#requirements">Requirements</a></li>
+<li><a href="#installation">Installation</a></li>
+<li><a href="#command-line-options">Command line options</a></li>
+<li><a href="#controls">Controls</a></li>
+<li><a href="#stations-file">Stations file</a></li>
+<li><a href="#player-detection-selection">Player detection / selection</a></li>
+<li><a href="#player-default-volume-level">Player default volume level</a></li>
+<li><a href="#debug-mode">Debug mode</a></li>
+</ul>
+<h2 id="requirements">Requirements</h2>
+<ul>
+<li>python 2.6+/3.2+</li>
+<li>MPV, MPlayer or VLC installed and in your path.</li>
+<li><a href="http://www.dest-unreach.org/socat/">socat</a> (if you wish to use MPV)</li>
+</ul>
+<h2 id="installation">Installation</h2>
+<p>The best way to install <strong>PyRadio</strong> is via a distribution package, if one exists (e.g. <em>Arch Linux</em> and derivatives can install <a href="https://aur.archlinux.org/packages/pyradio-git/">pyradio-git</a> from AUR).</p>
+<p>In any other case, and since <strong>PyRadio</strong> is currently not available via pip, you will have to <a href="build.html">build it from source</a>.</p>
+<h2 id="command-line-options">Command line options</h2>
+<pre>$ pyradio -h
+
+usage: pyradio [-h] [-s STATIONS] [-p [PLAY]] [-a] [-l] [-d] [-u USE_PLAYER]
+
+Curses based Internet radio player
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -s STATIONS, --stations STATIONS
+                        Use specified station CSV file.
+  -p [PLAY], --play [PLAY]
+                        Start and play.The value is num station or empty for
+                        random.
+  -a, --add             Add station to list.
+  -l, --list            List of added stations.
+  -d, --debug           Start pyradio in debug mode.
+  -u USE_PLAYER, --use-player USE_PLAYER
+                        Use specified player. A comma-separated list can be
+                        used to specify detection order. Supported players:
+                        mpv, mplayer, vlc.</pre>
+<h2 id="controls">Controls</h2>
+<pre>Up/Down/j/k/PgUp/PgDown   Change station selection.
+g                         Jump to first station.
+&lt;n&gt;G                      Jump to n-th / last station.
+Enter/Right/l             Play selected station.
+r                         Select and play a random station.
+Space/Left/h              Stop/start playing selected station.
+-/+ or ,/.                Change volume.
+m                         Mute.
+v                         Save volume (not applicable for vlc).
+?,/                       Show keys help.
+Esc/q                     Quit.</pre>
+<h2 id="stations-file">Stations file</h2>
+<p><strong>PyRadio</strong> reads the stations to use from a CSV file (named <em>stations.csv</em>), where each line contains two columns, the first being the station name and the second being the stream URL.</p>
+<p><strong>PyRadio</strong> will by default use the user’s configuration file (e.g. <em>~/.config/pyradio/stations.csv</em>) to read the stations. If this file is not found, it will be created and populated with a default set of stations.</p>
+<p style="margin: 1.5em 4em 0 4em; text-indent: -2em;"><strong>Tip:</strong> If you already have a custom <em>stations.csv</em> file, but want to update it with <strong>PyRadio</strong>’s default one, you just rename it, run <strong>PyRadio</strong> (so that the default one get created) and then merge the two files.</p>
+<p>A different file can be used when the <strong>-s</strong> command line option is used.</p>
+<h2 id="player-detection-selection">Player detection / selection</h2>
+<p><strong>PyRadio</strong> 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.</p>
+<p>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.</p>
+<p>MPV will be used only when the <a href="http://www.dest-unreach.org/socat/">socat</a> multipurpose relay is also installed.</p>
+<p>Users can alter this default behavior by using the <strong><em>-u</em></strong> command line option. This option will permit the user either to specify the player to use, or change the detection order.</p>
+<p>Example:</p>
+<pre>pyradio -u vlc</pre>
+<p>will instruct <strong>PyRadio</strong> to use VLC; if it is not found, the program will terminate with an error.</p>
+<pre>pyradio -u vlc,mplayer,mpv</pre>
+<p>will instruct <strong>PyRadio</strong> 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.</p>
+<h2 id="player-default-volume-level">Player default volume level</h2>
+<p>MPV and MPlayer, when started, use their saved (or default) volume level to play any multimedia content. Fortunately, this is not the case with VLC.</p>
+<p>This introduces a problem to <strong>PyRadio</strong>: 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.</p>
+<p>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.</p>
+<p>This is done by typing “<strong><em>v</em></strong>” right after setting a desired volume level.</p>
+<h3 id="mpv">MPV</h3>
+<p>MPV uses profiles to customize its behavior.</p>
+<p><strong>PyRadio</strong> defines a profile called “<strong>[pyradio]</strong>” in MPV’s configuration file (e.g. <em>~/.config/mpv/mpv.conf</em>). This profile will be used every time playback is started.</p>
+<p>Example:</p>
+<pre>volume=100
+
+[pyradio]
+volume=50</pre>
+<h3 id="mplayer">MPlayer</h3>
+<p>MPlayer uses profiles to customize its behavior as well.</p>
+<p><strong>PyRadio</strong> defines a profile called “<strong>[pyradio]</strong>” in MPV’s configuration file (e.g. <em>~/.mplayer/config</em>). This profile will be used every time playback is started.</p>
+<p>Example:</p>
+<pre>volume=100
+
+[pyradio]
+volstep=1
+volume=28</pre>
+<h2 id="debug-mode">Debug mode</h2>
+<p>Adding the <strong><em>-d</em></strong> option to the command line will instruct <strong>PyRadio</strong> to enter <em>Debug mode</em>, 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 <em>pyradio.log</em>.</p>
+<p>In case of a bug or a glitch, please include this file to the issue you will <a href="https://github.com/coderholic/pyradio/issues">open in github</a>.</p>
+</body>
+</html>
diff --git a/README.md b/README.md
@@ -2,91 +2,119 @@
 
 Command line internet radio player.
 
-Ben Dowling - [http://www.coderholic.com/pyradio](http://www.coderholic.com/pyradio)
+Ben Dowling - [https://github.com/coderholic](https://github.com/coderholic)
+
+## Table of contents
+
+* [Requirements](#requirements)
+* [Installation](#installation)
+* [Command line options](#command-line-options)
+* [Controls](#controls)
+* [Stations file](#stations-file)
+* [Player detection / selection](#player-detection-selection)
+* [Player default volume level](#player-default-volume-level)
+* [Debug mode](#debug-mode)
 
 ## Requirements
 
 * python 2.6+/3.2+
-* python-pip
-* mpv, mplayer or vlc installed and in your path.
-* socat (if you wish to use MPV)
+* MPV, MPlayer or VLC installed and in your path.
+* [socat](http://www.dest-unreach.org/socat/) (if you wish to use MPV)
 
-## Installation via pip
+## Installation 
 
-This is the simplist method for installing PyRadio.
+The best way to install **PyRadio** is via a distribution package, if one exists (e.g. *Arch Linux* and derivatives can install [pyradio-git](https://aur.archlinux.org/packages/pyradio-git/) from AUR).
 
-The first thing is to make sure MPV, MPlayer or VLC are installed and are in the
-PATH. To check this, go in your favorite terminal and make sure thiese programs
-are launched when you type "mpv", "mplayer" or "cvlc".
+In any other case, and since **PyRadio** is currently not available via pip, you will have to [build it from source](build.md).
 
-#### MacOSX
+## Command line options
 
-MPlayer is one of the available packages provided by [Homebrew](https://github.com/Homebrew/homebrew).
+```
+$ pyradio -h
+
+usage: pyradio [-h] [-s STATIONS] [-p [PLAY]] [-a] [-l] [-d] [-u USE_PLAYER]
+
+Curses based Internet radio player
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -s STATIONS, --stations STATIONS
+                        Use specified station CSV file.
+  -p [PLAY], --play [PLAY]
+                        Start and play.The value is num station or empty for
+                        random.
+  -a, --add             Add station to list.
+  -l, --list            List of added stations.
+  -d, --debug           Start pyradio in debug mode.
+  -u USE_PLAYER, --use-player USE_PLAYER
+                        Use specified player. A comma-separated list can be
+                        used to specify detection order. Supported players:
+                        mpv, mplayer, vlc.
+```
 
-But it is not the case of VLC. Nevertheless, pyradio will also work with the binary of the application [VLC](http://www.videolan.org/vlc/download-macosx.html).
+## Controls
 
-You simply can add a symbolic link to the executable as follows (this link must of course be in your PATH):
+```
+Up/Down/j/k/PgUp/PgDown   Change station selection.
+g                         Jump to first station.
+<n>G                      Jump to n-th / last station.
+Enter/Right/l             Play selected station.
+r                         Select and play a random station.
+Space/Left/h              Stop/start playing selected station.
+-/+ or ,/.                Change volume.
+m                         Mute.
+v                         Save volume (not applicable for vlc).
+?,/                       Show keys help.
+Esc/q                     Quit.
+```
 
-    ln -s /Applications/VLC.app/Contents/MacOS/VLC cvlc
+## Stations file
 
-The second step is to use pip to install the python package:
+**PyRadio** reads the stations to use from a CSV file (named *stations.csv*), where each line contains two columns, the first being the station name and the second being the stream URL.
 
-    pip install pyradio
+**PyRadio** will by default use the user's configuration file (e.g. *~/.config/pyradio/stations.csv*) to read the stations. If this file is not found, it will be created and populated with a default set of stations.
 
-#### Linux
+**Tip:** If you already have a custom *stations.csv* file, but want to update it with **PyRadio**'s default one, you just rename it, run **PyRadio** (so that the default one get created) and then merge the two files.
 
-    pip install pyradio
+A different file can be used when the **-s** command line option is used.
 
-## Building from source
+## Player detection / selection
 
-#### MaxOSX and Linux
+**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.
 
-    python setup.py build
+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.
 
-The second step is to install the build:
+MPV will be used only when the [socat](http://www.dest-unreach.org/socat/) multipurpose relay is also installed.
 
-    sudo python setup.py install
+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.
 
-## Shell commands
+Example:
 
-    $ pyradio -h
+```
+pyradio -u vlc
+```
+will instruct **PyRadio** to use VLC; if it is not found, the program will terminate with an error.
 
-    usage: main.py [--help] [--stations <path>] [--random] [--add] [--list]
+```
+pyradio -u vlc,mplayer,mpv
+```
+will instruct **PyRadio** to look for VLC, then MPlayer and finaly for MPV and use whichever it finds first; if none is found, the program will terminate with an error.
 
-    Console radio player
+## Player default volume level
 
-    optional arguments:
-    -h, --help            Show this help message and exit.
-    -s, --stations <path> Use specified station CSV file.
-    -p, --play [play]     Start and play. The value is num station or empty for random.
-    -a, --add             Add station to list.
-    -l, --list            List of added stations.
-    -u, --use-player      Specify which player to use (mpv, mplayer or cvlc).
-    -d, --debug           Debug mode (pyradio.log created).
-                          To be attached with any bug report.
+MPV and MPlayer, when started, use their saved (or default) volume level to play any multimedia content. Fortunately, this is not the case with VLC.
 
-## Controls
+This introduces a problem to **PyRadio**: every time a user plays a station (i.e restarts playback), even though he may have already set the volume to a desired level, the playback starts at the player's default level.
 
-```
-Up/Down/j/k/PgUp/PgDown Change station selection.
-Enter/Right/l           Play selected station.
--/+ or ,/.              Change volume.
-v                       Save volume (mpv and mplayer only).
-m                       Mute.
-r                       Select and play a random station.
-g                       Jump to first station.
-<n>G                    Jump to n-th station.
-Space/Left/h            Stop/start playing selected station.
-Esc/q                   Quit.
-```
+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.
 
-## Player default volume
+This is done by typing "***v***" right after setting a desired volume level.
 
-### mpv
+### MPV
 
-mpv uses profiles to customize its behavior.
+MPV uses profiles to customize its behavior.
 
-Users can define a profile called "**[pyradio]**" in mpv's configuration file (e.g. *~/.config/mpv/mpv.conf*) and pyradio will use it when playing.
+**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:
 
@@ -95,21 +123,23 @@ Example:
     [pyradio]
     volume=50
 
-### mplayer
+### MPlayer
 
-mplayer uses profiles to customize its behavior as well.
+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.
 
-Users can define a profile called "**[pyradio]**" in mplayers's configuration file (e.g. *~/.mplayer/config*) and pyradio will use it when playing.
 
 Example:
 
     volume=100
 
     [pyradio]
-    softvol=yes
     volstep=1
     volume=28
 
-### vlc
+## 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*.
 
-vlc by default saves the volume, so no customization is necessary.
+In case of a bug or a glitch, please include this file to the issue you will [open in github](https://github.com/coderholic/pyradio/issues).
-Original file line number
+Diff line change
@@ Expand Up / @@ -6,3 +6,4 @@ dist @@
     build
     .vimrc
     *.log
+    *.sh