# googlearchive/drive-music-player architecture

> Architecture diagram of the GitHub repository googlearchive/drive-music-player, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/googlearchive/drive-music-player
- Repository: https://github.com/googlearchive/drive-music-player

## Overview

##### Project type and purpose (what you’re diagramming)
This repo is a **fully client-side web application** (static HTML/CSS/JS) that acts as a **music player for audio files stored in Google Drive**. There is **no server-side backend** owned by the project. The “system” is essentially:

- A **browser-based SPA-ish app** (index.html + JS modules)
- Integrations with **Google Drive APIs / Google OAuth** (to list/read files)
- Optional integration with **Last.fm** (scrobbling/metadata)
- Local parsing of audio metadata (ID3/AAC tags) and playback via a JS audio player library

##### Top-level entrypoints / app shell
- `index.html` → app shell, bootstraps scripts and UI container.
- `css/drive-music-player.css` → core styling.
- `images/` → cursors/visual assets.

##### Application logic (your “modules” / “layers”)
All under `js/`:
- `js/dmp.js` → likely the main orchestrator / app bootstrap.
- `js/dmp.ui.js` → UI rendering, event binding, view updates.
- `js/dmp.player.js` → playback control (play/pause/seek/volume), probably wraps jPlayer.
- `js/dmp.playlist.js` → playlist model, ordering, navigation between tracks.
- `js/dmp.drive.js` → Google Drive integration: auth/session, file listing, file download/stream URLs, “Open with” flow.
- `js/dmp.lastfm.js` → Last.fm integration (scrobbling or metadata).
- `js/dmp.url.js` → URL/state management (deep links, query params, Drive “open with” ids).
- `js/base64.js` → utility.

These strongly suggest drawing an internal separation:
- **UI layer**
- **Domain layer** (playlist/player state)
- **Integration layer** (Drive, Last.fm)
- **3rd-party libraries**

##### Third-party libraries (explicit vendor components)
Under `third-party/`:
- `third-party/jplayer/…` (and `swfobject/…`) → playback engine (HTML5 audio + fallback Flash).
- `third-party/id3-tag-reader/…` + `third-party/jdataview/…` → client-side binary parsing and tag extraction (ID3v1/v2, MP4/AAC tags).

- `manifest.json`, `manifest.webapp` → web app / installable app metadata.
- `cws/manifest.json` + `cws/*` assets → Chrome Web Store packaging for the app/extension.
- `app.yaml` → likely Google App Engine config for static hosting at driveplayer.com (even though no backend logic, hosting still exists).
These imply multiple “delivery channels”:
- Static hosting (App Engine or similar)
- Chrome Web Store distribution
- “Open with Google Drive” integration

##### README-derived architecture constraints and flows
Key constraints from README:
- “**Entirely client side** and does not require any server side component.”
- Supports “**Open-with** from Google Drive UI” → there’s an inbound launch context from Drive (fileId(s), state, and auth).
- Plays multiple audio formats and reads tags → requires **binary fetch of file content** + parsing + UI updates.
- “Handles users signed-in multiple Google account” → implies an **auth/session manager** inside `dmp.drive.js` (token handling, account switching).

- Browser ↔ Google OAuth
- Browser ↔ Google Drive API (metadata listing + file content download/stream)
- Browser ↔ Last.fm API (optional)
- Internal: Player ↔ Playlist ↔ UI, and Tag Reader ↔ UI/Playlist

##### App load
- User Browser → Static Hosting → delivers `index.html`, `css`, `js`, `third-party/*`

##### Authentication
- Drive Music Player → Google OAuth → returns access token
- Token stored/managed inside Drive integration module

##### File discovery & open-with
- (Path A) User opens app normally:
- App → Google Drive API: list files/folders / search audio
- (Path B) User uses “Open with” in Drive:
- Google Drive UI → launches app with fileId(s) (URL params/state) → `dmp.url.js`/`dmp.drive.js` consumes it

##### Playback
- App → Google Drive API: fetch file bytes / stream URL
- Player module → jPlayer: decode/play audio in browser (Flash fallback via SWFObject, if applicable)

##### Metadata extraction (tags + album art)
- App obtains file bytes (or partial range) → ID3 Tag Reader/jDataView → returns tags/art
- Metadata → UI module (now playing info) and/or Playlist module (track listing)

##### Scrobbling / external metadata (optional)
- App → Last.fm API: scrobble “now playing” / track played events

##### Architectural patterns used
- **Client-only architecture**: no custom backend; all state and logic in browser.
- **Modular JS design**: separate modules for UI, player, playlist, integrations.
- **External-API-driven**: Drive API is the “data store” and content source.
- **Library-wrapped playback**: app logic wraps jPlayer; parsing wraps ID3 reader.

