BlazeStream

[steveseguin]

**Note to Reviewer:** The provided "Summary of Code Changes (Diff)" and "Original PR Description" were empty. This description is therefore based on the PR Title "BlazeStream" and the general context of the "Raspberry Ninja" project (social stream consolidation, overlay, TTS, API). Specific details about the exact files changed, function implementations, or precise performance metrics are placeholders and would need to be populated once the actual code changes are available.

---

# BlazeStream: Core Streaming Enhancement

**Target Branch:** `main`
**Source Branch:** `beta`

## Purpose

This Pull Request introduces the foundational `BlazeStream` module, a significant enhancement aimed at upgrading and expanding Raspberry Ninja's core streaming data processing capabilities. The primary goal is to provide a more robust, efficient, and scalable pipeline for ingesting, processing, and delivering social stream events, laying the groundwork for future features and improved user experience.

## Key Changes

*   **New `BlazeStream` Core Module:**
    *   Adds a new, independent module (`src/blazestream/`) responsible for high-performance stream data ingestion and standardization across various social platforms.
    *   Implements an optimized event queue and processing logic to handle high-volume stream activity more efficiently.
*   **Integration with Existing Components:**
    *   Updates the `Twitch` and `YouTube` integration services to feed raw event data into the new `BlazeStream` pipeline instead of direct processing.
    *   Modifies the `Overlay Engine` and `TTS Processor` to consume processed, standardized events directly from `BlazeStream`, ensuring consistent data formats.
*   **API Refinements:**
    *   Adjusts internal API endpoints (`/api/stream/events`) to expose data generated by `BlazeStream`, potentially introducing new event types or formats.
    *   Updates relevant API handlers (`src/api/`) to interact with the `BlazeStream` service layer.
*   **Performance Optimizations:**
    *   (Inferred) Includes improvements in data buffering, reduced latency for event delivery, and more efficient resource utilization during peak stream activity.
*   **Configuration Updates:**
    *   Adds new configuration options to `config.json` for `BlazeStream` specific settings, such as buffering thresholds or processing parallelization.

## Context/Why

The existing stream processing architecture, while functional, presented limitations in scalability and flexibility, particularly as the number of supported platforms and features grew. The `BlazeStream` initiative addresses these challenges by centralizing stream data processing, making it more resilient, performant, and easier to extend. This change is crucial for maintaining Raspberry Ninja's reliability and for enabling advanced features in the future.

## How to Test

Reviewers should focus on the following areas to ensure the `BlazeStream` integration is stable and performant:

1.  **Stream Connectivity:**
    *   Connect to multiple social streams (e.g., Twitch, YouTube) simultaneously.
    *   Verify that all stream events (chat messages, follows, subscriptions, raids, etc.) are correctly received and processed.
2.  **Overlay Functionality:**
    *   Ensure that all alerts, widgets, and dynamic content driven by stream events in `dock.html` appear correctly and without noticeable delay.
    *   Check for any visual glitches or incorrect data display.
3.  **TTS Integration:**
    *   Confirm that Text-to-Speech (TTS) messages from chat or alerts are correctly synthesized and played back.
    *   Verify that TTS doesn't experience delays or broken audio.
4.  **API Responsiveness:**
    *   Monitor the `/api/stream/events` endpoint for correct data output and latency using browser developer tools or API clients.
    *   Confirm that event data matches what is observed on the actual streams.
5.  **Performance:**
    *   Observe CPU and memory usage under sustained stream load to detect any regressions or unexpected spikes.
    *   (If applicable) Compare event processing latency with previous versions.

## Considerations

*   **Backward Compatibility:** Assess if any external integrations or custom API consumers might be affected by changes to event formats or endpoint behaviors.
*   **Resource Usage:** Monitor for any significant changes in CPU, memory, or network resource consumption, especially under high-load scenarios.
*   **Error Handling:** Verify that the new `BlazeStream` module gracefully handles disconnections, API rate limits, and malformed data from social platforms.