# YouTube Live Chat Overlay - Development Plan

## Current Status (v0.1.0-alpha)

The YouTube Live Chat Overlay is a functional prototype that scrapes live chat messages from a specified YouTube live stream and displays them in a customizable web-based overlay.

**Key Features Implemented:**
*   **Backend (`overlay_backend.py`):**
    *   Scrapes YouTube Live Chat using `pytchat`.
    *   Converts common text-based emotes (e.g., `:smiling_face_with_heart_eyes:`) to their Unicode emoji equivalents for better display.
    *   Applies rich text markup (`[magenta]` for Unicode emojis, `[blue]` for other text-based emotes if detected).
    *   Manages persistent user colors, assigning unique colors to chat participants.
    *   Exposes a `/chat` API endpoint using Flask to provide live chat messages to the frontend.
    *   Includes CORS support to allow access from local `file://` origins.
    *   Runs Flask in a separate thread and `pytchat` scraping in the main thread to avoid `signal` errors.
    *   Suppresses verbose terminal output for cleaner operation.
*   **Frontend (HTML/CSS/JavaScript):**
    *   **`index.html`:** Basic structure for the chat overlay.
    *   **`style.css`:** Provides basic styling for chat messages, including text shadow for readability and distinct colors for emotes.
    *   **`script.js`:**
        *   Periodically fetches chat messages from the Python Flask backend.
        *   Dynamically updates the HTML content with new messages.
        *   Converts rich text markup (`[magenta]...[/magenta]`, `[blue]...[/blue]`) into corresponding HTML `<span>` tags with CSS classes (`.emoji`, `.blue-text`).

**Known Issues/Limitations:**
*   The `emote_to_unicode_map` is hardcoded in `backend.py` and is not exhaustive. New or less common text-based emotes will not be converted.
*   The frontend uses polling (fetching data every second) which is not ideal for real-time applications and can be inefficient.
*   The `emoji_pattern` for detecting general Unicode emojis in `backend.py` is comprehensive, but may not cover all edge cases or future Unicode additions.
*   No support for YouTube's custom channel emotes (e.g., Twitch-style subscriber emotes).

## Future Development Ideas

1.  **Dynamic Emote Mapping:**
    *   Implement a way to dynamically fetch or update text-based emote to Unicode/image mappings (e.g., from a configuration file, an external API, or by scraping common YouTube emote lists).
2.  **WebSocket Integration:**
    *   Replace HTTP polling with a WebSocket connection for true real-time chat updates, reducing latency and resource usage.
    *   This would involve using Flask-SocketIO or a similar library in the backend and a WebSocket client in the frontend.
3.  **Customizable Themes/Layouts:**
    *   Allow users to easily customize the appearance of the overlay (fonts, colors, message layout) without editing CSS directly (e.g., via a simple configuration file or an in-browser settings panel).
4.  **YouTube Custom Emote Support:**
    *   Investigate ways to display YouTube's custom channel-specific emotes, which are often image-based. This would likely involve fetching emote image URLs and incorporating `<img>` tags.
5.  **Error Handling & Robustness:**
    *   Improve error handling in both backend and frontend for network issues, API changes, or unexpected data.
    *   Add better reconnection logic for the chat scraper.
6.  **Packaging/Deployment:**
    *   Provide scripts or instructions for easily packaging the backend (e.g., as a Docker container or standalone executable) and the frontend for OBS Studio or other streaming software.
7.  **Configuration:**
    *   Implement a configuration file (e.g., `config.ini` or `config.json`) for backend settings like the Flask port, default video ID, and emote mappings.

## Installation and Usage

Refer to the `HOW-TO.md` or `INSTALLATION.md` for instructions on setting up and running the overlay.