From 0edead505f4d055610d2bd07abdafe9ae80fadf4 Mon Sep 17 00:00:00 2001 From: Decobus Date: Sat, 26 Jul 2025 00:24:42 -0400 Subject: [PATCH] Update documentation to reflect recent enhancements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add studio mode support with preview/program controls and transition API - Document API key authentication middleware for production security - Add collapsible stream groups and consolidated CSS architecture - Split API documentation into separate docs/API.md file for better organization - Update feature descriptions and endpoint specifications - Include new system scenes and enhanced footer functionality 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CLAUDE.md | 23 ++++- README.md | 63 ++++-------- docs/API.md | 288 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 324 insertions(+), 50 deletions(-) create mode 100644 docs/API.md diff --git a/CLAUDE.md b/CLAUDE.md index 2bda7ca..17bd6d4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -23,10 +23,11 @@ This is a Next.js web application (branded as "Live Stream Manager") that contro ### Technology Stack - **Frontend**: Next.js 15.1.6 with React 19, TypeScript, and custom CSS with glass morphism design -- **Backend**: Next.js API routes +- **Backend**: Next.js API routes with authentication middleware - **Database**: SQLite with sqlite3 driver - **OBS Integration**: obs-websocket-js for WebSocket communication with OBS Studio -- **Styling**: Solarized Dark theme with CSS custom properties, Tailwind CSS utilities, and accessible glass morphism components +- **Styling**: Consolidated CSS architecture with Solarized Dark theme, CSS custom properties, Tailwind CSS utilities, and accessible glass morphism components +- **Security**: API key authentication middleware for production deployments ### Project Structure - `/app` - Next.js App Router pages and API routes @@ -34,7 +35,8 @@ This is a Next.js web application (branded as "Live Stream Manager") that contro - `/streams` - Streams management page (add new streams and view existing) - `/teams` - Team management page - `/edit/[id]` - Individual stream editing -- `/components` - Reusable React components (Header, Footer, Dropdown, Toast) +- `/components` - Reusable React components (Header, Footer, Dropdown, Toast, CollapsibleGroup) +- `/middleware.ts` - API authentication middleware for security - `/lib` - Core utilities and database connection - `database.ts` - SQLite database initialization and connection management - `obsClient.js` - OBS WebSocket client with persistent connection management @@ -76,6 +78,10 @@ This is a Next.js web application (branded as "Live Stream Manager") that contro 10. **OBS Scene Control**: Direct scene switching controls with dynamic state tracking and real-time synchronization between UI and OBS +11. **Studio Mode Support**: Full preview/program scene management with transition controls for professional broadcasting + +12. **Collapsible Stream Groups**: Organized stream display with expandable team groups for better UI management + ### Environment Configuration - `FILE_DIRECTORY`: Directory for database and text files (default: ./files) - `OBS_WEBSOCKET_HOST`: OBS WebSocket host (default: 127.0.0.1) @@ -117,9 +123,10 @@ This is a Next.js web application (branded as "Live Stream Manager") that contro #### OBS Scene Control - `POST /api/setScene` - Switch OBS to specified scene layout (1-Screen, 2-Screen, 4-Screen) - `GET /api/getCurrentScene` - Get currently active OBS scene for state synchronization +- `POST /api/triggerTransition` - Trigger studio mode transition from preview to program (requires studio mode enabled) #### System Status -- `GET /api/obsStatus` - Real-time OBS connection and streaming status +- `GET /api/obsStatus` - Real-time OBS connection, streaming, recording, and studio mode status ### Database Schema @@ -188,6 +195,9 @@ See [OBS Setup Guide](./docs/OBS_SETUP.md) for detailed configuration instructio ### Security Architecture **Authentication**: API key-based authentication protects all API endpoints through Next.js middleware +- Middleware intercepts all API requests when `API_KEY` is set +- Bypasses authentication for localhost in development +- Returns 401 for unauthorized requests **Input Validation**: Comprehensive validation using centralized security utilities in `/lib/security.ts`: - Screen parameter allowlisting prevents path traversal attacks @@ -212,6 +222,8 @@ See [OBS Setup Guide](./docs/OBS_SETUP.md) for detailed configuration instructio - **Visual Feedback**: Clear "View Stream" links with proper contrast for accessibility - **Team Association**: Streams organized under teams with proper naming conventions - **Active Source Detection**: Properly reads current active sources from text files on page load and navigation +- **Collapsible Organization**: Streams grouped by team in expandable sections for cleaner UI +- **Enhanced Stream Display**: Shows stream status with preview/program indicators in studio mode ### Team & Group Management - **UUID-based Tracking**: Robust OBS group synchronization using scene UUIDs @@ -247,12 +259,15 @@ See [OBS Setup Guide](./docs/OBS_SETUP.md) for detailed configuration instructio - **Error Recovery**: Graceful error handling with user-friendly messages - **Enhanced Footer**: Real-time team/stream counts, OBS connection status with visual indicators - **Optimistic Updates**: Immediate UI feedback with proper stream group name matching +- **Studio Mode Status**: Footer displays studio mode state with preview/program scene information +- **Transition Controls**: "Cut to Preview" button available when studio mode is active ### OBS Integration Improvements - **Text Size**: Team name overlays use 96pt font for better visibility - **Color Display**: Fixed background color display (#002b4b) using proper ABGR format - **Standardized APIs**: All endpoints use consistent `{ success: true, data: [...] }` response format - **Performance Optimization**: Reduced code duplication and improved API response handling +- **CSS Consolidation**: Eliminated repetitive styles, centralized theming in globals.css ### Developer Experience - **Type Safety**: Comprehensive TypeScript definitions throughout diff --git a/README.md b/README.md index d44ace2..ce5b8e9 100644 --- a/README.md +++ b/README.md @@ -7,19 +7,22 @@ A professional [Next.js](https://nextjs.org) web application for managing live s ## Features +- **Studio Mode Support**: Full preview/program scene management with transition controls for professional broadcasting - **OBS Scene Control**: Switch between OBS layouts (1-Screen, 2-Screen, 4-Screen) with dynamic button states - **Multi-Screen Source Control**: Manage 7 different screen positions (large, left, right, and 4 corners) - **Real-time OBS Integration**: WebSocket connection with live status monitoring - **Enhanced Stream Management**: Create, edit, and delete streams with comprehensive OBS cleanup - **Team Organization**: Organize streams by teams with full CRUD operations and scene synchronization +- **Collapsible Stream Groups**: Organized stream display with expandable team groups for better UI management - **Comprehensive Deletion**: Remove streams/teams with complete OBS component cleanup (scenes, sources, text files) - **Audio Control**: Browser sources created with muted audio and OBS control enabled - **Modern UI**: Glass morphism design with responsive layout and accessibility features - **Professional Broadcasting**: Audio routing, scene management, and live status indicators - **Dual Integration**: WebSocket API + text file monitoring for maximum compatibility - **UUID-based Tracking**: Robust OBS group synchronization with rename-safe tracking -- **Enhanced Footer**: Real-time team/stream counts and OBS connection status -- **Optimized Performance**: Reduced code duplication and standardized API responses +- **Enhanced Footer**: Real-time team/stream counts, OBS connection status, and studio mode indicators +- **API Security**: Optional API key authentication for production deployments +- **Optimized Performance**: Consolidated CSS architecture and standardized API responses ## Quick Start @@ -109,54 +112,22 @@ npm run type-check # TypeScript validation - **Styling**: Custom CSS with glass morphism and Tailwind utilities - **CI/CD**: Forgejo workflows with self-hosted runners -## API Endpoints +## API Documentation -### Stream Management -- `GET /api/streams` - List all streams with team information -- `GET /api/streams/[id]` - Get individual stream details -- `POST /api/addStream` - Create new stream with browser source and team association -- `PUT /api/streams/[id]` - Update stream information -- `DELETE /api/streams/[id]` - Delete stream with comprehensive OBS cleanup: - - Removes stream's nested scene - - Deletes browser source - - Removes from all source switchers - - Clears text files referencing the stream +The application provides a comprehensive REST API for managing streams, teams, and OBS integration. -### Source Control -- `POST /api/setActive` - Set active stream for screen position (writes team-prefixed name to text file) -- `GET /api/getActive` - Get currently active sources for all screen positions +**📚 [Complete API Documentation](docs/API.md)** -### Team Management -- `GET /api/teams` - Get all teams with group information and sync status -- `POST /api/teams` - Create new team with optional OBS scene creation -- `PUT /api/teams/[teamId]` - Update team name, group_name, or group_uuid -- `DELETE /api/teams/[teamId]` - Delete team with comprehensive OBS cleanup: - - Deletes team scene/group - - Removes team text source - - Deletes all associated stream scenes - - Removes all browser sources with team prefix - - Clears all related text files -- `GET /api/getTeamName` - Get team name by ID +Key endpoints include: +- Stream management (CRUD operations) +- Source control for 7 screen positions +- Team and OBS group management +- Scene switching and studio mode controls +- Real-time status monitoring -### OBS Group/Scene Management -- `POST /api/createGroup` - Create OBS scene from team and store UUID -- `POST /api/syncGroups` - Synchronize all teams with OBS groups -- `GET /api/verifyGroups` - Verify database groups exist in OBS with UUID tracking - - Detects orphaned groups (excludes system scenes) - - Identifies name mismatches - - Shows sync status for all teams +All endpoints support API key authentication for production deployments. -### OBS Scene Control -- `POST /api/setScene` - Switch OBS to specified scene (1-Screen, 2-Screen, 4-Screen) -- `GET /api/getCurrentScene` - Get currently active OBS scene - -### System Status -- `GET /api/obsStatus` - Real-time OBS connection, streaming, and recording status - -### Authentication -All endpoints require API key authentication when `API_KEY` environment variable is set. - -See `CLAUDE.md` for detailed architecture documentation and implementation details. +See [`CLAUDE.md`](CLAUDE.md) for detailed architecture documentation and [`docs/API.md`](docs/API.md) for complete endpoint specifications. ## Known Issues @@ -167,7 +138,7 @@ See `CLAUDE.md` for detailed architecture documentation and implementation detai ### System Scene Exclusion Infrastructure scenes containing source switchers are excluded from orphaned group detection: -- 1-Screen, 2-Screen, 4-Screen, Starting, Ending, Audio, Movies +- 1-Screen, 2-Screen, 4-Screen, Starting, Ending, Audio, Movies, Resources - Additional scenes can be added to the `SYSTEM_SCENES` array in `/app/api/verifyGroups/route.ts` diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 0000000..be61781 --- /dev/null +++ b/docs/API.md @@ -0,0 +1,288 @@ +# API Documentation + +This document provides detailed information about all API endpoints available in the Live Stream Manager application. + +## Base URL +All API endpoints are available at `/api/*` relative to your application's base URL. + +## Authentication +All endpoints require API key authentication when the `API_KEY` environment variable is set. Include the API key in the `Authorization` header: + +``` +Authorization: Bearer your_api_key_here +``` + +Authentication is bypassed for localhost requests in development mode. + +## Response Format +All endpoints return JSON responses in the following format: + +```json +{ + "success": true, + "data": { /* response data */ }, + "message": "Optional success message" +} +``` + +Error responses: +```json +{ + "success": false, + "error": "Error description", + "message": "User-friendly error message" +} +``` + +## Stream Management + +### GET /api/streams +List all streams with team information. + +**Response:** +```json +{ + "success": true, + "data": [ + { + "id": 1, + "name": "StreamerName", + "obs_source_name": "TeamName_StreamerName", + "url": "https://twitch.tv/streamername", + "team_id": 1, + "team_name": "Team Alpha" + } + ] +} +``` + +### GET /api/streams/[id] +Get individual stream details by ID. + +### POST /api/addStream +Create new stream with browser source and team association. + +**Request Body:** +```json +{ + "name": "StreamerName", + "url": "https://twitch.tv/streamername", // or just "streamername" + "team_id": 1 +} +``` + +### PUT /api/streams/[id] +Update stream information. + +### DELETE /api/streams/[id] +Delete stream with comprehensive OBS cleanup: +- Removes stream's nested scene +- Deletes browser source +- Removes from all source switchers +- Clears text files referencing the stream + +## Source Control + +### POST /api/setActive +Set active stream for screen position (writes team-prefixed name to text file). + +**Request Body:** +```json +{ + "screen": "large", // large, left, right, top_left, top_right, bottom_left, bottom_right + "source": "TeamName_StreamerName" +} +``` + +### GET /api/getActive +Get currently active sources for all screen positions. + +**Response:** +```json +{ + "success": true, + "data": { + "large": "TeamName_StreamerName", + "left": "TeamName_StreamerName2", + "right": "", + // ... other positions + } +} +``` + +## Team Management + +### GET /api/teams +Get all teams with group information and sync status. + +**Response:** +```json +{ + "success": true, + "data": [ + { + "team_id": 1, + "team_name": "Team Alpha", + "group_name": "Team Alpha", + "group_uuid": "abc123-def456-ghi789" + } + ] +} +``` + +### POST /api/teams +Create new team with optional OBS scene creation. + +**Request Body:** +```json +{ + "team_name": "New Team", + "create_group": true // optional +} +``` + +### PUT /api/teams/[teamId] +Update team name, group_name, or group_uuid. + +### DELETE /api/teams/[teamId] +Delete team with comprehensive OBS cleanup: +- Deletes team scene/group +- Removes team text source +- Deletes all associated stream scenes +- Removes all browser sources with team prefix +- Clears all related text files + +### GET /api/getTeamName +Get team name by ID. + +**Query Parameters:** +- `teamId`: Team ID to lookup + +## OBS Group/Scene Management + +### POST /api/createGroup +Create OBS scene from team and store UUID. + +**Request Body:** +```json +{ + "team_id": 1 +} +``` + +### POST /api/syncGroups +Synchronize all teams with OBS groups. Updates database with current OBS scene information. + +### GET /api/verifyGroups +Verify database groups exist in OBS with UUID tracking. + +**Response:** +```json +{ + "success": true, + "data": { + "teams": [ + { + "team_id": 1, + "team_name": "Team Alpha", + "group_name": "Team Alpha", + "group_uuid": "abc123", + "status": "linked", // linked, name_changed, not_found + "obs_name": "Team Alpha Modified" // if name changed in OBS + } + ], + "orphanedGroups": [ + { + "sceneName": "Orphaned Scene", + "sceneUuid": "orphan123" + } + ] + } +} +``` + +Features: +- Detects orphaned groups (excludes system scenes) +- Identifies name mismatches +- Shows sync status for all teams + +## OBS Scene Control + +### POST /api/setScene +Switch OBS to specified scene (1-Screen, 2-Screen, 4-Screen). + +**Request Body:** +```json +{ + "scene": "2-Screen" // 1-Screen, 2-Screen, or 4-Screen +} +``` + +### GET /api/getCurrentScene +Get currently active OBS scene. + +**Response:** +```json +{ + "success": true, + "data": { + "currentScene": "2-Screen" + } +} +``` + +### POST /api/triggerTransition +Trigger studio mode transition from preview to program (requires studio mode enabled). + +**Response:** +```json +{ + "success": true, + "data": { + "programScene": "2-Screen", + "previewScene": "1-Screen" + }, + "message": "Successfully transitioned preview to program" +} +``` + +**Error Conditions:** +- Studio mode not enabled (400 error) +- OBS connection issues (500 error) + +## System Status + +### GET /api/obsStatus +Real-time OBS connection, streaming, recording, and studio mode status. + +**Response:** +```json +{ + "success": true, + "data": { + "connected": true, + "streaming": false, + "recording": true, + "studioMode": { + "enabled": true, + "previewScene": "1-Screen", + "programScene": "2-Screen" + } + } +} +``` + +## Error Codes + +- **400**: Bad Request - Invalid parameters or studio mode not enabled +- **401**: Unauthorized - Missing or invalid API key +- **404**: Not Found - Resource doesn't exist +- **500**: Internal Server Error - OBS connection issues or server errors + +## Rate Limiting + +Currently no rate limiting is implemented, but consider implementing it for production deployments to prevent abuse. + +## WebSocket Integration + +The application maintains a persistent WebSocket connection to OBS Studio for real-time communication. All API endpoints use this shared connection for optimal performance. \ No newline at end of file