memeshift/mplayer

1. Overall shape

- This is a self-hosted PHP music player with a very clear split: a single-file browser frontend in index.html, plus a few PHP endpoints that read MP3 files directly from disk.

- There is no database, no upload flow, and no build pipeline. The server-side state is the music/ folder itself.

2. Primary runtime boundary

- The browser is responsible for the full UI, playback controls, sorting, theming, visualizer, and sharing.

- PHP is only used for filesystem-backed metadata and asset serving: scanning tracks, extracting album art, and loading single-track embed pages.

3. Main frontend subsystem

- index.html contains the complete main player UI and all client-side logic.

- It owns playlist rendering, transport controls, theme switching, deep-link handling, mobile layout behavior, Spectrum visualizer, keyboard shortcuts, Media Session integration, and localStorage persistence for theme choice.

4. Track discovery and metadata flow

- scan.php scans the configured music directory on the server, reads ID3 tags, and returns the playlist as JSON.

- The browser consumes that JSON to build the track list and track info panel.

- Track order starts from the scan result, then the UI can re-sort by Artist, Album, or Year.

5. Shared tag parsing

- id3.php contains the shared ID3 parsing logic used by embed.php.

- The same parsing behavior also exists in scan.php, but embed.php cannot include scan.php because scan.php is a JSON-emitting endpoint.

- This creates a small shared parsing boundary for consistent metadata handling across the main player and embeds.

6. Audio delivery path

- Actual audio playback is browser-based through HTML5 <audio>.

- The frontend points to the MP3 files under the configured music/ URL path, so the browser streams files directly from the web server.

- The PHP app does not proxy audio; it only exposes metadata and embedded art.

7. Album art and supporting media

- art.php serves embedded album artwork extracted from MP3 ID3 tags.

- The UI uses this for thumbnails and track detail views.

- The README indicates image validation is done server-side before serving, which keeps art delivery separate from track streaming.

8. Embed/share subsystem

- embed.php is a separate mini-player intended for <iframe> embeds on external sites.

- It loads a single track via ?t=filename.mp3 and uses the same filesystem/tag constraints as the main player.

- The main UI generates shareable direct links and embed snippets that point at this endpoint and the deep-link track parameter.

9. Configuration boundary

- config.php centralizes environment-specific settings: absolute music directory, public music URL, allowed extensions, and cache TTLs.

- This file is intentionally the only one expected to be edited for deployment.

- The rest of the app depends on these constants, so deployment is mainly a path-mapping problem.

10. Security and server policy

- .htaccess hardens the deployment by blocking direct access to sensitive files like config.php and applying security headers.

- music/.htaccess disables directory listing and PHP execution inside the content folder.

- Endpoint code validates paths with realpath() / basename checks, and only allowed extensions are accepted.

11. PWA and static assets

- site.webmanifest and the favicons/ directory provide app-like install and branding support.

- These are supportive assets rather than core logic, but they matter for how the player is surfaced on mobile and desktop browsers.

12. Data flow summary

- The browser loads index.html → calls scan.php for the playlist JSON → streams MP3s from music/ → fetches art via art.php when needed.

- If the user shares an embed, external sites load embed.php, which reads the same music files and tag data through the shared parser.

- The entire system is therefore a simple content-driven architecture centered on a server folder of MP3s plus a thin PHP metadata layer.