youtube-chat-webhook-v2/README.md

YouTube Chat Webhook Listener (Version 2)

This project aims to create a more robust and quota-friendly YouTube Live Chat monitor by leveraging third-party streaming services (like StreamElements) that provide webhook notifications for new chat messages. This approach avoids constant polling of the YouTube Data API, thus eliminating quota issues and providing near real-time chat updates.

Project Goal

To build a Python application that listens for chat message webhooks from a third-party service, processes them, and displays them in the terminal, effectively creating an event-driven chat monitor.

Detailed Implementation Plan

Phase 1: Setup Local Webhook Server

1. Choose a Python Web Framework: We will use Flask for its simplicity in setting up a basic web server.

   • Action: Install Flask: pip install Flask

2. Create webhook_server.py: This file will contain the Flask application.

   • Action: Create webhook_server.py with a basic Flask app structure.

3. Define Webhook Endpoint: Implement a POST endpoint (e.g., /chat-webhook) that will receive JSON payloads from the third-party service.

   • Action: Add @app.route('/chat-webhook', methods=['POST']) to webhook_server.py.

4. Parse Incoming Data: The Flask app will need to parse the JSON data received from the webhook. The structure of this data will depend on the chosen third-party service (e.g., StreamElements).

   • Action: Add logic to handle_webhook() to extract username and message from request.json.

5. Queue Messages: Instead of directly printing, the Flask app will put received messages into a Python queue.Queue object. This queue will be shared with the main display thread.

   • Action: Implement a shared queue.Queue and add messages to it.

6. Run Flask App in a Separate Thread: The Flask development server should run in a separate thread to avoid blocking the main application.

   • Action: Implement run_flask_app() function and start it in a threading.Thread.

Phase 2: Integrate with Main Display Logic

1. Modify main.py: The existing main.py will be adapted to become the display client.

   • Action: Remove all YouTube Data API polling logic (fetch_live_chat_messages, get_live_chat_id).

2. Start Webhook Server: main.py will initiate the webhook_server.py in a separate thread.

   • Action: Import webhook_server and start its Flask thread in main().

3. Retrieve and Display Messages: main.py will continuously check the shared queue for new messages from the webhook server and display them using rich styling.

   • Action: Implement a loop in main() to queue.get_nowait() messages and console.print() them.

4. Maintain Terminal Display: Ensure rich styling (colors, alternating backgrounds) is applied to webhook-received messages.

   • Action: Adapt existing rich styling logic for new message source.

Phase 3: Third-Party Service Configuration (Manual Steps)

1. Choose a Service: Select a streaming service that provides webhook functionality (e.g., StreamElements, Streamlabs).

   • Action: User to sign up/log in to chosen service.

2. Link YouTube Channel: Connect your YouTube channel to the chosen service.

   • Action: User to follow service-specific instructions.

3. Configure Webhook: Find the webhook settings within the service's dashboard.

   • Action: User to configure a webhook to send POST requests on new chat messages.

4. Expose Local Server (ngrok): Since webhook services need a public URL, you'll likely need a tunneling service like ngrok during development.

   • Action: User to install ngrok and run ngrok http 5000 (if Flask runs on port 5000). Use the provided public https URL in the webhook configuration.

5. Test: Send a message in your YouTube live chat and verify it appears in your terminal via the webhook.

Dependencies

• Flask
• rich
• ngrok (for development/testing with public webhooks)

Future Enhancements

• Interactive message sending via webhook (if supported by the third-party service).
• More advanced terminal UI (e.g., prompt_toolkit for input).
• Web overlay integration.