This is a guide to the basic functionality of MousikóFídi.

Throughout the guide, the official MousikóFídi demo will be linked to as a referenc


MousikóFídi ships with two executables: mousikofidi and mousikofidi-client.


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.


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:


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/
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/
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

# If using runit
sv reload fidi

# If you are managing the process manually
mousikofidi --reload ~/run/

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 you are managing the process manually
mousikofidi --reload ~/run/
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:

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


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


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 music_dirs. From here, you can navigate freely.

You may note a grey triangle in the lower righthand corner of the screen; clicking this will skip you to the top of any given page without doing a reload. This can be useful on the playlist player page, where a reload would stop playback.

Additionally, on any page with a player the MousikóFídi logo in the nav bar will become a link to that player. If there's both an audio and a video player, the video player gets the link.

The "top" triangle combined with the logo shortcut can be a great combo for quick navigating.

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 a "+" 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 Files 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.

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.


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").


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.


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.

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.

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 is set to true in your config file and that the configured playlist.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 Files 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.

There is a hard limit on the size of a queue; MousikóFídi is currently limited by the maximum allowed size for a cookie, 4093 bytes. If an add operation will exceed this size, it will be canceled and you will be given a message in red text.

This can be worked around by creating a playlist file externally from MousikóFídi, for instance from the command line (see below for a specific example). There is no known limit to the number of songs that can be loaded from playlist files (see below for more information on that).

In the future, MousikóFídi will have an option to leverage the Web Storage API as an improved way to handle your queue over cookies.

Saving A Playlist

When tracks are added to the queue, and provided 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 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.

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!

Clearing The Queue

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

After doing so, there will be a message confirming the clearing as well as an "Undo?" button. This can be clicked to undo the action, restoring the queue as it was.

Be aware that if you don't click "Undo?" and navigate away from the page, the chance to undo is lost forever!

About this wiki

commit c7aa8adde209af4256caa44eb0a930f96d40d5ef
Author: Hristos N. Triantafillou <>
Date:   2019-11-25T12:46:48-06:00

Put the "Contributing" section at the top, mention the dev branch

The way things were before, it wasn't very clear that the "dev" branch
is what someone would want to work off of (need to even).

Moving the "Contributing" section to the top, and adding specific
wording about "dev", will help make this more clear.

I've also swapped out the link for a direct link to
the new "make a patch" link on sourcehut, and removed the bit about
the git book (out of scope for the document anyways).
Clone this wiki (read-only) (read/write)