PHP Music

A simple, fast, and modern self-hosted music player built entirely in a single PHP file.

Galleries

Introduction

PHP Music is an open-source, web-based, self-hosted music platform contained entirely within index.php. By utilizing an embedded SQLite database (music.db), it offers a seamless deployment experience. It boasts a beautiful dark UI inspired by YouTube Music, complete with user accounts, metadata editing, synchronized lyrics, PWA support, dynamic playlists, auto-generated mixes, and extensive social sharing functionality.

🎵 Scan & Play: Recursively scans your directory for mp3, m4a, flac, ogg, and wav files.
🔒 User Accounts: Secure registration, profile management, backup key restore features, and upload quotas.
📱 Progressive Web App (PWA): Dynamic Service Worker caches assets for offline browsing.
✏️ Metadata Editor & Lyrics: Edit ID3 tags (Title, Artist, Album, Genre, Lyrics) and view synchronized LRC lyrics in real-time.
🔗 Social Ecosystem: Follow artists, copy playlists, and share direct links instantly.

Features

Library Management

Browse by songs, artists, albums, or genres. Infinite scrolling, rapid local search, and diverse sorting options (A-Z, Year, Date Added).

ID3 Tags & Lyrics

Modify a song's metadata directly from the browser. Supports viewing and embedding synchronized LRC lyrics. Changes update the database and use getID3 to physically rewrite the tags inside the audio file.

Playlists & Favorites

Create custom playlists. Drag-and-drop to visually reorder your lists using SortableJS. Import/export entire playlists and favorites as portable JSON files.

Playlist Downloader

Built-in sequential downloader interface. Batch download entire playlists to your local device with real-time logging, or grab single tracks instantly.

Protected Uploads

Upload multiple songs simultaneously. Features a daily limit (default: 10 songs/day, resets at midnight) and requires explicit admin verification.

Account Recovery

Keep your data safe with advanced account management. Generate backup keys to wipe your credentials while preserving your music data, allowing seamless account restoration later.

Image Optimization

Profile pictures and embedded album arts are automatically extracted, squared, resized (to 500x500 or 200x200), and converted to WebP to drastically save bandwidth.

Smart Recommendations

The "For You" tab generates personalized shelves and auto-mixes based on your listening history (logs play after 30 seconds), top genres, and followed artists.

Installation & Setup

Clone the repository:

git clone https://github.com/HirotakaDango/PHP-Music.git
cd PHP-Music

Dependencies: Ensure PHP 7.4+ is installed. Download the latest getID3 library and extract it into a getid3/ folder inside the project root.
Enable SQLite in PHP: PHP Music runs entirely on SQLite. If you are using XAMPP/LAMPP, you may need to enable it manually.
- XAMPP (Windows/macOS): Open xampp/php/php.ini and remove the semicolon (;) before extension=pdo_sqlite and extension=sqlite3. Restart Apache.
- LAMPP (Linux): Open /opt/lampp/etc/php.ini, uncomment the same extensions, and run sudo /opt/lampp/lampp restart.
Permissions: PHP must have write permissions to the project directory to create music.db and the uploads/ folder.
```
chmod -R 777 . # Use appropriate permissions based on your environment
```
Run the app:
```
php -S localhost:8080
```
Open http://localhost:8080 in your browser. Register an account, log into the admin panel (?access=admin, password: admin) to verify yourself, and hit "Scan All" to build your library.

Security Tip: Change the ADMIN_PASSWORD constant in index.php before deploying to a public server!

Usage

Accounts & Verification: Registering an account allows you to track history, save favorites, and create playlists. To upload music, an admin must toggle your verification status to "yes".
Playback & Media Keys: The player utilizes the browser's Media Session API. You can control playback in the background using your keyboard media keys or mobile lock screen. Holding the "Next" or "Previous" buttons on the UI skips forward/backward by 5 seconds.
Playlists & Reordering: Inside any playlist or your Favorites tab (when sorted by "My Order"), simply click and drag a song to reposition it. The new order is immediately saved to the database.
Import/Export & Downloading: You can backup your playlists and favorites to a portable JSON file. You can also use the integrated Downloader tool to sequentially download an entire playlist directly to your hard drive, or download single tracks via the song context menu.
Edit Metadata & Lyrics: Click the context menu on a song you uploaded (or as admin) and choose "Edit Info" to change Title, Artist, Album, Genre, Lyrics, and Cover Art. You can also view lyrics via "Show Lyrics" or check file details via "View Metadata".
- Adding Synchronized Lyrics (LRC): When adding timestamps, ensure there is a space between the timestamp and the lyric text so the code parses it correctly.
  Correct [00:15.30] Never gonna give you up
  
  Incorrect [00:15.30]Never gonna give you up
Delete & Download: Use the context menu on any of your uploaded songs to delete it from the library or download the original file to your device.
Sharing: Click the share icon on an album, artist, or playlist. PHP Music generates direct query parameters (e.g., ?share_type=album&album_name=...) that launch directly into that specific view for anyone with the link.
App Cache: If the UI updates but you see old data, use the "Clear Cache" button in the sidebar. This wipes the IndexedDB app version cache and unregisters the Service Worker dynamically.

How It Works

