rtaspi 0.1.39

Real-Time Annotation and Stream Processing Interface

RTASPI Documentation ✍

Overview

RTASPI (Real-Time Audio and Stream Processing Interface) is a comprehensive Python library for managing and processing audio/video streams, device control, and automation. This documentation provides detailed information about all aspects of the library.

Table of Contents

Getting Started

• Installation Guide - Complete installation instructions
• Quick Start - Get up and running quickly
• Basic Concepts - Core concepts and architecture
• Scripts Guide - Utility scripts for installation and configuration

Core Features

• Configuration - Configuration system and options
• Device Management - Working with devices
• Streaming - Stream handling and processing
• Processing - Audio/video processing capabilities
• Security - Security features and analysis

Interfaces

• API Reference - Complete API documentation
• CLI Guide - Command-line interface usage
• Web Interface - Web interface documentation

Advanced Topics

• DSL Guide - Domain Specific Language for pipelines
• Automation - Rules and automation system
• Industrial Integration - Industrial protocols support
• Speech Processing - Speech recognition and processing

Development

• Development Guide - Contributing to RTASPI
• Project Structure - Codebase organization
• Testing Guide - Testing procedures and guidelines

Examples and Tutorials

• Example Projects - Complete project examples
• Local Development - Local development setup
• Examples Directory - Code examples by category

Directory Structure

docs/
├── README.md                 # This file
├── automation/              # Automation documentation
├── devices/                # Device management docs
├── dsl/                    # DSL documentation
├── industrial/            # Industrial protocols docs
├── processing/            # Processing documentation
├── security/              # Security features docs
├── streaming/             # Streaming documentation
└── web/                   # Web interface docs

Contributing

See CONTRIBUTING.md for guidelines on contributing to the documentation.

License

This documentation is licensed under the same terms as the RTASPI project. See LICENSE for details.

Usage Examples and Tutorials ✍

This document provides practical examples and tutorials for common RTASPI use cases.

Basic Examples

1. Stream from USB Webcam

# Start RTASPI
rtaspi start

# List available devices
rtaspi devices list

# Start RTSP stream from webcam
rtaspi streams start \
  --device video0 \
  --protocol rtsp \
  --path /webcam \
  --video-codec h264 \
  --video-bitrate 2M

Access the stream at: rtsp://localhost:8554/webcam

2. Connect IP Camera

# Add network camera
rtaspi devices add \
  --type network \
  --protocol rtsp \
  --address 192.168.1.100 \
  --port 554 \
  --username admin \
  --password secret

# Start WebRTC stream
rtaspi streams start \
  --device ipcam1 \
  --protocol webrtc \
  --path /camera1

Access the stream at: http://localhost:8080/webrtc/camera1

3. Record Audio from Microphone

# Start RTMP stream from microphone
rtaspi streams start \
  --device audio0 \
  --protocol rtmp \
  --path /mic \
  --audio-codec aac \
  --audio-bitrate 128k

# Record stream
rtaspi pipelines create \
  --input mic_stream \
  --config - <<EOF
output:
  - type: "record"
    format: "mp3"
    path: "recordings/"
EOF

Advanced Examples

1. Motion Detection Pipeline

Create a pipeline that detects motion and sends notifications:

# motion_detection.yaml
pipelines:
  - id: "security_cam"
    input:
      stream_id: "camera1"
    
    stages:
      - type: "motion_detector"
        sensitivity: 0.8
        region: [0, 0, 1920, 1080]
        min_area: 1000
      
      - type: "object_detector"
        model: "yolov3"
        confidence: 0.5
        classes: ["person", "car"]
      
      - type: "event_trigger"
        conditions:
          - type: "motion"
            duration: 5
          - type: "object"
            classes: ["person"]
    
    output:
      - type: "webhook"
        url: "http://localhost:8000/alerts"
      
      - type: "record"
        format: "mp4"
        duration: 30
        pre_buffer: 5

# Start the pipeline
rtaspi pipelines create --config motion_detection.yaml

2. Multi-Camera Setup

Stream from multiple cameras with different configurations:

# multi_camera.yaml
streams:
  - id: "entrance_cam"
    device_id: "ipcam1"
    protocol: "rtsp"
    path: "/entrance"
    settings:
      video:
        codec: "h264"
        bitrate: "2M"
        framerate: 30
      audio:
        enabled: false
  
  - id: "parking_cam"
    device_id: "ipcam2"
    protocol: "rtmp"
    path: "/parking"
    settings:
      video:
        codec: "h264"
        bitrate: "1M"
        framerate: 15
      audio:
        enabled: false
  
  - id: "reception_cam"
    device_id: "video0"
    protocol: "webrtc"
    path: "/reception"
    settings:
      video:
        codec: "vp8"
        bitrate: "1.5M"
      audio:
        enabled: true
        codec: "opus"

# Start all streams
rtaspi streams start --config multi_camera.yaml

3. Video Processing Pipeline

Create a pipeline for real-time video processing:

# video_processing.yaml
pipelines:
  - id: "video_effects"
    input:
      stream_id: "webcam_stream"
    
    stages:
      - type: "resize"
        width: 1280
        height: 720
      
      - type: "color_correction"
        brightness: 1.2
        contrast: 1.1
        saturation: 1.1
      
      - type: "overlay"
        text: "%timestamp%"
        position: [10, 10]
        font: "Arial"
        size: 24
      
      - type: "face_detection"
        model: "face_detection_v1"
        blur_faces: true
    
    output:
      - type: "rtmp"
        url: "rtmp://localhost/live/processed"
      
      - type: "webrtc"
        path: "/processed"

# Start the processing pipeline
rtaspi pipelines create --config video_processing.yaml

4. Audio Processing Pipeline

Create a pipeline for audio processing:

# audio_processing.yaml
pipelines:
  - id: "audio_effects"
    input:
      stream_id: "mic_stream"
    
    stages:
      - type: "noise_reduction"
        strength: 0.7
      
      - type: "equalizer"
        bands:
          - frequency: 100
            gain: -3
          - frequency: 1000
            gain: 2
          - frequency: 8000
            gain: 1
      
      - type: "compressor"
        threshold: -20
        ratio: 4
        attack: 5
        release: 50
      
      - type: "speech_detection"
        language: "en"
        output_format: "srt"
    
    output:
      - type: "rtmp"
        url: "rtmp://localhost/live/processed_audio"
      
      - type: "file"
        path: "subtitles.srt"

# Start the audio processing pipeline
rtaspi pipelines create --config audio_processing.yaml

Integration Examples

1. Web Application Integration

// Connect to WebSocket API
const ws = new WebSocket('ws://localhost:8081/api/ws');

// Subscribe to events
ws.send(JSON.stringify({
  type: 'subscribe',
  topics: ['devices/status', 'streams/status']
}));

// Handle events
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  switch(data.type) {
    case 'device_status':
      updateDeviceStatus(data);
      break;
    case 'stream_status':
      updateStreamStatus(data);
      break;
  }
};

// Start WebRTC stream
async function startStream(deviceId) {
  const response = await fetch('http://localhost:8081/api/streams', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ' + token
    },
    body: JSON.stringify({
      device_id: deviceId,
      protocol: 'webrtc',
      path: '/stream1'
    })
  });
  
  const data = await response.json();
  const player = new RTCPeerConnection();
  // ... WebRTC setup code ...
}

