Docs: Update README with Gitea clone instructions.

.gitignore

@@ -1,176 +1,6 @@
-# ---> Python
-# Byte-compiled / optimized / DLL files
-__pycache__/
-*.py[cod]
-*$py.class
-
-# C extensions
-*.so
-
-# Distribution / packaging
-.Python
-build/
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-share/python-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.nox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-*.py,cover
-.hypothesis/
-.pytest_cache/
-cover/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-.pybuilder/
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# IPython
-profile_default/
-ipython_config.py
-
-# pyenv
-#   For a library or package, you might want to ignore these files since the code is
-#   intended to run in multiple environments; otherwise, check them in:
-# .python-version
-
-# pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-#Pipfile.lock
-
-# UV
-#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#uv.lock
-
-# poetry
-#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
-#poetry.lock
-
-# pdm
-#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
-#pdm.lock
-#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
-#   in version control.
-#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
-.pdm.toml
-.pdm-python
-.pdm-build/
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
-__pypackages__/
-
-# Celery stuff
-celerybeat-schedule
-celerybeat.pid
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
-.env
-.venv
-env/
+client_secret.json
+token.json
 venv/
-ENV/
-env.bak/
-venv.bak/
-
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
-
-# mypy
-.mypy_cache/
-.dmypy.json
-dmypy.json
-
-# Pyre type checker
-.pyre/
-
-# pytype static type analyzer
-.pytype/
-
-# Cython debug symbols
-cython_debug/
-
-# PyCharm
-#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
-#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
-#  and can be added to the global gitignore or merged into this file.  For a more nuclear
-#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
-
-# Ruff stuff:
-.ruff_cache/
-
-# PyPI configuration file
-.pypirc
-
+chat_logs/
+__pycache__/
+*.pyc

README.md

@@ -1,7 +1,83 @@
-# youtube-chat-terminal
+# YouTube Live Chat in Terminal
 
-"YouTube Live Chat Terminal Viewer
+## Project Description
+This project aims to provide a customizable way to view YouTube Live Chat directly in your terminal. It is implemented in `main.py`.
 
