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

Add Forgejo CI/CD workflows with self-hosted runners #1

Merged
deco merged 4 commits from forgejo-workflows into main 2025-07-19 12:03:34 +03:00
Conversation 0 Commits 4 Files changed 9 +133 -49
2 changed files with 133 additions and 49 deletions
Download patch file Download diff file Expand all files Collapse all files
Showing only changes of commit 91ef418b1b - Show all commits

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 lint` - Run ESLint to check code quality
- `npm run type-check` - Run TypeScript type checking without emitting files - `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 ## Architecture Overview
### Technology Stack ### 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 - **Backend**: Next.js API routes
- **Database**: SQLite with sqlite3 driver - **Database**: SQLite with sqlite3 driver
- **OBS Integration**: obs-websocket-js for WebSocket communication with OBS Studio - **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 ### Project Structure
- `/app` - Next.js App Router pages and API routes - `/app` - Next.js App Router pages and API routes
- `/api` - Backend API endpoints for stream management - `/api` - Backend API endpoints for stream management
- `/add` - Page for adding new stream clients - `/add` - Streams management page (add new streams and view existing)
- `/components` - Reusable React components (e.g., Dropdown) - `/teams` - Team management page
- `/edit/[id]` - Individual stream editing
- `/components` - Reusable React components (Header, Footer, Dropdown)
- `/lib` - Core utilities and database connection - `/lib` - Core utilities and database connection
- `database.ts` - SQLite database initialization and connection management - `database.ts` - SQLite database initialization and connection management
- `obsClient.js` - OBS WebSocket client for communicating with OBS Studio - `obsClient.js` - OBS WebSocket client with persistent connection management
- `constants.ts` - Shared constants (table names, etc.) - `constants.ts` - Dynamic table naming system for seasonal deployments
- `/types` - TypeScript type definitions - `/types` - TypeScript type definitions
- `/files` - Default directory for SQLite database and text files (configurable via .env.local) - `/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: 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
- name: Display name
- obs_source_name: Name of the source in OBS
- url: Stream URL
- team_id: Associated team identifier
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**: 4. **Glass Morphism UI Architecture**: Modern design system with backdrop blur effects, gradient backgrounds, and responsive glass card components
- `FILE_DIRECTORY`: Directory for database and text files (default: ./files)
- `OBS_WEBSOCKET_HOST`: OBS WebSocket host (default: 127.0.0.1) 5. **Screen Position Management**: Seven distinct screen positions (large, left, right, topLeft, topRight, bottomLeft, bottomRight) with individual source control
- `OBS_WEBSOCKET_PORT`: OBS WebSocket port (default: 4455)
- `OBS_WEBSOCKET_PASSWORD`: OBS WebSocket password (optional) 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 ### 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/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 - `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 - `GET /api/getTeamName` - Get team name by ID
#### System Status
- `GET /api/obsStatus` - Real-time OBS connection and streaming status
### Database Schema ### Database Schema
Two main tables: Dynamic table names with seasonal configuration:
- `streams`: id, name, obs_source_name, url, team_id - `streams_YYYY_SEASON_SUFFIX`: id, name, obs_source_name, url, team_id
- `teams`: team_id, team_name - `teams_YYYY_SEASON_SUFFIX`: team_id, team_name
### OBS Integration Pattern ### OBS Integration Pattern
The app communicates with OBS through: The app uses a sophisticated dual integration approach:
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
When setting an active source: 1. **WebSocket Connection**: Direct OBS control using obs-websocket-js with persistent connection management
1. User selects stream in UI 2. **Text File System**: Each screen position has a corresponding text file that OBS Source Switcher monitors
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 **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 ## 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 FILE_DIRECTORY=C:\\OBS\\source-switching
```
If no `.env.local` file is created, it will default to `./files`, as seen in `config.js`
# OBS WebSocket settings (optional, these are defaults)
```javascript OBS_WEBSOCKET_HOST=127.0.0.1
const config = { OBS_WEBSOCKET_PORT=4455
FILE_DIRECTORY: path.resolve('./files'), 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 ### Database Setup
`npm run dev` to run it.
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.