Initial commit for YouTube Live Chat Overlay project.

DEVELOPMENT_PLAN.md

@@ -0,0 +1,52 @@
+# 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.