Music Library & Player

Installation Instructions

To install, do the following:

1. Unzip the source file.
2. The directory should have the following contents:
3. languages > lang-en.php, lang-en-uk.php, lang-es.php, lang-fr.php, lang-de.php
4. favicon.ico
5. file.php
6. functions.php
7. functionsUI.php
8. icons.svg
9. image.php
10. index.php
11. playlist.php
12. README.md
13. script.js.php
14. setup.php
15. style.css
16. Rename the resulting directory if you like. This will be your Music Library & Player directory.
17. Upload the whole directory to the desired location on your web host or local NAS. If installing as an upgrade, overwrite existing files. Any config options added in the new version will have default values loaded. NOTE: There are structural changes in the config file between v2 and v3. Your existing config.php from v2 will not load in v3.
18. Set the configuration options. There is a menu button at the top left of the site which allows easy UI config. If installing as an upgrade, any new config options will load with default values (see previous NOTE). Revisit the config menu to verify after upgrading.
19. Visit the Music Library & Player directory in a browser and enjoy.

System Requirements

• Web accessible directory
• PHP 5.3/7/8
• Web browser that supports HTML5 media
• UTF-8 encoding for all files, especially those in the /languages/ folder
• Music files arranged in this manner (suggested): [ROOT]/[ARTIST]/[ALBUM]/[TRACKS]
• The [ROOT] directory can be located anywhere on the server, it doesn't need to be web accessible

Config options

Click the menu option at the top left of the site and set the following:

Folder & System Settings

• Language. Language files found in /languages folder
• Allow debugging. Enable/Disable the ability to add "&debug=log" to the URL, creating verbose log file.
• Root folder. The relative root where music resides, trailing slash will be removed.
• URL. URL of this Music Library & Player script with port number, if necessary. Trailing slash will be removed.

Folder Content Display Settings

