fediversion/docs/VIDEO_INTEGRATION_SPEC.md

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:

# 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:

{
  "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:

{
  "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