SpotiFLAC Web Portal

SpotiFLAC Web is a high-fidelity web port of the original SpotiFLAC-Mobile application. It decouples the Go backend core logic from native mobile platform channels, exposing it via a structured Go REST & SSE API served alongside a premium, responsive React Single-Page Application.

🏗️ Architecture

                                  +-----------------------+
                                  |   React Frontend SPA  |
                                  |   (Vite / ES6 / CSS)  |
                                  +-----------+-----------+
                                              | (HTTP REST / SSE)
                                              v
+------------------+              +-----------------------+
|  FFmpeg Binary   | <--(Exec)----|     Go HTTP Server    |
| (Transcoding/Tags)|             |      (main.go)        |
+------------------+              +-----------+-----------+
                                              |
                                              v
                                  +-----------------------+
                                  |    Go Backend Core    |
                                  | (Extension Engine VMs)|
                                  +-----------------------+

1. Vite + React Frontend: A gorgeous, glassmorphic dark-themed SPA supporting track/album/artist search, live download tracking (SSE), registry extensions management, ID3/FLAC metadata tag editing, and settings preferences.
2. Go HTTP Server (main.go): Serves the frontend assets, provides REST endpoints for management and actions, hosts an EventSource stream for download progress, and runs asynchronous queue workers.
3. Go Core Engine: The native Go module (./backend) which parses and executes JS extensions inside safe goja JavaScript VMs.
4. FFmpeg Integration: The server spawns background processes using system ffmpeg to execute queued audio transcoding and advanced tag injection for non-native formats (e.g. MP3, Opus).

---

⚙️ Prerequisites

To run SpotiFLAC Web locally, you need the following tools installed on your host system:

1. Go (v1.22 or higher)
2. Node.js & npm (for compiling frontend assets)
3. FFmpeg (on your system's global PATH)
   • Note: FFmpeg is required for transcoding downloaded audio and writing tags to MP3/Opus files.

---

🚀 Getting Started

1. Build the Frontend SPA

Compile the React source files into static production assets:

cd frontend
npm install
npm run build
cd ..

The compiled output is saved to ./frontend/dist/.

2. Run the Go Server

Launch the server in development or production mode:

go run main.go

By default, the application runs on http://localhost:8080.

You can customize runtime options by changing settings directly within the UI Settings Panel or modifying ./data/settings.json after the first run.

---

📂 Project Directory Structure

• /backend - Legacy Go core business logic and VM runner.
• /frontend - React source files, CSS, assets, and build configurations.
• /data - Local storage directory for configurations and extensions cache.
• /downloads - Default folder where downloaded FLAC/MP3 files are stored.
• main.go - The entry point web server and async background worker queue runner.

---

🛰️ API Endpoint Documentation

Endpoint	Method	Description
/api/settings	GET / POST	Retrieve or update system configurations (paths, formats, priorities)
/api/extensions	GET	List all locally installed extensions and their status
/api/extensions/registry	GET	Fetch all available extensions from the global JSON registry
/api/extensions/install	POST	Install a registry extension by ID or upload a .spotiflac-ext
/api/extensions/toggle	POST	Enable or disable a loaded extension VM
/api/extensions/delete	POST	Remove an extension from local storage
/api/search	GET	Perform text-based search queries or parse Spotify links
/api/download	POST	Trigger asynchronous music downloading background tasks
/api/download/progress	GET	Server-Sent Events (SSE) stream for download percentage
/api/download/cancel	POST	Terminate active background download operations
/api/library	GET	List audio files in your local downloads folder
/api/library/metadata	GET / POST	Read or edit track ID3/FLAC metadata tags

---

📜 License

Ported with ❤️ from SpotiFLAC-Mobile.