Skip to content

Commit 1068214

Browse files
s-n-gs-n-g
committed
- version 0.9.3.11.8 - 0.9.3.12-beta8
- adding bufferring.md and pyradio_buf man page - updating docs - updating Windows MPV download link
1 parent 77d7a99 commit 1068214

12 files changed

+475
-252
lines changed

‎Changelog

+13
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,16 @@
1+
2025-03-19 s-n-g
2+
* version 0.9.3.11.8 - 0.9.3.12-beta8
3+
* fixing #281 - Favourite list becomes corrupted after adding station
4+
* adding buffering config parameters: buffering and mplayer_save_br
5+
* pressing \b will toggle global buffering for the session
6+
* the Buffering Window will change station buffering value instead of config
7+
* station volume will be saved (\v by default) and the playlist will
8+
be silently saved - station volume will work for VLC only
9+
* saveCurrentPlaylist: trailling commas will be eliminated
10+
* updating Windows MPV download link
11+
* adding bufferring.md and pyradio_buf man page
12+
* updating docs
13+
114
2025-03-13 s-n-g
215
* version 0.9.3.11.7 - 0.9.3.12-beta7
316
* fixing #280 - Removing station and saving removes

‎devel/pre-commit

+10-1
Original file line numberDiff line numberDiff line change
@@ -156,7 +156,8 @@ for afile in index.md \
156156
themes.md \
157157
headless.md \
158158
client.md \
159-
rec-dir.md
159+
rec-dir.md \
160+
buffering.md
160161
do
161162
sed -i -e "s/'s-/s-/g" -e "s/s'-/s-/g" "$afile"
162163
git add "$afile"
@@ -199,6 +200,8 @@ do
199200
echo '% PyRadio Headless Operation' > tmp.md
200201
elif [ "$afile" = "rec-dir.md" ];then
201202
echo '% PyRadio Recordings Directory' > tmp.md
203+
elif [ "$afile" = "buffering.md" ];then
204+
echo '% PyRadio Buffering' > tmp.md
202205
fi
203206
cat ${afile} >> tmp.md
204207
pandoc --wrap=none -s -t html tmp.md -o ${out} || {
@@ -312,6 +315,12 @@ do
312315
"$out"
313316
fi
314317

318+
if [ "$out" = "buffering.html" ];then
319+
sed -i -e '/pyradio-buffering-win.jpg/s/src=/style="width: 280px" src=/' \
320+
-e '/pyradio-b\.jpg/s/src=/style="width: 450px" src=/' \
321+
"$out"
322+
fi
323+
315324
sed -i '/^<[Aa]/s|.*|<p>&</p>|' "$out"
316325
git add ${out}
317326
done

‎docs/buffering.html

+135
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
<!DOCTYPE html>
2+
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
3+
<head>
4+
<meta charset="utf-8" />
5+
<meta name="generator" content="pandoc" />
6+
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
7+
<title>PyRadio Buffering</title>
8+
<style>
9+
body {padding: 2em;}
10+
@media screen and (max-width: 770px) {
11+
body {padding: 10px;}
12+
}
13+
body {max-width: 750px; margin: auto;}
14+
h2 {margin-top: 2.5em; border-bottom:1px solid SaddleBrown; color: SaddleBrown;}
15+
h3 {margin-top: 2em; color: SaddleBrown; text-decoration: underline SaddleBrown}
16+
h4 {margin: 2em 0 1em 0; color: SaddleBrown; font-size: 1em;}
17+
h4:before {content: "# "; font-weight: bold; vertical-align: middle;}
18+
h5 {margin: 2em 0 1em 0; color: SaddleBrown; font-size: 1em;;}
19+
h5:before {content: "## "; font-weight: bold; vertical-align: middle;}
20+
p, table, ol, ul {margin-left: .8em;}
21+
STRONG {color: SaddleBrown;}
22+
dl {margin: 2em;}
23+
dd {margin: 1em;}
24+
dt {font-weight: bold;}
25+
TABLE {border: 1px solid SaddleBrown; border-collapse: collapse; margin-left: auto; margin-right: auto; border-radius: 5px; -moz-border-radius: 5px; border-collapse:separate; box-shadow: 5px 5px 15px #888888;}
26+
TH {text-align: left; vertical-align: top; padding: 5px;color: SaddleBrown;border: 1px solid SaddleBrown; background-color: SaddleBrown; color: white;}
27+
TD {text-align: left; vertical-align: top; padding: 5px 10px;border: 1px solid SaddleBrown;}
28+
pre { background-color: rgba(245, 245, 245, 1); color: #474747; padding: 1.5em; border: 1px solid #C7C7C7; border-radius: 5px; -moz-border-radius: 5px; -webkit-border-radius: 5px; overflow: auto; box-shadow: 5px 5px 15px #C7C7C7;}
29+
.task-list {list-style-type: none; padding: 0; margin: 0 0 0 1em ;}
30+
img{display: block; margin-left: auto; margin-right: auto; max-width: 750px; width: 100%; background:transparent; padding:3px; border:1px solid #999999; border-radius: 5px; -moz-border-radius: 5px; -webkit-border-radius: 5px; box-shadow:5px 5px 15px #888888;}
31+
.indented {text-indent: -1.5em; padding-left: 1.5em; margin-left: 1em;}
32+
a{ color: SaddleBrown;}
33+
a:visited{color: SaddleBrown;}
34+
</style>
35+
</head>
36+
<body>
37+
<header id="title-block-header">
38+
</header>
39+
<h1 style="color: SaddleBrown" id="pyradio-buffering">PyRadio Buffering</h1>
40+
<p>Command line internet radio player.</p>
41+
<h2 id="table-of-contents">Table of Contents <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></span></h2>
42+
<!-- vim-markdown-toc Marked -->
43+
<ul>
44+
<li><a href="#introduction">Introduction</a></li>
45+
<li><a href="#how-it-all-works">How it all works</a>
46+
<ul>
47+
<li><a href="#mplayer-buffering">MPlayer buffering</a></li>
48+
</ul></li>
49+
<li><a href="#parameters-used">Parameters used</a></li>
50+
<li><a href="#user-experience">User experience</a></li>
51+
</ul>
52+
<!-- vim-markdown-toc -->
53+
<p class="indented">[ <a href="index.html#buffering">Return to main doc</a> ]</p>
54+
<h2 id="introduction">Introduction <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></span></h2>
55+
<p>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, <strong>PyRadio</strong> will connect to the station, but the sound will be choppy and crackling.</p>
56+
<p>The solution is to use a large enough <strong>buffer</strong> to connect to the station; this will effectively make <strong>PyRadio</strong> connect to the station and start receiving data, but will not start playback until the buffer is full.</p>
57+
<p>All <strong>PyRadio</strong> supported players support buffering, using a number of command line parameters to actually set it up. <strong>PyRadio</strong> will remove all this complexity by making is as simple as inserting a single value to the <strong>Configuration Window</strong>.</p>
58+
<p>In addition to that, or instead of that, one can set up a buffering value for any individual station using the “<em>Buffering</em>” window, shown below.</p>
59+
<p><a href="https://members.hellug.gr/sng/pyradio/pyradio-buffering-win.jpg" target="_blank"><img style="width: 280px" src="https://members.hellug.gr/sng/pyradio/pyradio-buffering-win.jpg" alt="PyRadio Buffering Window" /></a></p>
60+
61+
<p>The window opens by pressing “<strong>\B</strong>” while in the <strong>Main</strong> mode.</p>
62+
<p>It will display the current station’s buffer size (0 means no buffering), and will permit to adjust it, or use the previously used value (pressing “<strong>r</strong>”).</p>
63+
<h2 id="how-it-all-works">How it all works <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></span></h2>
64+
<p><strong>PyRadio</strong> has both a configuration parameter and a station parameter that will be taken into account when trying to determine if a station will use buffering or not.</p>
65+
<ol type="1">
66+
<li><p>The global <em>buffering value</em> which will be used for all stations (if set). It can be found under the “<em>Connection Options</em>” section in the <strong>Configuration Window</strong>, parameter <strong>Buffering (seconds)</strong>.</p></li>
67+
<li><p>The <em>station buffering</em> value set using “<strong>\B</strong>” as described above.<br />
68+
If used, the station will be updated and the playlist will be silently saved.<br />
69+
<br />
70+
In this case, a string of the form “<strong>7@128</strong>” will be inserted in the appropriate field of the station definition, “<strong>7</strong>” being the buffering value in seconds and “<strong>128</strong>” the bitrate of the station, which is only relevant to <strong>MPlayer</strong>.</p></li>
71+
</ol>
72+
<p>In any case, one can enable or disable the use of buffering by pressing “<strong>\b</strong>”. This value will not be saved and will be set to True whenever a player change occurs.</p>
73+
<h3 id="mplayer-buffering">MPlayer buffering</h3>
74+
<p>Both <em>MPV</em> and <em>VLC</em> will directly use the buffering value (expressed in seconds) in order to buffer a stream.</p>
75+
<p>This is not the case with <em>MPlayer</em> unfortunately; it has to receive the number of KBytes to buffer.</p>
76+
<p>In order to do that in a consistent way, the station’s bitrate must be known beforehand, which is impossible. So, a workaround is being used: the player will trigger a station update (and a silent playlist save), if:</p>
77+
<ol type="1">
78+
<li><strong>MPlayer</strong> is installed and detected as a supported player.</li>
79+
<li>The “<strong>MPlayer auto save br</strong>” configuration parameter (under <strong>Connection Options</strong>) is set to <strong>True</strong>.</li>
80+
<li>The station streams at a bitrate different to 128 kbps (the default).</li>
81+
</ol>
82+
<p>This way, the first time <strong>MPlayer</strong> is used to buffer the station the buffering will be incorrect (shorter or longer depending on the real bitrate), but subsequent playback of the station will correctly set the number of KBytes that corresponds to the buffering time set.</p>
83+
<h2 id="parameters-used">Parameters used <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></span></h2>
84+
<p>The following table shows the command line parameters used by <strong>PyRadio</strong> when the “<em>Buffering</em>” window is used to set up buffering.</p>
85+
<table>
86+
<colgroup>
87+
<col style="width: 38%" />
88+
<col style="width: 30%" />
89+
<col style="width: 30%" />
90+
</colgroup>
91+
<thead>
92+
<tr>
93+
<th>mpv<br>(X in seconds)</th>
94+
<th>mplayer<br>(X in KBytes)</th>
95+
<th>vlc<br>(X in seconds)</th>
96+
</tr>
97+
</thead>
98+
<tbody>
99+
<tr>
100+
<td>–demuxer-readahead-secs=X-1</td>
101+
<td>-cache X</td>
102+
<td>–network-caching X*1000</td>
103+
</tr>
104+
<tr>
105+
<td>–demuxer-cache-wait=yes</td>
106+
<td>-cache-min 80</td>
107+
<td></td>
108+
</tr>
109+
<tr>
110+
<td>–cache=yes</td>
111+
<td></td>
112+
<td></td>
113+
</tr>
114+
<tr>
115+
<td>–cache-secs=X</td>
116+
<td></td>
117+
<td></td>
118+
</tr>
119+
<tr>
120+
<td>–cache-on-disk=yes/no *</td>
121+
<td></td>
122+
<td></td>
123+
</tr>
124+
</tbody>
125+
</table>
126+
<p>* disabled if more than 500KB of memory is free</p>
127+
<h2 id="user-experience">User experience <span style="padding-left: 10px;"><sup style="font-size: 50%"><a href="#" title="Go to top of the page">Top</a></sup></span></h2>
128+
<p>When buffering is enabled, and a connection to a station initializes, <strong>PyRadio</strong> will display a “<strong>[B]</strong>” at the top left corner of the window, and display “<strong>Buffering:</strong>” and the name of the station in the status bar, until it get a token that the buffering has stopped.</p>
129+
<p><a href="https://members.hellug.gr/sng/pyradio/pyradio-b.jpg" target="_blank"><img style="width: 450px" src="https://members.hellug.gr/sng/pyradio/pyradio-b.jpg" alt="PyRadio Buffering" /></a></p>
130+
131+
<p>An example is shown in the image above.</p>
132+
<p>Now, this behavior 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.</p>
133+
<p>It should be noted that, no volume adjustment can be preformed while buffering.</p>
134+
</body>
135+
</html>

‎docs/buffering.md

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# PyRadio Buffering
2+
3+
Command line internet radio player.
4+
5+
## Table of Contents
6+
<!-- vim-markdown-toc Marked -->
7+
8+
* [Introduction](#introduction)
9+
* [How it all works](#how-it-all-works)
10+
* [MPlayer buffering](#mplayer-buffering)
11+
* [Parameters used](#parameters-used)
12+
* [User experience](#user-experience)
13+
14+
<!-- vim-markdown-toc -->
15+
16+
[ [Return to main doc](index.md#buffering) ]
17+
18+
## Introduction
19+
20+
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.
21+
22+
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.
23+
24+
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 is as simple as inserting a single value to the **Configuration Window**.
25+
26+
In addition to that, or instead of that, one can set up a buffering value for any individual station using the "*Buffering*" window, shown below.
27+
28+
![PyRadio Buffering Window](https://members.hellug.gr/sng/pyradio/pyradio-buffering-win.jpg)
29+
30+
The window opens by pressing "**\\B**" while in the **Main** mode.
31+
32+
It will display the current station's buffer size (0 means no buffering), and will permit to adjust it, or use the previously used value (pressing "**r**").
33+
34+
## How it all works
35+
36+
**PyRadio** has both a configuration parameter and a station parameter that will be taken into account when trying to determine if a station will use buffering or not.
37+
38+
1. The global *buffering value* which will be used for all stations (if set). It can be found under the "*Connection Options*" section in the **Configuration Window**, parameter **Buffering (seconds)**.
39+
40+
2. The *station buffering* value set using "**\\B**" as described above. \
41+
If used, the station will be updated and the playlist will be silently saved.\
42+
\
43+
In this case, a string of the form "**7@128**" will be inserted in the appropriate field of the station definition, "**7**" being the buffering value in seconds and "**128**" the bitrate of the station, which is only relevant to **MPlayer**.
44+
45+
In any case, one can enable or disable the use of buffering by pressing "**\\b**". This value will not be saved and will be set to True whenever a player change occurs.
46+
47+
### MPlayer buffering
48+
49+
Both *MPV* and *VLC* will directly use the buffering value (expressed in seconds) in order to buffer a stream.
50+
51+
This is not the case with *MPlayer* unfortunately; it has to receive the number of KBytes to buffer.
52+
53+
In order to do that in a consistent way, the station's bitrate must be known beforehand, which is impossible. So, a workaround is being used: the player will trigger a station update (and a silent playlist save), if:
54+
55+
1. **MPlayer** is installed and detected as a supported player.
56+
2. The "**MPlayer auto save br**" configuration parameter (under **Connection Options**) is set to **True**.
57+
3. The station streams at a bitrate different to 128 kbps (the default).
58+
59+
This way, the first time **MPlayer** is used to buffer the station the buffering will be incorrect (shorter or longer depending on the real bitrate), but subsequent playback of the station will correctly set the number of KBytes that corresponds to the buffering time set.
60+
61+
## Parameters used
62+
63+
The following table shows the command line parameters used by **PyRadio** when the "*Buffering*" window is used to set up buffering.
64+
65+
| mpv<br>(X in seconds) | mplayer<br>(X in KBytes) | vlc<br>(X in seconds) |
66+
|--------------------------------|--------------------------|--------------------------|
67+
| --demuxer-readahead-secs=X-1 | -cache X | --network-caching X*1000 |
68+
| --demuxer-cache-wait=yes | -cache-min 80 | |
69+
| --cache=yes | | |
70+
| --cache-secs=X | | |
71+
| --cache-on-disk=yes/no \* | | |
72+
73+
\* disabled if more than 500KB of memory is free
74+
75+
## User experience
76+
77+
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 get a token that the buffering has stopped.
78+
79+
![PyRadio Buffering](https://members.hellug.gr/sng/pyradio/pyradio-b.jpg)
80+
81+
An example is shown in the image above.
82+
83+
Now, this behavior 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.
84+
85+
It should be noted that, no volume adjustment can be preformed while buffering.
86+

0 commit comments

Comments
 (0)