Architecture Overview

Gazer Mobile Stream Studio is built with a modular, scalable architecture that separates concerns and enables easy testing and maintenance.

High-Level Architecture

graph TD
    A[MainActivity] --> B[UsbCaptureManager]
    A --> C[StreamingManager] 
    A --> D[CameraOverlayView]

    B --> E[UsbVideoCapture]
    C --> F[StreamCompositor]
    C --> G[RtmpStreamer]

    E --> H[VideoPreviewRenderer]
    F --> H
    D --> F

    I[Settings] --> A
    J[PermissionManager] --> A

Core Components

MainActivity

Responsibility: Main UI coordination and lifecycle management

• Manages all core components
• Handles user interactions and UI updates
• Implements responsive design logic
• Coordinates between different managers

UsbCaptureManager

Responsibility: USB device detection and management

• Monitors USB device connections/disconnections
• Handles USB permissions and device access
• Maintains device compatibility list
• Provides connection state updates

UsbVideoCapture

Responsibility: Video frame capture from USB devices

• Captures raw video data from USB devices
• Handles multiple video formats (YUV, NV21, JPEG)
• Provides video frames via Kotlin coroutines Flow
• Manages capture device lifecycle

VideoPreviewRenderer

Responsibility: Real-time video rendering

• Renders video frames to SurfaceView
• Handles format conversion and scaling
• Maintains proper aspect ratios
• Provides smooth preview experience

CameraOverlayView

Responsibility: Camera overlay functionality

• Integrates Android CameraX for device camera
• Handles touch-based positioning and resizing
• Manages overlay visibility and settings
• Provides customizable overlay options

StreamCompositor

Responsibility: Video composition and synchronization

• Combines USB video with camera overlay
• Handles frame synchronization between sources
• Applies overlay positioning and scaling
• Generates final composite frames for streaming

RtmpStreamer

Responsibility: RTMP streaming and encoding

• Manages RTMP/RTMPS connections
• Handles video encoding and compression
• Provides streaming status updates
• Manages streaming lifecycle

Data Flow

Video Pipeline

1. Capture: UsbVideoCapture receives raw video from USB device
2. Preview: VideoPreviewRenderer displays video on screen
3. Overlay: CameraOverlayView captures camera input
4. Composition: StreamCompositor combines video sources
5. Encoding: RtmpStreamer encodes composite video
6. Streaming: Encoded video sent to RTMP endpoint

Control Flow

1. User Input: MainActivity receives user interactions
2. State Management: Managers update internal state
3. UI Updates: MainActivity updates UI based on state changes
4. Configuration: Settings propagated to relevant components

Threading Model

Main Thread

• UI updates and user interactions
• Component initialization
• State management

Background Threads

• USB video capture (IO dispatcher)
• Video encoding and streaming (Default dispatcher)
• Camera operations (CameraX executors)

Coroutines Usage

// Video capture flow
class UsbVideoCapture {
    private val videoFrameFlow = flow {
        while (currentCoroutineContext().isActive) {
            val frame = captureFrame()
            emit(frame)
            delay(frameDelayMs)
        }
    }.flowOn(Dispatchers.IO)
}

// Streaming coordination
class StreamingManager {
    suspend fun startStreaming() = withContext(Dispatchers.Default) {
        compositor.getCompositeFrames()
            .collect { frame ->
                rtmpStreamer.encodeAndStream(frame)
            }
    }
}

Error Handling

Error Propagation

• Components use Result<T> for error-prone operations
• Exceptions are caught and converted to user-friendly messages
• Error states are propagated through LiveData/StateFlow

Recovery Strategies

• Automatic USB device reconnection
• RTMP connection retry with backoff
• Graceful fallback when camera overlay fails

State Management

Component States

• UsbCaptureManager: Disconnected, Connecting, Connected, Error
• StreamingManager: Idle, Starting, Streaming, Stopping, Error
• CameraOverlayView: Disabled, Initializing, Ready, Error

State Synchronization

• Components communicate through well-defined interfaces
• State changes are coordinated through MainActivity
• UI reflects current state of all components

Testing Architecture

Unit Testing

• Individual components tested in isolation
• Mock dependencies for testing different scenarios
• Coroutine testing for async operations

Integration Testing

• End-to-end testing of video pipeline
• USB device simulation for automated testing
• UI testing with Espresso framework

Performance Considerations

Memory Management

• Efficient bitmap handling and recycling
• Proper cleanup of resources on component destruction
• Memory monitoring and optimization

Threading Optimization

• Non-blocking UI operations
• Efficient video frame processing
• Minimal thread switching overhead

Battery Optimization

• Efficient encoding settings
• Power management during streaming
• Background processing optimization