PHP Music is architected to minimize dependencies while maximizing performance and features:

Single File Execution: The index.php file handles both the frontend HTML/JS/CSS payload and the backend REST-like JSON API via the ?action= parameter.
Database Schema: SQLite is used for zero-config persistence. The core tables include:
- users: Authentication, profile pictures (stored as WebP blobs), upload quotas, and verification status.
- music: Cached metadata (Title, Album, Genre, Duration, Bitrate) and embedded album arts (WebP blobs).
- favorites & playlist_songs: Pivot tables handling user relations and manual sort_order.
- history & play_counts: Logs exact timestamps of playback (triggered after 30 seconds of listening) to fuel the recommendation engine.
- follows: Tracks user-to-artist and user-to-user following relationships.
Caching & PWA: A Service Worker (?pwa=sw) caches static assets (Bootstrap, Fonts, HTML payload) using a Cache-First strategy. API calls and audio streams bypass the Service Worker to guarantee live data and HTTP Range support.
Audio Streaming: The get_stream endpoint natively handles HTTP_RANGE requests, allowing browsers to seek through audio files without downloading the entire file first.

Admin Panel

Access the administrative dashboard by appending ?access=admin to your URL. Log in using the admin password.

User Management: View a paginated list (20 users/page) of all registered users.
Verification: Toggle the verification status of users. Unverified users cannot bypass the daily upload restriction.
Ban System: Suspend malicious users immediately. Banned users are completely locked out of the application.
Analytics: Monitor the Last Upload Date and Daily Upload Count of each user to prevent abuse.
The "Music Library" User: Files scanned locally via "Scan All" are automatically assigned to a hidden system user named "Music Library" (ID is dynamically assigned).

API Endpoints

The backend operates via GET/POST requests targeting ?action=.... All responses (except file streams and images) return strict JSON.

Endpoint	Method	Description
`get_session`	GET	Returns active user profile, daily limits, and auth status.
`register` / `login`	POST	Handles authentication. Requires JSON payload (email, password).
`restore_account`	POST	Restores an account mapping using a generated backup key.
`delete_account_keep_data`	GET	Wipes user credentials and email, but keeps user data and generates a backup key.
`upload_profile_picture`	POST	Accepts Multipart form data. Crops image 1:1, resizes to 200px, converts to WebP.
`full_scan`	GET	Recursively syncs disk files with the DB. Triggers getID3 parser for missing files.
`upload_song`	POST	Accepts MP3/FLAC/OGG. Parses ID3 tags immediately. Checks daily limit.
`edit_metadata`	POST	Updates DB and writes ID3v2/Vorbis tags (including lyrics) directly into the audio file.
`get_songs`	GET	Returns paginated songs. Supports parameters: `sort`, `page`, `artist`, `album`, `genre`, `filter_user_id`.
`get_view_data`	GET	Aggregates data for deep links. Supports types: `profile`, `playlist`, `artist`, `album`.
`get_recommendations`	GET	Generates "For You" shelves based on `play_counts`, `history`, and `follows`.
`log_play`	POST	Logs a playback event to the user's history array.
`clear_history`	GET	Wipes all play history and play counts for the logged-in user.
`toggle_favorite`	POST	Adds/removes a song from favorites.
`toggle_follow`	POST	Follows/unfollows a target user or artist.
`update_favorite_order`	POST	Accepts an array of Song IDs to rewrite the `sort_order` column.
`create_playlist`	POST	Generates a new playlist with a unique 8-byte hexadecimal `public_id`.
`copy_playlist`	POST	Clones another user's public playlist into the active user's account.
`export_playlist` / `export_favorites`	GET	Generates a downloadable JSON representation of a playlist or favorites.
`import_playlist` / `import_favorites`	POST	Parses an uploaded JSON file, matches DB files, and builds a new playlist or favorites list.
`download_song`	GET	Downloads the specific song audio file as an attachment.
`get_stream`	GET	Streams the physical audio file with 206 Partial Content (HTTP Range) support.

Troubleshooting & FAQ

Ensure the getid3/ directory exists and is accessible. Make sure PHP has read/write permissions for the local files and the project root (to create music.db). If using XAMPP/LAMPP, ensure SQLite extensions are activated in php.ini.

Make sure the uploads/ directory is writable. Check your php.ini settings for upload_max_filesize and post_max_size and ensure they are large enough (e.g., 50M) to accommodate FLAC or WAV files. Also, verify your account is verified by the admin!

If the database updates but the physical file tags do not change, check the file permissions of the specific MP3/FLAC file. PHP needs write permissions to the file to utilize the getID3 tag writer.

Some files may lack embedded images. The app uses a default SVG icon as a fallback. You can manually assign a cover via the "Edit Metadata" context menu option (requires a 1:1 cropped image).

PHP Music supports the standard LRC format for synchronized lyrics. If your lyrics appear as plain text instead of syncing with the playback, ensure that each timestamp is followed by a space. For example, use [00:15.30] Lyric text instead of [00:15.30]Lyric text.

PHP Music

Galleries

Scan Errors or Empty Library

Upload Errors (File too large)

Metadata Not Saving

Missing Album Art

Lyrics are not synchronizing with the song