Introduction
The music player v0.1 is an easy to install, easy to use HTML5 music player. It features a searchable playlist, covers support, oscilloscope and spectrum analysis, numerous keyboard shortcuts, support for assistive technologies (WAI-ARIA), vibration feedback for supported devices, light/dark modes interface and much more!
It is written in HTML, SVG, CSS and JavaScript, using standard technologies for better compatibility and short-driven code for performance and easy debugging. It stands in a single file without any external dependencies.
This document describes the installation process and the user interface, and has some technical sections as well.
Installation
Requirements
- A Linux host with Apache web server installed.
- Command-line access to the Linux host, directly or through SSH. You may need root priviledges for optional parts.
- A music folder shared publicly on this Apache web server.
Setup
Connect to the Linux host directly or through SSH, and navigate to your music folder:
$ ssh user@example.com user@example.com's password: $ cd /path/to/music/ $ █
Generate a playlist file using the following command:
$ find ./ -type f \( -iname "*.aac" -or -iname "*.flac" -or -iname "*.ogg" \
-or -iname "*.mp3" -or -iname "*.mp4" -or -iname "*.wav" \
-or -iname "*.webm" -or -iname "*.apng" -or -iname "*.avif" \
-or -iname "*.bmp" -or -iname "*.gif" -or -iname "*.jfif" \
-or -iname "*.jpeg" -or -iname "*.jpg" -or -iname "*.pjp" \
-or -iname "*.pjpeg" -or -iname "*.png" -or -iname "*.webp" \) \
| sort --numeric-sort > playlist.txt
The resulting file playlist.txt (example) should contain one line per media file, starting with "./".
Download the file player.html (56kB) into your music folder:
$ wget -q -O player.html https://dradis.be/music-player/player-0.1.html
Navigate to the file player.html in your web browser. The music player should display and load the playlist file.
In case of error, look into the web server log files in /var/log/apache2/ and make sure the player.html, playlist.txt and music files are readable by the user www-data. You may also want to display the JavaScript log console in your web browser by pressing Ctrl + Shift + J.
Autoindex
This part is optional and requires root priviledges. The music player displays the links to the folders name of the current track in the interface. In order for these links to work and not return a 403 Forbidden error, you must enable the Apache module "mod_autoindex". This module lists the content of a folder if no index file is found inside.
First, if the module mod_autoindex isn't active already, do so:
$ sudo a2enmod autoindex
Next edit the configuration file for the correct website. Example with the nano editor and default configuration file:
$ sudo nano /etc/apache2/sites-available/000-default.conf
Add the following line inside the <VirtualHost>, <Directory> or <Location> section of your choice:
Options +Indexes
Restart the Apache server:
$ sudo service apache2 restart
Finally, make sure your music folder is browsable. You now have mod_autoindex working.
Interface
This section details the music player's interface.
Address bar
The web browser's address bar URL is updated to reflect the current playing track. The parameter #track=NUMBER is added at the end of the URL so you can share it with friends, and the music player will load with the selected track.
If you pause the playback, another parameter &time=NUMBER will be added at the end of the URL. Sharing this URL will load the player with the selected track at a pre-selected time.
Track information
This section explains the music player's track information area.
Visualizations
There are three types of visualizations: cover, oscilloscope and spectrum analysis. Right-clicking the visualization or pressing V switches between the three types. On touchscreen, touch and hold the visualization to achieve the same effect. The oscilloscope and spectrum analysis visualizations are affected by the volume setting and mute option.
Cover
Hovering the mouse over the cover displays image information such as the file name, size and the dimensions. Left-clicking the cover opens it in a new tab in full size. The cover is also used to slightly alter the background of the music player.
The music player tries to find the best cover matching the current track. It does so by looking into the same folder (and children folders) of the current track to find an image matching "front", "cover" or "folder" in the file name. On multiple covers, it displays one at random. If none is found, a random image from the same folders will be picked.
The music player may also look up in the parent folder if the current folder name contains something like "disk 01", "CD2" or "Disc THREE", denoting a multi-disc media where the cover might be in the parent folder.
Oscilloscope
The oscilloscope displays the sound signal in the spatial domain.
Known bug: the oscilloscope in dark mode sometimes uses light mode colors on Webkit-based browsers, no fix found.
Spectrum analysis
The spectrum analysis displays the sound signal in the frequency domain.
Folders
The folders part displays the path to the current track, folder by folder in a hierarchy. Each folder is clickable and opens a page listing the files in it, if the web server allows browsing and has mod_autoindex enabled. There you can download files more easily than pressing the download button for each track. You may even use wget to grab entire folders.
Title
The title part displays the current playing track's file name, without extension.
Time
The current time in the track playback is on the left of the position slider. It displays the current time in readable format. Clicking the current time toggles between increasing or decreasing track time. Use T to toggle it.
Duration
The track duration is on the right of the position slider. It displays the track duration in readable format.
Controls
This section details the music player's track controls area.
Position
The position slider allows to navigate through the current playing track. Use ←, B or Shift + MouseWheelUp to rewind 5 seconds. Use →, F or Shift + MouseWheelDown to move forward 5 seconds.
Previous folder
The previous folder button skips to the first track of the previous folder. If the shuffle option is active, the first track of a random folder will be selected. Use PageUp or Ctrl + Shift + ← to achieve the same effect.
Previous track
The previous track button skips to the previous track. If the shuffle option is active, a random track will be selected. Use P, Home or Ctrl + ← to achieve the same effect.
Play/pause
The play/pause button pauses or resumes the audio. Use Space to achieve the same effect.
Stop
The stop button stops playing the audio and rewinds the track to the beginning. Use Escape to achieve the same effect.
Download
Clicking the download button or pressing D starts downloading the current track.
Next track
The next track button skips to the next track. If the shuffle option is active, a random track will be selected. Use N, End or Ctrl + → to achieve the same effect.
Next folder
The next folder button skips to the first track of the next folder. If the shuffle option is active, the first track of a random folder will be selected. Use PageDown or Ctrl + Shift + → to achieve the same effect.
Shuffle
The shuffle option allows random playing. Use S to toggle it. At the end of each track, another one will be selected randomly. If you skip to the previous or next folder when the shuffle option is active, the first track of a random folder will be selected.
Repeat
The repeat option allows to repeat playing the current track. Use R to toggle it.
Volume
This section details the music player's volume area.
Peak meter
The peak meter represents the peak volume of the playback at any time. Its value is affected by the volume setting and mute option.
Volume setting
The volume setting adjusts the playback volume. You can use ↑ and ↓ to change it. The volume setting is disabled when the playback is muted.
Mute
The mute button mutes or unmutes the playback. Use M, Delete or Insert to achieve the same effect.
Playlist
This section details the music player's playlist area.
Search
The search field allows to search in the playlist. The complete path, file name and extension are searched for correspondances with the keywords, even if the simple playlist option is active.
Warning: search may be slow with a big playlist.
Known bug: the search returns only half the results, no fix found.
Reset
The reset button empties the search field and displays the playlist back in full. It also puts the current playing track back in view if you are lost scrolling in the playlist.
Warning: reset may be slow with a big playlist.
Simple playlist
The simple playlist option toggles between a full playlist with the complete path, file name and extension or a lighter playlist with only file name and no extension. Use I to toggle it.
Warning: toggling simple playlist mode may be slow with a big playlist.
Tracks playlist
The tracks playlist displays the available tracks for playing. Click on any track to load and play it. In full mode, the playlist displays the complete path, file name and extension for each track. In simple mode, the playlist displays only the file name without extension.
Help
Click the Help link at the bottom of the music player or press H at any moment to display a help page listing a link to this user manual and the shortcuts of the music player.
A link to this user manual is also provided at the bottom of the music player.
Shortcuts
The following keyboard (and mouse) shortcuts are available in the music player:
- Show/hide the help screen
- H
- Switch visualizations
- V
- Play/pause the current track
- Space
- Stop playing
- Escape
- Download the current track
- D
- Rewind 5 seconds
- ←
- B
- Shift + MouseWheelUp
- Move forward 5 seconds
- →
- F
- Shift + MouseWheelDown
- Skip to the previous track
- P
- Home
- Ctrl + ←
- Skip to the next track
- N
- End
- Ctrl + →
- Skip to the previous folder
- PageUp
- Ctrl + Shift + ←
- Skip to the next folder
- PageDown
- Ctrl + Shift + →
- Increase volume
- ↑
- +
- Decrease volume
- ↓
- -
- Mute/unmute the audio
- M
- Delete
- Insert
- Toggle between increasing or decreasing track time
- T
- Toggle the shuffle option
- S
- Toggle the repeat track option
- R
- Toggle the simple playlist option
- I
Storage
The following variables are saved in the web browser's local storage to preserve the state of the music player after a reload:
- player-index
- The index of the current track in the playlist.
- player-visualization
- The current visualization mode.
- player-timemode
- The current time mode.
- player-shuffle
- The state of the shuffle option.
- player-repeat
- The state of the repeat option.
- player-volume
- The current playback volume.
- player-filter
- The current playlist search string.
- player-simple
- The state of the simple playlist option.
Performances
Depending on the size of the playlist and your computer/device configuration, you may encounter a performance issue or lag with the music player while loading, searching and reseting the playlist and toggling the simple playlist mode. Tested with a 18MB playlist file with more than 110,000 tracks and 31,000 covers, amounting to more than 1.3TB of data.
Known bugs
- The oscilloscope in dark mode sometimes uses light mode colors on Webkit-based browsers. No fix found.
- The search returns only half the results. No fix found.
Change log
- version 0.1:
- First pre-release.
Contact
Please use music-player@dradis.be to contact us. Feedback is appreciated. Say hello!