# Video Integration Specification

**Date:** 2025-12-22  
**Status:** In Progress

## Overview

This spec outlines the complete video integration for elmeg.xyz, ensuring YouTube videos are properly displayed and discoverable across the application.

---

## Current State

### Database Schema ✅

- `Performance.youtube_link` - Individual performance video URL
- `Show.youtube_link` - Full show video URL  
- `Song.youtube_link` - Studio/canonical video URL

### Import Pipeline ✅

- `import_youtube.py` processes `youtube_videos.json`
- Handles: single songs, sequences (→), and full shows
- Sequences link the SAME video to ALL performances in the sequence

### Frontend Display (Current)

| Page | Video Display | Status |
|------|--------------|--------|
| Show Page | Full show video (`show.youtube_link`) | ✅ Working |
| Song Page | Top performance video or song video | ✅ Working |
| Performance Page | Should show `performance.youtube_link` | ❌ MISSING |
| Videos Page | Lists all videos | ✅ Working |

### Visual Indicators (Current)

| Location | Indicator | Status |
|----------|-----------|--------|
| Setlist items | Video icon for performances with video | ❌ MISSING |
| Archive/Show list | Video badge for shows with video | ❌ MISSING |

---

## Implementation Plan

### Phase 1: Performance Page Video Display ⚡ HIGH PRIORITY

**File:** `frontend/app/performances/[id]/page.tsx`

**Requirements:**

1. Import `YouTubeEmbed` component
2. Add video section ABOVE the "Version Timeline" card when `performance.youtube_link` exists
3. Style consistently with show page video section

**UI Placement:**

```
[Hero Banner]
[VIDEO EMBED] <-- NEW: Only when youtube_link exists
[Version Timeline]
[About This Performance]
[Comments]
[Reviews]
```

### Phase 2: Setlist Video Indicators

**File:** `frontend/app/shows/[id]/page.tsx`

**Requirements:**

1. Add small YouTube icon (📹 or `<Youtube>`) next to song title when `perf.youtube_link` exists
2. Make icon clickable - links to performance page (where video is embedded)
3. Use red color for YouTube brand recognition

**Visual Design:**

```
1. Dramophone 📹 >
2. The Empress of Organos 📹
```

### Phase 3: Archive Video Badge

**File:** `frontend/app/archive/page.tsx` (or show list component)

**Requirements:**

1. Add video badge to show cards that have:
   - `show.youtube_link` (full show video), OR
   - Any `performance.youtube_link` in their setlist
2. API enhancement: Add `has_videos` or `video_count` to show list endpoint

**Backend Enhancement:**

```python
# In routers/shows.py - list_shows endpoint
# Add computed field: has_videos = show.youtube_link is not None or any performance has youtube_link
```

**Visual Design:**

- Small YouTube icon in corner of show card
- Tooltip: "Full show video available" or "X song videos available"

---

## Data Flow

```
YouTube Video → import_youtube.py → Database
                                        ↓
                         ┌──────────────┼──────────────┐
                         ↓              ↓              ↓
                   Show.youtube_link   Performance.youtube_link   Song.youtube_link
                         ↓              ↓              ↓
                   Show Page       Performance Page   Song Page
```

---

## API Changes Required

### 1. Shows List Enhancement (Phase 3)

**Endpoint:** `GET /shows/`

**New Response Fields:**

```json
{
  "id": 123,
  "date": "2025-12-13T00:00:00",
  "has_video": true,        // NEW: true if show.youtube_link OR any perf.youtube_link
  "video_count": 3          // NEW: count of performances with videos
}
```

### 2. Performance Detail (Already Exists)

**Endpoint:** `GET /performances/{id}`

**Verify Field Included:**

```json
{
  "youtube_link": "https://www.youtube.com/watch?v=zQI6-LloYwI"
}
```

---

## Testing Checklist

- [ ] Dramophone 2025-12-13 shows video on performance page
- [ ] Empress of Organos 2025-12-13 shows SAME video on performance page
- [ ] Setlist on 2025-12-13 show shows video icons for both songs
- [ ] Archive view shows video indicator for 2025-12-13 show
- [ ] Video page accurately reflects all linked videos

---

## Files Modified

### Phase 1

- `frontend/app/performances/[id]/page.tsx` - Add video embed

### Phase 2  

- `frontend/app/shows/[id]/page.tsx` - Add video icons to setlist

### Phase 3

- `backend/routers/shows.py` - Add has_videos to list response
- `frontend/app/archive/page.tsx` - Add video badge to cards