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:

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:

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

RtspServer

The core server class that manages the stream:

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:

[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.