Build a desktop-operated, open-source YouTube Live chat client that delivers a fast, reliable stream of messages and allows a streamer to spotlight a selected chat message on an OBS-ready overlay.

Currently work in progress - bugs might be present.

• High-Performance Chat: A sleek, minimal dashboard for monitoring YouTube Live chat in real-time with intelligent auto-scroll that stops when you scroll up to read previous messages.
• OBS Integration: Select any message to instantly display it on an OBS-ready overlay with transparent background for seamless integration.
• Rich Message Support: Full support for Super Chats, gifted memberships, user badges (moderator, member, verified), and custom emojis.
• Compact and Efficient: A dark, minimalist UI designed to be space-efficient and easy on the eyes with a modern glass-morphism design.
• Flexible Connection: Connect to any YouTube Live stream using either the stream ID or full URL.

.
├── backend/              # Node.js backend service
│   ├── src/
│   │   ├── ingestion/    # YouTube chat ingestion via youtubei.js
│   │   │   └── youtubei.ts
│   │   └── index.ts      # Main backend entry point
│   └── tsconfig.json
├── client/               # Next.js frontend application
│   ├── app/
│   │   ├── dashboard/    # Operator dashboard for monitoring chat
│   │   │   └── page.tsx
│   │   ├── overlay/      # OBS-ready overlay page
│   │   │   └── page.tsx
│   │   ├── layout.tsx
│   │   └── page.tsx
│   └── next.config.js
├── shared/               # Shared TypeScript definitions
│   └── chat.ts
├── memory-bank/          # Project documentation and context
└── package.json          # Project dependencies and scripts

Follow these instructions to set up the project for local development.

• Node.js (v20.x or later)
• pnpm

1. Clone the repository:

   git clone https://github.com/aliemrevezir/YTChatHub.git
   cd YTChatHub

2. Install dependencies:

   pnpm install

3. Configure environment variables:

   Copy the example environment file and fill in your YouTube Live stream ID:

   cp .env.example .env.local

   Edit .env.local and add your YouTube Live stream ID:

   YOUTUBE_LIVE_ID=your_youtube_live_stream_id
   

   You can use either a full YouTube URL or just the video ID.

To start the development server for both the backend and frontend, run:

pnpm dev

This command will start both services concurrently:

• The backend API will be available at http://localhost:4100
• The dashboard will be available at http://localhost:3000/dashboard
• The OBS overlay will be available at http://localhost:3000/overlay

1. Access the Dashboard: Navigate to http://localhost:3000/dashboard in your browser
2. Connect to a Stream: If you haven't set YOUTUBE_LIVE_ID in your environment, you'll see a connection prompt where you can enter a YouTube Live stream ID or URL
3. Monitor Chat: View incoming chat messages in real-time across three panels:
   • Regular chat messages
   • Super Chats (paid messages)
   • Memberships and milestones
4. Feature Messages: Click on any message to spotlight it on the OBS overlay
5. OBS Integration: Add http://localhost:3000/overlay as a browser source in OBS to display selected messages

• Frontend: Next.js (React 19 with App Router) + TypeScript
• Backend: Node.js with Fastify and tsx
• YouTube Integration: youtubei.js for Innertube API access
• Real-time Communication: Server-Sent Events (SSE) for overlay updates
• Styling: Handcrafted CSS with modern design principles
• State Management: React hooks and event emitters
• Build Tools: TypeScript, pnpm

• GET /health - Check backend status and connection info
• POST /chat/connect - Connect to a YouTube Live stream
• POST /chat/disconnect - Disconnect from current stream
• GET /chat/messages - Retrieve chat messages
• POST /overlay/selection - Select a message for the overlay
• DELETE /overlay/selection - Clear the current overlay selection
• GET /overlay/stream - Server-Sent Events stream for overlay updates

• pnpm dev - Start both backend and frontend in development mode
• pnpm dev:backend - Start only the backend service
• pnpm dev:client - Start only the frontend client
• pnpm build - Build both backend and frontend for production
• pnpm build:backend - Build only the backend service
• pnpm build:client - Build only the frontend client
• pnpm start:backend - Start the built backend service
• pnpm start:client - Start the built frontend client

The project follows a monorepo structure with clear separation of concerns:

1. Backend Service:

   • Connects to YouTube Live chat via youtubei.js
   • Maintains in-memory storage of recent messages (up to 500)
   • Exposes REST API for dashboard communication
   • Provides SSE stream for overlay updates
   • Handles connection management and error recovery

2. Frontend Client:

   • Dashboard for monitoring and selecting messages
   • Overlay page for OBS integration
   • Real-time updates via polling and SSE
   • Responsive design with dark theme

3. Shared Types:

   • Common TypeScript definitions for chat messages
   • Ensures type consistency between backend and frontend

Contributions are welcome! Please read our Contribution Guide for details on our development process and how to propose improvements.

See our Progress Tracker for current development status and upcoming features:

• Search and filtering functionality for chat messages
• Enhanced error recovery and reconnection logic
• Keyboard shortcuts for quick message selection
• Entrance/exit animations for overlay message transitions

This project is licensed under the MIT License - see the LICENSE file for details.