## Streamer Widgets (OBS Browser Sources)

This app runs a **single local web server** that hosts multiple streamer widgets on **one port**, and pushes updates via **WebSockets**.

### Available Widgets

- **Now Playing**: Display currently playing music from Windows Media
- **Live Chat**: Display Twitch and YouTube live chat with emote support (FFZ, BTTV, 7TV)
- **Viewer Count**: Display live viewer count from Twitch and/or YouTube

### Run (dev)

```bash
uv sync
uv run streamer-widgets --tray
```

Then add as OBS Browser Sources:

- **Now Playing**: `http://127.0.0.1:8765/widgets/nowplaying/`
- **Live Chat**: `http://127.0.0.1:8765/widgets/livechat/`
- **Viewer Count**: `http://127.0.0.1:8765/widgets/viewercount/`
- **Configuration**: `http://127.0.0.1:8765/config`

---

## Widget Documentation

### Now Playing Widget

Displays the currently playing song from Windows Media with album art.

**Features:**
- Real-time updates via WebSocket
- Album art display with animated bubble fallback
- Auto-hide when nothing is playing
- Marquee scrolling for long titles
- Playing/Paused status indicator

**OBS Setup:**
- URL: `http://127.0.0.1:8765/widgets/nowplaying/`
- Recommended size: 400×150 px
- Transparent background

**Note:** This widget reads from Windows Media Session (works with Spotify, Windows Media Player, browsers playing media, etc.)

---

### Live Chat Widget

Displays Twitch and YouTube live chat with emote support.

**URL Options:**

| Parameter | Values | Default | Description |
|-----------|--------|---------|-------------|
| `theme` | `dark`, `light` | `dark` | Background style (dark is transparent) |
| `direction` | `down`, `up` | `down` | Message flow direction |
| `fontsize` | `small`, `medium`, `large`, `xlarge` | `medium` | Text and emote size |
| `hidetime` | `true`, `false` | `false` | Hide message timestamps |

**Example URLs:**
```
# Default (dark, scrolls down)
http://127.0.0.1:8765/widgets/livechat/

# Light theme for light backgrounds
http://127.0.0.1:8765/widgets/livechat/?theme=light

# Large font, no timestamps
http://127.0.0.1:8765/widgets/livechat/?fontsize=large&hidetime=true

# Bubbles up (newest at bottom, anchored)
http://127.0.0.1:8765/widgets/livechat/?direction=up
```

**OBS Setup:**
- Recommended size: 400×600 px
- Check "Shutdown source when not visible" for performance

**Emote Support:**
- Twitch native emotes
- FrankerFaceZ (FFZ) - global + channel
- BetterTTV (BTTV) - global + top shared + trending + channel
- 7TV - global + top + trending + channel

See [CHAT_SETUP.md](CHAT_SETUP.md) for OAuth setup instructions.

---

### Viewer Count Widget

The viewer count widget displays your live viewer count from Twitch and/or YouTube.

**URL Options:**

| Parameter | Values | Default | Description |
|-----------|--------|---------|-------------|
| `theme` | `dark`, `light`, `minimal` | `dark` | Widget background style |
| `fontsize` | `small`, `medium`, `large`, `xlarge` | `medium` | Text size |
| `hidelabel` | `true`, `false` | `false` | Hide "viewers" label |
| `livedot` | `true`, `false` | `false` | Show animated red live indicator |
| `interval` | Number (seconds, min 10) | `30` | Refresh interval |

**Example URLs:**
```
# Default
http://127.0.0.1:8765/widgets/viewercount/

# Large with live dot
http://127.0.0.1:8765/widgets/viewercount/?fontsize=large&livedot=true

# Minimal for clean overlay
http://127.0.0.1:8765/widgets/viewercount/?theme=minimal&hidelabel=true

# Compact with fast refresh
http://127.0.0.1:8765/widgets/viewercount/?fontsize=small&interval=15
```

**Note:** The widget uses the Twitch channel and YouTube video ID configured in `/config`. Requires OAuth login for API access.

### Build a standalone `.exe` (PyInstaller)

```bash
uv sync --group build
pyinstaller --noconsole --onefile --name streamer-widgets ^
  --add-data "app/assets/web;app/assets/web" ^
  run_tray.py
```

The executable will be in `dist/streamer-widgets.exe`.

**For end users:** Configuration files are stored in `%LOCALAPPDATA%\StreamerWidgets\`. The app auto-creates a config template on first run. Use the config UI at http://127.0.0.1:8765/config to open the config directory and set up OAuth credentials.