deco/obs-ss-plugin-webui
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Update documentation to reflect recent enhancements
Some checks failed
Lint and Build / build (pull_request) Failing after 1m42s
Details

Browse source 
- 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 <noreply@anthropic.com>
This commit is contained in:
Decobus 2025-07-26 00:24:42 -04:00
parent bc4cfe607d
commit 0edead505f
3 changed files with 324 additions and 50 deletions
Download patch file Download diff file Expand all files Collapse all files

23
CLAUDE.md
View file

@ -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

63
README.md
View file

@ -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`

288
docs/API.md Normal file
View file

@ -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.