# Installation and Usage Instructions

This document provides detailed instructions for setting up and running the `pytchat_listener.py` script for monitoring YouTube Live Chat.

## Prerequisites

*   Python 3.8+
*   `pip` (Python package installer)
*   `git` (for cloning the repository)

## Installation Steps

1.  **Clone the Repository:**
    Open your terminal and clone the project repository from Gitea:
    ```bash
    git clone https://gitea.ramforth.net/ramforth/youtube-chat-webhook-v2.git
    cd youtube-chat-webhook-v2
    ```

2.  **Create and Activate a Virtual Environment:**
    It is highly recommended to use a Python virtual environment to manage project dependencies.
    ```bash
    python3 -m venv venv
    ```
    *   **For Bash/Zsh:**
        ```bash
        source venv/bin/activate
        ```
    *   **For Fish Shell:**
        ```bash
        source venv/bin/activate.fish
        ```

3.  **Install Dependencies:**
    With your virtual environment activated, install the required Python packages:
    ```bash
    pip install pytchat rich
    ```

## Usage

1.  **Run the Script:**
    Ensure your virtual environment is activated, then run the `pytchat_listener.py` script:
    ```bash
    python pytchat_listener.py
    ```

2.  **Enter Video ID:**
    The script will prompt you to "Enter the YouTube Live Stream Video ID:". Paste the 11-character ID of the live stream you wish to monitor and press Enter.

3.  **Observe Chat:**
    The script will then start fetching and displaying live chat messages in your terminal.

4.  **Save Chat Log:**
    To exit the script gracefully, press `Ctrl+C`. You will then be prompted if you want to save the chat log.

## Installation and Usage (Compiled Executable)

For users who prefer a standalone application without needing to install Python or manage dependencies, a compiled executable is available for Linux.

1.  **Download the Executable:**
    *   Go to the [Gitea Releases page](https://gitea.ramforth.net/ramforth/youtube-chat-webhook-v2/releases).
    *   Download the `pytchat_listener` executable from the latest release (e.g., `v0.1.0-alpha`).

2.  **Make Executable:**
    *   Open your terminal and navigate to the directory where you downloaded the executable.
    *   Make the file executable:
        ```bash
        chmod +x pytchat_listener
        ```

3.  **Run the Executable:**
    *   Execute the program directly:
        ```bash
        ./pytchat_listener
        ```

4.  **Enter Video ID:**
    *   The program will prompt you to "Enter the YouTube Live Stream Video ID:". Paste the 11-character ID of the live stream you wish to monitor and press Enter.

5.  **Observe Chat:**
    *   The program will then start fetching and displaying live chat messages in your terminal.

6.  **Save Chat Log:**
    *   To exit the program gracefully, press `Ctrl+C`. You will then be prompted if you want to save the chat log.

**Note:** This executable is compiled for Linux. If you are on a different operating system (e.g., Windows, macOS), you will need to follow the "Installation Steps" above to run the script from source.

## User Colors Persistence (`user_colors.json`)

The script assigns unique, persistent colors to chatters. This mapping is stored in a file named `user_colors.json` in the project directory.

*   If this file does not exist, it will be created automatically.
*   If it exists, the script will load the previously assigned colors.
*   You can manually edit this file to change a user's color or reset the mapping.

## YouTube API Authentication (Optional)

For the core functionality of fetching live chat using `pytchat`, explicit YouTube Data API v3 authentication (e.g., API keys or OAuth 2.0 credentials) is **not required**. `pytchat` leverages an internal YouTube API endpoint that does not necessitate these credentials for public live chat streams.

However, if you plan to extend this project to interact with other YouTube Data API v3 services (e.g., managing videos, accessing private data, or performing actions that require user authorization), you will need to set up API credentials. You can find detailed instructions on how to obtain and configure these credentials in the official Google Cloud documentation:

*   [Google Cloud Console - Credentials](https://console.cloud.google.com/apis/credentials)
*   [YouTube Data API v3 Overview](https://developers.google.com/youtube/v3)

For Python projects, you would typically use libraries like `google-auth-oauthlib` and `google-api-python-client` to handle authentication and API interactions.