2. REST API Integration

Python example using requests:

import requests

class RTASPIClient:
    def __init__(self, base_url, token):
        self.base_url = base_url
        self.headers = {'Authorization': f'Bearer {token}'}
    
    def list_devices(self):
        response = requests.get(
            f'{self.base_url}/api/devices',
            headers=self.headers
        )
        return response.json()
    
    def start_stream(self, device_id, protocol, path):
        response = requests.post(
            f'{self.base_url}/api/streams',
            headers=self.headers,
            json={
                'device_id': device_id,
                'protocol': protocol,
                'path': path
            }
        )
        return response.json()
    
    def create_pipeline(self, config):
        response = requests.post(
            f'{self.base_url}/api/pipelines',
            headers=self.headers,
            json=config
        )
        return response.json()

# Usage example
client = RTASPIClient('http://localhost:8081', 'your-token')

# List devices
devices = client.list_devices()

# Start stream
stream = client.start_stream('video0', 'rtsp', '/webcam')

# Create pipeline
pipeline = client.create_pipeline({
    'id': 'motion_detection',
    'input': {'stream_id': stream['id']},
    'stages': [
        {
            'type': 'motion_detector',
            'sensitivity': 0.8
        }
    ],
    'output': [
        {
            'type': 'webhook',
            'url': 'http://localhost:8000/events'
        }
    ]
})

3. System Service Integration

Create a systemd service for automatic startup:

1. Create service file /etc/systemd/system/rtaspi.service:

[Unit]
Description=RTASPI Service
After=network.target

[Service]
Type=simple
User=rtaspi
Environment=RTASPI_CONFIG=/etc/rtaspi/config.yaml
ExecStart=/usr/local/bin/rtaspi start
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

2. Create configuration in /etc/rtaspi/config.yaml:

system:
  storage_path: "/var/lib/rtaspi"
  log_level: "INFO"

local_devices:
  enable_video: true
  enable_audio: true
  auto_start: true

streaming:
  rtsp:
    port_start: 8554
  rtmp:
    port_start: 1935
  webrtc:
    port_start: 8080

3. Setup and start service:

# Create rtaspi user
sudo useradd -r rtaspi

# Create directories
sudo mkdir -p /etc/rtaspi /var/lib/rtaspi
sudo chown -R rtaspi:rtaspi /etc/rtaspi /var/lib/rtaspi

# Enable and start service
sudo systemctl enable rtaspi
sudo systemctl start rtaspi

Best Practices

1. Resource Management

   • Monitor system resources
   • Use appropriate video quality settings
   • Clean up unused streams and pipelines

2. Security

   • Use strong passwords
   • Enable SSL/TLS
   • Implement access control
   • Monitor access logs

3. Performance

   • Choose appropriate codecs
   • Set reasonable bitrates
   • Monitor network bandwidth
   • Use hardware acceleration when available

4. Reliability

   • Implement error handling
   • Set up automatic recovery
   • Monitor system health
   • Keep logs for troubleshooting

Installation Guide ✍

This guide covers the installation and initial setup of RTASPI.

System Requirements

• Python 3.8 or newer
• FFmpeg 4.0 or newer
• GStreamer 1.14 or newer (for WebRTC support)
• NGINX with RTMP module (for RTMP support)

Dependencies Installation

Ubuntu/Debian

# Update package list
sudo apt update

# Install system dependencies
sudo apt install -y \
    python3 python3-pip python3-venv \
    ffmpeg \
    gstreamer1.0-tools \
    gstreamer1.0-plugins-base \
    gstreamer1.0-plugins-good \
    gstreamer1.0-plugins-bad \
    gstreamer1.0-plugins-ugly \
    nginx \
    libnginx-mod-rtmp \
    v4l-utils

# Install additional development libraries
sudo apt install -y \
    build-essential \
    python3-dev \
    libgstreamer1.0-dev \
    libgstreamer-plugins-base1.0-dev \
    libavcodec-dev \
    libavformat-dev \
    libswscale-dev

macOS (using Homebrew)

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install python@3.10
brew install ffmpeg
brew install gstreamer
brew install gst-plugins-base
brew install gst-plugins-good
brew install gst-plugins-bad
brew install gst-plugins-ugly
brew install nginx

Windows

1. Install Python 3.8 or newer from python.org

2. Install FFmpeg:

   • Download from ffmpeg.org
   • Add to system PATH

3. Install GStreamer:

   • Download from gstreamer.freedesktop.org
   • Select Complete installation
   • Add to system PATH

4. Install NGINX with RTMP module:

   • Download from nginx-rtmp-win32

RTASPI Installation

1. Create Virtual Environment

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Linux/macOS:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

2. Install RTASPI

# Install from PyPI
pip install rtaspi

# Or install from source
git clone https://github.com/rt-asp/rtaspi.git
cd rtaspi
pip install -e .

3. Configuration

1. Create configuration directory:

# Linux/macOS
mkdir -p ~/.config/rtaspi

# Windows (PowerShell)
New-Item -ItemType Directory -Force -Path "$env:APPDATA\rtaspi"

2. Create basic configuration:

# config.yaml
system:
  storage_path: "~/.local/share/rtaspi"  # Windows: %LOCALAPPDATA%\rtaspi
  log_level: "INFO"

local_devices:
  enable_video: true
  enable_audio: true
  auto_start: false

streaming:
  rtsp:
    port_start: 8554
  rtmp:
    port_start: 1935
  webrtc:
    port_start: 8080
    stun_server: "stun:stun.l.google.com:19302"

4. System Service Setup (Linux)

1. Create service file:

sudo tee /etc/systemd/system/rtaspi.service << 'EOF'
[Unit]
Description=RTASPI Service
After=network.target

[Service]
Type=simple
User=rtaspi
Environment=RTASPI_CONFIG=/etc/rtaspi/config.yaml
ExecStart=/usr/local/bin/rtaspi start
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

2. Create system user and directories:

# Create system user
sudo useradd -r rtaspi

# Create configuration directories
sudo mkdir -p /etc/rtaspi /var/lib/rtaspi
sudo chown -R rtaspi:rtaspi /etc/rtaspi /var/lib/rtaspi

3. Enable and start service:

sudo systemctl enable rtaspi
sudo systemctl start rtaspi

5. Verify Installation

1. Check RTASPI version:

rtaspi --version

2. List available devices:

rtaspi devices list

3. Check system status:

rtaspi status

Troubleshooting

Common Issues

1. Missing Dependencies

# Check Python version
python --version

# Check FFmpeg installation
ffmpeg -version

# Check GStreamer installation
gst-launch-1.0 --version

2. Permission Issues

# Add user to video group (Linux)
sudo usermod -a -G video $USER

# Check device permissions
ls -l /dev/video*

3. Port Conflicts

# Check if ports are in use
sudo netstat -tulpn | grep "8554\|1935\|8080"

Debug Mode

Enable debug logging for troubleshooting:

# config.yaml
system:
  log_level: "DEBUG"
  debug_mode: true

Log Files

Check logs for detailed information:

