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

Update project documentation with comprehensive architecture details
Some checks failed
Lint and Build / build (22) (pull_request) Failing after 43s
Details
Lint and Build / build (20) (pull_request) Failing after 46s
Details

Browse source 
- Enhanced CLAUDE.md with detailed architectural concepts and patterns
- Added dynamic table naming system documentation
- Documented persistent OBS connection management and dual integration
- Explained glass morphism UI architecture and real-time monitoring
- Updated README.md with modern professional presentation
- Added comprehensive setup instructions and feature highlights
- Included all development commands and API endpoint references
- Cross-referenced CLAUDE.md for detailed technical documentation

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Decobus 2025-07-19 04:47:47 -04:00
parent 9f019db74f
commit 91ef418b1b
2 changed files with 133 additions and 49 deletions
Download patch file Download diff file Expand all files Collapse all files

96
CLAUDE.md
View file

@ -15,68 +15,98 @@ This is a Next.js web application that controls multiple OBS Source Switchers. I
- `npm run lint` - Run ESLint to check code quality
- `npm run type-check` - Run TypeScript type checking without emitting files
### Database Management
- `npm run create-sat-summer-2025-tables` - Create database tables with seasonal naming convention
## Architecture Overview
### Technology Stack
- **Frontend**: Next.js 15.1.6 with React 19, TypeScript, and Tailwind CSS
- **Frontend**: Next.js 15.1.6 with React 19, TypeScript, and custom CSS with glass morphism design
- **Backend**: Next.js API routes
- **Database**: SQLite with sqlite3 driver
- **OBS Integration**: obs-websocket-js for WebSocket communication with OBS Studio
- **Styling**: Tailwind CSS with @tailwindcss/forms plugin
- **Styling**: Custom CSS with Tailwind CSS utilities and modern glass card components
### Project Structure
- `/app` - Next.js App Router pages and API routes
- `/api` - Backend API endpoints for stream management
- `/add` - Page for adding new stream clients
- `/components` - Reusable React components (e.g., Dropdown)
- `/add` - 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)
- `/lib` - Core utilities and database connection
- `database.ts` - SQLite database initialization and connection management
- `obsClient.js` - OBS WebSocket client for communicating with OBS Studio
- `constants.ts` - Shared constants (table names, etc.)
- `obsClient.js` - OBS WebSocket client with persistent connection management
- `constants.ts` - Dynamic table naming system for seasonal deployments
- `/types` - TypeScript type definitions
- `/files` - Default directory for SQLite database and text files (configurable via .env.local)
- `/scripts` - Database setup and management scripts
- `/.forgejo/workflows` - Forgejo CI/CD workflows for self-hosted runners
### Key Concepts
### Key Architectural Concepts
1. **Stream Management**: The app manages stream sources that can be assigned to different screen positions. Each stream has:
- name: Display name
- obs_source_name: Name of the source in OBS
- url: Stream URL
- team_id: Associated team identifier
1. **Dynamic Table Naming System**: Uses seasonal configuration for table names (e.g., `streams_2025_summer_sat`, `teams_2025_summer_sat`) to support recurring deployments
2. **Screen Types**: Seven different screen positions are supported: large, left, right, topLeft, topRight, bottomLeft, bottomRight
2. **Persistent OBS Connection Management**: Single WebSocket connection shared across all API requests with automatic reconnection and connection state tracking
3. **Text File Integration**: The app writes the active source name to text files that OBS Source Switcher reads to switch sources automatically
3. **Dual Integration Pattern**:
- WebSocket API for direct OBS control (source creation, status monitoring)
- Text file system for OBS Source Switcher plugin integration (source switching)
4. **Environment Configuration**:
- `FILE_DIRECTORY`: Directory for database and text files (default: ./files)
- `OBS_WEBSOCKET_HOST`: OBS WebSocket host (default: 127.0.0.1)
- `OBS_WEBSOCKET_PORT`: OBS WebSocket port (default: 4455)
- `OBS_WEBSOCKET_PASSWORD`: OBS WebSocket password (optional)
4. **Glass Morphism UI Architecture**: Modern design system with backdrop blur effects, gradient backgrounds, and responsive glass card components
5. **Screen Position Management**: Seven distinct screen positions (large, left, right, topLeft, topRight, bottomLeft, bottomRight) with individual source control
6. **Real-time Status Monitoring**: Footer component polls OBS status every 30 seconds showing connection, streaming, and recording status
### Environment Configuration
- `FILE_DIRECTORY`: Directory for database and text files (default: ./files)
- `OBS_WEBSOCKET_HOST`: OBS WebSocket host (default: 127.0.0.1)
- `OBS_WEBSOCKET_PORT`: OBS WebSocket port (default: 4455)
- `OBS_WEBSOCKET_PASSWORD`: OBS WebSocket password (optional)
### API Endpoints
- `POST /api/addStream` - Add new stream to database and OBS
#### Stream Management
- `POST /api/addStream` - Add new stream to database and create browser source in OBS
- `GET /api/streams` - Get all available streams
- `GET /api/teams` - Get all teams
- `GET /api/streams/[id]` - Individual stream operations
#### Source Control
- `POST /api/setActive` - Set active stream for specific screen position
- `GET /api/getActive` - Get currently active sources for all screens
- `POST /api/setActive` - Set active stream for a specific screen
#### Team Management
- `GET /api/teams` - Get all teams
- `GET /api/getTeamName` - Get team name by ID
#### System Status
- `GET /api/obsStatus` - Real-time OBS connection and streaming status
### Database Schema
Two main tables:
- `streams`: id, name, obs_source_name, url, team_id
- `teams`: team_id, team_name
Dynamic table names with seasonal configuration:
- `streams_YYYY_SEASON_SUFFIX`: id, name, obs_source_name, url, team_id
- `teams_YYYY_SEASON_SUFFIX`: team_id, team_name
### OBS Integration Pattern
The app communicates with OBS through:
1. WebSocket connection using obs-websocket-js
2. Text files that OBS Source Switcher monitors for source changes
3. Direct source management through OBS WebSocket API
The app uses a sophisticated dual integration approach:
When setting an active source:
1. User selects stream in UI
2. API writes source name to corresponding text file (e.g., largeScreen.txt)
3. OBS Source Switcher detects file change and switches to that source
1. **WebSocket Connection**: Direct OBS control using obs-websocket-js with persistent connection management
2. **Text File System**: Each screen position has a corresponding text file that OBS Source Switcher monitors
**Source Control Workflow**:
1. User selects stream in React UI
2. API writes source name to position-specific text file (e.g., `large.txt`, `left.txt`)
3. OBS Source Switcher detects file change and switches to specified source
4. Real-time status updates via WebSocket API
**Connection Management**: The OBS client ensures a single persistent connection across all API requests with automatic reconnection handling and connection state validation.
### Component Patterns
- **Client Components**: All interactive components use `'use client'` directive for React 19 compatibility
- **Optimistic Updates**: UI updates immediately with error rollback for responsive user experience
- **Consistent Layout**: Glass morphism design with unified component styling across all pages
- **Responsive Design**: Grid layouts adapt to different screen sizes with mobile-first approach

