From 60bf3290d3241106385aaee7190d60fb31fa8492 Mon Sep 17 00:00:00 2001 From: Ramforth Date: Thu, 30 Oct 2025 17:21:57 +0100 Subject: [PATCH] Add DEVELOPMENT_PLAN.md and update README.md --- DEVELOPMENT_PLAN.md | 47 ++++++++++++++++++++++++++++++++++++++++++++ README.md | 48 +++------------------------------------------ 2 files changed, 50 insertions(+), 45 deletions(-) create mode 100644 DEVELOPMENT_PLAN.md diff --git a/DEVELOPMENT_PLAN.md b/DEVELOPMENT_PLAN.md new file mode 100644 index 0000000..db12ae8 --- /dev/null +++ b/DEVELOPMENT_PLAN.md @@ -0,0 +1,47 @@ +# YouTube Chat Webhook Listener (Version 2) - gRPC Implementation Plan + +This document outlines the detailed plan for implementing a robust, quota-friendly, open-source, and Linux-compatible solution for monitoring YouTube Live Chat by leveraging the recommended `liveChatMessages.streamList` gRPC endpoint. + +## Phase 1: gRPC Client Setup + +1. **Install Dependencies:** + * **Action:** Install `grpcio` and `grpcio-tools` Python packages. + +2. **Obtain `.proto` File:** + * **Action:** Locate and download the official Protocol Buffers (`.proto`) file that defines the `liveChatMessages.streamList` service. + +3. **Generate Python Client Code:** + * **Action:** Use `grpc_tools.protoc` to generate the Python client-side libraries from the `.proto` file. + +4. **Develop gRPC Client:** + * **Action:** Write a Python script to: + * Establish a secure gRPC channel to the YouTube API endpoint. + * Create a client stub for the `liveChatMessages.streamList` service. + * Initiate the `StreamList` request to begin receiving messages. + * Implement a loop to continuously process messages as they are pushed from the server. + +## Phase 2: Integration and Enhancements + +1. **Integrate with Display Logic:** + * **Action:** Adapt the existing `rich` display logic from `main.py` to consume messages received from the gRPC client instead of the polling mechanism. + +2. **Error Handling & Resilience:** + * **Action:** Implement robust error handling for gRPC connections, including automatic reconnection logic. + * **Action:** Utilize `nextPageToken` (if provided by the gRPC stream) to resume receiving messages from where the connection was interrupted, preventing data loss. + +3. **Configuration:** + * **Action:** Externalize API keys, default video ID, and display preferences into a configuration file (e.g., `config.ini` or `config.json`). + +4. **Enhance Display Features:** + * **Action:** Implement a more sophisticated system to assign consistent, unique colors to each user. + * **Action:** Improve emote rendering and potentially integrate with external emote services (e.g., BTTV, FrankerFaceZ) if feasible and compliant. + * **Action:** Add options for message filtering (e.g., by user, keywords, message type). + +## Phase 3: Testing and Documentation + +1. **Unit and Integration Tests:** + * **Action:** Write comprehensive unit tests for the gRPC client, message processing, and display logic. + * **Action:** Develop integration tests to ensure the end-to-end flow works correctly. + +2. **Update Documentation:** + * **Action:** Update the project's `README.md` with detailed usage instructions, setup guides, and explanations of the gRPC implementation. diff --git a/README.md b/README.md index 4c76092..e88d5e5 100644 --- a/README.md +++ b/README.md @@ -6,51 +6,9 @@ This project aims to create a robust, quota-friendly, open-source, and Linux-com To build a Python application that leverages the `liveChatMessages.streamList` gRPC endpoint to receive real-time YouTube Live Chat messages, process them, and display them in the terminal with rich formatting. This will ensure a highly efficient and compliant method for sustained live stream monitoring. -## Implementation Plan: gRPC Client +## Detailed Implementation Plan -### Phase 1: gRPC Client Setup - -1. **Install Dependencies:** - * **Action:** Install `grpcio` and `grpcio-tools` Python packages. - -2. **Obtain `.proto` File:** - * **Action:** Locate and download the official Protocol Buffers (`.proto`) file that defines the `liveChatMessages.streamList` service. - -3. **Generate Python Client Code:** - * **Action:** Use `grpc_tools.protoc` to generate the Python client-side libraries from the `.proto` file. - -4. **Develop gRPC Client:** - * **Action:** Write a Python script to: - * Establish a secure gRPC channel to the YouTube API endpoint. - * Create a client stub for the `liveChatMessages.streamList` service. - * Initiate the `StreamList` request to begin receiving messages. - * Implement a loop to continuously process messages as they are pushed from the server. - -### Phase 2: Integration and Enhancements - -1. **Integrate with Display Logic:** - * **Action:** Adapt the existing `rich` display logic from `main.py` to consume messages received from the gRPC client instead of the polling mechanism. - -2. **Error Handling & Resilience:** - * **Action:** Implement robust error handling for gRPC connections, including automatic reconnection logic. - * **Action:** Utilize `nextPageToken` (if provided by the gRPC stream) to resume receiving messages from where the connection was interrupted, preventing data loss. - -3. **Configuration:** - * **Action:** Externalize API keys, default video ID, and display preferences into a configuration file (e.g., `config.ini` or `config.json`). - -4. **Enhance Display Features:** - * **Action:** Implement a more sophisticated system to assign consistent, unique colors to each user. - * **Action:** Improve emote rendering and potentially integrate with external emote services (e.g., BTTV, FrankerFaceZ) if feasible and compliant. - * **Action:** Add options for message filtering (e.g., by user, keywords, message type). - -### Phase 3: Testing and Documentation - -1. **Unit and Integration Tests:** - * **Action:** Write comprehensive unit tests for the gRPC client, message processing, and display logic. - * **Action:** Develop integration tests to ensure the end-to-end flow works correctly. - -2. **Update Documentation:** - * **Action:** Update the project's `README.md` with detailed usage instructions, setup guides, and explanations of the gRPC implementation. +For a detailed breakdown of the implementation steps, please refer to the [DEVELOPMENT_PLAN.md](DEVELOPMENT_PLAN.md) file. ## Dependencies @@ -64,4 +22,4 @@ To build a Python application that leverages the `liveChatMessages.streamList` g * Interactive message sending via gRPC (if supported by the API). * More advanced terminal UI (e.g., `prompt_toolkit` for input). -* Web overlay integration. +* Web overlay integration. \ No newline at end of file