# System service logs
sudo journalctl -u rtaspi

# Application logs
tail -f ~/.local/share/rtaspi/logs/rtaspi.log

Next Steps

• Read the Configuration Guide for detailed configuration options
• Check the Examples for common usage scenarios
• Explore the API Reference for programmatic control
• See the CLI Guide for command-line usage

Core Concepts ✍

This document explains the core concepts and architecture of RTASPI.

Architecture Overview

RTASPI is built with a modular architecture where different components communicate through a central message broker using the Module Communication Protocol (MCP). Here's a high-level overview:

graph TD
    A[Device Managers] -->|MCP| B[Core Broker]
    C[Streaming Services] -->|MCP| B
    D[Processing Pipeline] -->|MCP| B
    E[Web Interface] -->|MCP| B
    F[CLI] -->|MCP| B
    G[API Server] -->|MCP| B

Key Components

1. Device Managers

Device managers handle the discovery and management of audio/video devices:

• Local Device Manager: Manages USB cameras, webcams, and microphones connected directly to the system
• Network Device Manager: Handles IP cameras and network audio devices, supporting:
  • ONVIF protocol for IP cameras
  • UPnP for device discovery
  • mDNS for zero-configuration networking

2. Streaming Services

RTASPI supports multiple streaming protocols:

• RTSP (Real Time Streaming Protocol)

  • Ideal for low-latency streaming
  • Supports both server and client modes
  • Used for IP camera integration

• RTMP (Real Time Messaging Protocol)

  • Popular for streaming to services like YouTube, Twitch
  • Supports high-quality video delivery
  • Built-in NGINX-RTMP integration

• WebRTC

  • Browser-based real-time communication
  • Peer-to-peer capabilities
  • Low latency video conferencing features

3. Processing Pipeline

The processing pipeline enables real-time media processing:

graph LR
    A[Input Stream] --> B[Decoder]
    B --> C[Processing Filters]
    C --> D[Encoder]
    D --> E[Output Stream]

Supported processing features:

• Video filters (resize, crop, rotate, etc.)
• Audio filters (normalize, noise reduction, etc.)
• Object detection
• Motion detection
• Speech recognition

4. Module Communication Protocol (MCP)

MCP is the backbone of RTASPI's inter-module communication:

• Publish/Subscribe Pattern: Modules communicate by publishing messages to topics and subscribing to receive messages
• Message Types:
  • Commands: Request actions from modules
  • Events: Notify about state changes
  • Data: Share information between modules
