~hristoast/mousikofidi

ref: mousikofidi.info mousikofidi/site/user_guide.html -rw-r--r-- 21.0 KiB
d1c22b44Hristos N. Triantafillou Clean out old info, update config reference (#139) 11 days ago
                                                                                
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
<h1>
  User's Guide
</h1>

<p>
  This is a guide to the basic functionality of MousikóFídi.
</p>

<div id="toc"></div>

<p>
  Throughout the guide, <a href="https://demo.mousikofidi.info/">the official MousikóFídi demo</a> will be linked to as a reference.
</p>

<h2>Executables</h2>

<p>
  MousikóFídi ships with two executables: <code>mousikofidi</code> and <code>mousikofidi-client</code>.
</p>

<h3><code>mousikofidi</code></h3>

<p>
  The <code>mousikofidi</code> executable is used to manage and interact with the server process.  It will look for a file at <code>~/.config/fidi/uwsgi.ini</code> and if it is present it will automatically use it.
</p>

<pre><code>mousikofidi --processes $(nproc) --daemonize ~/logs/uwsgi.log</code></pre>

<p>
  It can also be used to start MousikóFídi via the Flask dev server:
</p>

<pre><code>mousikfdi --dev</code></pre>

<p>
  Run <code>mousikofidi --help</code> to see all the options.
</p>

<h3><code>mousikofidi-client</code></h3>

<p>
  The <code>mousikofidi-client</code> executable is a convenience utility for opening the MousikóFídi instance of your choosing in the browser of your choosing.
</p>

<p>
  An instance can be specified with the <code>--instance-url</code> argument:
</p>

<pre><code>mousikofidi-client --instance-url my-cool-fidi.instance.tld</code></pre>

<p>
  It will also read the <code>FIDI_URL</code> environment variable if it's present:
</p>

<pre><code>FIDI_URL=my-fidi.instance.tld mousikofidi-client</code></pre>

<p>
  By default, it opens the demo instance with Chromium:
</p>

<pre><code>mousikofidi-client</code></pre>

<p>
  You can use another browser like this:
</p>

<pre><code>mousikofidi-client --other "palemoon --private-window"</code></pre>

<p>
  Run <code>mousikofidi-client --help</code> to see all the options.
</p>

<h2>Server Admin</h2>

<p>
  Working with the MousikóFídi process after it's been installed.  The below items assume that <a href="/setup/">the setup guide</a> has been followed.
</p>

<h3>Stopping MousikóFídi</h3>

<p>
  The MousikóFídi <code>uwsgi</code> process can be stopped like this:
</p>

<pre><code>sudo su - fidi
mousikofidi --stop ~/run/mousikfdi.pid</code></pre>

<h3>Restarting MousikóFídi</h3>

<p>
  If MousikóFídi is running with the <code>daemonize</code> option, it can be reloaded like this:
</p>

<pre><code>sudo su - fidi
mousikofidi --reload ~/run/mousikfdi.pid</code></pre>

<h3>Updating MousikóFídi</h3>

<h4>Via Pip</h4>

<p>
  If you've installed MousikóFídi via <code>pip</code> as <a href="/setup/#installing-mousik--f--di">per the setup guide</a>, it can be upgraded like this:
</p>

<pre><code>pip3 install --upgrade --user MousikoFidi

# Or this if your python is newer:
python3 -m pip install --upgrade --user MousikoFidi

# If using runit
sv reload fidi

# If using systemd
systemctl --user reload mousikofidi.service

# If you are managing the process manually
mousikofidi --reload ~/run/mousikfdi.pid</code></pre>

<p>
  The reload command must be issued for any changes to take effect.
</p>

<h4>Via Git</h4>

<p>
  Update the code, then restart the <code>uwsgi</code> process:
</p>

<pre><code>sudo su - fidi

cd ~/mousikofidi

git pull

make install

# If using runit
sv reload fidi

# If using systemd
systemctl --user reload mousikofidi.service

# If you are managing the process manually
mousikofidi --reload ~/run/mousikfdi.pid</code></pre>

<h4>Dev Build</h4>

<p>
  If you want to try out a prerelease version of MousikóFídi, you can do so with <code>pip</code>:
</p>

<pre><code>pip3 install --upgrade --user git+https://git.sr.ht/~hristoast/mousikofidi@dev

# Or this if your python is newer:
python3 -m pip install --user --upgrade git+https://git.sr.ht/~hristoast/mousikofidi@dev</code></pre>

<p>
  This installs directly from the <code>dev</code> branch on the main git repo.
</p>

<h2>Adding Your Collection</h2>

<p>
  As described in <a href="/config/">the configuration guide</a>, paths to your music and video collections should be added to the config file in order to be made available with MousikóFídi.
</p>

<p>
  On Linux and similar systems, often times a user's home directory is set up with permissions that are too tight for <a href="/setup/#creating-the-fidi-user">the recommended setup</a> of MousikóFídi.
</p>

<p>
  As an alternative, a path such as <code>/srv</code> can be used that's a bit more neutral on the permissions side:
</p>

<pre><code>sudo mkdir -p /srv/{music,playlists,video}</code></pre>

<p>
  Then, assuming your collections are found in those directories, set the config file:
</p>

<pre><code>[library]
dirs = [
  "/srv/music",
  "/srv/video",
]</code></pre>

<p>
  If multi-user access to the files isn't a concern, these can of course be put under the <code>fidi</code> user's home directory in <code>/opt/fidi</code>.
</p>

<h3>Valid Media Types</h3>

<p>
  Any media type supported by modern web browsers is playable via MousikóFídi.  Please see <a href="https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Audio_codecs#Common_codecs">this MDN reference</a> on common supported audio codecs, and <a href="https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Video_codecs#Common_codecs">this one for video codecs</a>.
</p>

<p>
  Note that some <code>.mkv</code> video files are supported <strong>via Chrome or Chromium only</strong>.
</p>

<h2>Shortcuts</h2>

<p>
  It's often useful to have a shortcut for quickly accessing your MousikóFídi instance.  Depending on your OS, this can be done a few ways:
</p>

<h3>Desktop</h3>

<p>
  Desktop users can make a direct link with a launcher; simply run your web browser of choice with the address of your instance as the argument.
</p>

<p>
  The <code>mousikofidi-client</code> program is a nice way to orchestrate this, simply put that in a <code>.desktop</code> file or call it directly with something like <a href="https://tools.suckless.org/dmenu/"><code>dmenu</code></a>.
</p>

<h3>Mobile</h3>

<p>
  Mobile users can make a direct link to their MousikóFídi instance as well; most browsers should have some option to "Add Page Shortcut" (Fennec/Firefox) or similar.
</p>

<p>
  Doing this places a direct link to the specified web page, in this case your MousikóFídi instance, on your device's home screen.
</p>

<p>
  It will likely even sport the MousikóFídi logo, or whatever you have chosen for the site favicon.  This has been tested on Android with: Fennec, Firefox, Chrome, and Chromium.
</p>

<h2>Browsing</h2>

<p>
  The <a href="https://demo.mousikofidi.info/">main page of MousikóFídi</a> features only the logo, and a nav bar with links.
</p>

<p>
  Clicking the "Browse" button takes you to <a href="https://demo.mousikofidi.info/browse">an index of your configured <a href="/config/#library-dirs"><code>library.dirs</code></a></a>.  From here, you can navigate freely while directly browsing directories and files in your collection.
</p>

<p>
  You may note a grey triangle in the lower and upper left corners of the screen; clicking then will skip you to the top and bottom of any given page without doing a reload, respectively.
</p>

<h3>Breadcrumb Links</h3>

<p>
  At the top of any given "browse" page you will find a link or series of links that represent the path to the particular <a href="https://demo.mousikofidi.info/browse/srv/music/JaB/JaB%20-%20Web%20City%20Vol%201-%20Way%20Of%20The%20Samurai/04%20-%20No%20Weapon.mp3">file</a> or <a href="https://demo.mousikofidi.info/browse/srv/music/JaB/JaB%20-%20Web%20City%20Vol%201-%20Way%20Of%20The%20Samurai">directory</a> you are looking at.
</p>

<p>
  This is a convenient way to navigate while browsing, and when you use these links MousikóFídi will position you on the next page with the thing you were just looking at in view; this saves you the trouble of needing to navigate back to your place.  It's an effect that is most noticeable in large collections, with many and/or deeply nested directories.
</p>

<h3>File Detail Page</h3>

<p>
  A <a href="https://demo.mousikofidi.info/browse/srv/music/from_freemusicarchive.org/Black_Ant_-_01_-_Fater_Lee.mp3">file detail page</a> is what you see when you click the title of a file on a <a href="https://demo.mousikofidi.info/browse/srv/music/from_freemusicarchive.org">directory detail page</a>.
</p>

<p>
  At the top is a series of links to any directory between the file and the base music dir, and an "Add to queue" button for adding this file to your queue.
</p>

<p>
  For audio files, any metadata found will be shown as well as an audio player for just this file.
</p>

<h3>Track Metadata</h3>

<p>
  MousikóFídi will try to read an audio or video file and find any metadata that available.  These values will be displayed on the various views where you can see tracks.  If no metadata is present, the the track is referred to by its filename.
</p>

<p>
  Other software, such as <a href="http://beets.io/">beets</a> or <a href="https://kid3.sourceforge.io/">Kid3</a> can be used to update or edit the metadata of your files.
</p>

<h3>Directory Detail Page</h3>

<p>
  A directory detail page might have <a href="https://demo.mousikofidi.info/browse/srv/music/FF6_Balance_and_Ruin">other directories in it</a>, it may have <a href="https://demo.mousikofidi.info/browse/srv/music/from_freemusicarchive.org">files in it</a>, or it may have a combination of both.
</p>

<p>
  In the event that files are present, a button is offered to "Add All Tracks To Queue".  As expected, it will add any files in the current directory to <a href="https://demo.mousikofidi.info/queue">your queue</a>, found by clicking the "Queue" button in the nav.
</p>

<p>
  Also present in any directory with files: the audio and/or video players will be present for their respective files.
</p>

<h3>Playlist Detail Page</h3>

<p>
  When playlist files are present, each playlist will have its own detail page found at <a href="https://demo.mousikofidi.info/playlist/JaB%20Mixtapes"><code>/playlist/NAME</code></a> where <code>NAME</code> here is the name of the playlist.
</p>

<p>
  This page looks like a directory detail page with files in it.  The playlist detail page also sports the audio/video player as found on other pages.  Read on for more information about the player and related controls.
</p>

<h4>A Playlist</h4>

<p>
  At the bottom of each Playlist Detail page is a button labeled "Delete Playlist ..." that can be used to delete a playlist file, provided that <a href="/config/#playlists-allow-delete"><code>playlist.allow_delete</code></a> is enabled in your MousikóFídi config.
</p>

<p>
  <strong>Note that this action cannot be undone!</strong>
</p>

<h3>MousikóFídi Mobile UI</h3>

<p>
  When using MousikóFídi on a device with a smaller viewport (or, if you just shrink your browser window small enough) the user interface will respond by adjusting certain elements so everything fits right and looks nice.
</p>

<p>
  Under this "Mobile UI", certain columns in track lists are hidden and some features, like the reorder queue arrows, are hidden. This is to ensure that the UI remains uncluttered and still reasonably usable when limited screen space is available.
</p>

<h2>The Player</h2>

<p>
  The MousikóFídi player is the only component in the application that requires the usage of javascript.  If you are blocking javascript, it will need to be allowed for any MousikóFídi instance that you want to use the player on.
</p>

<h3>Audio And Video</h3>

<p>
  The MousikóFídi player supports anything that can be played via your browser and the <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/audio"><code>&lt;audio&gt;</code></a> and/or <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video"><code>&lt;video&gt;</code></a> elements.  The player controls look and act the same for both audio and video playlists, with the exception that they only affect their respective player.
</p>

<p>
  If there is both audio and video tracks in a playlist, enabling Shuffle for the audio player won't also do the same for the video; the shuffle button beneath the video player needs to be clicked for video playback to shuffle too.
</p>

<h3>Track Skipping</h3>

<p>
  Clicking the "Previous" or "Next" buttons will advance the playlist in either direction;  if on the first track and "Previous" is clicked, the last track is changed to.  If on the last track and "Next" is clicked, the first track is changed to.
</p>

<p>
  Additionally, the green play arrow next to each track name can be clicked to change to that track.
</p>

<h3>Repeat</h3>

<p>
  By default, the player will play through all tracks and then pause playback.  To repeat the current track, when the repeat button says "No Repeat" click it once.  It should now say "Repeat One", and as described before the current track will be repeated.
</p>

<p>
  Clicking the button once more will change it to say "Repeat All" - this will play the entire playlist and repeat it when finished.
</p>

<p>
  When "Repeat All" is active, you can click the button once more to disable repeating altogether (the button will return to saying "No Repeat").
</p>

<h3>Shuffle</h3>

<p>
  The playlist may be played in a shuffled order by clicking the "Shuffle Off" button; once clicked, it will say "Shuffle On".
</p>

<p>
  When shuffling is enabled the tracks will play in a shuffled order until the last track is reached, at which time playback will end unless "Repeat All" is enabled.
</p>

<p>
  If "Repeat All" is enabled, once the last track in the shuffled list finishes a new shuffled order will be generated and begin to play.
</p>

<p>
  Additionally, clicking the green play arrow for any track will generate a new shuffled order beginning with this track.
</p>

<p>
  No shuffling will occur if "Repeat One" is enabled.
</p>

<h3>Follow</h3>

<p>
  Enabled by default, the "Follow" option will jump to the currently playing track when one ends and another begins.  This behavior can be disabled by unchecking the box in the player.
</p>

<h3>Copy Link</h3>

<p>
  The audio and video players each have a button that, when clicked, will insert a link to the current track at the current time into your clipboard.
</p>

<p>
  Listen to or view a track you enjoy, click the link button at the desired time, then share the link with family and friends.
</p>

<h3>Volume Control</h3>

<p>
  The MousikóFídi player volume controls will save volume levels for each player. Use the slider or the -/+ buttons to adjust the volume level, and it will perist as you browse your collection.
</p>

<h3>Keyboard Controls</h3>

<p>
  MousikóFídi provides keyboard shortcuts for common player functions. Read more about it <a href="/config/#key-bindings">on the config page</a>.
</p>

<h2>The Queue</h2>

<p>
  MousikóFídi supports adding audio and video tracks into a queue for your session.  Audio tracks loaded in this queue can be played in order or shuffled, as well as saved to a playlist file for later loading.
</p>

<p>
  Saving and loading a queue into a playlist requires that <code>playlists.allow_save</code> is set to <code>true</code> in your config file and that the configured <code>playlists.dir</code> exists and is writeable.
</p>

<h3>Adding Tracks To The Queue</h3>

<p>
  As described above, tracks can be added to the queue in various ways; either by clicking the "+" next to the track name on a directory detail page, by clicking the "Add All Tracks To Queue" button, or by clicking the "+" on a file detail page.
</p>

<p>
  After adding tracks to the queue, you can click the "Queue" button in the nav to play them or save it to a file.
</p>

<h3>Saving A Playlist</h3>

<p>
  When tracks are added to the queue, and provided <code>playlists.allow_save</code> is set to <code>true</code> (this is the default), when visiting the queue page form will be available which will save it as a file.
</p>

<p>
  Enter the desired name for the playlist into the text box labeled 'Name', and hit enter of click the "Save Queue" button right next to it.
</p>

<p>
  <strong>Playlist names may only contain alphanumeric characters, spaces, underscores, and plus signs.</strong>
</p>

<p>
  If <code>playlists.allow_save</code> is disabled, no queue saving will be allowed.  Any playlists that exist in the playlist directory will be loadable, however.  Any <code>.m3u</code> that has tracks with full paths and that are in your MousikóFídi music directories can be loaded, regardless of whether or not it was saved via MousikóFídi.
</p>

<p>
  Here's an exmaple of me creating a playlist for the demo site from the command-line:
</p>

<pre><code>ls -1 ~/music/FF6_Balance_and_Ruin/**/** &gt; ~/playlists/OC\ Remix:\ FF6\ Balance\ And\ Ruin.m3u
</code></pre>

<p>
  I'm listing out all directories under that album and outputting it to a playlist file.
</p>

<h3>Loading A Playlist</h3>

<p>
  Any playlist that's been saved may be loaded into the queue.
</p>

<p>
  Navigate to the queue page by clicking the "Queue" button in the nav.  If saved playlists are present, two buttons and a drop-down menu will be present.
</p>

<p>
  Use the drop-down menu to select the playlist you wish to load, then click the "Load Playlist" button.
</p>

<p>
  Note that any playlist created outside of MousikóFídi that has relative paths will not load in MousikóFídi.
</p>

<h4>Playlist Load Errors</h4>

<p>
  If a playlist contains a trat is not identifiable as <a href="#valid-media-types">a valid media track</a>, you will receive an error message upon loading the playlist.
</p>

<p>
  The MousikóFídi server log will have error entries for each track that is considered invalid, the server administrator should check there for specific information about what was considered invalid.
</p>

<h3>Deleting A Playlist</h3>

<p>
  Any playlist within the MousikóFídi playlist directory can be deleted by selecting it from the drop-down menu and clicking the "Delete Playlist" button.
</p>

<p>
  After doing this, another button will appear asking you to confirm if you really want to delete the selected playlist.  Clicking this button will permanently delete the specified playlist (not the one in the drop-down menu, the one mentioned on the button).  <strong>This cannot be undone</strong>!
</p>

<h3>Removing A Track From The Queue</h3>

<p>
  On the Queue page, each track has a red X that can be clicked to remove the track from your queue. Upon clicking the X for any given track, the queue will re-render with the selected track gone.  If the X'd track was playing, it will be stopped and the first track of the queue will be loaded for playback.
</p>

<h3>Moving A Track Within The Queue</h3>

<p>
  Next to the red removal "X" are two orange-colored arrows. Clicking the down-pointing orange arrow will move that track down if possible, and clicking the up-pointing orange arrow will move the track up if possible.
</p>

<h3>Clearing The Queue</h3>

<p>
  A "Clear Queue" button is also available on the queue page.  Clicking it empties your queue of any tracks. <strong>This cannot be undone</strong>!
</p>

<h2>MousikóFídi as a PWA</h2>

<p>
  MousikóFídi <a href="https://demo.mousikofidi.info/manifest.webmanifest">provides</a> a <a href="https://developer.mozilla.org/en-US/docs/Web/Manifest">web app manifest</a>, allowing it to be "installed" as a <a href="https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps">progressive web app</a>.
</p>

<p>
  To use this feature: simply open your MousikóFídi instance URL with your favorite mobile browser and look for the "Add To Home" or "Install" option.
</p>

<p>
  <span class="bold">Note that there is no offline support</span> since MousikóFídi requires network access to the server in order to download tracks.
</p>

<h2>Troubleshooting</h2>

What to do when MousikóFídi isn't working right.

<h3>MousikóFídi Won't Start</h3>

<p>
  Any problems will be noted in the application log. Where this is depends on how you are running MousikóFídi; the easiest way to see any problems would be to run the dev server:
</p>

<pre><code># Become the app user, if applicable:
sudo su - fidi

# Run the dev server:
mousikofidi --dev</code></pre>

<p>
  If there's a problem that is stopping MousikóFídi from running, it will be mentioned:
</p>

<pre><code>$ mousikofidi --dev
 * Serving Flask app "mousikofidi" (lazy loading)
 * Environment: development
 * Debug mode: on
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
 * Restarting with stat
[2020-10-03 14:29:32,363] DEBUG in mousikofidi: Reading User Config: /opt/fidi/.config/fidi/config.toml
[2020-10-03 14:29:32,363] ERROR in mousikofidi: The '[player]' section is missing from your config file!
[2020-10-03 14:29:32,363] ERROR in mousikofidi: Add it or rename your existing file to have a new, valid one generated!
[2020-10-03 14:29:32,363] ERROR in mousikofidi: Exiting now because we are unable to do anything...</code></pre>

<h3>How To Get Help</h3>

<p>
  If there's some other problem, please feel free to reach out via <a href="https://lists.sr.ht/~hristoast/mousikofidi">the mailing list</a> or by <a href="https://todo.sr.ht/~hristoast/mousikofidi">opening a bug report</a>. You can also join <a href="https://demo.mousikofidi.info/about#get-help">#mousikofidi on irc.freenode.net</a>, please be patient if you don't get a response right away.
</p>