From dbb5a3ca77d67f945a58a0dd186a9631e1f6062d Mon Sep 17 00:00:00 2001 From: ramforth Date: Wed, 29 Oct 2025 13:39:37 +0100 Subject: [PATCH] Initial commit: Webhook Listener Project Plan --- README.md | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..1263cd7 --- /dev/null +++ b/README.md @@ -0,0 +1,68 @@ +# 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.