# Finamp Integration (Phase 1 – Quick Embed)

This document explains how we embed the Finamp web build inside **SamCloud Music** with minimal code changes.  The goal is to get a fully-featured player & library running **inside** the existing UI, then iterate toward a native JS implementation.

---
## 0.  Prerequisites

| Tool           | Version | Notes |
| -------------- | ------- | ----- |
| Finamp source  | `main`  | <https://github.com/jmshrv/finamp> |
| Flutter SDK    | 3.22+   | Required to build Finamp for Web |
| Node / Yarn    | n/a     | Only for SamCloud front-end dev |
| Python         | 3.10+   | Flask backend |

>  You **don’t** need to install SpotDL / SamCloud back-end extras for the build step.

---
## 1.  Build the Finamp Web Bundle

```bash
# Clone Finamp and build for web
$ git clone https://github.com/jmshrv/finamp.git && cd finamp
$ flutter build web --release --base-href /static/finamp/ --web-renderer canvaskit
# Result:  ./build/web  (≈5 MB)
```

*We use `--base-href /static/finamp/` so that all relative asset URLs resolve when the bundle is served from Flask static.*

---
## 2.  Copy Assets into SamCloud

```bash
$ mkdir -p ../SamCloud\ Music/backend/static/finamp
$ cp -R build/web/* ../SamCloud\ Music/backend/static/finamp/
```

The folder tree now looks like:
```
backend/static/
└── finamp/
    ├── index.html
    ├── main.dart.js
    ├── flutter.js
    └── assets/ …
```
Flask automatically serves anything under `backend/static/*`, so `/static/finamp/index.html` is now reachable.

---
## 3.  Front-End Changes

1. **Add a `listen` tab container**
   ```html
   <!-- Listen Tab -->
   <div id="listen" class="tab-content">
       <iframe class="finamp-iframe" src="/static/finamp/index.html" title="Finamp Player"></iframe>
   </div>
   ```
   *Styling tip:* add
   ```css
   .finamp-iframe { width:100%; height:70vh; border:none; }
   ```

2. **Update bottom navigation**
   Convert the existing `<a>` with `openFinamp()` to a button that calls `showTab('listen')`.
   ```html
   <button class="nav-item" onclick="showTab('listen')">
       <div class="nav-icon">🎧</div>
       <div>Listen</div>
   </button>
   ```
   Then delete (or noop) the legacy `openFinamp()` JS function.

3. **Extend `showTab()`**
   The helper already hides/shows elements whose ids match the argument; no code change needed—just ensure the new tab id is included in the markup.

> **Optional auth** – If your Jellyfin server requires an access token, append query parameters to the iframe src:  
> `/static/finamp/index.html?server=https://jellyfin.example.com&token=XYZ`.

---
## 4.  Testing

1. Start the Flask backend (`flask run` or `./start.sh`).
2. Open the SamCloud web UI and click **Listen**.
3. The Finamp UI should load inside the page and immediately prompt for Jellyfin server settings (or auto-login if you passed the URL & token).
4. Confirm playback works from Library.

---
## 5.  Known Caveats (Phase 1)

| Limitation | Impact |
| ---------- | ------ |
| Bundle size (~5 MB) | First load is slower on low-bandwidth connections |
| Visual style | Finamp’s material styles are inside the iframe and don’t inherit the glass-blur theme |
| Navigation duplication | Finamp has its own sidebar; you may get two sets of navigation controls |

---
## 6.  Phase 2 Ideas (Native Player)

* Build a lightweight queue & audio engine with `howler.js` + Media Session API
* Replace browse views with our existing glass-morphism cards
* WebSocket to Jellyfin for playback scrobbling & now-playing
* Offline caching using IndexedDB / Service Worker

---
## 7.  Clean Uninstall

Simply delete the `backend/static/finamp/` folder and remove the `listen` tab markup; no Python changes are permanent.

---
## Changelog

| Date | Author | Notes |
| ---- | ------ | ----- |
| 2025-06-29 | Cascade AI | Initial documentation & integration steps |