-
Notifications
You must be signed in to change notification settings - Fork 127
/
Copy pathpyradio_rb.1
363 lines (224 loc) · 16.2 KB
/
pyradio_rb.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
.\" Copyright (C) 2018-2025 Spiros Georgaras <[email protected]>
.\" This manual is freely distributable under the terms of the GPL.
.\"
.TH pyradio_rb 1 "June 2024" pyradio
.SH Name
.PP
pyradio \- a curses Internet radio player.
.SH PyRadio\ RadioBrowser\ Implementation
\fBRadioBrowser\fR "is a community driven effort (like wikipedia) with the aim of collecting as many internet radio and TV stations as possible".
\fBPyRadio\fR uses the API provided to integrate it and provide its users the possibility to enjoy this great project.
.IP \fBNote:\fR
As of the writing of this, the implementation is complete, but the service's configuration is not.
.IP \fBOpening\ RadioBrowser
To open \fBRadioBrowser\fR one would just press "\fIO\fR" at the program's main window. Since at this point this is the only service supported, the service will be activated.
Upon activation, the \fBdefault query\fR will be preformed and (if successful) its results will be presented to the user. If unsuccessful, a relevant message will be displayed and the program will return to the local playlist that was previously opened.
By default, \fBPyRadio\fR will load the first 100 most voted stations on \fBRadioBrowser\fR.
.IP \fBClosing\ RadioBrowser
\fBPyRadio\fR treats the service as a special kind of a playlist, thus to close the service it is enough to "\fIgo back to playlist history\fR", pressing "\fI\\\\\fR", in addition to the normal way ("\fIq\fR" or "\fIEscape\fR").
.IP \fBHow\ it\ works
The implementation uses a list structure (we'll call it \fBsearch history\fR from now on) to keep user specified queries (we'll call them \fIsearch terms\fR).
The first item in the \fBsearch history\fR is the \fIempty search term\fR (or \fIempty item\fR), which cannot be deleted and cannot be used to actually query \fBRadioBrowser\fR; it is there to provide a \fIsearch term template\fR for user inserted search terms.
Upon activation, the \fIdefault search term\fR is used to automatically query a randomly selected \fBRadioBrowser\fR server and display stations' results.
Once the results are fetched, they act as a special kind of playlist (some of the features of a local playlist are not functional, such as station renaming and such), and other features are introduced (such as the sort function and the station database info function).
Each search result, i.e. each station, has more data attached to it than just its name and URL (bitrate, votes, clicks, etc.). This data is displayed in field columns; the number of visible columns depend on the terminal of the window. The name of the column that matches the sorting criteria is "highlighted".
.RS
.IP \fBSearching\ in\ the\ list\ of\ stations
The normal local playlist search function has been enhanced in order to be able to search through the list of stations, since each station has a lot more info attached to it.
Searching for any string will return matches in the \fIName\fR field only (just like in a local playlist), but starting the search string with a plus sign ("\fI+\fR") will produce results from all available fields (visible or not).
.IP \fBSorting\ stations
Pressing "\fIS\fR" will present the user with a sorting list. Selecting one of the items will sort the stations based on it; selecting it again will reverse sorting order.
.RE
.RS 14
.IP \fBNote:
This sorting function is different than the query sorting criterion which can be selected in the \fRSearch window\fR. This one just sorts a query result set, the one in the \fBSearch window\fR affects the actual stations that will be in the result set.
.RE
.IP \fBControls
These are the \fBRadioBrowser\fR specific keys one can use in addition to local playlist keys (if applicable).
.RS 10
.IP \fIO
Open RadioBrowser
.IP \fI{\ [\ ]
Load the first / previous / next result page. Each page will have as many stations as the max. number of results used for the request; the last page will have less than that number (which actually indicates it is the last page)
.IP \fIc
Open config window
.IP \fIC
Select server to connect to
.IP \fIs
Search for stations
.IP \fIS
Sort search results
.IP \fII
Station database info (current selection) |
.IP \fIV
Vote for station
.IP \fI\\\\\\\\\ q\ Escape
Close RadioBrowser
.RE
.IP \fBConfiguration
One can get to \fBRadioBrowser\fR's configuration in any of the following ways:
.RS 11
.IP \fI1.\fR\ From\ \fBPyRadio\ Configuration\fR,\ section\ \fBOnline\ Services\fR
.IP \fI2.\fR\ From\ within\ \fBRadioBrowser\fR\ playlist,\ by\ pressing\ "\fIc\fR"
.RE
.RS 7
The configuration window presents the following options:
.RE
.RS 11
.IP \fI1.\fR\ \fBAuto\ save\ config\fR
If True, no confirmation will be asked before saving the configuration when leaving the search window.
Default value: \fIFalse\fR
.IP \fI2.\fR\ \fBMaximum\ number\ of\ results\fR
\fBRadioBrowser\fR's database is really huge and some queries will produce too many results. This is the way to limit returned result number.
Setting this parameter to \fI-1\fR will disable result limiting.
Default value: \fI100\fR
.IP \fI3.\fR\ \fBNumber\ of\ ping\ packages
The number of ping (ICMP) packages to send to a server while checking its availability. More on \fIServer pinging\fR later in this section.
A value of 0 will disable server pinging.
Default value: \fI1\fR
.IP \fI4.\fR\ \fBPing\ timeout\ (seconds)
The number of seconds to wait for a ping command to terminate while checking a server's availability.
A value of 0 will disable server pinging.
Default value: \fI1\fR
.IP \fI5.\fR\ \fBDefault\ Server
The default server to connect to when using the service.
Default value: \fIRandom\fR
.IP \fI6.\fR\ \fBSearch\ Terms
User defined \fISearch Terms\fR displayed in a compact way.
Available actions: change the \fBdefault\fR search term and \fBdelete\fR existing search terms.
.RE
.RS 7
\fBServer pinging\fR
\fBRadioBrowser\fR provides several servers to the public (currently in Germany, France and The Netherlands) to connect to (always kept in sync with each other), in order to limit down time.
In the rare event an individual server is down, an application can just connect to any of the remaining servers to keep using the service.
\fBPyRadio\fR will use the ICMP protocol (ping) to check servers availability before even trying to query a server. The configuration parameters "\fINumber of ping packages\fR" and "\fIPing timeout (seconds)\fR" will be used to ping the servers. If any of them is set to 0, server pinging \fBwill be disabled\fR.
When opening the service, \fBPyRadio\fR will act depending upon its configured settings.
.IP \fI1.\ No\ default\ server\ is\ specified\ and\ pinging\ is\ enabled
In this case, \fBPyRadio\fR will randomly select a server, make sure it's online (ping it) and then use it to query and display results.
If no server is available or if the internet connection has failed, a message will be displayed informing the user.
.IP \fI2.\ A\ default\ server\ has\ been\ specified\ and\ pinging\ is\ enabled
\fBPyRadio\fR will ping the server and will connect to it if it's available.
If the default server is unresponsive, \fBPyRadio\fR will try to find and use one that is available.
If no server is available or if the internet connection has failed, a message will be displayed informing the user.
.IP \fI3.\ Pinging\ is\ disabled
No server availability check will occur.
If the server (default or random) is unavailable or if the internet connection has failed, a message will be displayed informing the user.
.RE
.RS 7
When using the "\fBServer Selection Window\fR" (either within the configuration window or the playlist):
.IP \fI1.\ If\ pinging\ is\ enabled
The selected server availability will be checked, and if not responsive, it will not be accepted.
.IP \fI2.\ If\ pinging\ is\ disabled
The server will be accepted regardless of its availability.
.RE
.IP \fBIn\ session\ Server\ Selection
In addition to the \fIdefault server\fR which can be set at the configuration window, one has the possibility to select a server to connect after opening the service.
Pressing "\fIC\fR" will provide a list of available servers to choose from. This selection will be honored until the service is closed.
.RE
.IP \fBStation\ Database\ Information
The database information of the selected station can be displayed by pressing "\fII\fR". Keep in mind that, this is different than the \fIStation Info\fR displayed by pressing "\fIi\fR", which is still available and presents live data.
.IP \fBStation\ clicking\ and\ voting
\fBRadioBrowser\fR provides two ways to measure a station's popularity: voting and clicking.
\fIClicking\fR a station means that the station has been listened to; \fBPyRadio\fR will send a "click request" any time the user starts playback of a station; \fBRadioBrowser\fR will either reject or accept the action, and either ignore or increase click count for the station based on several criteria (time between consecutive clicks, possibly IP, etc.)
For this reason \fBPyRadio\fR will in no case adjust the click count presented to the user.
\fIVoting\fR for a station is a different thing; the user has to choose to vote for it. In \fBPyRadio\fR a "vote request" is sent when "\fIV\fR" is pressed. If the vote has been accepted, the vote counter will be increased by one.
.RS
.IP \fBNote:
Inconsistencies between a voted for station's local vote counter value and the one reported in a consecutive server response should be expected, since it seems servers' vote counter sync may take some time to complete.
.RE
.IP \fBThe\ Search\ Window
The \fBSearch window\fR opens when "\fIs\fR" is pressed and loads the \fIsearch term\fR that was used to fetch the stations currently presented in the \fBRadioBrowser window\fR. If this is the first time this window is opened within this session, the search term that's loaded is the \fIdefault search term\fR.
.RS
.IP \fBNote
In case the server returns no results, the window will automatically reopen so that you can redefine the \fIsearch term\fR.
.PP
Navigation between the various fields is done using the "\fBTab\fR" (and "\fBShift-Tab\fR") key, the arrows and vim keys ("\fBj\fR", "\fBk\fR", "\fBh\fR" and "\fBl\fR"), provided that any given key is not already used by one of the on window "widgets".
Toggling the state of check boxes is done by pressing \fISPACE\fR. The \fBDisplay by\fR and \fBSearch for\fR check boxes are mutually exclusive (enabling one disables the other). Each of them will give access to more fields when enabled.
To perform a search (server query) one would just press \fIEnter\fR on the "\fBOK\fR" button, or "\fIs\fR" on any widget other than a \fBLine editor\fR.
This window performs two functions:
.RS 5
.IP \fI1) 3
composes a search term to be forwarded to the search function and
.IP \fI2)
manages the \fBsearch history\fR.
.RE
.IP \fB1.\ Search\ term\ composition
.RS 5
.PP
The \fBSearch window\fR can be divided in four parts:
.IP \fI1.\fR\ The\ \fBDisplay\fR\ part
In this part one would select to fetch a list of stations based on a single criterion such as their vote count, click count, etc.
.IP \fI2.\fR\ The\ \fBSearch\fR\ part
In this part, the user would insert a search string to one or more of the available fields.
Each of the fields has an \fIExact\fR checkbox. If checked, an exact match will be returned, hopefully.
In the \fICountry\fR field one could either provide the name of a country or its two-letter code (based on [ISO 3166](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)). For example, to get a list of Greek stations, you would either insert \fIgreece\fR or the country code, which is \fIgr\fR.
These two parts are mutually exclusive, since when one is activated through its corresponding checkbox, the other one gets disabled.
.IP \fI3.\fR\ The\ \fBSort\fR\ part
This part affects both previous parts.
It provides the server with the sorting criteria upon which the results will be returned.
.IP \fI4.\fR\ The\ \fBLimit\fR
In this part the maximum number or returned stations is specified. The default value is 100 stations (0 means no limit).
The value can be changed using the left and right arrows or "\fIh\fR", "\fIl\fR" and "\fIPgUp\fR", "\fIPgDn\fR" for a step of 10.
.RE
.IP \fB2.\ History\ Management
.RS 5
At the bottom of the \fBSearch window\fR you have the \fIhistory information\fR section; on the left the number of history items is displayed along with the number of the current history item (\fIsearch term\fR) and on the right there's the history help legend.
The keys to manage the history are all \fBControl\fR combinations:
.IP \fI^N\fR\ \fI^P\fR 5
Move to next / previous \fIsearch term\fR definition.
.IP \fIHOME\fR\ or\ \fI0\fR
Move to the \fIempty search term\fR (history item 0), the \fItemplate item\fR. This is a quick way to "reset" all settings and start new. Of course, one could just navigate to this history item using \fI^N\fR or \fI^P\fR, but it's here just for convenience.
Pressing \fI0\fR works on all widgets; \fIHOME\fR does not work on \fBLine editors\fR.
To inster a \fI0\fR on a \fBLine editor\fR just type "\fB\\0\fR".
.IP \fIEND\fR\ or\ \fIg\fR\ or\ \fI$\fR 5
Move to the last \fIsearch term\fR.
Pressing \fI$\fR works on all widgets; \fIEND\fR and \fIg\fR do not work on \fBLine editors\fR.
To inster a \fI$\fR on a \fBLine editor\fR just type "\fB\\$\fR".
.IP \fIPgUp\fR\ /\ \fIPgDown\fR
Jump up or down within the \fIsearch history\fR list. Note that these keys do not work when the \fBResult limit\fR counter field is focused.
.IP \fI^Y\fR
Add current item to history.
.IP \fI^X\fR
Delete the current history item.
There is no confirmation and once an item is deleted there's no undo function.
These rules apply:
.RS 5
.IP \fI1. 3
The first item (\fIsearch term template\fR) cannot be deleted.
.IP \fI2. 3
When the history contains only two items (the \fIsearch term template\fR will always be the first one; the second one is a user defined \fIsearch term\fR), no item deletion is possible.
.IP \fI3. 3
When the \fIdefault search term\fR is deleted, the first user defined \fIsearch term\fR becomes the default one.
.RE
.IP \fI^B\fR
Make the current history item the \fIdefault\fR one for \fBRadioBrowser\fR and save the history.
This means that, next time you open \fBRadioBrowser\fR this history item (\fIsearch term\fR) will be automatically loaded.
.IP \fI^E\fR
Save the history.
.RE
.RS 5
.IP \fBNote\fR
All keys can also be used without pressing the Control key, provided that a line editor does not have the focus. For example, pressing "\fIx\fR" is the same as pressing "\fI^X\fR", "\fIe\fR" is the same as "\fI^E\fR" and so on. This feature is provided for tiling window manager users who may have already assigned actions to any of these Contol-key combinations.
.P
All history navigation actions (\fI^N\fR, \fI^P\fR, \fIHOME\fR, \fIEND\fR, \fIPgUp\fR, \fIPgDown\fR) will check if the data currently in the "form" fields can create a new \fBsearch term\fR and if so, will add it to the history.
The \fBSearch Window\fR actually works on a copy of the \fIsearch history\fR used by the service itself, so any changes made in it (adding and deleting items) are not passed to the service, until "\fIOK\fR" is pressed (or "\fIs\fR" is typed on any field other than a \fBLine editor\fR). Pressing "\fICancel\fR" will make all the changes go away.
Even when "\fIOK\fR" is pressed (or "\fIs\fR" is typed on any field other than a \fBLine editor\fR), and the \fBSearch Window\fR is closed, the "new" history is loaded into the service, but \fBNOT\fR saved to the \fIconfiguration file\fR.
To really save the "new" history, press "\fI^E\fR" in the \fBSearch Window\fR (or type "\fIe\fR" on any field other than a \fBLine editor\fR), or press "\fIy\fR" in the confirmation window upon exiting the service.
.RE
.SH Reporting Bugs
.PP
When a bug is found, please do report it by opening an issue at github at \<\fIhttps://github.com/coderholic/pyradio/issues\fR\>, as already stated above.
In you report you should, at the very least, state your \fIpyradio version\fR, \fIpython version\fR and \fImethod of installation\fR (built from source, AUR, snap, whatever).
It would be really useful to include \fB~/pyradio.log\fR in your report.
To create it, enter the following commands in a terminal:
.HP
\fI$\fR \fBrm ~/pyradio.log\fR
.br
\fI$\fR \fBpyradio -d\fR
.PP
Then try to reproduce the bug and exit pyradio.
Finally, include the file produced in your report.
.SH Files
\fI~/.config/pyradio/radio-browser.config\fR
.SH See also
pyradio(1)