- HTML/CSS/JavaScript
- Google Drive API + OAuth 2.0
- jPlayer (HTML5 Audio + Flash fallback)
- ID3 tag parsing (id3-tag-reader, jDataView)
- Last.fm API (optional)
- Chrome Web Store packaging + “Open with Drive” integration

2) **Packaging & deployment context** (how it’s shipped: App Engine hosting + Chrome Web Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Deployment / Distribution
%% =========================
subgraph "Packaging & Deployment Context (not runtime logic)"
direction TB

subgraph "Static Hosting"
direction TB
Host["Static Hosting (App Engine)"]:::hosting
AppYaml["app.yaml"]:::hosting
Host -->|"configures"| AppYaml
end

subgraph "Install / Manifest Metadata"
direction TB
ManifestJson["Web App Manifest (manifest.json)"]:::hosting
ManifestWebapp["Web App Manifest (manifest.webapp)"]:::hosting
end

subgraph "Chrome Web Store Distribution"
direction TB
CWS["Chrome Web Store Package (cws/)"]:::hosting
CWSManifest["CWS Manifest (cws/manifest.json)"]:::hosting
CWS -->|"includes"| CWSManifest
end

end

%% =========================
%% Runtime Host
%% =========================
User["User"]:::external

subgraph "Runtime: User Browser (Chrome)"
direction TB

subgraph "Drive Music Player (Client-side Web App)"
direction TB

subgraph "App Shell"
direction TB
IndexHtml["index.html (App Shell)"]:::owned
CSS["CSS (drive-music-player.css)"]:::owned
Images["Images (cursors/assets)"]:::owned
end

subgraph "Owned JS Modules (js/)"
direction TB
DMP["App Bootstrap / Controller (dmp.js)"]:::owned
UI["UI Renderer / Event Binding (dmp.ui.js)"]:::owned
URL["URL / Launch Context (dmp.url.js)"]:::owned
Drive["Google Drive Integration (dmp.drive.js)"]:::owned
Playlist["Playlist Model (dmp.playlist.js)"]:::owned
Player["Player Facade (dmp.player.js)"]:::owned
LastFM["Last.fm Client (dmp.lastfm.js)"]:::owned
Base64["Utility (base64.js)"]:::owned
end

subgraph "Third-party Libraries (third-party/)"
direction TB

subgraph "Playback Engine"
direction TB
JPlayer["jPlayer (HTML5 Audio)"]:::thirdparty
JPlayerSWF["jPlayer SWF (Flash fallback)"]:::thirdparty
SWFObject["SWFObject (Flash embed/support)"]:::thirdparty
JPlayerSkin["jPlayer Skin/CSS"]:::thirdparty
end

subgraph "Metadata Extraction"
direction TB
ID3["ID3 Tag Reader (id3.js)"]:::thirdparty
ID3v1["ID3v1 Parser (id3v1.js)"]:::thirdparty
ID3v2["ID3v2 Parser (id3v2.js)"]:::thirdparty
ID4["MP4/AAC Parser (id4.js)"]:::thirdparty
JDataView["Binary Data Reader (jdataview.js)"]:::thirdparty
end

end

end

end

%% =========================
%% External Services
%% =========================
subgraph "External Services"
direction TB
OAuth["Google Identity / OAuth 2.0"]:::external
DriveAPI["Google Drive API (metadata + file content)"]:::external
DriveUI["Google Drive UI (Open with...)"]:::external
LastFMAPI["Last.fm API (scrobble/metadata)"]:::external
end

%% =========================
%% Delivery flow
%% =========================
User -->|"opens app"| Host
Host -->|"serves static assets"| IndexHtml
IndexHtml -->|"loads"| CSS
IndexHtml -->|"loads"| Images
IndexHtml -->|"loads"| DMP

%% =========================
%% Internal module wiring
%% =========================
DMP -->|"initializes"| UI
DMP -->|"initializes"| URL
DMP -->|"initializes"| Drive
DMP -->|"initializes"| Playlist
DMP -->|"initializes"| Player
DMP -->|"initializes"| LastFM

UI <-->|"events/state updates"| DMP
UI <-->|"playlist rendering"| Playlist
UI <-->|"player controls"| Player

URL -->|"launch context (fileIds/state)"| DMP
URL -->|"open-with params"| Drive

Drive -->|"supplies track list/ids"| Playlist
Playlist -->|"selects next/prev track"| Player

Player -->|"wraps"| JPlayer
JPlayer -->|"fallback via"| SWFObject
JPlayer -->|"may use"| JPlayerSWF
JPlayer -->|"styled by"| JPlayerSkin

Drive -->|"audio bytes/stream"| Player
Drive -->|"file bytes (for tags)"| ID3
ID3 -->|"uses"| JDataView
ID3 -->|"parses via"| ID3v1
ID3 -->|"parses via"| ID3v2
ID3 -->|"parses via"| ID4
ID3 -->|"tags/album art"| UI
ID3 -->|"track metadata"| Playlist

Base64 -->|"utility used by"| DMP
Base64 -->|"utility used by"| Drive

%% =========================
%% Auth + API flows
%% =========================
Drive -->|"OAuth request"| OAuth
OAuth -->|"OAuth token"| Drive

Drive -->|"file list metadata (JSON)"| DriveAPI
DriveAPI -->|"file list results"| Drive

Drive -->|"file content fetch (bytes/stream)"| DriveAPI
DriveAPI -->|"audio bytes/stream"| Drive

DriveUI -->|"launches app (Open with) + fileId(s)"| URL

%% =========================
%% Last.fm (optional)
%% =========================
Player -->|"now playing/track played"| LastFM
LastFM -->|"scrobble event"| LastFMAPI
LastFMAPI -->|"scrobble response"| LastFM

%% =========================
%% Context connections (distribution)
%% =========================
CWS -->|"distributes"| IndexHtml
ManifestJson -->|"install metadata for"| IndexHtml
ManifestWebapp -->|"install metadata for"| IndexHtml

%% =========================
%% Click Events (component mappings)
%% =========================
click IndexHtml "https://github.com/googlearchive/drive-music-player/blob/master/index.html"
click CSS "https://github.com/googlearchive/drive-music-player/blob/master/css/drive-music-player.css"
click Images "https://github.com/googlearchive/drive-music-player/tree/master/images/"

click DMP "https://github.com/googlearchive/drive-music-player/blob/master/js/dmp.js"
click UI "https://github.com/googlearchive/drive-music-player/blob/master/js/dmp.ui.js"
click Player "https://github.com/googlearchive/drive-music-player/blob/master/js/dmp.player.js"
click Playlist "https://github.com/googlearchive/drive-music-player/blob/master/js/dmp.playlist.js"
click Drive "https://github.com/googlearchive/drive-music-player/blob/master/js/dmp.drive.js"
click LastFM "https://github.com/googlearchive/drive-music-player/blob/master/js/dmp.lastfm.js"
click URL "https://github.com/googlearchive/drive-music-player/blob/master/js/dmp.url.js"
click Base64 "https://github.com/googlearchive/drive-music-player/blob/master/js/base64.js"

click JPlayer "https://github.com/googlearchive/drive-music-player/blob/master/third-party/jplayer/js/jquery.jplayer.js"
click JPlayerSWF "https://github.com/googlearchive/drive-music-player/blob/master/third-party/jplayer/js/Jplayer.swf"
click SWFObject "https://github.com/googlearchive/drive-music-player/blob/master/third-party/swfobject/swfobject.js"
click ID3 "https://github.com/googlearchive/drive-music-player/blob/master/third-party/id3-tag-reader/id3.js"
click ID3v1 "https://github.com/googlearchive/drive-music-player/blob/master/third-party/id3-tag-reader/id3v1.js"
click ID3v2 "https://github.com/googlearchive/drive-music-player/blob/master/third-party/id3-tag-reader/id3v2.js"
click ID4 "https://github.com/googlearchive/drive-music-player/blob/master/third-party/id3-tag-reader/id4.js"
click JDataView "https://github.com/googlearchive/drive-music-player/blob/master/third-party/jdataview/jdataview.js"
click JPlayerSkin "https://github.com/googlearchive/drive-music-player/tree/master/third-party/jplayer/skin/"

click AppYaml "https://github.com/googlearchive/drive-music-player/blob/master/app.yaml"
click ManifestJson "https://github.com/googlearchive/drive-music-player/blob/master/manifest.json"
click ManifestWebapp "https://github.com/googlearchive/drive-music-player/blob/master/manifest.webapp"
click CWSManifest "https://github.com/googlearchive/drive-music-player/blob/master/cws/manifest.json"
click CWS "https://github.com/googlearchive/drive-music-player/tree/master/cws/"

%% =========================
%% Styles
%% =========================
classDef owned fill:#2b6cb0,stroke:#1a365d,color:#ffffff,stroke-width:1.5px
classDef thirdparty fill:#718096,stroke:#2d3748,color:#ffffff,stroke-width:1.25px
classDef external fill:#ed8936,stroke:#7b341e,color:#1a202c,stroke-width:1.25px
classDef hosting fill:#38a169,stroke:#22543d,color:#ffffff,stroke-width:1.25px
```
