Aquatic Music Player
Posted on 2020-06-16

I'm one of those dinosaurs who keeps their music library as files on their hard disk. As such, I like a nice visual presentation when I'm in a music-listening mood.

Some years back I enjoyed using the "Subsonic" music player, which had a web interface with a nice, dynamic showcasing of cover art. However, it didn't queue up videos like it did with songs, and the UI started moving in a different direction, so I decided to try writing my own!

Thus begat the Aquatic Music Player, a javascript application that runs in your browser. You can get it on github:


The caveat is it is only supported for unix-like systems such as Linux, Apple macOS, and BSD, as the database buider is launched from a bash script, and throughout the application the standard unix file path conventions are assumed.


The installation involves downloding the aquatic-mp-master directory using the github link above, then running the "build_db" script to build the database of your media. This database is in the form of an auto-generated javascript file that has data structures specifying your albums, songs, videos, and cover art, along with their paths and other information. The file gets loaded when the application is launched in the browser.

To run the "build_db" script, you'll need the following commands in your path: "nodejs", "ffprobe", and "identify", which runs the database builder script invoked from "build_db", scrapes song metadata, and scrapes photo metadata, respectively. The metadata scraping is time consuming, so expect the database build to take a while - on my laptop, it takes about a minute per hundred albums.

If you're using a Debian-based system, you can get these command-line tools as follows:

sudo apt install nodejs ffmpeg imagemagick

If you're using macOS, you can get these from an open source package system such as Homebrew. Once these commands are there (you can check by typing "which nodejs ffprobe identify"), cd into the "aquatic-mp-master" directory and type "./build_db -h" for help on how to specify your media directory, and also how to organize the data within it. build_db expects there to be albums organized as directories, each containing the songs and cover art for that album. The build_db help will provide details and examples. If you don't necessarily have traditional "albums" of music, you can just create directories to group certain songs and/or videos together to form makeshift "albums", along with any cover art imagery you like.

The Interface

Once the media database has been built, you're ready to launch. This is done by opening the file "(path to install)/aquatic-mp-master/www/index.html" in a browser, substituting "(path to install)" with the actual path to your aquatic-mp-master directory. I recommend using Google Chrome in "app mode", which on my Xubuntu laptop I launch as follows:

google-chrome-stable --app="file:///home/sporkman/applications/aquatic-mp-master/www/index.html"

from a launcher button in the panel.


Once you're in the Aquatic page, you'll see a list of your albums in the right-hand panel, a welcome message in the center area (called the "workspace"), and the left-hand panel is where the playlist and media player device will be. It's mostly blank now, because you haven't yet queued up any music to play.

From here on I'll mention "songs" as the contents of albums, but these can actually be either songs or videos. Whether a particular media file is a song or video is determined during the database build process, and will be handled correctly by the Aquatic player.

To start listening to music, click on one of your albums in the right-hand panel, which will bring up the album contents in the center workspace. To select a specific song to listen to, click on the "+" button on the left of the song title, which adds it to the playlist in the left-hand panel. To add all the songs, click the "+++" button on the right above the song list. Note that a particular song from an album can only appear once in the playlist, so if you add a song using "+", then click "+++" to add all songs, the entire song list minus the one you already added will appear at the bottom of the playlist.


Once you have a playlist, you can start listening to a song by clicking on its title, which plays it in the media device above the playlist. You can use the controls in the media device to pause the music, maximize the player, etc., in the usual way. Once a song completes, the next song in the playlist will begin. You can rearange the order or remove songs by using the buttons beside the individual song titles in the playlist.

In the upper right of the window you'll notice a row of images, mostly of cover art. This area is called the "ad space". Clicking on a cover image here will bring up the album detail in the workspace. Occasionally you'll see wider-than-usual images here, which I call "ads". I consider all the images ads (the cover art sort of "advertising" the album), however these wider images can be considered an advertisement-like interlude to the usual flow of cover-art, sort of like billboards along your musical journey. The standard Aquatic installation comes with a handful of ads, however you may add more to suit your tastes, or remove them all if you're not interested in that feature. I'll describe the details a little later.

Why an "ad space", which also appears to have actual ad-like imagery? Although the Aquatic player has an "under the sea" theme, I wanted it to have a rich visual component with an urban flair. You can think of the ad space as invoking the experience of floating through a busy avenue at night in New York City, Tokyo, or other dense megacity where you're surrounded by culture and hip advertisements.


Finally, a fun, semi-hidden feature of Aquatic is an "aquarium" in the workspace when you click the "X" button in the the album detail view. This is a randomized, animated view of a sandy seabed with various aquatic flora and fauna coming and going. It builds up slowly, so at first all you'll see is the seabed at the bottom, but be patient and it will grow more active. Also included are slowly rising air bubbles to provide ambiance. I used to keep real aquariums, and enjoyed listening to music while watching them, so this seemed a natural addition for me.

You'll notice that the animated features - the adspace shuffling, the ticker-tape-style banner above the player, and the aquarium - all move very slowly. I found that when things moved too quickly, it distracted from the music itself and I ended up paying more attention to those and not to what I was listening to. After some experimentation I settled on the current rates of movement, which seem to be ideal.

Updating your media and the ads

So you built the database in the initial install, but now want to add more music, or possibly remove music or rearange your music directories. Any such changes require rebuilding the database using the "build_db" script just like you did on install. Unfortunately there is no incremental rebuild, nor are changes to your media library auto-detected, so you'll need to remember to do this. If you don't, any new music you've added won't appear in the player, and if anything was moved or deleted, you'll see evidence of broken links during use.

Those extra "ads" I mentioned above are also processed during the database build step. These are images of size 428px x 240px located in the "(path to install)/aquatic-mp-master/ads" directory. You may add new ads in this directory, or remove existing ones. If you add new ads here, make sure they have the same 428px x 240px dimensions as the others, and note that when you hover the mouse over the ad, the base part of the ad's filename is displayed in the pop-up. And, as mentioned, changes to the ads will require a database rebuild.

That's it - thanks for reading, and enjoy your smooth listening experience!