86
README.md
View file

@ -1,28 +1,82 @@
This is a [Next.js](https://nextjs.org) app to control multiple OBS [Source Switchers](https://obsproject.com/forum/resources/source-switcher.941/)
# OBS Source Switcher Plugin UI
A professional [Next.js](https://nextjs.org) web application for controlling multiple OBS [Source Switchers](https://obsproject.com/forum/resources/source-switcher.941/) with real-time WebSocket integration and modern glass morphism UI.
## Features
- **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
- **Team & Stream Management**: Organize streams by teams with full CRUD operations
- **Modern UI**: Glass morphism design with responsive layout
- **Professional Broadcasting**: Audio routing, scene management, and live status indicators
- **Dual Integration**: WebSocket API + text file monitoring for maximum compatibility
## Quick Start
```bash
npm install
npm run dev
```
Open [http://localhost:3000](http://localhost:3000) to access the control interface.
## Configuration
The application uses a configurable directory for storing files and the database. To update the directory: create `.env.local` in the root of the project.
`.env.local` should look like:
```
### Environment Variables
Create `.env.local` in the project root:
```env
# File storage directory (optional, defaults to ./files)
FILE_DIRECTORY=C:\\OBS\\source-switching
```
If no `.env.local` file is created, it will default to `./files`, as seen in `config.js`
```javascript
const config = {
FILE_DIRECTORY: path.resolve('./files'),
};
# OBS WebSocket settings (optional, these are defaults)
OBS_WEBSOCKET_HOST=127.0.0.1
OBS_WEBSOCKET_PORT=4455
OBS_WEBSOCKET_PASSWORD=your_password_here
```
In the "Source Switcher" properties in OBS, at the bottom, is a setting called `Current Source File`. Enable that, point it to the location of one of the text files, and put the read interval to 1000ms. Your source will change whenever the text file changes to a source _that is defined in the Source Switcher properties_
### OBS Source Switcher Setup
The list of available sources is defined in a SQLite3 DB, location set in the `api/setActive.ts` route.
1. In OBS, configure Source Switcher properties
2. Enable "Current Source File" at the bottom
3. Point to one of the generated text files (e.g., `large.txt`, `left.txt`)
4. Set read interval to 1000ms
5. Sources will switch automatically when files change
`npm install` and
`npm run dev` to run it.
### Database Setup
This is my first [Next.js](https://nextjs.org) app and I am not a Javascript Developer professionally, use at your own risk.
```bash
# Create seasonal database tables
npm run create-sat-summer-2025-tables
```
## Development Commands
```bash
npm run dev # Start development server
npm run build # Build for production
npm run start # Start production server
npm run lint # Run ESLint
npm run type-check # TypeScript validation
```
## Architecture
- **Frontend**: Next.js 15 with React 19 and TypeScript
- **Backend**: Next.js API routes with SQLite database
- **OBS Integration**: WebSocket connection + text file monitoring
- **Styling**: Custom CSS with glass morphism and Tailwind utilities
- **CI/CD**: Forgejo workflows with self-hosted runners
## API Endpoints
- `GET /api/streams` - List all streams
- `POST /api/addStream` - Create new stream and OBS source
- `POST /api/setActive` - Set active stream for screen position
- `GET /api/obsStatus` - Real-time OBS connection status
- `GET /api/teams` - Team management
See `CLAUDE.md` for detailed architecture documentation.