meteor_detect/docs/rtsp_streaming.md

# RTSP Streaming System

## Overview

The RTSP (Real-Time Streaming Protocol) Streaming System enables the meteor detection system to broadcast live video feeds over a network. This allows for remote monitoring, collaborative observation, and integration with other systems that support standard video streaming protocols.

## Key Features

1. **Standardized Protocol**: Uses RTSP, a widely supported streaming protocol compatible with many client applications including VLC, FFmpeg, and GStreamer
   
2. **Configurable Quality**: Supports multiple quality presets to balance between bandwidth usage and video detail:
   - Low (480p, low bitrate)
   - Medium (720p, medium bitrate)
   - High (original resolution, high bitrate)
   - Custom (user-defined resolution, bitrate, and framerate)

3. **Network Control**: Provides configuration for server port and mount point for flexible deployment scenarios

4. **Optional Authentication**: Supports username/password authentication for secure access control

5. **Adaptive Behavior**: Can respond to configuration changes at runtime without application restart

## Implementation Details

The RTSP streaming system is implemented in `src/streaming/rtsp.rs` and consists of:

### RtspConfig

Configuration struct that controls streaming behavior:

```rust
pub struct RtspConfig {
    pub enabled: bool,
    pub port: u16,
    pub mount_point: String,
    pub quality: StreamQuality,
    pub custom_width: Option<u32>,
    pub custom_height: Option<u32>,
    pub custom_bitrate: Option<u32>,
    pub custom_framerate: Option<u32>,
    pub username: Option<String>,
    pub password: Option<String>,
}
```

### StreamQuality

Enum specifying predefined quality levels:

```rust
pub enum StreamQuality {
    Low,
    Medium,
    High,
    Custom,
}
```

### RtspServer

The core server class that manages the stream:

```rust
pub struct RtspServer {
    config: RtspConfig,
    frame_rx: Option<mpsc::Receiver<Frame>>,
    is_running: Arc<Mutex<bool>>,
    gst_process: Option<Child>,
    frame_tx: Option<mpsc::Sender<Frame>>,
}
```

The server class provides methods for:
- Starting and stopping the stream
- Feeding frames to the stream
- Updating configuration at runtime
- Checking stream status
- Getting the stream URL

## Technical Implementation

The RTSP system uses GStreamer as the underlying streaming engine:

1. **Pipeline Architecture**:
   - Input: OpenCV frames from the camera module
   - Processing: Conversion to H.264 video
   - Output: RTSP streams via rtsp2sink

2. **Data Flow**:
   - Frames are received through a `tokio::sync::mpsc` channel
   - They are processed and fed to the GStreamer pipeline
   - GStreamer handles encoding and network transmission

3. **External Process**:
   - The GStreamer pipeline runs as a separate process
   - Communication happens through standard input/output
   - This improves stability by isolating potential crashes

## Integration with the Application

The RTSP server integrates with the meteor detection application:

1. **Initialization**: In `main.rs`, an RTSP server instance is created during application startup
2. **Configuration**: Settings are loaded from the application configuration file
3. **Frame Feeding**: A dedicated task continuously feeds frames from the frame buffer to the RTSP server
4. **Lifecycle Management**: The server is started/stopped based on configuration and application state

## Configuration Example

The RTSP server can be configured in the application configuration file:

```toml
[rtsp]
enabled = true
port = 8554
mount_point = "/meteor"
quality = "Medium"  # "Low", "Medium", "High", or "Custom"
custom_width = 1280  # Only used if quality = "Custom"
custom_height = 720  # Only used if quality = "Custom"
custom_bitrate = 2000  # In kbps, only used if quality = "Custom"
custom_framerate = 30  # Only used if quality = "Custom"
username = "admin"  # Optional
password = "password"  # Optional
```

## Quality Presets

The system provides the following quality presets:

| Quality | Resolution | Bitrate | Framerate |
|---------|------------|---------|-----------|
| Low     | 640x480    | 500 kbps | 15 fps   |
| Medium  | 1280x720   | 1500 kbps | 30 fps  |
| High    | 1920x1080  | 3000 kbps | 30 fps  |
| Custom  | User-defined | User-defined | User-defined |

## Client Access

Clients can access the stream using any RTSP-compatible player:

```
# Using VLC
vlc rtsp://[username:password@]hostname:port/meteor

# Using FFmpeg
ffplay rtsp://[username:password@]hostname:port/meteor

# Using GStreamer
gst-launch-1.0 playbin uri=rtsp://[username:password@]hostname:port/meteor
```

## Performance Considerations

The streaming system is designed with performance in mind:

1. **Resource Management**: Frames are only encoded when the RTSP server is active and has clients
2. **Buffer Control**: A limited-size frame buffer prevents memory issues with slow clients
3. **Adaptive Encoding**: Different quality presets allow adaptation to available bandwidth and CPU
4. **Separate Process**: Using a separate GStreamer process isolates encoding load from the main application

For resource-constrained environments (like Raspberry Pi), consider:
- Using the Low quality preset
- Reducing the framerate
- Disabling streaming when not needed

## Security Considerations

When deploying the RTSP server:

1. **Authentication**: Enable username/password authentication when exposing to untrusted networks
2. **Firewall Rules**: Restrict access to the RTSP port (default: 8554) to trusted IP addresses
3. **TLS Tunneling**: For additional security, consider tunneling RTSP over TLS using a reverse proxy
4. **Privacy**: Be aware that streaming may include sensitive metadata in watermarks (GPS coordinates, etc.)

## Extending the System

The streaming system can be extended in several ways:

1. **Multiple Streams**: Support for multiple streams with different qualities
2. **Recording**: Adding direct-to-disk recording capability
3. **Stream Health Monitoring**: Adding diagnostics for stream performance
4. **WebRTC Support**: Adding WebRTC for browser-based viewing
5. **Adaptive Bitrate**: Implementing dynamic quality adjustment based on network conditions

## Troubleshooting

Common issues and solutions:

1. **Stream Not Starting**: Check that GStreamer and its RTSP plugins are installed on the system
2. **No Video**: Verify that the camera is producing frames and that encoding parameters are compatible
3. **High Latency**: Adjust the buffer size or reduce quality settings
4. **Connection Refused**: Ensure the port is not blocked by a firewall
5. **Poor Quality**: Try increasing the bitrate or resolution in the configuration

## Conclusion

The RTSP Streaming System provides a robust and configurable way to share live video from the meteor detection system. Its integration with industry-standard protocols ensures compatibility with a wide range of client applications and systems, making it suitable for both amateur and professional astronomical observation networks.