-
Notifications
You must be signed in to change notification settings - Fork 127
/
Copy pathpyradio.1
2071 lines (1453 loc) · 82.4 KB
/
pyradio.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
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
.\" Copyright (C) 2011 Ben Dowling <http://www.coderholic.com/pyradio>
.\" Copyright (C) 2018-2024 Spiros Georgaras <[email protected]>
.\" This manual is freely distributable under the terms of the GPL.
.\"
.TH pyradio 1 "March 2025" pyradio
.SH Name
.PP
pyradio \- a curses Internet radio player.
.SH Synopsis
.PP
\fBpyradio\fR\ [\fIOPTIONS\fR]
.SH Description
.PP
.B pyradio
is a command line Internet Radio Player based on curses, that uses external media players to perform the actual playback.
.PP
It currently supports the following players: \fIMPV\fR, \fIMPlayer\fR and \fIVLC\fR.
.SH Options
.PP
\fIGeneral options:\fR
.IP\ \fB-c\fR\ \fICONFIG_DIR\fR,\ \fB--config\fR\fB-dir\fR\ \fICONFIG_DIR\fR
Use specified configuration directory instead of the
default one. PyRadio will try to create it, if it does
not exist. Not available on Windows.
.IP\ \fB-p\fR\ [\fISTATION_NUMBER\fR],\ \fB--play\fR\ [\fISTATION_NUMBER\fR]
Start and play. The value is num station or empty for
random.
.IP\ \fB-x\fR,\ \fB--external-player\fR
Play station in external player. Can be combined with \fB--play\fR.
.IP\ \fB-u\fR\ \fIPLAYER\fR,\ \fB--use\fR\fB-player\fR\ \fIPLAYER\fR
Use specified player. A comma-separated list can be
used to specify detection order. Supported players:
\fImpv\fR, \fImplayer\fR, \fIvlc\fR.
.IP\ \fB-l\fR,\ \fB--list\fR
List of available stations in a playlist.
.IP\ \fB-lt\fR,\ \fB--log\fR\fB-titles\fR
Log titles to file.
.IP\ \fB-sds\fR,\ \fB--show\fR\fB-dirs\fR
Print all the directories used by PyRadio and exit.
.IP\ \fB-sd\fR,\ \fB--show\fR\fB-config\fR\fB-dir\fR
Print config directory [\fICONFIG\fR \fIDIR\fR] location and exit.
.IP\ \fB-od\fR,\ \fB--open\fR\fB-config\fR\fB-dir\fR
Open config directory [\fICONFIG\fR \fIDIR\fR] with default file
manager.
.IP\ \fB-pc\fR,\ \fB--print-config\fR
Print PyRadio sonfig.
.IP\ \fB-d\fR,\ \fB--debug\fR
Start PyRadio in debug mode.
.IP\ \fB--d-player-input\ \fID_PLAYER_INPUT\fR
When \fB-d\fR is used, this option will not log player input (value
= \fI0\fR), log accepted input (value = \fI1\fR) or raw input
(value = \fI2\fR).
.IP\ \fB-ul\fR,\ \fB--unlock\fR
Remove sessions' lock file.
.IP\ \fB-us\fR,\ \fB--update\fR\fB-stations\fR
Update "\fIstations.csv\fR" (if needed).
.IP\ \fB-U\fR,\ \fB--update\fR
Update PyRadio.
.IP\ \fB-R\fR,\ \fB--uninstall\fR
Uninstall PyRadio.
.IP\ \fB-V\fR,\ \fB--version\fR
Display version information.
.PP
\fIPlaylist selection:\fR
.IP\ \fB-ls\fR,\ \fB--list\fR\fB-playlists\fR
List of available playlists in config dir.
.IP\ \fB-s\fR\ \fIPLAYLIST\fR,\ \fB--stations\fR\ \fIPLAYLIST\fR
Load the specified playlist instead of the default
one.
.IP\ \fB-tlp\fR,\ \fB--toggle\fR\fB-load\fR\fB-last\fR\fB-playlist\fR
Toggle autoload last opened playlist.
.PP
\fIThemes:\fR
.IP\ \fB-t\fR\ \fITHEME\fR,\ \fB--theme\fR\ \fITHEME\fR
Use specified theme.
.IP\ \fB--show\fR\fB-themes\fR
Show Internal and System Themes names.
.IP\ \fB--no\fR\fB-themes\fR
Disable themes (use default theme).
.IP\ \fB--write\fR\fB-theme\fR\ \fIIN_THEME\fR\ \fIOUT_THEME\fR,
Write an Internal or System Theme to themes directory.
.PP
\fITerminal selection:\fR
.IP\ \fB--terminal\fR\ \fITERMINAL\fR
Use this terminal for Desktop file instead of the
auto-detected one. Use "\fInone\fR" to reset to the default
terminal or "\fIauto\fR" to reset to the auto-detected one.
.IP\ \fB--terminal-param\fR\ \fI...\fR
Use this as PyRadio parameter in the Desktop File.
Please make sure that the argument is at the end of the command line,
for example: \fB--terminal-param\fR \fI"-p 3 -t
light"\fR.
.PP
\fICache:\fR
.IP\ \fB-oc\fR,\ \fB--open\fR\fB-cache\fR
Open the Cache folder.
.IP\ \fB-sc\fR,\ \fB--show\fR\fB-cache\fR
Show Cache contents.
.IP\ \fB-cc\fR,\ \fB--clear\fR\fB-cache\fR
Clear Cache contents.
.IP\ \fB-gc\fR,\ \fB--get\fR\fB-cache\fR
Download source code, keep it in the cache and exit.
.PP
\fIRecording stations:\fR
.IP\ \fB-r\fR,\ \fB--record\fR
Turn recording on (not available for \fIVLC\fR player on Windows).
.IP\ \fB-or\fR,\ \fB--open\fR\fB-recordings\fR
Open the Recordings folder.
.IP\ \fB-lr\fR,\ \fB--list\fR\fB-recordings\fR
List recorded files.
.IP\ \fB-mkv\fR\ \fIMKV_FILE\fR,\ \fB--mkv\fR\fB-file\fR\ \fIMKV_FILE\fR
Specify a previously recorded \fIMKV\fR file to be used with
one of the following options. The \fIMKV_FILE\fR can either
be an absolute or a relative path, or a number
provided by the \fB-lr\fR command line paremater. If it is a
relative path, it should be found in the current or in
the Recordings directory.
.IP\ \fB-scv\fR\ \fIPNG_FILE\fR,\ \fB--set\fR\fB-mkv\fR\fB-cover\fR\ \fIPNG_FILE\fR
Add or change the cover image of a previously recorded
\fIMKV\fR file. \fIPNG_FILE\fR can either be an absolute or a
relative path. If relative, it should be found in the
current or in the Recordings directory.
.IP\ \fB-srt\fR,\ \fB--export\fR\fB-srt\fR
Export a previously recorded \fIMKV\fR file chapters to an
\fISRT\fR file. The file produced will have the name of the
input file with the "mkv" extension replaced by "srt".
.IP\ \fB-ach\fR,\ \fB--add\fR\fB-chapters\fR
Add (or replace) chapter markers to a previously
recorded \fIMKV\fR file. The chapters file will be a \fISRT\fR
file, much like the one produced by the previous
command line parameter.
.PP
\fIHeadless operation:\fR
.IP\ \fB--headless\fR\ \fIIP_AND_IPORT\fR
Start in headless mode. \fIIP_AND_IPORT\fR can be a) auto
(use \fBlocalhost\fR:\fI11111\fR), b) \fBlocalhost\fR:\fIXXXXX\fR (access the
web server through localhost), c) \fBlan\fR:\fIXXXXX\fR (access
the web server through the \fILAN\fR) or d) \fBIP_ADDRESS\fR:\fIXXXX\fR
(the \fBIP_ADDRESS\fR must be already assigned to one of the
network interfaces). \fIXXXXX\fR can be any port number
above 1025. Please make sure it is different than the
one set in the configuration file.
.IP\ \fB--address\fR
Show remote control server address.
.IP\ \fB-fd\fR,\ \fB--free\fR\fB-dead\fR\fB-headless\fR\fB-server\fR
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).
.RE
.PP
The following options can also be set in \fBpyradio\fR’s configuration file:
.RS 5
.IP \fB-s\fR
parameter \fIdefault_playlist\fR (default value: \fBstations\fR)
.IP \fB-p\fR
parameter \fIdefault_station\fR (default value: \fB-1\fR)
.IP \fB-u\fR
parameter \fIplayer\fR (default value: \fBmpv, mplayer, vlc\fR)
.RE
.SH Controls
.IP \fBUp\fR/\fBDown\fR/\fBPgUp\fR/\fBPgDown
Change station selection
.IP \fBj\fR/\fBk
Change station selection (vi-like)
.IP \fBEnter\fR/\fBRight\fR/\fBl
Play selected station
.IP \fBr
Select and play a random station
.IP \fBSpace\fR/\fBLeft\fR/\fBh
Stop/start playing selected station
.IP \fBP\fR
Jump to playing station
.IP \fBH\ M\ L
Jump to top / middle / bottom of screen
.IP \fBg
Jump to the start of the playlist
.IP \fI<n>\fBG
Jump to the end of the playlist
.br
If \fI<n>\fR (line number) was entered, jump to it
.IP \fB-\fR/\fB+\fR\ or\ \fB,\fR/\fB.
Change volume
.IP \fBm
Mute
.IP \fBv
Save volume (\fIMPV\fR and \fIMPlayer\fR only)
.IP \fBo\ s\ R
\fBO\fIpen\fR / \fBS\fIave\fR / \fBR\fIeload\fR playlist
.IP \fBa\ A\fR
Add / append a new station
.IP \fBe\fR
Edit current station
.IP \fBE\fR
Change current station's encoding
.IP \fBDEL\fR,\fBx
Delete selected station
.IP \fBO\fR
Open \fIRadioBrowser\fR
.IP \fB<\fR\ /\ \fB>\fR
Browse the \fIStations history\fR list
.IP \fBJ
Create a \fIJump tag
.IP \fI<n>\fB^U\fR,\fI<n>\fB^D
Move current station up / down
.br
If \fI<n>\fR (line number) was entered, or a \fIJump tag\fR has been defined, move the station there
.IP \fBt
Open the \fITheme Selection\fR window
.IP \fBT
Toggle background transparency
.IP \fBc
Open the \fIConfiguration window
.IP \fB'\ \\\\\ y\fR
Get into \fIRegisters\fR, \fIExtra Commands\fR, \fIYank\fR mode, respectively
.IP \fBz\fR
Toggle "Force http connections"
.IP \fBZ\fR
Display the "Extra Player Parameters" window.
.IP \fB?
Show keys help
.IP \fBEsc\fR/\fBq
Quit
.P
The same logic applies to all \fBpyradio\fR windows.
.IP \fBNote:
When inserting numbers (either to jump to a station or to move a station), the number will be displayed at the right bottom corner of the window, suffixed by a "\fIG\fR", i.e. pressing \fI35\fR will display \fI[35G]\fR.
.IP \fBNote:
When tagging a station position for a move action (by pressing "\fBJ\fR"), the position will be displayed at the right bottom corner of the window, suffixed by a "\fIJ\fR", i.e. pressing "\fIJ\fR" on position \fI35\fR will display \fI[35J]\fR.
.IP \fBGlobal\ shortcuts\fR
Some of the functions provided by \fBpyradio\fR will always be available to the user. These functions are:
.RS 10
.IP \fB+\fR/\fB-\fR\ and\ \fB,\fR/\fB.\fR
adjust volume
.IP \fBm\fR
mute player
.IP \fBv\fR
save volume
.IP \fBT\fR
toggle transparency
.IP \fBW\fR
toggle title logging
.IP \fBw\fR
like a station
.IP \fB^N\fR\//\fB^P\fR\ [\fI1\fR]\ [\fI2\fR]
play next / previous station
.IP \fB<\fR\//\fB>\fR\ [\fI1\fR]
play next / previous station history entry
.RE
.RS 7
Every window in \fBpyradio\fR will respect these shortcuts, even the ones with a “\fIPress any key to…\fR” message.
When focus is on a \fBLine editor\fR, all shortcuts will work when preceded by a "\fI\\\fR".
\fBNotes\fR
.RS 3
.IP [\fI1\fR]
Function not available when in \fBPlaylist\fR and \fBRegisters\fR mode. More info on \fBpyradio's modes\fR below.
.IP [\fI2\fR]
Function not available in the \fBRadioBrowser\fR Search window.
.RE
.SH PyRadio's Modes
\fBpyradio\fR has the following primary modes:
.RS 5
.IP 1. 3
The \fBMain\fR mode, which is the one you get when you open the program, showing you a list of stations (a playlist), that you can play and edit; this is why it is also called the \fBediting mode\fR. All other modes derive from this one, and it's the mode you have to get to in order to terminate the program.
.IP 2. 3
The \fBPlaylist\fR mode, which you can open by pressing "\fBo\fR". Then you can open, create, paste a station, etc.
.IP 3. 3
The \fBRegisters\fR mode. This is identical to the "\fIPlaylist\fR" mode, but instead of displaying playlists, it displays register. You can enter this mode by pressing "\fB''\fR" (two single quotes) and exit from it by pressing "\fBEsc\fR" or "\fBq\fR". You can also press "\fB'\fR" (single quote) to get to the "\fIPlaylist\fR" mode and back.
.IP 4. 3
The \fBRegister Main\fR mode, which is identical to the "\fIMain\fR" mode, except it displays the content of a \fBnamed\fR register.
.IP 5. 3
The \fBListening\fR mode, which is intended to be used when you want \fBpyradio\fR to just play your favorite station and not take up too much space. It is ideal for tilling window manager use, as the whole TUI can be reduced all the way down to a single line (displaying the "\fIStatus Bar\fR"). In this mode, adjusting, muting and saving the volume are the only actions available. To get \fBpyradio\fR back to normal operation one would just resize its window to a reasonable size (7 lines vertically, or more).
.RE
A set of \fBsecondary modes\fR is also available (a secondary mode works within a primary one):
.RE
.RS 5
.IP 1. 3
The \fBExtra Commands\fR mode, which gives you access to extra commands. You can enter this mode by pressing "\fB\\\fR" (backslash). Then a backslash is displayed at the bottom right corner of the window.
.IP 2. 3
The \fBYank (Copy)\fR mode, which is used to copy stations to \fBregisters\fR. You can enter this mode by pressing "\fBy\fR". Then a "\fIy\fR" is displayed at the bottom right corner of the window.
.IP 3. 3
The \fBOpen Register\fR mode, which is used to open a register or get into the \fIRegisters\fR or \fIRegister Main\fR mode. You can enter this mode by pressing "\fB'\fR" (single quote). Then a single quote is displayed at the bottom right corner of the window.
.IP 4. 3
The \fBPaste\fR mode, which is available in the \fIStation editor\fR window only. It is designed to help the user paste a URL (and optionally a station's name). Why you might ask... Well, the \fIStation editor\fR normally treats the "\fI?\fR" and "\fI\\\fR" characters as special characters (actually commands). So, if a URL which contains these characters (more frequently the "\fI?\fR" character) is pasted it will be corrupted unless the \fBPaste\fR mode is enabled.
.RE
The functions availabe through the \fIsecondary modes\fR are content dependant, so you can see what command is available by pressing "\fB?\fR" while within such a mode. Pressing any other key will exit the secondary mode.
\fBTiling manager modes\fR
.RS 5
These modes are specifically designed to be used with tiling window managers, trying to face a rapid reduction of window height or width (or both).
.IP 1. 3
The \fBLimited Height\fR mode, which is automatically enabled when the window height gets \fIbelow 8 lines\fR.
In this mode, only a limited information is visible and if playback is on, the volume is the only thing that can be adjusted (or muted) and saved. This is the \fBLimited display\fR.
.IP 2. 3
The \fBLimited Width\fR mode, which is automatically enabled when the window width get below certain limits:
.RE
.RS 8
.IP a. 3
When the width gets \fIbelow 40 columns\fR, all windows will be closed and the main window will be the only visible one (either displaying stations, playlists or registers).
.IP b. 3
When the width gets \fIbelow 20 columns\fR, the \fBLimited display\fR will be activated.
.SH Config File
\fBpyradio\fR upon its execution will first read its package configuration file and then will try to read the user configuration file. If an error occurs while parsing it, an error message will be displayed and \fBpyradio\fR will terminate.
\fBThe package config file\fR
.RS
The \fIpackage\fR configuration file contains the program’s \fBdefault\fR parameters. These are the player to use, the playlist to load etc.
It is heavily commented, so that it can be used as a template in order to manual create the user configuration file.
One can also get the configuration file with the \fIactive parameter values\fR (i.e. after changed by the user config file), by executing the command:
.RS
\fIpyradio -pc\fR
.RE
.RE
\fBThe user config file\fR
.RS
This file (typically \fI~/.config/pyradio/config\fR) is created by \fBpyradio\fR when needed.
It will contain only the parameters whose value is different to the one set in the \fIpackage\fR configuration file.
One can easily edit it manually, though. The best practice to do so is by executing \fBpyradio\fR with the \fI-ocd\fR command line option, which will open the configuration directory in your file manager, and then edit (or create it) it using your preferable text editor. Don’t forget you can get the list of parameters by executing \fIpyradio -pc\fR.
The file can also be altered while \fBpyradio\fR is running by pressing “\fIc\fR”, which will open the “\fIConfiguration window\fR”. This window presents all \fBpyradio\fR options and provide the way to change them and finally save them by pressing “\fIs\fR”.
In any case, \fBpyradio\fR will save the file before exiting (or in case Ctrl-C is pressed) if needed (e.g. if a config parameter has been changed during its execution).
If saving the configuration file fails, \fBpyradio\fR will create a back up file and terminate. When restarted, \fBpyradio\fR will try to restore previously used settings from the said back up file.
.RE
.SH About Playlist Files
.PP
\fBpyradio\fR reads the stations to use from a CSV file, where each line contains two columns, the first being the \fBstation name\fR and the second being the \fBstream URL\fR.
.PP
Optionally, a number of more columns can be used.
.IP - 3
The third column will define the \fBEncoding\fR used by the station (more on this at \fISpecifying stations' encoding\fR).
.IP - 3
The fourth column will set an \fBIcon URL\fR, to be used when displaying \fIDesktop Notifications\fR.
.IP - 3
The fifth column is the \fBProfile\fR to be used with this station.
.IP - 3
The sixth column will determine whether \fBBuffering\fR will be used (more on this at \fIBuffering\fR).
.IP - 3
The seventh column will determine whether the station will be forced to be using \fBhttp\fR instead of https (more on this at \fIPlayer connection protocol\fR).
.IP - 3
The eighth column defines the \fBVolume\fR value to be used.
.IP - 3
The last column will define the \fBReferer\fR to be used (more on this at \fISpecifying a station's Referer URL\fR).
.PP
The following table presents the \fBStation's fields\fR and the current level of support.
.PP
.TS
center;
l l.
\fBStation field Takes Effect Customizable
in Playlist in Program
_
\fIName\fR <0.9.3.11.5 <0.9.3.11.5
\fIURL\fR <0.9.3.11.5 <0.9.3.11.5
\fIEncoding\fR <0.9.3.11.5 <0.9.3.11.5
\fIIcon\fR <0.9.3.11.5 <0.9.3.11.5
\fIProfile\fR \fBNo No\fR
\fIBuffering\fR 0.9.3.11.8 0.9.3.11.8
\fIForce HTTP\fR 0.9.3.11.6 \fBNo\fR
\fIVolume\fR \fBNo\fR for \fIMPV\fR and \fIMPlayer\fR 0.9.3.11.5
\fIReferer URL\fR <0.9.3.11.5 \fBNo\fR (\fIUsing a referer file\fR)
.TE
.PP
\fBpyradio\fR will by default load the user's stations file (e.g. \fI~/.config/pyradio/stations.csv\fR). If this file is not found, it will be created and populated with a default set of stations.
.IP \fBTip:
If you already have a custom \fIstations.csv\fR file, but want to update it with \fBpyradio\fR's default one, you just rename it, run \fBpyradio\fR (so that the default one get created) and then merge the two files.
.IP \fBNote:
Older versions used to use \fI~/.pyradio\fR as default stations file. If this file is found, it will be copied to use's config directory (e.g. \fI~/.config/pyradio\fR) and renamed to \fIstations.csv\fR or if this file exists, to \fIpyradio.csv\fR. In this case, this file will be the default one.
.PP
.B
Defining and using Groups
In order to better organize stations within a (large) playlist, \fBpyradio\fR supports \fIGroups\fR.
A \fIGroup\fR is defined as a normal "station" entry, whose URL field is a hyphen ("\fB-\fR"). For example, the following will define a \fBGroup Header\fR for a \fIGroup\fR called \fBBlues\fR.
.RS 5
\fIBlues,-\fR
.RE
A \fBGroup Header\fR entry does not define a station, and subsequently cannot stat a playback session. Other that that, it can be moved, copied, deleted, etc, just like any other playlist entry.
To add a \fBGroup Header\fR, just press "\fBa\fR", fill in the name and type a "\fB-\fR" in the \fIURL\fR field.
Navigation among \fIGroups\fR can be achieved by:
.RS 5
.IP \fB^E\fR\ /\ \fB^Y\fR
Go to next / previous \fBGroup\fR.
.IP \fB^G\fR
Display a list of existing \fBGroups\fR to select from.
.RE
.PP
.B
Integrating new stations
When the package's "\fIstations.csv\fR" files is updated, the changes it has will not automatically appear in the user's stations file.
\fBpyradio\fR will display a message asking the user to either update the file, ignore the changes for this version or postpone his decision for the next time \fBPyRadio\fR will be executed.
Either way, the user can always manually update his \fBstations file\fR, by issuing the following command:
.RS 4
\fIpyradio -us\fR
.RE
If changes have been applied, a message resembling the following will appear:
.RS 4
\fIReading config...
.br
Updating "\fBstations.csv\fI"
.br
Last updated version: \fB0.9.2\fI
.br
Last synced version: \fBNone\fI
.br
From version: \fB0.9.2\fI
.br
+/- updating: "\fBReggae Dancehall (Ragga Kings)\fI"
.br
+++ adding: "\fBGroove Salad Classic (Early 2000s Ambient)\fI"
.br
+++ adding: "\fBn5MD Radio (Ambient and Experimental)\fI"
.br
+++ adding: "\fBVaporwaves [SomaFM]\fI"
.br
+++ adding: "\fBThe Trip: [SomaFM]\fI"
.br
+++ adding: "\fBHeavyweight Reggae\fI"
.br
+++ adding: "\fBMetal Detector\fI"
.br
+++ adding: "\fBSynphaera Radio (Space Music)\fI"
.br
.br
\fBSummary\fI
.br
+++ added : \fB7\fI
.br
+/- updated : \fB1\fI
.br
--- deleted : \fB0\fI
.br
\fR
.RE
If the file is already up to date, the following message will be displayed:
.RS 4
\fIReading config...
.br
Updating "\fBstations.csv\fI"
.br
Last updated version: \fB0.9.2\fI
.br
Last synced version: \fB0.9.2\fI
.br
Already synced: "\fBstations.csv\fI"
.RE
.PP
.B
Specifying a playlist to load (command line)
.PP
\fBpyradio\fR will normally load its default playlist file, as described above, upon its execution. A different file can be loaded when the \fI-s\fR command line option is used.
.PP
The \fI-s\fR option will accept:
.HP
\fI*\fR a relative or absolute file name.
\fI*\fR the name of a playlist file which is already in its configuration directory.
\fI*\fR the number of a playlist file, as provided by the \fI-ls\fR command line option.
.PP
\fBExamples:\fR
.HP
To load a playlist called "\fIblues.csv\fR", one would use the command:
.RS 5
\fBpyradio -s /path/to/\fIblues.csv\fR
.RE
If this file was saved inside \fBpyradio\fR's configuration directory, one could use the following command:
.RS 5
\fBpyradio -s \fIblues\fR
.RE
To use the playlist number, one would execute the commands:
.RS 5
\fBpyradio -ls\fR
Playlists found in "\fI/home/user/.config/pyradio\fR"
.br
┏━━━━┳━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┓
.br
┃ # ┃ Name ┃ Size ┃ Date ┃
.br
┡━━━━╇━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━┩
.br
│ 1 │ hip-hop │ 6.41 KB │ Mon Nov 7 18:17:47 2022 │
.br
│ 2 │ party │ 1.94 KB │ Fri Nov 29 10:49:39 2021 │
.br
│ 3 │ stations │ 5.30 KB │ Sat Jul 18 23:32:04 2022 │
.br
│ 4 │ huge │ 1.94 MB │ Wed Oct 23 11:05:09 2019 │
.br
│ \fI5\fR │ \fIblues\fR │ 5.30 KB │ Thu Jul 16 16:30:51 2020 │
.br
│ 6 │ rock │ 2.56 KB │ Fri Jan 10 00:20:07 2023 │
.br
│ 7 │ pop │ 1.01 KB │ Fri Sep 18 00:06:51 2020 │
.br
└────┴──────────┴─────────┴──────────────────────────┘
\fBpyradio -s \fI5\fR
.IP \fBNote\fR
Python 2 output is much simpler, but the functionality is the same.
.IP \fBNote\fR
The default playlist to load can also be set in \fBpyradio\fR’s configuration file, parameter \fIdefault_playlist\fR (default value is \fIstations\fR).
.RE
.PP
.B
Autoloading playlists
As already stated, \fBpyradio\fR will normally load its default playlist (called "\fBstations\fR") upon startup.
This behavior can be then changed in two ways:
.RS 5
.IP 1. 3
Changing the default playlist.
This is accomplished using the "\fBDef. playlist\fR" configuration option (optionally along with the "\fBDef. station\fR" option).
.IP 2. 3
Always loading the last used playlist at startup.
This is accomplished using the "\fBOpen last playlist\fR" configuration option.
In this case, the last used playlist will be opened the next time \fBpyradio\fR will be executed, trying to restore the previously selected station or starting playback.
This option will take precedence before the "\fBDef. playlist\fR" configuration option (if it is used) and the "\fI-s\fR" ("\fI--stations\fR") command line option.
.RS 3
.IP \fBNote:\fR
When the "\fBOpen last playlist\fR" configuration option is set, all playlist operations will be performed to the last opened playlist. In order to use the "\fI-a\fR" ("\fI--add\fR") or "\fI-l\fR" ("\fI--list\fR") command line options along with the "\fI-s\fR" ("\fI--stations\fR") command line option, the "\fI-tlp\fR" "\fI--toggle-load-last-playlist\fR") option can be used to temporarily deactivate autoloading.
.RE
.RE
.PP
.B
Managing Playlists (within PyRadio)
Once \fBpyradio\fR has been loaded, one can perform a series of actions on the current playlist and set of playlists saved in its configuration directory.
Currently, the following actions are available:
Pressing "\fIa\fR" or "\fIA\fR" will enable you to add a new station (either below the currently selected station or at the end of the list), while "\fIe\fR" will edit the currently selected station. All of these actions will open the "\fIStation editor\fR".
If you just want to change the encoding of the selected station, just press "\fIE\fR". If the station is currently playing, playback will be restarted so that the encoding's change takes effect (hopefully correctly displaying the station/song title).
Then, when this is done, you can either save the modified playlist, by pressing "\fIs\fR", or reload the playlist from disk, by pressing "\fIR\fR". A modified playlist will \fIautomatically\fR be saved when \fBpyradio\fR exits (or Ctrl-C is pressed).
One thing you may also want to do is remove a station from a playlist, e.g. when found that it not longer works. You can do that by pressing "\fIDEL\fR" or "\fIx\fR".
Finally, opening another playlist is also possible. Just press "\fIo\fR" and you will be presented with a list of saved playists to choose from. These playlists must be saved beforehand in \fBpyradio\fR's configuration directory.
While executing any of the previous actions, you may get confirmation messages (when opening a playlist while the current one is modified but not saved, for example) or error messages (when an action fails). Just follow the on screen information, keeping in mind that a capital letter as an answer will save this answer in \fBpyradio\fR's configuration file for future reference.
.PP
.B
Managing “Foreign” Playlists
A playlist that does not reside within the program’s configuration directory is considered a "\fIforeign\fR" playlist. This playlist can only be opened by the \fB-s\fR command line option.
When this happens, \fBpyradio\fR will offer you the choise to copy the playlist in its configuration directory, thus making it available for manipulation within the program.
If a playlist of the same name already exists in the configuration directory, the "\fIforeign\fR" playlist will be time-stamped. For example, if a "\fIforeign\fR" playlist is named "\fIstations.csv\fR", it will be named "\fI2019-01-11_13-35-47_stations.csv\fR" (provided that the action was taked on March 11, 2019 at 13:35:47).
.PP
.B
Playlist History
\fBpyradio\fR will keep a history of all the playlists opened (within a given session), so that navigating between them is made easy.
In order to go back to the previous playlist, the user just has to press "\fI\\\\\fR" (double backslash). To get to the first playlist "\fI\\]\fR" (backslash - closing square bracket) can be used.
Going forward in history is not supported.
.SH Stations history
Playing several stations, sometimes among different playlists, and returning to them is sometimes a tedious operation.
This problem is addressed with the \fBStation history\fR functionality, which is actually a list of stations which have been played back.
The user can go back and forth in this list using the "\fI<\fR" and "\fI>\fR" keys.
The list is not saved between sessions (restarting the program will lead to an empty list). When an \fBonline service\fR is used (e.g. \fIRadioBrowser\fR) the list is reseted with every search that is performed.
.SH Search Function
On any window presenting a list of items (stations, playlists, themes) a \fBsearch function\fR is available by pressing "\fI/\fR".
The \fISearch Window\fR supports normal and extend editing and in session history.
One can always get help by pressing the "\fI?\fR" key.
After a search term has been successfully found (search is case insensitive), next occurrence can be obtained using the "\fIn\fR" key and previous occurrence can be obtained using the "\fIN\fR" key.
.SH Line Editor
\fBpyradio\fR "\fISearch function\fR" and "\fIStation editor\fR" use a \fILine editor\fR to permit typing and editing stations' data.
The \fILine editor\fR works both on \fBPython 2\fR and \fBPython 3\fR, but does not provide the same functionality for both versions:
.RS 5
.IP \fI*\fR 2
In \fBPython 2\fR, only ASCII characters can be inserted.
.IP \fI*\fR 2
In \fBPython 3\fR, no such restriction exists. Furthermore, using CJK characters is also supported.
.RE
.PP
One can always display help by pressing "\fI?\fR", but that pauses a drawback; one cannot actually have a "\fI?\fR" withing the string.
To do that, one would have to use the backslash key "\fI\\\fR" and then press "\fI?\fR".
To sum it all up:
.IP
1. Press "\fI?\fR" to get help.
.IP
2. Press "\fI\\?\fR" to get a "\fI?\fR".
.IP
3. Press "\fI\\\\\fR" to get a "\fI\\\fR".
.PP
When in \fIStation editor\fR, the \fBLine editor\fR recognizes an extra mode: \fBPaste mode\fR.
This mode is enabled by pressing "\fB\\p\fR" and gets automatically disabled when the focus moves off the line editors.
This mode is designed to directly accept the "\fI?\fR" and "\fI\\\fR" characters (which are normally used as commands indicators). This makes it possible to easily paste a station's name and URL, especially when the "\fI?\fR" and "\fI\\\fR" characters exist in them; it is very common to have them in URLs.
.PP
\fBCJK Characters Support\fR
The \fILine editor\fR supports the insertion of \fICJK Unified Ideographs [1]\fR, as described on \fICJK Unified Ideographs (Unicode block) [2]\fR, also known as URO, abbreviation of Unified Repertoire and Ordering. These characters, although encoded as a single code-poin (character), actually take up a 2-character space, when rendered on the terminal.
A depiction of the editor's behavior can be seen at this image:
\fIhttps://members.hellug.gr/sng/pyradio/pyradio-editor.jpg\fR
[1] \fIhttps://en.wikipedia.org/wiki/CJK_Unified_Ideographs\fR
[2] \fIhttps://en.wikipedia.org/wiki/CJK_Unified_Ideographs_(Unicode_block)\fR
.SH Moving Stations Around
Rearranging the order of the stations in the playlist is another feature \fBpyradio\fR offers.
All you have to do is specify the \fIsource\fR station (the station to be moved) and the position it will be moved to (\fItarget\fR).
There are three way to do that:
.RS 5
.IP 1. 3
Press \fICtrl-U\fR or \fICtrl-D\fR to move the current station up or down.
.IP 2. 3
Type a station number and press \fICtrl-U\fR or \fICtrl-D\fR to move the current station there.
.IP 3. 3
Go to the position you want to move a station to, and press "\fIJ\fR". This will tag this position (making it the target of the move). Then go to the station you want to move and press \fICtrl-U\fR or \fICtrl-D\fR to move it there.
.SH Specifying Stations' Encoding
Normally, stations provide information about their status (including the title of the song playing, which \fBpyradio\fR displays) in Unicode (\fIutf-8\fR encoded). Therefore, \fBpyradio\fR will use \fIutf-8\fR to decode such data, by default.
In an ideal world that would be the case for all stations and everything would be ok and as far as \fBpyradio\fR is concerned, songs' titles would be correctly displayed. Unfortunately, this is not the case.
A lot of stations encode and transmit data in a different encoding (typically the encoding used at the region the come from). The result in \fBpyradio\fR would be that a song title would be incorrectly displayed, not displayed at all, or trying to displaying it might even break \fBpyradio\fR's layout.
.IP \fBNote\fR
\fIvlc\fR will not work in this case; it presumably tries to decode the said data beforehand, probably using \fIutf-8\fR by default, and when it fails, it provides a "\fI(null)\fR" string, instead of the actual data. So, you'd better not use \fIvlc\fR if such stations are in your playlists.
.PP
\fBpyradio\fR addresses this issue by allowing the user to declare the encoding to use either in a station by station mode or globally.
.PP
.B
Station By Station Encoding Declaration
As previously stated, a \fBpyradio\fR's playlist can optionally contain a third column (in addition to the station name and station URL columns), which declares the station's encoding.
So, when a \fInon-utf-8\fR encoded station is inserted in a playlist, its encoding can also be declared along with its other data. The drawback of this feature is that an encoding must be declared for \fBall stations\fR (so that the \fBCSV\fR file structure remains valid). To put it simple, since one station comprises the third column, all stations must do so as well.
This may seem intimidating (and difficult to achieve), but it's actually really simple; just add a "\fI,\fR" character at the end of the line of each station that uses the default encoding. In this way, all stations comprise the third column (either by declaring an actual encoding or leaving it empty).
Example:
Suppose we have a playlist with one \fIutf-8\fR encoded station:
.HP
\fIStation1\fB,\fIStation1_URL
.PP
Now we want to add "\fIStation2\fR" which is \fIiso-8859-7\fR (Greek) encoded.
Since we know \fBall stations\fR must comprise the third (encoding) column, we add it to the existing station:
.HP
\fIStation1\fB,\fIStation1_URL\fB,
.PP
This way we add an empty encoding, forcing
.PP
Finally, we insert the new station to the playlist:
.HP
\fIStation1\fB,\fIStation1_URL\fB,\fI
.br
Station2\fB,\fIStation2_URL\fB,\fIiso-8859-7
.IP \fBNote\fR
Using the \fB-a\fR command line option will save you all this trouble, as it will automatically take care of creating a valid \fBCSV\fR file. Alternatively, you can change the selected station's encoding by pressing "\fIE\fR" while in \fBpyradio\fR.
.PP
.B
Global Encoding Declaration
\fBpyradio\fR's configuration file contains the parameter \fBdefault_encoding\fR, which by default is set to \fIutf-8\fR.
Setting this parameter to a different encoding, will permit \fBpyradio\fR to successfully decode such stations.
This would be useful in the case where most of your stations do not use \fIutf-8\fR. Instead of editing the playlist and add the encoding to each and every affected station, you just set it globally.
.PP
.B
Finding The Right Encoding
A valid encoding list can be found at:
\fIhttps://docs.python.org/2.7/library/codecs.html#standard-encodings
\fRreplacing \fI2.7\fR with specific version: \fI3.0\fR up to current python version.
.SH Player Detection / Selection
.PP
\fBpyradio\fR is basically built around the existence of a valid media player it can use. Thus, it will auto detect the existence of its supported players upon its execution.
.PP
Currently, it supports \fIMPV\fR, \fIMPlayer\fR and \fIVLC\fR, and it will look for them in that order. If none of them is found, the program will terminate with an error.
.PP
Users can alter this default behavior by using the \fB-u\fR command line option. This option will permit the user either to specify the player to use, or change the detection order.
.PP
Example:
.IP \fBpyradio\ -u\ vlc
will instruct \fBpyradio\fR to use VLC; if it is not found, the program will terminate with an error.
.IP \fBpyradio\ -u\ vlc,mplayer,mpv
will instruct \fBpyradio\fR to look for VLC, then MPlayer and finaly for MPV and use whichever it finds first; if none is found, the program will terminate with an error.
.IP \fBNote\fR
The default player to use can also be set in \fBpyradio\fR’s configuration file, parameter \fIplayer\fR (default value is \fImpv, mplayer, vlc\fR).
.P
\fBChanging player mid-session\fR
.RS 4
If the user faces a playback problem with a given station, chances are that a different player will successfully play it.
Pressing "\fI\\m\fR" will bring up the "\fBSwitch Media Player\fR" window, where a different player can be activated.
.IP \fBNote\fR
The activated player will not be saved; **PyRadio** will still use the player defined at its config next time it is executed.
.SH Specifying a station's Referer URL
Although \fBpyradio\fR 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 \fBReferer URL\fR has to be provided so that the connection does not fail.
\fBpyradio\fR now does support the declaration of a \fBReferer URL\fR 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 "\fIMy video station\fR" 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 "\fB.referer.txt\fR" extension.
In our example above, the file will have to be named:
.RS
"\fIMy video station.referer.txt\fR"
.RE
\fBNote\fR
.RS 2
This will unfortunately not work with \fBMPlayer\fR.
It seems it will not use the \fIReferer\fR provided, as shown in the following part of the command execution output:
\fI[tcp @ 0x7f4a42c7fa60]Successfully connected to XX.XX.XXX.XX port 443
.br
[https @ 0x7f4a42c7fa60]request: GET /live/XXXXXXXX.m3u8 HTTP/1.1
.br
\fBUser-Agent: Lavf/60.16.100\fI
.br
Accept: */*
.br
Range: bytes=0-
.br
Connection: close
.br
Host: XXXXXX-XXXXXXXXX.XXXXXX.XXX.XXX.XX
.br
Icy-MetaData: 1
[https @ 0x7f4a42c7fa60]\fBHTTP error 403 Forbidden\fR
.RE
\fBReferer support in the playlist\fR
As of v. \fB0.9.3.11.5\fR, support for the referer in the playilist has been implemented.
In this case, if a referer file is found for a station, \fBpyradio\fR will:
.IP
1. update the station info in the playlist
.IP
2. mark the playlist as \fBmodified\fR
.IP
3. remove the referer file
.IP
4. inform the user so that he saves the playlist
.P
\fBNote\fR
.RS 2
At this point, inserting the referer from \fBpyradio\fR TUI has not yet been implemented. \
\
One can either use the referer file method described above, or just manually edit the playlist file and add it using the following format:
\fIStation Name,Station URL,,,,,,Referer URL\fR
.RE
.P
.RS 2
Please note the number of commas inserted after the \fIStation URL\fR.
.RS
.SH Extra Player Parameters
All three supported players can accept a significant number of "\fIcommand line parameters\fR", which are well documented and accessible through man pages (on linux and macOs) or the documentation (on Windows).
\fBpyradio\fR uses some of these parameters in order to execute and communicate with the players. In particular, the following parameters are in use \fBby default\fR:
.RS 5
.IP \fBPlayer\fR 10
\fBParameters\fR
.IP \fBmpv\fR 10
--no-video, --quiet, --input-ipc-server, --input-unix-socket, --playlist, --profile
.IP \fBmplayer\fR 10
-vo, -quiet, -playlist, -profile
.IP \fBvlc\fR 10
-Irc, -vv. \fIOn Windows only:\fR --rc-host, --file-logging, --logmode, --log-verbose, --logfile
.RE
.IP \fBNote\fR
The user should not use or change the above player parameters. Failing to do so, may render the player \fBunusable\fR.
.P
\fBpyradio\fR provides a way for the user to add extra parameters to the player, either by a command line parameter, or the "\fIConfiguration Window\fR" (under "\fIPlayer:\fR").
This way, 10 sets of parameters can be inserted and made available for selection.
.P
\fBUsing The Configuration Window\fR
When the user uses the configuration window (shown in the following image), he is presented with an interface which will permit him to select the player to use with \fBpyradio\fR and edit its extra parameters.
[pyradio-player-selection.jpg](https://members.hellug.gr/sng/pyradio/pyradio-player-selection.jpg)
Each of the supported players can have up to 11 sets of extra parameters (the first one is the default).
The user can add ("\fBa\fR") a new parameter, edit ("\fBe\fR") an existing set and delete ("\fBx\fR" or "\fBDEL\fR") one.
.SH Player Connection Protocol
Most radio stations use plain old http protocol to broadcast, but some of them use https.
Experience has shown that playing a \fBhttps\fR radio station depends on the combination of the station's configuration and the player used.
If such a station fails to play, one might as well try to use \fBhttp\fR protocol to connect to it.
\fBpyradio\fR provides a way to instruct the player used to do so; the "\fIForce http connections\fR" configuration parameter. If it is \fIFalse\fR (the default), the player will use whatever protocol the station proposes (either \fBhttp\fR or \fBhttps\fR). When changed to \fBTrue\fR, all connections will use the \fBhttp\fR protocol.
When the selected player is initialized (at program startup), it reads this configuration parameter and acts accordingly.