-  A Python-based command-line interface (CLI) application designed for Linux content creators to view YouTube Live Chat directly in their terminal. It enhances readability with color-coded
-  usernames, alternating message backgrounds, and textual representation of emotes and emojis. The application also includes robust chat logging with an option to save sessions. Future plans
-  include interactive message sending and a web overlay for streaming software."
+## Features
+*   **Real-time Live Chat Display:** Fetches and displays messages from YouTube Live Streams.
+*   **OAuth 2.0 Authentication:** Securely connects to your YouTube account to access your live stream data.
+*   **Terminal-based Interface:** View chat directly in your command-line interface.
+
+### Planned Features
+*   Color-coded usernames for better readability.
+*   Customizable terminal output (e.g., font size, message formatting).
+*   Ability to send messages back to the live chat.
+*   Local web overlay for use with streaming software like OBS.
+
+## Setup Instructions
+
+### 1. Clone the Repository
+Clone the project from your Gitea instance:
+```bash
+git clone https://gitea.ramforth.net/RamTech/youtube-chat-terminal.git
+cd youtube-chat-terminal
+```
+
+### 2. Gitea Repository
+This project is hosted on your Gitea instance at: `https://gitea.ramforth.net/RamTech/youtube-chat-terminal`
+
+```bash
+cd /home/joe/Cloud9/Documents/Obisdian/youtube_chat_terminal
+python3 -m venv venv
+source venv/bin/activate
+```
+*(If you are using a shell like `fish` and encounter issues with `source venv/bin/activate`, try running `bash` first, then `source venv/bin/activate` within the bash session.)*
+
+### 3. Install Dependencies
+With your virtual environment activated, install the required Python libraries:
+
+```bash
+pip install google-api-python-client google-auth-oauthlib google-auth-httplib2 prompt_toolkit
+```
+
+### 4. Google Cloud Project Setup
+To allow this application to access YouTube Live Chat data, you need to set up a project in the Google Cloud Console:
+
+1.  Go to the [Google Cloud Console](https://console.cloud.google.com/).
+2.  Create a new project or select an existing one.
+3.  Navigate to "APIs & Services" > "Library".
+4.  Search for and **enable the "YouTube Data API v3"**.
+5.  Go to "APIs & Services" > "Credentials".
+6.  Click "+ CREATE CREDENTIALS" and choose **"OAuth client ID"**.
+7.  For "Application type", select **"Desktop app"**.
+8.  Give it a name (e.g., "YouTube Chat Terminal App") and click "CREATE".
+9.  Download the JSON file containing your Client ID and Client Secret. Rename this file to `client_secret.json`.
+
+### 5. Place `client_secret.json`
+Move the downloaded `client_secret.json` file into the root directory of this project (i.e., `/home/joe/Cloud9/Documents/Obisdian/youtube_chat_terminal/`).
+
+### 6. Initial Authentication
+Run the `main.py` script for the first time to complete the OAuth 2.0 authentication flow:
+
+```bash
+python main.py
+```
+This will open a browser window, prompting you to log in with your Google account and grant permissions to the application. Upon successful authentication, a `token.json` file will be created in the project directory. This file stores your credentials for future use, so you won't need to re-authenticate every time.
+
+## Usage
+To view the live chat of a YouTube stream, run the script and provide the YouTube Live Stream Video ID when prompted:
+
+```bash
+python main.py
+```
+The script will then continuously fetch and display live chat messages in your terminal.
+
+### Finding the YouTube Live Stream Video ID
+*   Go to the live stream on YouTube.
+*   The Video ID is the alphanumeric string in the URL after `v=` (e.g., in `https://www.youtube.com/watch?v=YOUR_VIDEO_ID`, `YOUR_VIDEO_ID` is the ID you need).
+
+## Future Development
+Contributions and suggestions are welcome! Planned enhancements include:
+*   Advanced terminal formatting and styling.
+*   Integration for sending chat messages.
+*   Development of a local web overlay.

chat_reader.py

@@ -0,0 +1,172 @@
+from datetime import datetime
+import re
+import os
+import google.oauth2.credentials
+import google_auth_oauthlib.flow
+import googleapiclient.discovery
+import googleapiclient.errors
+import time
+from rich.console import Console
+from rich.style import Style
+
+# The CLIENT_SECRETS_FILE contains your Client ID and Client Secret.
+CLIENT_SECRETS_FILE = "client_secret.json"
+
+# This scope allows read-only access to YouTube analytics data.
+SCOPES = ['https://www.googleapis.com/auth/youtube.readonly']
+API_SERVICE_NAME = 'youtube'
+API_VERSION = 'v3'
+
+console = Console()
+
+def get_authenticated_service():
+    credentials = None
+
+    # Check if we have saved credentials
+    if os.path.exists('token.json'):
+        credentials = google.oauth2.credentials.Credentials.from_authorized_user_file('token.json', SCOPES)
+
+    # If no valid credentials available, let the user log in.
+    if not credentials or not credentials.valid:
+        if credentials and credentials.expired and credentials.refresh_token:
+            credentials.refresh(google.auth.transport.requests.Request())
+        else:
+            flow = google_auth_oauthlib.flow.InstalledAppFlow.from_client_secrets_file(
+                CLIENT_SECRETS_FILE, SCOPES)
+            credentials = flow.run_local_server(port=0)
+        # Save the credentials for the next run
+        with open('token.json', 'w') as token:
+            token.write(credentials.to_json())
+
+    return googleapiclient.discovery.build(
+        API_SERVICE_NAME, API_VERSION, credentials=credentials)
+
+def get_live_chat_id(youtube, video_id):
+    try:
+        response = youtube.videos().list(
+            part='liveStreamingDetails',
+            id=video_id
+        ).execute()
+
+        if 'items' in response and response['items']:
+            video = response['items'][0]
+            if 'liveStreamingDetails' in video and 'activeLiveChatId' in video['liveStreamingDetails']:
+                return video['liveStreamingDetails']['activeLiveChatId']
+        return None
+    except googleapiclient.errors.HttpError as e:
+        console.print(f"[red]An HTTP error {e.resp.status} occurred: {e.content}[/red]")
+        return None
+
+def fetch_live_chat_messages(youtube, live_chat_id, page_token=None):
+    try:
+        request = youtube.liveChatMessages().list(
+            liveChatId=live_chat_id,
+            part='snippet,authorDetails',
+            pageToken=page_token
+        )
+        response = request.execute()
+        return response
+    except googleapiclient.errors.HttpError as e:
+        console.print(f"[red]An HTTP error {e.resp.status} occurred: {e.content}[/red]")
+        return None
+
+def main():
+    youtube = get_authenticated_service()
+    console.print("[green]Successfully authenticated with YouTube API![/green]")
+
+    # Clear the terminal screen
+    os.system('clear')
+
+    video_id = input("Enter the YouTube Live Stream Video ID: ")
+    live_chat_id = get_live_chat_id(youtube, video_id)
+
+    if not live_chat_id:
+        console.print("[red]Could not find an active live chat for the given video ID.[/red]")
+        return
+
+    console.print(f"[green]Found live chat ID: {live_chat_id}[/green]")
+
+    # Setup chat logging
+    log_dir = "chat_logs"
+    os.makedirs(log_dir, exist_ok=True)
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    log_filename = os.path.join(log_dir, f"chat_{video_id}_{timestamp}.log")
+    log_file = open(log_filename, "w", encoding="utf-8")
+    console.print(f"[green]Chat will be logged to {log_filename}[/green]")
+
+    next_page_token = None
+    message_count = 0
+
+    try:
+        while True:
+            # Fetch new messages
+            response = fetch_live_chat_messages(youtube, live_chat_id, next_page_token)
+            if response:
+                for item in response.get('items', []):
+                    author_display_name = item['authorDetails']['displayName']
+                    message_text = item['snippet']['displayMessage']
+
+                    # Process emotes provided by the API
+                    if 'textMessageDetails' in item['snippet'] and 'emotes' in item['snippet']['textMessageDetails']:
+                        emotes = item['snippet']['textMessageDetails']['emotes']
+                        # Sort emotes by offset to replace them correctly from right to left
+                        emotes.sort(key=lambda x: x['offsets'][0]['startIndex'], reverse=True)
+                        
+                        for emote in emotes:
+                            start = emote['offsets'][0]['startIndex']
+                            end = emote['offsets'][0]['endIndex'] + 1 # +1 because end index is inclusive
+                            emote_id = emote['emoteId']
+                            # Replace the original text with the emote ID surrounded by colons and styled
+                            message_text = message_text[:start] + f"[blue]:{emote_id}:[/blue]" + message_text[end:]
+
+                    # After processing API-provided emotes, use regex for text-based emotes (e.g., :face-purple-sweating:)
+                    # This catches emotes that are just part of the messageText without explicit emote data.
+                    message_text = re.sub(r'(:[a-zA-Z0-9_-]+:)', r'[blue]\1[/blue]', message_text)
+
+                    # Add coloring for standard emojis
+                    # This regex matches a broader range of common emoji unicode characters and sequences.
+                    # It's important to compile with re.UNICODE for proper Unicode character matching.
+                    emoji_pattern = re.compile(
+                        "("  # Start capturing group
+                        "\U0001F600-\U0001F64F"  # emoticons
+                        "\U0001F300-\U0001F5FF"  # symbols & pictographs
+                        "\U0001F680-\U0001F6FF"  # transport & map symbols
+                        "\U0001F1E0-\U0001F1FF"  # flags (iOS)
+                        "\U00002702-\U000027B0"  # Dingbats
+                        "\U000024C2-\U0001F251"  # Enclosed characters
+                        "\U0001F900-\U0001F9FF"  # Supplemental Symbols and Pictographs
+                        "\U0000200D"  # Zero Width Joiner (for emoji sequences)
+                        "\U0000FE0F"  # Variation Selector-16 (for emoji presentation)
+                        ")+"
+                        , re.UNICODE)
+                    message_text = emoji_pattern.sub(r'[magenta]\1[/magenta]', message_text)
+
+                    # Alternate background styles
+                    background_style = Style(bgcolor="#2B2B2B") if message_count % 2 == 0 else Style(bgcolor="#3A3A3A")
+                    
+                    # Simple color for username (can be expanded to unique colors per user)
+                    username_style = Style(color="#4CAF50", bold=True)
+
+                    # Format message for terminal and log file
+                    formatted_message = f"{author_display_name}: {message_text}"
+                    console.print(formatted_message, style=background_style)
+                    log_file.write(f"{datetime.now().strftime("%H:%M:%S")} {formatted_message}\n")
+                    message_count += 1
+
+                next_page_token = response.get('nextPageToken')
+                polling_interval_millis = response['pollingIntervalMillis']
+                time.sleep(polling_interval_millis / 1000.0)
+            else:
+                console.print("[yellow]No new messages or an error occurred. Retrying...[/yellow]")
+                time.sleep(5) # Wait 5 seconds before retrying on error
+    finally:
+        log_file.close()
+        save_log = input(f"\nDo you want to save the chat log to {log_filename}? (y/n): ").lower()
+        if save_log != 'y' and save_log != 'yes':
+            os.remove(log_filename)
+            console.print(f"[red]Chat log not saved. {log_filename} deleted.[/red]")
+        else:
+            console.print(f"[green]Chat log saved to {log_filename}[/green]")
+
+if __name__ == '__main__':
+    main()

main.py

@@ -0,0 +1,181 @@
+from datetime import datetime
+import re
+import os
+import google.oauth2.credentials
+import google_auth_oauthlib.flow
+import googleapiclient.discovery
+import googleapiclient.errors
+import time
+from rich.console import Console
+from rich.style import Style
+from rich.panel import Panel
+from rich.live import Live
+from rich.text import Text
+
+# The CLIENT_SECRETS_FILE contains your Client ID and Client Secret.
+CLIENT_SECRETS_FILE = "client_secret.json"
+
+# This scope allows read-only access to YouTube analytics data.
+SCOPES = ['https://www.googleapis.com/auth/youtube.readonly']
+API_SERVICE_NAME = 'youtube'
+API_VERSION = 'v3'
+
+console = Console()
+
+def get_authenticated_service():
+    credentials = None
+
+    # Check if we have saved credentials
+    if os.path.exists('token.json'):
+        credentials = google.oauth2.credentials.Credentials.from_authorized_user_file('token.json', SCOPES)
+
+    # If no valid credentials available, let the user log in.
+    if not credentials or not credentials.valid:
+        if credentials and credentials.expired and credentials.refresh_token:
+            credentials.refresh(google.auth.transport.requests.Request())
+        else:
+            flow = google_auth_oauthlib.flow.InstalledAppFlow.from_client_secrets_file(
+                CLIENT_SECRETS_FILE, SCOPES)
+            credentials = flow.run_local_server(port=0)
+        # Save the credentials for the next run
+        with open('token.json', 'w') as token:
+            token.write(credentials.to_json())
+
+    return googleapiclient.discovery.build(
+        API_SERVICE_NAME, API_VERSION, credentials=credentials)
+
+def get_live_chat_id(youtube, video_id):
+    try:
+        response = youtube.videos().list(
+            part='liveStreamingDetails',
+            id=video_id
+        ).execute()
+
+        if 'items' in response and response['items']:
+            video = response['items'][0]
+            if 'liveStreamingDetails' in video and 'activeLiveChatId' in video['liveStreamingDetails']:
+                return video['liveStreamingDetails']['activeLiveChatId']
+        return None
+    except googleapiclient.errors.HttpError as e:
+        console.print(f"[red]An HTTP error {e.resp.status} occurred: {e.content}[/red]")
+        return None
+
+def fetch_live_chat_messages(youtube, live_chat_id, page_token=None):
+    try:
+        request = youtube.liveChatMessages().list(
+            liveChatId=live_chat_id,
+            part='snippet,authorDetails',
+            pageToken=page_token
+        )
+        response = request.execute()
+        return response
+    except googleapiclient.errors.HttpError as e:
+        console.print(f"[red]An HTTP error {e.resp.status} occurred: {e.content}[/red]")
+        return None
+
+def main():
+    youtube = get_authenticated_service()
+    console.print("[green]Successfully authenticated with YouTube API![/green]")
+
+    # Clear the terminal screen
+    os.system('clear')
+
+    video_id = input("Enter the YouTube Live Stream Video ID: ")
+    live_chat_id = get_live_chat_id(youtube, video_id)
+
+    if not live_chat_id:
+        console.print("[red]Could not find an active live chat for the given video ID.[/red]")
+        return
+
+    console.print(f"[green]Found live chat ID: {live_chat_id}[/green]")
+
+    # Setup chat logging
+    log_dir = "chat_logs"
+    os.makedirs(log_dir, exist_ok=True)
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    log_filename = os.path.join(log_dir, f"chat_{video_id}_{timestamp}.log")
+    log_file = open(log_filename, "w", encoding="utf-8")
+    console.print(f"[green]Chat will be logged to {log_filename}[/green]")
+
+    # Wait for 5 seconds, then clear the screen again
+    time.sleep(5)
+    os.system('clear')
+
+    next_page_token = None
+    message_count = 0
+
+    try:
+        while True:
+            # Fetch new messages
+            response = fetch_live_chat_messages(youtube, live_chat_id, next_page_token)
+            if response:
+                for item in response.get('items', []):
+                    author_display_name = item['authorDetails']['displayName']
+                    message_text = item['snippet']['displayMessage']
+
+                    # Process emotes provided by the API
+                    if 'textMessageDetails' in item['snippet'] and 'emotes' in item['snippet']['textMessageDetails']:
+                        emotes = item['snippet']['textMessageDetails']['emotes']
+                        # Sort emotes by offset to replace them correctly from right to left
+                        emotes.sort(key=lambda x: x['offsets'][0]['startIndex'], reverse=True)
+                        
+                        for emote in emotes:
+                            start = emote['offsets'][0]['startIndex']
+                            end = emote['offsets'][0]['endIndex'] + 1 # +1 because end index is inclusive
+                            emote_id = emote['emoteId']
+                            # Replace the original text with the emote ID surrounded by colons and styled
+                            message_text = message_text[:start] + f"[blue]:{emote_id}:[/blue]" + message_text[end:]
+
+                    # After processing API-provided emotes, use regex for text-based emotes (e.g., :face-purple-sweating:)
+                    # This catches emotes that are just part of the messageText without explicit emote data.
+                    message_text = re.sub(r'(:[a-zA-Z0-9_-]+:)', r'[blue]\1[/blue]', message_text)
+
+                    # Add coloring for standard emojis
+                    # This regex matches a broader range of common emoji unicode characters and sequences.
+                    # It's important to compile with re.UNICODE for proper Unicode character matching.
+                    emoji_pattern = re.compile(
+                        "("  # Start capturing group
+                        "\U0001F600-\U0001F64F"  # emoticons
+                        "\U0001F300-\U0001F5FF"  # symbols & pictographs
+                        "\U0001F680-\U0001F6FF"  # transport & map symbols
+                        "\U0001F1E0-\U0001F1FF"  # flags (iOS)
+                        "\U00002702-\U000027B0"  # Dingbats
+                        "\U000024C2-\U0001F251"  # Enclosed characters
+                        "\U0001F900-\U0001F9FF"  # Supplemental Symbols and Pictographs
+                        "\U0000200D"  # Zero Width Joiner (for emoji sequences)
+                        "\U0000FE0F"  # Variation Selector-16 (for emoji presentation)
+                        ")+"
+                        , re.UNICODE)
+                    message_text = emoji_pattern.sub(r'[magenta]\1[/magenta]', message_text)
+
+                    # Alternate background styles
+                    background_style = Style(bgcolor="#2B2B2B") if message_count % 2 == 0 else Style(bgcolor="#3A3A3A")
+                    
+                    # Simple color for username (can be expanded to unique colors per user)
+                    username_style = Style(color="#4CAF50", bold=True)
+
+                    # Format message for terminal and log file
+                    formatted_message = f"{author_display_name}: {message_text}"
+                    console.print(formatted_message, style=background_style)
+                    log_file.write(f"{datetime.now().strftime("%H:%M:%S")} {formatted_message}\n")
+                    message_count += 1
+
+                next_page_token = response.get('nextPageToken')
+                polling_interval_millis = response['pollingIntervalMillis']
+                time.sleep(polling_interval_millis / 1000.0)
+            else:
+                console.print("[yellow]No new messages or an error occurred. Retrying...[/yellow]")
+                time.sleep(5) # Wait 5 seconds before retrying on error
+    except KeyboardInterrupt:
+        pass # Exit gracefully on Ctrl+C
+    finally:
+        log_file.close()
+        save_log = input(f"\nDo you want to save the chat log to {log_filename}? (y/n): ").lower()
+        if save_log != 'y' and save_log != 'yes':
+            os.remove(log_filename)
+            console.print(f"[red]Chat log not saved. {log_filename} deleted.[/red]")
+        else:
+            console.print(f"[green]Chat log saved to {log_filename}[/green]")
+
+if __name__ == '__main__':
+    main()