rtaspi

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.

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:

Create service file /etc/systemd/system/rtaspi.service: ```ini [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`:
```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

Setup and start service: ```bash
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 [<span style='font-size:20px;'>&#x270D;</span>](git@github.com:rt-asp/rtaspi/edit/main/docs/INSTALL.md)

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

```bash
# 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

Install Python 3.8 or newer from python.org
Install FFmpeg:
- Download from ffmpeg.org
- Add to system PATH
Install GStreamer:
- Download from gstreamer.freedesktop.org
- Select Complete installation
- Add to system PATH
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

Create configuration directory: ```bash
Linux/macOS

mkdir -p ~/.config/rtaspi

Windows (PowerShell)

New-Item -ItemType Directory -Force -Path “$env:APPDATA\rtaspi”

2. Create basic configuration:
```yaml
# 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)

Create service file: ```bash 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:
```bash
# 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

Enable and start service:

sudo systemctl enable rtaspi
sudo systemctl start rtaspi

5. Verify Installation

Check RTASPI version:
```
rtaspi --version
```
List available devices:
```
rtaspi devices list
```
Check system status:
```
rtaspi status
```

Troubleshooting

Common Issues

Missing Dependencies ```bash
Check Python version

python –version

Check FFmpeg installation

ffmpeg -version

Check GStreamer installation

gst-launch-1.0 –version

2. **Permission Issues**
```bash
# Add user to video group (Linux)
sudo usermod -a -G video $USER

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

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

Device Discovery:
- Local devices are detected through system APIs
- Network devices are discovered via protocols (ONVIF, UPnP, mDNS)
- Device information is published to MCP
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
Processing Pipeline:
- Input stream is decoded
- Configured filters are applied
- Processed stream is encoded
- Output is sent to streaming service

Best Practices

Device Management:
- Regular device scanning intervals
- Proper error handling for device disconnections
- Automatic stream recovery
Stream Handling:
- Buffer management for smooth playback
- Adaptive bitrate when supported
- Proper stream cleanup on termination
Resource Management:
- CPU/memory monitoring
- Stream quality vs resource usage balance
- Proper cleanup of resources
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

Start RTASPI:
```
rtaspi start
```
List available devices:
```
rtaspi devices list
```

Start streaming from a webcam:

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

Advanced Usage

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

Monitor system status and logs: ```bash
Show system status

rtaspi status

Follow logs

rtaspi logs -f –level info

3. Manage multiple streams:
```bash
# 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

Shell Completion: Install shell completion for improved productivity

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

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

Configuration Management:
- Keep configuration files under version control
- Use environment variables for sensitive information
- Regularly validate configuration files
Logging:
- Use appropriate log levels for different environments
- Rotate log files to manage disk space
- Monitor logs for errors and warnings
Resource Management:
- Monitor system resources with rtaspi status
- Clean up unused streams and pipelines
- Use appropriate video quality settings
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:

Obtain a token:

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

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');

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>](git@github.com: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:

Environment variables (RTASPI_{ENUM_CLASS}_{ENUM_NAME})
Project configuration (rtaspi.config.yaml)
User configuration (~/.config/rtaspi/config.yaml)
Global configuration (/etc/rtaspi/config.yaml)
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

Security:
- Keep sensitive information in rtaspi.secrets.yaml
- Use environment variables for deployment-specific settings
- Enable SSL for production deployments
Performance:
- Adjust buffer sizes based on available memory
- Enable GPU processing if available
- Set appropriate scan intervals
Maintenance:
- Regular backup of configuration files
- Version control for configuration changes
- Documentation of custom settings
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

Clone the Repository

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

Create Virtual Environment

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

Install Development Dependencies
```
pip install -r requirements-dev.txt
```
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

Interactive Debugger
```
import pdb; pdb.set_trace()
```

Debug Configuration

system:
  log_level: "DEBUG"
  debug_mode: true

Performance Profiling

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

Contributing

Workflow

Fork and Clone

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

Create Feature Branch

git checkout -b feature/your-feature-name

Make Changes
- Write code
- Add tests
- Update documentation
Run Quality Checks ```bash
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**
```bash
git add .
git commit -m "feat: add your feature description"

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

Create new device manager class: ```python 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 ```

register_device_manager(“custom”, CustomDeviceManager)

### Adding Processing Filters

1. Create new filter class:
```python
from rtaspi.processing.base import Filter

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

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

register_filter(“custom”, CustomFilter)

### Adding Stream Protocols

1. Create new protocol handler:
```python
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

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

```bash
# Build wheel
python setup.py bdist_wheel

# Build source distribution
python setup.py sdist

Creating System Service

Create service file: ```ini [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:
```bash
sudo cp rtaspi.service /etc/systemd/system/
sudo systemctl enable rtaspi
sudo systemctl start rtaspi

Troubleshooting

Common Issues

Device Detection
- Check device permissions
- Verify hardware compatibility
- Check system logs
Streaming Issues
- Verify network connectivity
- Check port availability
- Monitor system resources
Performance Problems
- Profile code execution
- Monitor resource usage
- Check for memory leaks

Debug Tools

System Information
```
rtaspi dev debug-info
```
Connection Testing
```
rtaspi dev test-connection
```
Resource Monitoring
```
rtaspi dev monitor
```

Security Considerations

Input Validation
- Validate all user input
- Sanitize file paths
- Check parameter bounds
Authentication
- Use secure password storage
- Implement rate limiting
- Use HTTPS for web interface
Device Access
- Implement device access control
- Validate device credentials
- Monitor device access logs

Best Practices

Code Quality
- Write comprehensive tests
- Document public interfaces
- Follow type hints
- Keep functions focused
Performance
- Profile before optimizing
- Use appropriate data structures
- Implement caching strategically
Security
- Review security implications
- Keep dependencies updated
- Follow security best practices
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:

Each major feature has its own directory
Related functionality is grouped together
Common utilities are centralized
Configuration is separated from code
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.

This site is open source. Improve this page.

rtaspi

RTASPI Documentation ✍

Overview

Table of Contents

Getting Started

Core Features

Interfaces

Advanced Topics

Development

Examples and Tutorials

Directory Structure

Contributing

License

Usage Examples and Tutorials ✍

Basic Examples

1. Stream from USB Webcam

2. Connect IP Camera

3. Record Audio from Microphone

Advanced Examples

1. Motion Detection Pipeline

2. Multi-Camera Setup

3. Video Processing Pipeline

4. Audio Processing Pipeline

Integration Examples

1. Web Application Integration

2. REST API Integration

3. System Service Integration

Create rtaspi user

Create directories

Enable and start service

macOS (using Homebrew)

Windows

RTASPI Installation

1. Create Virtual Environment

2. Install RTASPI

3. Configuration

Linux/macOS

Windows (PowerShell)

4. System Service Setup (Linux)

5. Verify Installation

Troubleshooting

Common Issues

Check Python version

Check FFmpeg installation

Check GStreamer installation

Debug Mode

Log Files

Next Steps

Core Concepts ✍

Architecture Overview

Key Components

1. Device Managers

2. Streaming Services

3. Processing Pipeline

4. Module Communication Protocol (MCP)

5. Configuration System

6. Web Interface

7. CLI Tool

8. API Server

Data Flow

Best Practices

CLI Guide ✍

Installation

Shell Completion

Bash

Zsh

Fish

Global Options

Commands

System Management

Start RTASPI

Stop RTASPI

Show System Status

View Logs

Device Management

List Devices

Show Device Details

Add Network Device

Update Device Settings

Remove Device