User's Guide

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

mousikofidi --processes $(nproc) --daemonize ~/logs/uwsgi.log

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

mousikfdi --dev

Run mousikofidi --help to see all the options.

→ `mousikofidi-client`

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

An instance can be specified with the --instance-url argument:

mousikofidi-client --instance-url my-cool-fidi.instance.tld

It will also read the FIDI_URL environment variable if it's present:

FIDI_URL=my-fidi.instance.tld mousikofidi-client

By default, it opens the demo instance with Chromium:

mousikofidi-client

You can use another browser like this:

mousikofidi-client --other "palemoon --private-window"

Run mousikofidi-client --help to see all the options.

→ Server Admin

Working with the MousikóFídi process after it's been installed. The below items assume that the setup guide has been followed.

→ Stopping MousikóFídi

The MousikóFídi uwsgi process can be stopped like this:

sudo su - fidi
mousikofidi --stop ~/run/mousikfdi.pid

→ Restarting MousikóFídi

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

sudo su - fidi
mousikofidi --reload ~/run/mousikfdi.pid

→ Updating MousikóFídi

→ Via Pip

If you've installed MousikóFídi via pip as per the setup guide, it can be upgraded like this:

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

The reload command must be issued for any changes to take effect.

→ Via Git

Update the code, then restart the uwsgi process:

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

→ Dev Build

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

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

This installs directly from the dev branch on the main git repo.

→ Adding Your Collection

As described in the configuration guide, paths to your music and video collections should be added to the config file in order to be made available with MousikóFídi.

On Linux and similar systems, often times a user's home directory is set up with permissions that are too tight for the recommended setup of MousikóFídi.

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

sudo mkdir -p /srv/{music,playlists,video}

Then, assuming your collections are found in those directories, set the config file:

[library]
dirs = [
  "/srv/music",
  "/srv/video",
]

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

→ Valid Media Types

Any media type supported by modern web browsers is playable via MousikóFídi. Please see this MDN reference on common supported audio codecs, and this one for video codecs.

Note that some .mkv video files are supported via Chrome or Chromium only.

→ Shortcuts

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:

→ Desktop

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.

The mousikofidi-client program is a nice way to orchestrate this, simply put that in a .desktop file or call it directly with something like dmenu.

→ Mobile

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.

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.

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.

→ Browsing

The main page of MousikóFídi features only the logo, and a nav bar with links.

Clicking the "Browse" button takes you to an index of your configured library.dirs. From here, you can navigate freely while directly browsing directories and files in your collection.

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.

At the top of any given "browse" page you will find a link or series of links that represent the path to the particular file or directory you are looking at.

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.

→ File Detail Page

A file detail page is what you see when you click the title of a file on a directory detail page.

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.

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

→ Track Metadata

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.

Other software, such as beets or Kid3 can be used to update or edit the metadata of your files.

→ Directory Detail Page

A directory detail page might have other directories in it, it may have files in it, or it may have a combination of both.

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 your queue, found by clicking the "Queue" button in the nav.

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

→ Playlist Detail Page

When playlist files are present, each playlist will have its own detail page found at /playlist/NAME where NAME here is the name of the playlist.

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.

→ A Playlist

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 playlist.allow_delete is enabled in your MousikóFídi config.

Note that this action cannot be undone!

→ MousikóFídi Mobile UI

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.

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.

→ The Player

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.

→ Audio And Video

The MousikóFídi player supports anything that can be played via your browser and the <audio> and/or <video> 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.

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.

→ Track Skipping

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.

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

→ Repeat

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.

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

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

→ Shuffle

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

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.

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.

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

No shuffling will occur if "Repeat One" is enabled.

→ Follow

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.

→ Copy Link

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.

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

→ Volume Control

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.

→ Keyboard Controls

MousikóFídi provides keyboard shortcuts for common player functions. Read more about it on the config page.

→ The Queue

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.

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

→ Adding Tracks To The Queue

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.

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

→ Saving A Playlist

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

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.

Playlist names may only contain alphanumeric characters, spaces, underscores, and plus signs.

If playlists.allow_save is disabled, no queue saving will be allowed. Any playlists that exist in the playlist directory will be loadable, however. Any .m3u 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.

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

ls -1 ~/music/FF6_Balance_and_Ruin/**/** > ~/playlists/OC\ Remix:\ FF6\ Balance\ And\ Ruin.m3u

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

→ Loading A Playlist

Any playlist that's been saved may be loaded into the queue.

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.

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

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

→ Playlist Load Errors

If a playlist contains a trat is not identifiable as a valid media track, you will receive an error message upon loading the playlist.

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.

→ Deleting A Playlist

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.

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). This cannot be undone!

→ Removing A Track From The Queue

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.

→ Moving A Track Within The Queue

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.

→ Clearing The Queue

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

→ MousikóFídi as a PWA

MousikóFídi provides a web app manifest, allowing it to be "installed" as a progressive web app.

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.

Note that there is no offline support since MousikóFídi requires network access to the server in order to download tracks.

→ Troubleshooting

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

→ MousikóFídi Won't Start

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:

# Become the app user, if applicable:
sudo su - fidi

# Run the dev server:
mousikofidi --dev

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

$ 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...

→ How To Get Help

If there's some other problem, please feel free to reach out via the mailing list or by opening a bug report. You can also join #mousikofidi on irc.freenode.net, please be patient if you don't get a response right away.