fishtank-dashboard/README.md

# Fishtank Monitor

A local dashboard for fishtank.live that shows live camera feeds, polls, TTS messages, stock prices, real-time notifications, and more — all in one place without needing the main site open.

---

## What You Need

- A Windows, Mac, or Linux computer
- A fishtank.live account
- Node.js installed (free, takes 2 minutes)

---

## Step 1 — Install Node.js

Node.js is a small program that lets your computer run the server that powers this dashboard.

1. Go to **https://nodejs.org**
2. Click the big green **"LTS"** download button (the recommended version)
3. Run the installer and click through — all default options are fine
4. When it's done, you're ready

---

## Step 2 — Set Up the Files

You should have two files:

- `fishtank-dashboard.html`
- `server.js`

Put both files in the **same folder** anywhere on your computer (e.g. your Desktop or a folder called `fishtank`).

---

## Step 3 — Install Dependencies

The server requires one npm package. Open a terminal in your folder (see Step 4 for how to do that) and run:

```
npm install ws
```

You only need to do this once. It creates a `node_modules` folder in the same directory — leave it there.

---

Clipping now requires ffmpeg installed, on windows:
```
winget install ffmpeg
```
Or download the installer from ffmpeg.org.

## Step 4 — Start the Server

**On Windows:**
1. Open the folder where you put the files
2. Click the address bar at the top of the folder window and type `cmd`, then press Enter
3. A black window will appear. Type the following and press Enter:
   ```
   node server.js
   ```

**On Mac:**
1. Open the Terminal app (search for it in Spotlight)
2. Drag your folder into the Terminal window — this sets the location
3. Type the following and press Enter:
   ```
   node server.js
   ```

You should see:
```
✓ Dashboard → http://localhost:3000
```

**Leave this window open** — closing it stops the dashboard.

---

## Step 5 — Open the Dashboard

Open your browser and go to:

```
http://localhost:3000
```

The dashboard will load with camera feeds starting automatically.

---

## Step 6 — Link Your Account

Linking your fishtank.live account unlocks polls, TTS messages, stock prices, live notifications, contestant locations, and other live data. The cameras work without it.

**To get your token:**
1. Go to **fishtank.live** and log in
2. Press **F12** to open Developer Tools
3. Go to **Storage** (Firefox) or **Application** (Chrome) tab
4. Click **Cookies** → `https://www.fishtank.live`
5. Find the cookie named `sb-wcsaaupukpdmqdjcgaoo-auth-token`
6. Copy the entire **Value** field (it starts with `%5B%22eyJ...`)

**To link it:**
1. Click the **LINK API** button in the top-left of the dashboard
2. Paste the value you copied into the input field
3. Press Enter or click **CONNECT**
4. The API dot turns green and shows **API LIVE**
5. The WS dot (next to the clock) also turns green and shows **WS LIVE** — this is the live WebSocket connection to fishtank

Your token is saved automatically — you won't need to do this again unless you log out or clear your browser data. The dashboard also refreshes the token automatically so it stays connected.

---

## Stopping the Server

In the terminal window where the server is running, press:
```
Ctrl + C
```

If you closed the terminal window and need to stop it:

- **Windows:** Open Task Manager → find `node.exe` → End Task
- **Mac/Linux:** Open Terminal and run `pkill node`

---

## Features

### 📹 Camera Feeds
- **17 live camera feeds** from the fishtank house displayed as thumbnails
- **Director Mode** plays as the main featured feed by default
- **Click any thumbnail** to switch it to the featured view — Director Mode takes its place in the grid
- **Click the cell showing Director Mode** in the grid to return to Director Mode
- **Double-click** the main feed to go fullscreen. Press Escape or double-click again to exit
- **Cameraman** feed displayed in its own panel next to the stocks chart, same switching behaviour
- **THUMBS / LIVE toggle** — Thumbs mode refreshes a snapshot every 30 seconds (saves bandwidth). Live mode streams all cameras simultaneously

### 🧑‍🤝‍🧑 Contestant Locations
- Contestant avatar icons appear **directly on the camera thumbnails** showing who is currently in each room
- Updated in real time via facial recognition data from the fishtank WebSocket feed
- Hover over an avatar to see the contestant's name, current action (sitting, standing, etc.), and mood
- The featured camera also shows avatars, slightly larger
- Contestants whose location is unknown (off-camera) show no icon

### 🔔 Live Notifications
- **Production announcements** (evictions, challenges, events, etc.) appear as a **popup overlay** in the top-center of the dashboard
- A notification sound plays when a new one arrives
- Auto-dismisses after 8 seconds, or click ✕ to close manually
- If a new notification arrives before the previous one dismisses, it replaces it immediately

### 📊 Polls
- Shows the current active poll with live vote bars
- Displays the winner of the last poll
- Narrative polls are labelled with a **NARRATIVE POLL** badge

### 💬 TTS Messages
- Accumulates TTS messages as they play in the house
- Shows the sender, voice used, room, status, cost, and timestamp
- **Click any message** to jump to the camera for that room
- A green/red dot next to the panel title shows whether TTS is currently enabled on the site

### 📈 Stocks
- Line chart showing all contestant stock prices over time
- Toggle between **1D**, **1H**, and **1W** views
- Each stock has its own colour — click a stock in the legend to hide/show it
- Percentage change shown next to each ticker with up/down arrows

### 📷 Capture Tools (in the camera panel header)
- **📷 SNAP** — takes a full resolution PNG screenshot of the current featured camera
- **✂ CLIP** — opens a trimming selection window showing the last ~60secs. Drag sliders and save a trimmed clip or save the entire buffer.
- **⏺ REC / ⏹ STOP** — records forward from when you click. A live file size counter shows how large the recording is getting
- **3.9MB LIMIT toggle** — when enabled, recording auto-stops before hitting 4MB (useful for sites with upload limits)
- **🔇 CLIPS MUTED / 🔊 AUDIO toggle** — controls whether clips and recordings include audio

### ⚙️ Other Controls
- **VOL slider** — controls the volume of the featured camera
- **Interval selector** (5s / 10s / 30s / 60s) — how often the API data refreshes
- **LOGOUT** — clears your stored token and disconnects from the API

---

## Troubleshooting

**Cameras not loading:**
Make sure the server is running (`node server.js`) and you're visiting `http://localhost:3000` — not opening the HTML file directly.

**"LINK API" not working:**
Make sure you copied the full cookie value starting with `%5B%22eyJ`. Just the token alone (starting with `eyJ`) also works but won't enable auto-refresh.

**WS dot stays red / no notifications or contestant locations:**
Make sure you've linked your account — the WebSocket connection requires auth. If it was already linked, try logging out and back in to refresh the token.

**Server won't start — "Cannot find module 'ws'":**
You need to install the ws package. Run `npm install ws` in the folder containing `server.js`, then try again.

**Server won't start:**
Make sure Node.js is installed. Open a terminal and type `node --version` — if it prints a version number, Node is installed. If not, go back to Step 1.

**Port already in use:**
Something else is using port 3000. Either stop that program or edit `server.js` and change `const PORT = 3000` to another number like `3001`, then visit `http://localhost:3001` instead.