• Playable files only. Only folders with playable tracks will be shown. Requires more processing time for each page load.
• Group folders. Group initial folder list by first letter (#, A, B, C...).

File Handling Options

• Download. Add download link alongside play links.
• M3U playlist. Add M3U stream link. Warning: If your web directory is password protected, most devices will not play an m3u containing those tracks.
• File delivery. Download is simple, but stream is more compatible with mobile.

Playback Behavior

• Autoplay. Begin playing first track automatically. You will still need to give autoplay audio permission in the browser.
• Repeat playlist. Repeat the track or playlist automatically.
• Random count. Number of tracks to include in a random playlist. If there are fewer tracks available, this amount will be adjusted automatically.

Visual Display Options

• Album art. If there is a jpg or png file with the same track name, "folder", or "cover" in the folder where the track resides, image will be displayed in the playlist and below the player.
• Color theme. Light and Dark themes included.

Why this project is maintained privately

Music Library & Player is a personal project that I have developed and refined over many years. It is designed to be lightweight, reliable, and minimal — avoiding unnecessary complexity or feature bloat.

The project was made freely available to the community because I believed it would be useful to others. It is not maintained in a public repository, and direct code contributions are not accepted at this time. This approach helps preserve the project's simplicity, reliability, and intended design philosophy.

If you would like to contribute, you are welcome to submit new language packs for additional translations or submit corrections in the existing machine translated packs. If you have feature suggestions or would like to report a bug, suggest a functional fix, etc. please email or open a ticket here on SourceForge.

A note about coding standards and use

The code contained in this script is written in long form and is well-documented for ease of use and customization.

Individual tracks are presented with optional download links and album art. Minimal effort has been put into limiting the reach of the player and download links. It is limited to the four audio file types that are supported by HTML5 audio. It is advised that you password protect the Music Library & Player directory using htaccess or other method to restrict public access.

You can optionally create m3u playlists. However, if you password protect the Music Library & Player directory, you may not be able to stream from an m3u playlist. Most players will not attempt to play the files. VLC player in particular will pop up a log in form for each track. To fix this, you would have to exclude file.php from password protection via .htaccess or equivalent. Contents of .htaccess would be the following:

<Files file.php>
    Satisfy Any
    Allow from all
</Files>

Release History

3.0.0 - 4/28/2025 - No external /or third-party depencies - Added multi-language support (human generated EN/EN-UK and machine translated ES0 FR, and DE included) - Added support for m3u files in playlist (treat m3u as folder, contents as tracks) - Allow keyboard input (M-mute, SPACE-play/pause, ARROW L/R-prev/next track, ARROW U/D-volume up/down) - Custom player (browser/device agnostic styles and functionality) - Breadcrumbs now fold up into a dropdown list on small screens - Unsupported file types (by browser/OS) are highlighted in playlist - Modernized PHP/JS/CSS while maintaining backward compatibility - Improved debug output - Playable files only option is much faster (1 second page load now vs. 8 second page load in v2.0.6) - Random playlist is now Fisher-Yates shuffle based (in 5x playlists of 20 tracks, 1 repeat now vs 44 in v2.0.6) - NOTE: file structure of config.php has changed slightly, so existing config.php from prior versions will not directly convert.

2.0.6 - 1/21/2024 - Change page title when track plays - Player fixed position at top of the page - Remove list bullets from directory list (drItems class) - Standardize audio player controls across different browsers/devices - Only use file.php for delivery if files are not web accessible - Case-insensitive album art image filename handling - Add support for png album art (track file name, cover, or folder) - Won't play a file with a # sign in the name - Removed html5media script. CDN link at https://api.html5media.info/1.2.2/html5media.min.js is dead. - IN PROGRESS: Remove HTML output from functions

2.0.5 - 12/12/2020 - Clicking directly on the menu button icon doesn't open the menu (svg swallowed the click event) - Play All Tracks In Child Folders button added to breadcrumbs (e.g. play all albums for artist) - Scroll current track into view doesn't scroll far enough - SVG icons don't show title tooltips (removed <title></title> from icons.svg) - getAllTracks() function renamed to getRandomTracks() for clarity - $playable config option omitted from ReadMe.txt Config Options section

2.0.4 - 8/18/2020 - Add support for m4a (audio/mp4) files - Moved file type array to global variable in functions.php

2.0.3 - 8/17/2020 - Shouldn't error if config.php doesn't exist on first load - New config option to only show directories with playable files - My music directory contains 97 subdirectories with playable files - $playable = true - Home page rendered in 1.22 seconds - $playable = false - Home page rendered in 802 milliseconds

2.0.2 - 5/17/2020 - Undefined variable linkStart - New function getTrackCountRecursive($dir) - Don't show directories or random playlist link when below the Music Library & Player root - Don't show directories or random playlist link when there are no playable tracks - Move stylesheet higher in page load sequence to avoid white flashes on load in directory - Show link to MLP root in breadcrumbs if below root or no playable tracks

2.0.1 - 9/24/2019 - trackmode=track won't play without autoplay=true - Missing favicon (404) - Javascript errors in Chrome (index.php > menuClose & liClick )

2.0.0 - 6/30/2019 - Complete redesign - Removed jwplayer - Removed bootstrap - Removed jquery - Added html5media script for browser compatibility - Reduced number of config options - Added Light and Dark themes - Easily install upgrades non-destructively - Added menu button to easily access config options - Added back to top button - Performance increase - fast & lightweight: - Version 2.0.0 - 5 file requests, 43.20KB transferred, 388 milliseconds - Version 1.1.6 - 95 file requests, 563.44KB transferred, 2.18 seconds - Smaller footprint on disk: - Version 1.1.6 - 127 files, 1.34MB - Version 2.0.0 - 12 files, 72.1KB

1.1.6 - 4/17/2019 - Random playlist can add empty tracks - File extensions still showing in random and track playlist

1.1.5 - 4/15/2019 - Album art isn't shown in single track mode - Album art isn't debugging properly - Hide file extensions in playlist

1.1.4 - 4/13/2019 - Display album art (trackname.jpg/folder.jpg/cover.jpg) - Added image.php for delivering album art - Don't underline links on hover - Folder with no tracks missing a <br> in between breadcrumbs and folder list - Some more general code cleanup

1.1.3 - 6/2/2018 - .htaccess file accidentally included in 1.1.2 release. - Removed unnecessary global $debug declarations - "&" character wasn't being escaped when parsing directory names - Random playlists don't work properly when there are fewer subdirectories than playlist count setting - setup.php adds a UI to help set initial configuration - New "debugging" config option allows you to disable verbose logging from "&debug=log" or "?debug=log" in the URL

1.1.2 - 1/21/2018 - displayDirectories() was being called when not used in playmode=random - Added global variables to keep the same function from being called multiple times - Random playlists don't recurse all directories and are very slow - Unset() variables to free memory along the way in resource-intensive functions - Cleaned up code to avoid PHP notices and warnings

1.1.1 - 11/4/2016 - Config options accidentally removed from ReadMe.txt - Random playlist count is now configurable - Adjust random count if fewer tracks are available - Random playlist now available from any directory that has files or subdirectories

1.1.0 - 11/3/2016 - Random Playlist can now be called from any location with more than one subdirectory - New function getAllTracks() used to generate random playlist

1.0.9 - 10/22/2016 - New "File Delivery" option in config.php allows download (old) or stream (new) - Refactored separate playlist functions into one - Random Playlist icon changed - Handle track links with proper bootstrap syntax - Playlist missing </ul> - &debug=log missing from random playlist link - cleanPath() is only needed in GetFiles() method - Playlist tracks are not links when downloads enabled - Removed gaps between grouped folder headers - Removed play and stream buttons from breadcrumbs when play mode is random - Added "Random Playlist" text to breadcrumbs when play mode is random - Changed shownowplaying() function to handle both <li and <a playlist items

1.0.8 - 10/20/2016 - New random playlist mode from music player root - Active track is not highlighted in playlist - When download links are disabled, entire row in playlist becomes link - GetList debug log is not nested properly and shows last track repeated - Changed config.php to config.default.php to make installing upgrades easier - Improved layout of JWPlayer 6 or 7 options in config

1.0.7 - 10/9/2016 - Switch file download to file streaming (now works on iOS and Android browsers) - Option to use JWPlayer version 6 or 7 - Download link option was ignored (always shown)

1.0.6 - 4/30/2016 -Replaced use of urlencode() and urldecode() with rawurlencode() and rawurldecode() because the space encoded as + was causing errors

1.0.5 - 2/23/2015 - Only show player row at the top of the page if something is playing - Freeze player row at the top of the page - Animated scroll up or down as necessary to show currently playing track

1.0.4 - 2/16/2015 - Current playing track not highlighted properly in track vs folder playmode

1.0.3 - 12/21/2014 - Moved debug check up higher in index.php because getWebRoot() was being called before debugging was enabled - getWebRoot() was not working correctly. - Now playing designation added to playmode=track

1.0.2 - 12/19/2014 - Gave the mlp skin a facelift - Removed extra images from the mlp skin - Enabled verbose logging from URL query string (add &debug=log or ?debug=log to the URL query string)

1.0.1 - 12/18/2014 - Replaced empty col-md-2 with col-md-offset-2 - Removed "Now Playing" icon from the playlist - Added option to group main list by first letter using Bootstrap collapse element - Added optional m3u download (won't work in a password protected directory) - Download links are now optional

1.0.0 - 12/16/2014 Initial release

License Information

Music Library & Player Copyright (c) 2025 James Moats - james@willowlakestudio.com - www.thejamesmachine.com

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.