This document provides a comprehensive overview of SPlayer, including its purpose, architecture, core systems, and deployment options. For detailed information about specific subsystems, refer to their dedicated pages:
SPlayer is a minimalist cross-platform music player built as an Electron desktop application with web deployment capabilities. It integrates with Netease Cloud Music API for online music streaming while supporting local music library management, multiple audio formats, and advanced features like DJ-style transitions, word-by-word lyrics, and desktop lyric overlays.
Key Characteristics:
Sources: package.json1-40 README.md1-35
Application Modes:
| Mode | Entry Point | Primary Use Case |
|---|---|---|
| Electron Desktop | src/main/index.ts | Full-featured desktop experience with native OS integration |
| Web/PWA | src/renderer/ | Browser-based access, limited native features |
| Docker | Dockerfile | Self-hosted web deployment with bundled API server |
Sources: package.json1-40 README.md163-239
Sources: package.json41-84 components.d.ts1-189
SPlayer uses Pinia for centralized state management with four specialized stores:
| Store | File Path | Primary Responsibility | Persistence |
|---|---|---|---|
StatusStore | src/stores/status.ts | Playback state, UI visibility, player modes | Partial (volume, modes) |
MusicStore | src/stores/music.ts | Current song, lyrics, playlist queue | Session-only |
DataStore | src/stores/data.ts | User profile, liked content, local library | Full (localStorage) |
SettingStore | src/stores/setting.ts | User preferences, feature toggles | Full (versioned) |
Sources: package.json79-80
Controller Responsibilities:
Sources: src/components/Player/FullPlayer.vue1-227
| Technology | Version | Purpose |
|---|---|---|
| Vue 3 | 3.5.28 | Reactive UI framework with Composition API |
| TypeScript | 5.9.3 | Type-safe JavaScript development |
| Naive UI | 2.43.2 | Component library for UI elements |
| Pinia | 3.0.4 | State management with TypeScript support |
| Vue Router | 4.6.4 | Client-side routing |
Sources: package.json128-130
| Technology | Version | Purpose |
|---|---|---|
| Electron | 39.4.0 | Desktop application framework |
| electron-vite | 5.0.0 | Build tooling for Electron projects |
| Vite | 7.3.1 | Fast build tool and dev server |
| electron-builder | 26.7.0 | Multi-platform packaging |
Sources: package.json106-109
SPlayer includes four native modules for performance-critical operations:
Build Process:
pnpm build:native using NAPI-RS and wasm-packSKIP_NATIVE_BUILD=true environment variableSources: package.json27-31 README.md35-38
Sources: README.md72-98
Initialization Sequence:
BrowserWindow and loads renderer HTMLSources: package.json7
For web deployments, the application skips Electron-specific initialization:
Sources: README.md198-216
| Command | Target Platform | Output Format |
|---|---|---|
pnpm build:win | Windows | NSIS installer + portable EXE |
pnpm build:mac | macOS | DMG + ZIP for Intel/Apple Silicon |
pnpm build:linux | Linux | AppImage, DEB, RPM, tar.gz |
pnpm build:web | Web | Static files in out/renderer/ |
Build Architecture:
CI/CD Workflows:
dev branch pushesSources: package.json21-39 README.md146-263
Pre-built binaries available from:
dev.yml workflowDocker image includes web frontend + API server:
Sources: README.md164-196
Requirements:
out/renderer/ directory as static siteVITE_API_URL environment variable to Netease API instanceout/renderer in build settingsSources: README.md198-216
Sources: README.md45-58
SPlayer/
├── src/
│ ├── main/ # Electron main process
│ │ ├── index.ts # Main entry point
│ │ └── ipc/ # IPC handlers
│ ├── preload/ # Preload scripts
│ └── renderer/ # Vue application
│ ├── main.ts # Renderer entry
│ ├── App.vue # Root component
│ ├── components/ # UI components
│ ├── stores/ # Pinia stores
│ ├── utils/ # Core controllers
│ └── views/ # Route views
├── native/ # Native modules (Rust)
│ ├── tools/ # Audio analysis + downloads
│ ├── taskbar-lyric/ # Windows taskbar integration
│ ├── external-media-integration/ # Media keys
│ └── ferrous-opencc-wasm/ # Text conversion
├── electron-builder.config.ts # Packaging configuration
├── package.json # Project metadata
└── pnpm-lock.yaml # Dependency lock file
Sources: package.json1-154 components.d.ts1-189
SPlayer is licensed under GNU Affero General Public License v3.0 (AGPL-3.0):
Important Notices:
Sources: package.json13-14 README.md289-312
Refresh this wiki