• Topics Structure:
  • devices/*: Device-related messages
  • streams/*: Streaming-related messages
  • processing/*: Processing pipeline messages
  • command/*: Control commands

Example MCP message flow:

sequenceDiagram
    participant CLI
    participant Broker
    participant DeviceManager
    participant StreamService
    
    CLI->>Broker: Publish command/devices/start_stream
    Broker->>DeviceManager: Forward command
    DeviceManager->>StreamService: Initialize stream
    StreamService->>Broker: Publish stream/started
    Broker->>CLI: Forward status

5. Configuration System

RTASPI uses YAML-based configuration files:

• rtaspi.config.yaml: Main system configuration
• rtaspi.devices.yaml: Device configurations
• rtaspi.streams.yaml: Stream configurations
• rtaspi.pipeline.yaml: Processing pipeline configurations

6. Web Interface

The web interface provides:

• Device management dashboard
• Stream monitoring
• Pipeline configuration
• System statistics

7. CLI Tool

The command-line interface enables:

• System control
• Device management
• Stream control
• Pipeline management
• Configuration updates

8. API Server

RESTful API providing:

• Device control endpoints
• Stream management
• Pipeline configuration
• System monitoring

Data Flow

1. Device Discovery:

   • Local devices are detected through system APIs
   • Network devices are discovered via protocols (ONVIF, UPnP, mDNS)
   • Device information is published to MCP

2. Stream Management:

   • Stream requests are sent via CLI/API/Web
   • Device manager initializes the device
   • Streaming service creates appropriate server/client
   • Processing pipeline is configured if needed

3. Processing Pipeline:

   • Input stream is decoded
   • Configured filters are applied
   • Processed stream is encoded
   • Output is sent to streaming service

Best Practices

1. Device Management:

   • Regular device scanning intervals
   • Proper error handling for device disconnections
   • Automatic stream recovery

2. Stream Handling:

   • Buffer management for smooth playback
   • Adaptive bitrate when supported
   • Proper stream cleanup on termination

3. Resource Management:

   • CPU/memory monitoring
   • Stream quality vs resource usage balance
   • Proper cleanup of resources

4. Security:

   • Authentication for web/API access
   • Secure storage of device credentials
   • HTTPS/WSS for web interface

CLI Guide ✍

RTASPI provides a powerful command-line interface (CLI) for managing devices, streams, and pipelines. This guide covers all available commands and their usage.

Installation

The CLI is automatically installed with RTASPI. You can verify the installation by running:

rtaspi --version

Shell Completion

RTASPI supports shell completion for bash, zsh, and fish shells.

Bash

source <(rtaspi completion bash)
# Add to ~/.bashrc for permanent installation
echo 'source <(rtaspi completion bash)' >> ~/.bashrc

Zsh

source <(rtaspi completion zsh)
# Add to ~/.zshrc for permanent installation
echo 'source <(rtaspi completion zsh)' >> ~/.zshrc

Fish

rtaspi completion fish > ~/.config/fish/completions/rtaspi.fish

Global Options

• --config, -c: Path to configuration file (default: rtaspi.config.yaml)
• --verbose, -v: Enable verbose output
• --quiet, -q: Suppress output
• --json: Output in JSON format
• --help, -h: Show help message

Commands

System Management

Start RTASPI

rtaspi start [options]

Options:

• --daemon: Run in background
• --log-file: Path to log file
• --pid-file: Path to PID file

Stop RTASPI

rtaspi stop

Show System Status

rtaspi status

View Logs

rtaspi logs [options]

Options:

• --level: Log level (debug, info, warning, error)
• --follow, -f: Follow log output
• --tail: Number of lines to show
• --since: Show logs since timestamp

Device Management

List Devices

rtaspi devices list [options]

Options:

• --type: Filter by device type (video, audio)
• --status: Filter by status (active, inactive)
• --format: Output format (table, json)

Example:

# List all video devices
rtaspi devices list --type video

# List active devices in JSON format
rtaspi devices list --status active --format json

Show Device Details

rtaspi devices show <device-id>

Example:

rtaspi devices show video0

Add Network Device

rtaspi devices add [options]

Options:

• --type: Device type (network)
• --protocol: Protocol (rtsp, onvif)
• --address: IP address
• --port: Port number
• --username: Username
• --password: Password

Example:

rtaspi devices add \
  --type network \
  --protocol rtsp \
  --address 192.168.1.100 \
  --port 554 \
  --username admin \
  --password secret

Update Device Settings

rtaspi devices update <device-id> [options]

Options:

• --resolution: Video resolution
• --framerate: Frame rate
• --format: Video format

Example:

rtaspi devices update video0 --resolution 1280x720 --framerate 30

Remove Device

rtaspi devices remove <device-id>

Stream Management

List Streams

rtaspi streams list [options]

Options:

• --protocol: Filter by protocol (rtsp, rtmp, webrtc)
• --status: Filter by status (active, stopped)

Show Stream Details

rtaspi streams show <stream-id>

Start Stream

rtaspi streams start [options]

Options:

• --device: Device ID
• --protocol: Streaming protocol
• --path: Stream path
• --video-codec: Video codec
• --video-bitrate: Video bitrate
• --audio-enabled: Enable audio

Example:

rtaspi streams start \
  --device video0 \
  --protocol rtsp \
  --path /webcam \
  --video-codec h264 \
  --video-bitrate 2M

Stop Stream

rtaspi streams stop <stream-id>

Pipeline Management

List Pipelines

rtaspi pipelines list

Show Pipeline Details

rtaspi pipelines show <pipeline-id>

Create Pipeline

rtaspi pipelines create [options]

Options:

• --input: Input stream ID
• --config: Pipeline configuration file

Example:

rtaspi pipelines create \
  --input webcam_stream \
  --config pipeline.yaml

Delete Pipeline

rtaspi pipelines delete <pipeline-id>

Configuration Management

Show Current Configuration

rtaspi config show [section]

Example:

# Show all configuration
rtaspi config show

# Show specific section
rtaspi config show streaming

Update Configuration

rtaspi config set <key> <value>

Example:

rtaspi config set streaming.rtsp.port_start 8554

Validate Configuration

rtaspi config validate [file]

Development Tools

Generate API Client

rtaspi dev generate-client [options]

Options:

• --language: Target language (python, javascript)
• --output: Output directory

Run Tests

rtaspi dev test [options]

Options:

• --unit: Run unit tests
• --integration: Run integration tests
• --coverage: Generate coverage report

Profile Performance

rtaspi dev profile [options]

Options:

• --duration: Profile duration
• --output: Output file

Examples

Basic Usage

1. Start RTASPI:

rtaspi start

2. List available devices:

rtaspi devices list

3. Start streaming from a webcam:

rtaspi streams start \
  --device video0 \
  --protocol rtsp \
  --path /webcam

Advanced Usage

1. Create a motion detection pipeline:

rtaspi pipelines create \
  --input webcam_stream \
  --config - <<EOF
stages:
  - type: motion_detector
    sensitivity: 0.8
  - type: object_detector
    model: yolov3
output:
  - type: webhook
    url: http://localhost:8000/events
EOF

2. Monitor system status and logs:

# Show system status
rtaspi status

# Follow logs
rtaspi logs -f --level info

3. Manage multiple streams:

# Start multiple streams
rtaspi streams start --device video0 --protocol rtsp --path /cam1
rtaspi streams start --device video1 --protocol webrtc --path /cam2

# List active streams
rtaspi streams list --status active

Best Practices

1. Shell Completion: Install shell completion for improved productivity

2. JSON Output: Use --json for scripting and automation:

rtaspi devices list --json | jq '.devices[].id'

3. Configuration Management:

• Keep configuration files under version control
• Use environment variables for sensitive information
• Regularly validate configuration files

4. Logging:

• Use appropriate log levels for different environments
• Rotate log files to manage disk space
• Monitor logs for errors and warnings

5. Resource Management:

• Monitor system resources with rtaspi status
• Clean up unused streams and pipelines
• Use appropriate video quality settings

6. Security:

• Use strong passwords for network devices
• Enable SSL for production deployments
• Regularly update RTASPI and dependencies

API Reference ✍

RTASPI provides a comprehensive RESTful API for managing devices, streams, and pipelines. This document details all available endpoints and their usage.

Authentication

The API uses JWT (JSON Web Token) authentication. To access protected endpoints:

1. Obtain a token:

curl -X POST http://localhost:8081/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your-password"}'

2. Use the token in subsequent requests:

curl -H "Authorization: Bearer your-token" http://localhost:8081/api/devices

Device Management

List Devices

GET /api/devices

Response:

{
  "devices": [
    {
      "id": "video0",
      "type": "video",
      "name": "Webcam",
      "status": "active",
      "capabilities": {
        "resolutions": ["1920x1080", "1280x720"],
        "formats": ["YUYV", "MJPG"]
      }
    }
  ]
}

Get Device Details

GET /api/devices/{device_id}

Response:

{
  "id": "video0",
  "type": "video",
  "name": "Webcam",
  "path": "/dev/video0",
  "status": "active",
  "settings": {
    "resolution": "1920x1080",
    "framerate": 30,
    "format": "YUYV"
  },
  "capabilities": {
    "resolutions": ["1920x1080", "1280x720"],
    "formats": ["YUYV", "MJPG"],
    "framerates": [30, 60]
  }
}

Add Network Device

POST /api/devices

Request:

{
  "type": "network",
  "protocol": "rtsp",
  "address": "192.168.1.100",
  "port": 554,
  "path": "/stream1",
  "username": "admin",
  "password": "password"
}

Update Device Settings

PATCH /api/devices/{device_id}

Request:

{
  "settings": {
    "resolution": "1280x720",
    "framerate": 60
  }
}

Remove Device

DELETE /api/devices/{device_id}

Stream Management

List Streams

GET /api/streams

Response:

{
  "streams": [
    {
      "id": "webcam_stream",
      "device_id": "video0",
      "protocol": "rtsp",
      "status": "active",
      "url": "rtsp://localhost:8554/webcam"
    }
  ]
}

Get Stream Details

GET /api/streams/{stream_id}

Response:

{
  "id": "webcam_stream",
  "device_id": "video0",
  "protocol": "rtsp",
  "status": "active",
  "url": "rtsp://localhost:8554/webcam",
  "settings": {
    "video": {
      "codec": "h264",
      "bitrate": "2M",
      "framerate": 30
    },
    "audio": {
      "enabled": false
    }
  },
  "stats": {
    "uptime": 3600,
    "bytes_sent": 1024000,
    "clients_connected": 2
  }
}

Start Stream

POST /api/streams

Request:

{
  "device_id": "video0",
  "protocol": "rtsp",
  "path": "/webcam",
  "settings": {
    "video": {
      "codec": "h264",
      "bitrate": "2M"
    },
    "audio": {
      "enabled": false
    }
  }
}

Update Stream Settings

PATCH /api/streams/{stream_id}

Request:

{
  "settings": {
    "video": {
      "bitrate": "4M"
    }
  }
}

Stop Stream

DELETE /api/streams/{stream_id}

Pipeline Management

List Pipelines

GET /api/pipelines

Response:

{
  "pipelines": [
    {
      "id": "motion_detection",
      "status": "running",
      "input": {
        "stream_id": "webcam_stream"
      }
    }
  ]
}

Get Pipeline Details

GET /api/pipelines/{pipeline_id}

Response:

{
  "id": "motion_detection",
  "status": "running",
  "input": {
    "stream_id": "webcam_stream"
  },
  "stages": [
    {
      "type": "motion_detector",
      "settings": {
        "sensitivity": 0.8,
        "region": [0, 0, 1920, 1080]
      }
    }
  ],
  "output": [
    {
      "type": "webhook",
      "url": "http://localhost:8000/events"
    }
  ],
  "stats": {
    "uptime": 3600,
    "events_triggered": 10,
    "last_event": "2025-04-29T08:15:30Z"
  }
}

Create Pipeline

POST /api/pipelines

Request:

{
  "id": "motion_detection",
  "input": {
    "stream_id": "webcam_stream"
  },
  "stages": [
    {
      "type": "motion_detector",
      "sensitivity": 0.8,
      "region": [0, 0, 1920, 1080]
    },
    {
      "type": "object_detector",
      "model": "yolov3",
      "confidence": 0.5
    }
  ],
  "output": [
    {
      "type": "webhook",
      "url": "http://localhost:8000/events"
    }
  ]
}

Update Pipeline

PATCH /api/pipelines/{pipeline_id}

Request:

{
  "stages": [
    {
      "type": "motion_detector",
      "sensitivity": 0.9
    }
  ]
}

Delete Pipeline

DELETE /api/pipelines/{pipeline_id}

System Management

Get System Status

GET /api/system/status

Response:

{
  "version": "1.0.0",
  "uptime": 3600,
  "components": {
    "web_interface": "running",
    "api_server": "running",
    "device_manager": "running"
  },
  "resources": {
    "cpu_usage": 25.5,
    "memory_usage": 512.0,
    "disk_usage": 1024.0
  }
}

Get System Logs

GET /api/system/logs

Query Parameters:

• level: Log level (debug, info, warning, error)
• start: Start timestamp
• end: End timestamp
• limit: Maximum number of logs to return

Response:

{
  "logs": [
    {
      "timestamp": "2025-04-29T08:00:00Z",
      "level": "info",
      "component": "device_manager",
      "message": "New device detected: video0"
    }
  ]
}

Update System Configuration

PATCH /api/system/config

Request:

{
  "system": {
    "log_level": "DEBUG"
  },
  "streaming": {
    "rtsp": {
      "port_start": 8654
    }
  }
}

WebSocket API

RTASPI also provides a WebSocket API for real-time updates.

Connect to WebSocket

const ws = new WebSocket('ws://localhost:8081/api/ws');

Subscribe to Events

ws.send(JSON.stringify({
  type: 'subscribe',
  topics: [
    'devices/status',
    'streams/status',
    'pipelines/events'
  ]
}));

Event Examples

Device Status Change:

{
  "type": "device_status",
  "device_id": "video0",
  "status": "active",
  "timestamp": "2025-04-29T08:00:00Z"
}

Stream Status Update:

{
  "type": "stream_status",
  "stream_id": "webcam_stream",
  "status": "streaming",
  "clients_connected": 2,
  "timestamp": "2025-04-29T08:00:00Z"
}

Pipeline Event:

{
  "type": "pipeline_event",
  "pipeline_id": "motion_detection",
  "event": {
    "type": "motion_detected",
    "region": [100, 100, 200, 200],
    "confidence": 0.85
  },
  "timestamp": "2025-04-29T08:00:00Z"
}

Error Handling

The API uses standard HTTP status codes and returns detailed error messages:

{
  "error": {
    "code": "DEVICE_NOT_FOUND",
    "message": "Device with ID 'video0' not found",
    "details": {
      "device_id": "video0"
    }
  }
}

Common status codes:

• 200: Success
• 201: Created
• 400: Bad Request
• 401: Unauthorized
• 403: Forbidden
• 404: Not Found
• 409: Conflict
• 500: Internal Server Error

Rate Limiting

The API implements rate limiting to prevent abuse:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1619683200

Versioning

The API version is included in the response headers:

X-API-Version: 1.0.0

CORS

The API supports Cross-Origin Resource Sharing (CORS) for web client integration:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, PATCH, DELETE
Access-Control-Allow-Headers: Content-Type, Authorization

# Configuration Guide [<span style='font-size:20px;'>&#x270D;</span>]([e-mail]:rt-asp/rtaspi/edit/main/docs/CONFIGURATION.md)

RTASPI uses YAML configuration files to manage its settings. This guide explains all available configuration options.

## Configuration Files

RTASPI uses several configuration files:

1. **rtaspi.config.yaml**: Main system configuration
2. **rtaspi.devices.yaml**: Device-specific settings
3. **rtaspi.streams.yaml**: Stream configurations
4. **rtaspi.pipeline.yaml**: Processing pipeline settings
5. **rtaspi.secrets.yaml**: Sensitive information (credentials, tokens)

## Main Configuration (rtaspi.config.yaml)

### System Settings
```yaml
system:
  # Base directory for storing temporary files, logs, etc.
  storage_path: "storage"
  
  # Logging level (DEBUG, INFO, WARNING, ERROR)
  log_level: "INFO"
  
  # Enable/disable system components
  components:
    web_interface: true
    api_server: true
    cli: true

Local Device Settings

local_devices:
  # Enable/disable device types
  enable_video: true
  enable_audio: true
  
  # Auto-start streams when devices are detected
  auto_start: false
  
  # Device scanning interval (seconds)
  scan_interval: 60
  
  # Starting ports for different protocols
  rtsp_port_start: 8554
  rtmp_port_start: 1935
  webrtc_port_start: 8080
  
  # Device-specific settings
  video_settings:
    default_resolution: "1280x720"
    default_framerate: 30
  
  audio_settings:
    default_sample_rate: 44100
    default_channels: 2

Network Device Settings

network_devices:
  # Enable network device support
  enable: true
  
  # Device scanning interval (seconds)
  scan_interval: 60
  
  # Discovery settings
  discovery:
    enabled: true
    methods:
      - "onvif"
      - "upnp"
      - "mdns"
    
  # Protocol port ranges
  rtsp_port_start: 8654
  rtmp_port_start: 2935
  webrtc_port_start: 9080

Streaming Settings

streaming:
  rtsp:
    # RTSP server settings
    port_start: 8554
    transport: ["tcp", "udp"]
    
  rtmp:
    # RTMP server settings
    port_start: 1935
    chunk_size: 4096
    
  webrtc:
    # WebRTC settings
    port_start: 8080
    stun_server: "stun://stun.l.google.com:19302"
    turn_server: ""
    turn_username: ""
    turn_password: ""

Processing Settings

processing:
  # Video processing settings
  video:
    enable_gpu: true
    default_codec: "h264"
    
  # Audio processing settings
  audio:
    enable_noise_reduction: true
    default_codec: "aac"
    
  # Pipeline settings
  pipeline:
    buffer_size: 10
    max_parallel: 4

Web Interface Settings

web:
  # HTTP server settings
  host: "0.0.0.0"
  port: 8080
  
  # Security settings
  ssl:
    enabled: false
    cert_file: ""
    key_file: ""
  
  # Authentication
  auth:
    enabled: true
    type: "basic"  # basic, jwt

API Settings

api:
  # API server settings
  host: "0.0.0.0"
  port: 8081
  
  # Security settings
  auth:
    enabled: true
    type: "jwt"
    token_expiry: 3600

Device Configuration (rtaspi.devices.yaml)

Local Device Example

devices:
  local:
    - id: "video0"
      type: "video"
      path: "/dev/video0"
      name: "Webcam"
      settings:
        resolution: "1920x1080"
        framerate: 30
        format: "YUYV"
    
    - id: "audio0"
      type: "audio"
      path: "hw:0,0"
      name: "Microphone"
      settings:
        sample_rate: 48000
        channels: 2
        format: "S16LE"

Network Device Example

devices:
  network:
    - id: "ipcam1"
      type: "video"
      protocol: "rtsp"
      address: "192.168.1.100"
      port: 554
      path: "/stream1"
      username: "${IPCAM1_USER}"  # References secrets file
      password: "${IPCAM1_PASS}"
      settings:
        profile: "high"

Stream Configuration (rtaspi.streams.yaml)

streams:
  - id: "webcam_stream"
    device_id: "video0"
    protocol: "rtsp"
    path: "/webcam"
    settings:
      video:
        codec: "h264"
        bitrate: "2M"
      audio:
        enabled: false
    
  - id: "ipcam_proxy"
    device_id: "ipcam1"
    protocol: "webrtc"
    path: "/camera1"
    processing:
      - type: "resize"
        width: 1280
        height: 720
      - type: "object_detection"
        model: "yolov3"

Pipeline Configuration (rtaspi.pipeline.yaml)

pipelines:
  - id: "motion_detection"
    input:
      stream_id: "ipcam_proxy"
    stages:
      - type: "motion_detector"
        sensitivity: 0.8
        region: [0, 0, 1920, 1080]
      
      - type: "object_detector"
        model: "yolov3"
        confidence: 0.5
        
      - type: "event_trigger"
        conditions:
          - type: "motion"
            duration: 5
          - type: "object"
            classes: ["person", "car"]
    
    output:
      - type: "webhook"
        url: "http://localhost:8000/events"
      - type: "record"
        format: "mp4"
        duration: 30

Secrets Configuration (rtaspi.secrets.yaml)

secrets:
  # Device credentials
  IPCAM1_USER: "admin"
  IPCAM1_PASS: "password123"
  
  # API tokens
  API_SECRET_KEY: "your-secret-key"
  
  # External service credentials
  CLOUD_STORAGE_KEY: "your-storage-key"

Enum Configuration

RTASPI supports configurable enumerations that can be overridden through the configuration hierarchy. This allows customizing enum values without modifying the code.

Enum Configuration in YAML

enums:
  # Device type overrides
  DeviceType:
    USB_CAMERA: "usb_cam"    # Override auto() value
    IP_CAMERA: "ip_cam"
    
  # Device protocol overrides
  DeviceProtocol:
    RTSP: "rtsp_stream"      # Override default "rtsp" value
    WEBRTC: "webrtc_peer"    # Override default "webrtc" value

Environment Variable Overrides

Enum values can be overridden using environment variables following the pattern:

RTASPI_{ENUM_CLASS}_{ENUM_NAME}=value

Examples:

# Override DeviceType.USB_CAMERA value
export RTASPI_DEVICETYPE_USB_CAMERA=usb_cam

# Override DeviceProtocol.RTSP value
export RTASPI_DEVICEPROTOCOL_RTSP=rtsp_stream

Configuration Hierarchy

Enum values are resolved in the following order:

1. Environment variables (RTASPI_{ENUM_CLASS}_{ENUM_NAME})
2. Project configuration (rtaspi.config.yaml)
3. User configuration (~/.config/rtaspi/config.yaml)
4. Global configuration (/etc/rtaspi/config.yaml)
5. Default enum value

Usage in Code

from rtaspi.constants.devices import DeviceType
from rtaspi.core.config import ConfigManager

config_manager = ConfigManager()

# Get value using the hierarchical system
camera_type = DeviceType.USB_CAMERA.get_value(config_manager)

# Get constant-style name
type_constant = DeviceType.USB_CAMERA.CONSTANT_NAME  # Returns "USB_CAMERA"

Environment Variables

Configuration values can reference environment variables using ${VAR_NAME} syntax. This is particularly useful for sensitive information:

api:
  auth:
    secret_key: "${API_SECRET_KEY}"

Best Practices

1. Security:

   • Keep sensitive information in rtaspi.secrets.yaml
   • Use environment variables for deployment-specific settings
   • Enable SSL for production deployments

2. Performance:

   • Adjust buffer sizes based on available memory
   • Enable GPU processing if available
   • Set appropriate scan intervals

3. Maintenance:

   • Regular backup of configuration files
   • Version control for configuration changes
   • Documentation of custom settings

4. Troubleshooting:

   • Set log_level to DEBUG for detailed logging
   • Monitor resource usage
   • Regular validation of configuration files

Development Guide ✍

This guide provides information for developers who want to contribute to RTASPI or extend its functionality.

Development Environment Setup

1. Clone the Repository

git clone https://github.com/rt-asp/rtaspi.git
cd rtaspi

2. Create Virtual Environment

python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

3. Install Development Dependencies

pip install -r requirements-dev.txt

4. Install Pre-commit Hooks

pre-commit install

Project Structure

rtaspi/
├── docs/               # Documentation
├── examples/           # Example configurations and scripts
├── scripts/           # Development and maintenance scripts
├── src/               # Source code
│   └── rtaspi/
│       ├── api/       # REST API implementation
│       ├── cli/       # Command-line interface
│       ├── core/      # Core functionality
│       ├── device_managers/  # Device management
│       ├── processing/      # Stream processing
│       ├── schemas/   # Data models and validation
│       ├── streaming/ # Streaming protocols
│       └── web/       # Web interface
├── tests/             # Test suite
└── tools/             # Development tools

Code Style

RTASPI follows PEP 8 with some modifications:

• Line length: 100 characters
• Docstring style: Google
• Import order: stdlib, third-party, local
• Type hints: Required for public interfaces

Example:

from typing import List, Optional
import os
import sys

import numpy as np
from pydantic import BaseModel

from rtaspi.core.types import DeviceID
from rtaspi.schemas.device import Device


class StreamConfig(BaseModel):
    """Configuration for a media stream.

    Args:
        device_id: ID of the source device
        protocol: Streaming protocol to use
        path: Stream path/endpoint
        settings: Optional stream settings

    Raises:
        ValueError: If protocol is invalid
    """
    device_id: DeviceID
    protocol: str
    path: str
    settings: Optional[dict] = None

    def validate_protocol(self) -> None:
        """Validate the streaming protocol.

        Raises:
            ValueError: If protocol is not supported
        """
        valid_protocols = ["rtsp", "rtmp", "webrtc"]
        if self.protocol not in valid_protocols:
            raise ValueError(f"Invalid protocol: {self.protocol}")

Testing

Running Tests

# Run all tests
pytest

# Run specific test file
pytest tests/test_discovery.py

# Run tests with coverage
pytest --cov=rtaspi

# Run tests in parallel
pytest -n auto

Writing Tests

Use pytest fixtures and parametrize for clean, maintainable tests:

import pytest
from rtaspi.device_managers.discovery import DeviceDiscovery

@pytest.fixture
def discovery():
    """Create a DeviceDiscovery instance for testing."""
    return DeviceDiscovery()

@pytest.mark.parametrize("protocol,expected", [
    ("rtsp", True),
    ("invalid", False),
])
def test_protocol_validation(discovery, protocol, expected):
    """Test protocol validation logic."""
    assert discovery.is_valid_protocol(protocol) == expected

Documentation

Building Documentation

# Install documentation dependencies
pip install -r docs/requirements.txt

# Build documentation
cd docs
make html

Writing Documentation

• Use clear, concise language
• Include code examples
• Document exceptions and edge cases
• Keep API documentation up-to-date
• Add diagrams where helpful

Debugging

Logging

from rtaspi.core.logging import get_logger

logger = get_logger(__name__)

logger.debug("Detailed information")
logger.info("General information")
logger.warning("Warning message")
logger.error("Error message", exc_info=True)

Debugging Tools

1. Interactive Debugger

import pdb; pdb.set_trace()

2. Debug Configuration

system:
  log_level: "DEBUG"
  debug_mode: true

3. Performance Profiling

python -m cProfile -o profile.stats your_script.py
python -m pstats profile.stats

Contributing

Workflow

1. Fork and Clone

git clone https://github.com/your-username/rtaspi.git

2. Create Feature Branch

git checkout -b feature/your-feature-name

3. Make Changes

• Write code
• Add tests
• Update documentation

4. Run Quality Checks

# Run linter
flake8 src tests

# Run type checker
mypy src

# Run tests
pytest

# Run pre-commit hooks
pre-commit run --all-files

5. Commit Changes

git add .
git commit -m "feat: add your feature description"

6. Push and Create Pull Request

git push origin feature/your-feature-name

Commit Message Format

Follow conventional commits:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes
• refactor: Code refactoring
• test: Test changes
• chore: Build/maintenance changes

Example:

feat(streaming): add WebRTC support

- Add WebRTC streaming capability
- Implement STUN/TURN configuration
- Add WebRTC stream tests

Extension Points

Adding New Device Types

1. Create new device manager class:

from rtaspi.device_managers.base import DeviceManager

class CustomDeviceManager(DeviceManager):
    """Custom device manager implementation."""

    def discover_devices(self):
        """Implement device discovery logic."""
        pass

    def start_device(self, device_id: str):
        """Implement device start logic."""
        pass

2. Register device manager:

from rtaspi.core.registry import register_device_manager

register_device_manager("custom", CustomDeviceManager)

Adding Processing Filters

1. Create new filter class:

from rtaspi.processing.base import Filter

class CustomFilter(Filter):
    """Custom video/audio filter implementation."""

    def process_frame(self, frame):
        """Implement frame processing logic."""
        pass

2. Register filter:

from rtaspi.core.registry import register_filter

register_filter("custom", CustomFilter)

Adding Stream Protocols

1. Create new protocol handler:

from rtaspi.streaming.base import StreamHandler

class CustomProtocolHandler(StreamHandler):
    """Custom streaming protocol implementation."""

    def start_stream(self, config):
        """Implement stream start logic."""
        pass

    def stop_stream(self):
        """Implement stream stop logic."""
        pass

2. Register protocol:

from rtaspi.core.registry import register_protocol

register_protocol("custom", CustomProtocolHandler)

Performance Optimization

Memory Management

• Use generators for large datasets
• Implement proper cleanup in __del__ methods
• Monitor memory usage with memory_profiler

CPU Optimization

• Use numpy for numerical operations
• Implement caching where appropriate
• Profile code to identify bottlenecks

GPU Acceleration

• Use CUDA when available
• Implement fallback for CPU-only systems
• Profile GPU memory usage

Deployment

Building Packages

# Build wheel
python setup.py bdist_wheel

# Build source distribution
python setup.py sdist

Creating System Service

1. Create service file:

[Unit]
Description=RTASPI Service
After=network.target

[Service]
Type=simple
User=rtaspi
ExecStart=/usr/local/bin/rtaspi start
Restart=always

[Install]
WantedBy=multi-user.target

2. Install service:

sudo cp rtaspi.service /etc/systemd/system/
sudo systemctl enable rtaspi
sudo systemctl start rtaspi

Troubleshooting

Common Issues

1. Device Detection

• Check device permissions
• Verify hardware compatibility
• Check system logs

2. Streaming Issues

• Verify network connectivity
• Check port availability
• Monitor system resources

3. Performance Problems

• Profile code execution
• Monitor resource usage
• Check for memory leaks

Debug Tools

1. System Information

rtaspi dev debug-info

2. Connection Testing

rtaspi dev test-connection

3. Resource Monitoring

rtaspi dev monitor

Security Considerations

1. Input Validation

• Validate all user input
• Sanitize file paths
• Check parameter bounds

2. Authentication

• Use secure password storage
• Implement rate limiting
• Use HTTPS for web interface

3. Device Access

• Implement device access control
• Validate device credentials
• Monitor device access logs

Best Practices

1. Code Quality

• Write comprehensive tests
• Document public interfaces
• Follow type hints
• Keep functions focused

2. Performance

• Profile before optimizing
• Use appropriate data structures
• Implement caching strategically

3. Security

• Review security implications
• Keep dependencies updated
• Follow security best practices

4. Maintenance

• Keep documentation updated
• Review and update dependencies
• Monitor system health

Project Structure ✍

This document provides an overview of RTASPI's directory structure and organization.

Root Directory

rtaspi/
├── docs/               # Documentation
├── examples/           # Example configurations and scripts
├── install/            # Installation scripts and guides
├── scripts/           # Maintenance and setup scripts
├── service/           # System service scripts
├── src/               # Source code
├── tests/             # Test suite
└── update/            # Update and maintenance tools

Source Code Structure

src/rtaspi/
├── api/               # REST API implementation
│   ├── devices.py     # Device management endpoints
│   ├── pipelines.py   # Pipeline management endpoints
│   ├── server.py      # API server implementation
│   └── streams.py     # Stream management endpoints
│
├── cli/               # Command-line interface
│   ├── commands/      # CLI command implementations
│   ├── completion/    # Shell completion scripts
│   └── shell.py       # CLI shell implementation
│
├── core/              # Core functionality
│   ├── config.py      # Configuration management
│   ├── logging.py     # Logging system
│   ├── mcp.py         # Module Communication Protocol
│   └── utils.py       # Utility functions
│
├── device_managers/   # Device management
│   ├── base.py        # Base device manager class
│   ├── local_devices.py    # Local device management
│   ├── network_devices.py  # Network device management
│   └── utils/        # Device management utilities
│
├── dsl/               # Domain Specific Language
│   ├── executor.py    # DSL execution engine
│   ├── lexer.py       # DSL lexical analyzer
│   └── parser.py      # DSL parser
│
├── processing/        # Stream processing
│   ├── audio/        # Audio processing
│   │   ├── filters.py   # Audio filters
│   │   └── speech.py    # Speech recognition
│   ├── video/        # Video processing
│   │   ├── detection.py # Object detection
│   │   └── filters.py   # Video filters
│   └── pipeline_executor.py  # Processing pipeline
│
├── quick/            # Quick access utilities
│   ├── camera.py     # Camera utilities
│   ├── microphone.py # Microphone utilities
│   └── utils.py      # Quick access helpers
│
├── schemas/          # Data models and validation
│   ├── device.py     # Device schemas
│   ├── pipeline.py   # Pipeline schemas
│   └── stream.py     # Stream schemas
│
├── streaming/        # Streaming protocols
│   ├── rtmp.py       # RTMP implementation
│   ├── rtsp.py       # RTSP implementation
│   ├── webrtc.py     # WebRTC implementation
│   └── utils.py      # Streaming utilities
│
└── web/             # Web interface
    ├── acme.py       # ACME protocol support
    ├── api.py        # Web API implementation
    ├── interface.py  # Web interface
    └── server.py     # Web server

Documentation Structure

docs/
├── API.md            # REST API reference
├── CLI.md            # Command-line interface guide
├── CONCEPTS.md       # Architecture and core concepts
├── CONFIGURATION.md  # Configuration guide
├── DEVELOPMENT.md    # Development guide
├── EXAMPLES.md       # Usage examples and tutorials
├── INSTALL.md        # Installation guide
├── README.md         # Project overview
└── TREE.md          # This file

Scripts and Tools

scripts/
├── configure_hardware.sh  # Hardware configuration
├── install_models.sh      # ML model installation
├── optimize_rpi.sh        # Raspberry Pi optimization
├── publish.sh            # Package publishing
├── setup_service.sh      # Service setup
└── upgrade.sh            # System upgrade

service/
├── start.sh             # Service start script
└── stop.sh              # Service stop script

update/
├── requirements.py      # Dependencies update
└── versions.py         # Version management

Configuration Files

rtaspi/
├── rtaspi.config.yaml    # Main configuration
├── rtaspi.devices.yaml   # Device configuration
├── rtaspi.pipeline.yaml  # Pipeline configuration
├── rtaspi.secrets.yaml   # Sensitive information
└── rtaspi.streams.yaml   # Stream configuration

Development Files

rtaspi/
├── pyproject.toml       # Project metadata
├── setup.cfg           # Package configuration
├── setup.py            # Package setup
├── requirements.txt    # Dependencies
├── MANIFEST.in         # Package manifest
└── Makefile           # Build automation

Key Directories

• src/rtaspi/: Main source code

  • Core functionality and implementations
  • Modular architecture with clear separation of concerns
  • Each module focuses on specific functionality

• docs/: Documentation

  • Comprehensive guides and references
  • Examples and tutorials
  • Architecture documentation

• tests/: Test suite

  • Unit tests
  • Integration tests
  • Test fixtures and utilities

• scripts/: Utility scripts

  • Installation and setup
  • System optimization
  • Maintenance tools

• service/: System service

  • Service management scripts
  • System integration

File Organization

The project follows a modular structure where:

1. Each major feature has its own directory
2. Related functionality is grouped together
3. Common utilities are centralized
4. Configuration is separated from code
5. Documentation is comprehensive and organized

This structure enables:

• Easy navigation
• Clear separation of concerns
• Modular development
• Simple maintenance
• Straightforward testing

.
├── CHANGELOG.md
├── changelog.py
├── config.yaml
├── CONTRIBUTING.md
├── debug_imports.py
├── dist
├── docs
│   ├── API.md
│   ├── CLI.md
│   ├── CONCEPTS.md
│   ├── CONFIGURATION.md
│   ├── DEVELOPMENT.md
│   ├── EXAMPLES.md
│   ├── INSTALL.md
│   ├── POST
│   │   ├── DE
│   │   ├── EN
│   │   └── PL
│   ├── PROJECTS_LOCAL.md
│   ├── PROJECTS.md
│   ├── README.md
│   ├── SPEECH_AND_INPUT.md
│   ├── TEST.md
│   └── TREE.md
├── DONE.md
├── examples
│   ├── automation
│   │   └── rules.json
│   ├── commands
│   │   └── keyboard_commands.json
│   ├── config
│   │   ├── project.config.yaml
│   │   ├── README.md
│   │   ├── rtaspi.config.yaml
│   │   └── user.config.yaml
│   ├── industrial
│   │   ├── modbus_config.yaml
│   │   └── opcua_config.yaml
│   └── security
│       ├── alarms_config.yaml
│       └── behavior_config.yaml
├── fedora
│   └── python.sh
├── flatedit.txt
├── git.sh
├── install
│   ├── pyaudio2.py
│   ├── pyaudio2.sh
│   ├── pyaudio3.sh
│   ├── pyaudiodiag.py
│   ├── pyaudio.py
│   ├── pyaudio.sh
│   ├── pyautogui.md
│   ├── pyautogui.py
│   ├── README.md
│   ├── SPACY.md
│   ├── spacy.sh
│   └── windows.ps1
├── LICENSE
├── Makefile
├── MANIFEST.in
├── pyproject.toml
├── pyproject.toml.bak
├── README.md
├── requirements-dev.txt
├── requirements.txt
├── rtaspi.config.yaml
├── rtaspi.devices.yaml
├── rtaspi.pipeline.yaml
├── rtaspi.secrets.yaml
├── rtaspi.streams.yaml
├── scripts
│   ├── configure_hardware.sh
│   ├── install_models.sh
│   ├── optimize_rpi.sh
│   ├── publish.sh
│   ├── setup_service.sh
│   └── upgrade.sh
├── service
│   ├── start.sh
│   └── stop.sh
├── setup.cfg
├── setup.py
├── src
│   ├── rtaspi
│   │   ├── api
│   │   ├── automation
│   │   ├── cli
│   │   ├── config
│   │   ├── constants
│   │   ├── core
│   │   ├── device_managers
│   │   ├── dsl
│   │   ├── __init__.py
│   │   ├── input
│   │   ├── __main__.py
│   │   ├── main.py
│   │   ├── processing
│   │   ├── __pycache__
│   │   ├── quick
│   │   ├── schemas
│   │   ├── security
│   │   ├── streaming
│   │   ├── _version.py
│   │   ├── _version.py.bak
│   │   └── web
│   └── rtaspi.egg-info
│       ├── dependency_links.txt
│       ├── entry_points.txt
│       ├── PKG-INFO
│       ├── requires.txt
│       ├── SOURCES.txt
│       └── top_level.txt
├── storage
├── test_imports.py
├── tests
│   ├── conftest.py
│   ├── __init__.py
│   ├── test_audio_filters.py
│   ├── test_command_processor.py
│   ├── test_discovery.py
│   ├── test_dsc.py
│   ├── test_hass.py
│   ├── test_honeywell.py
│   ├── test_intercom.py
│   ├── test_keyboard.py
│   ├── test_local_devices.py
│   ├── test_modbus.py
│   ├── test_motion.py
│   ├── test_mqtt.py
│   ├── test_network_devices.py
│   ├── test_opcua.py
│   ├── test_remote_desktop_manager.py
│   ├── test_remote_desktop.py
│   ├── test_sip.py
│   ├── test_speech_recognition.py
│   ├── test_streaming.py
│   ├── test_video_filters.py
│   ├── test_vnc.py
│   └── test_window_capture.py
├── TODO2.md
├── TODO.md
├── TODO.txt
├── tox.ini
├── update
│   ├── duplicated.py
│   ├── duplicated.sh
│   ├── pip.sh
│   ├── requirements.py
│   ├── requirements.sh
│   └── versions.py

├── version
│   ├── project.py
│   ├── README.md
│   ├── setup.py
│   └── src.py
└── version.sh

---

• Modular Documentation made possible by the FlatEdit project.