# memeshift/mplayer architecture

> Architecture diagram of the GitHub repository memeshift/mplayer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/memeshift/mplayer
- Repository: https://github.com/memeshift/mplayer

## Overview

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.

Main entry points: [`index.html`](https://github.com/memeshift/mplayer/blob/main/index.html) (Player UI), [`embed.php`](https://github.com/memeshift/mplayer/blob/main/embed.php) (Embed Player), [`config.php`](https://github.com/memeshift/mplayer/blob/main/config.php) (Runtime Config), [`art.php`](https://github.com/memeshift/mplayer/blob/main/art.php) (Album Art)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Browser UI"]
  node_index["Player UI<br/>frontend app<br/>[index.html]"]
  node_audio(("Audio Player<br/>html5 audio"))
  node_storage(("Prefs Store<br/>browser storage"))
  node_session(("Media Session<br/>browser api"))
end

subgraph group_server["PHP Backend"]
  node_scan["Track Scan<br/>json endpoint<br/>[scan.php]"]
  node_art["Album Art<br/>asset endpoint<br/>[art.php]"]
  node_embed["Embed Player<br/>mini player<br/>[embed.php]"]
  node_id3["Tag Parser<br/>metadata lib<br/>[id3.php]"]
  node_library[("Music Files<br/>content store")]
end

subgraph group_config["Deployment"]
  node_config["Runtime Config<br/>settings<br/>[config.php]"]
  node_htaccess["Web Policy<br/>server rules<br/>[.htaccess]"]
  node_readme["Docs<br/>documentation<br/>[README.md]"]
end

subgraph group_assets["Branding"]
  node_manifest["Web Manifest<br/>pwa manifest<br/>[site.webmanifest]"]
  node_favicons(("Favicons"))
end

node_index -->|"loads playlist"| node_scan
node_index -->|"plays tracks"| node_audio
node_audio -->|"streams MP3s"| node_library
node_index -->|"fetches art"| node_art
node_art -->|"reads tags"| node_library
node_index -->|"persists prefs"| node_storage
node_index -->|"registers controls"| node_session
node_index -->|"shares embeds"| node_embed
node_embed -->|"parses metadata"| node_id3
node_embed -->|"loads track"| node_library
node_scan -->|"uses paths"| node_config
node_art -->|"uses paths"| node_config
node_embed -->|"uses paths"| node_config
node_htaccess -->|"protects config"| node_config
node_htaccess -->|"hardens library"| node_library
node_index -->|"declares pwa"| node_manifest
node_index -->|"brands ui"| node_favicons
node_readme -->|"documents"| node_index
node_readme -->|"documents"| node_scan

click node_index "https://github.com/memeshift/mplayer/blob/main/index.html"
click node_scan "https://github.com/memeshift/mplayer/blob/main/scan.php"
click node_art "https://github.com/memeshift/mplayer/blob/main/art.php"
click node_embed "https://github.com/memeshift/mplayer/blob/main/embed.php"
click node_id3 "https://github.com/memeshift/mplayer/blob/main/id3.php"
click node_config "https://github.com/memeshift/mplayer/blob/main/config.php"
click node_htaccess "https://github.com/memeshift/mplayer/blob/main/.htaccess"
click node_readme "https://github.com/memeshift/mplayer/blob/main/README.md"
click node_manifest "https://github.com/memeshift/mplayer/blob/main/site.webmanifest"
click node_favicons "https://github.com/memeshift/mplayer/tree/main/favicons"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_index,node_audio,node_storage,node_session toneBlue
class node_scan,node_art,node_embed,node_id3,node_library toneAmber
class node_config,node_htaccess,node_readme toneMint
class node_manifest,node_favicons toneRose
```

## Components

### Browser UI

Main player experience delivered in the browser.

- [Player UI](https://github.com/memeshift/mplayer/blob/main/index.html): frontend app · Single-file browser app with playback, playlist, sorting, theming, sharing, visualizer, and keyboard/media controls. · `index.html`
- **Audio Player**: html5 audio · Browser playback runtime that streams MP3s directly from the web server.
- **Prefs Store**: browser storage · Persists client preferences such as theme selection.
- **Media Session**: browser api · Integrates playback state with system and lock-screen media controls.

### PHP Backend

Filesystem-backed metadata, art, and embed endpoints.

- [Track Scan](https://github.com/memeshift/mplayer/blob/main/scan.php): json endpoint · Scans the music directory, reads tags, and emits the playlist as JSON. · `scan.php`
- [Album Art](https://github.com/memeshift/mplayer/blob/main/art.php): asset endpoint · Serves embedded artwork extracted from MP3 tags with server-side validation. · `art.php`
- [Embed Player](https://github.com/memeshift/mplayer/blob/main/embed.php): mini player · Standalone iframe-friendly player for a single track shared via query parameter. · `embed.php`
- [Tag Parser](https://github.com/memeshift/mplayer/blob/main/id3.php): metadata lib · Shared ID3 parsing logic used for consistent track metadata handling. · `id3.php`
- **Music Files**: content store · Server-hosted MP3 collection that defines the app's playable content and state.

### Deployment

Runtime settings and web-server policy.

- [Runtime Config](https://github.com/memeshift/mplayer/blob/main/config.php): settings · Central deployment settings for music paths, allowed extensions, and cache behavior. · `config.php`
- [Web Policy](https://github.com/memeshift/mplayer/blob/main/.htaccess): server rules · Hardens deployment with access restrictions and security headers. · `.htaccess`
- [Docs](https://github.com/memeshift/mplayer/blob/main/README.md): documentation · Repository documentation and usage notes. · `README.md`

### Branding

Install metadata and icon assets.

- [Web Manifest](https://github.com/memeshift/mplayer/blob/main/site.webmanifest): pwa manifest · PWA metadata for install behavior and app identity. · `site.webmanifest`
- [Favicons](https://github.com/memeshift/mplayer/tree/main/favicons): icons · Browser icon assets for branding and install surfaces. · `favicons`

## Connections

- Player UI → Track Scan: loads playlist · Browser requests track metadata as JSON.
- Player UI → Audio Player: plays tracks · UI controls HTML5 audio playback directly.
- Audio Player → Music Files: streams MP3s · Audio source points at files served from the music library.
- Player UI → Album Art: fetches art · UI loads album artwork for lists and track details.
- Album Art → Music Files: reads tags · Artwork is extracted from the underlying MP3 files.
- Player UI → Prefs Store: persists prefs · Theme and related client preferences are stored locally.
- Player UI → Media Session: registers controls · Exposes playback state to the browser media session.
- Player UI → Embed Player: shares embeds · Generates deep links and iframe snippets for sharing.
- Embed Player → Tag Parser: parses metadata · Embed player uses shared ID3 parsing logic.
- Embed Player → Music Files: loads track · Embed resolves a single file from the music library.
- Track Scan → Runtime Config: uses paths · Scan endpoint relies on configured library location and allowed extensions.
- Album Art → Runtime Config: uses paths · Artwork endpoint uses the configured filesystem mapping.
- Embed Player → Runtime Config: uses paths · Embed endpoint is driven by deployment path settings.
- Web Policy → Runtime Config: protects config · Server rules keep sensitive configuration from being exposed directly.
- Web Policy → Music Files: hardens library · Server policy disables directory listing and PHP execution in the content folder.
- Player UI → Web Manifest: declares pwa · Browser app is installable through manifest metadata.
- Player UI → Favicons: brands ui · Browser UI uses icon assets for tabs and install surfaces.
- Docs → Player UI: documents · Documentation describes the main player experience.
- Docs → Track Scan: documents · Documentation explains metadata scanning behavior.