# alexxit/go2rtc architecture

> Architecture diagram of the GitHub repository alexxit/go2rtc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alexxit/go2rtc
- Repository: https://github.com/alexxit/go2rtc

## Overview

##### Project Type and Purpose
- It’s a monolithic, full-stack Go streaming server.
- Purpose: Ingest many camera/video/audio sources, perform on-the-fly transcoding via FFmpeg, and export streams via protocols (RTSP, WebRTC, HLS, MJPEG, MP4, RTMP, WebTorrent, HomeKit).

##### Top-Level Components
- Clients
– Web UI (HTML/JS in www/)
– REST/WebSocket API clients (browsers, Home Assistant, CLI examples)
– RTSP clients (e.g. FFmpeg, VLC, Home Assistant)
– WebRTC peers (browsers, OBS via WHIP)
– RTMP targets (YouTube, Telegram)
- go2rtc Server (single Go binary)
A. API Module (internal/api + www static assets + openapi.yaml)
B. Stream Manager (internal/streams)
C. Source Plugins (internal/{rtsp,rtmp,http,onvif,ffmpeg,homekit,…})
D. Output Modules
– RTSP Server (internal/rtsp)
– RTMP Server (internal/rtmp)
– WebRTC Server (internal/webrtc + Pion libraries)
– HLS Server (internal/hls)
– MP4/MSE Server (internal/mp4)
– MJPEG Server (internal/mjpeg)
– WebTorrent (internal/webtorrent)
– HomeKit Proxy (internal/homekit)
E. FFmpeg Manager (internal/ffmpeg) — spawns external ffmpeg processes
F. ngrok Integration (internal/ngrok) for NAT traversal
- External Dependencies
– FFmpeg CLI
– STUN/TURN servers
– ngrok service
– Home Assistant, Docker containers, hardware devices

##### Relationships and Data Flows
- Clients → API Module
– Configuration, “Add Stream,” status, UI assets
- API Module ↔ Stream Manager
– Control plane: start/stop streams, publish endpoints
- Stream Manager → Source Plugins
– Pull or subscribe to media from cameras and devices
- Source Plugins → Internal Media Pipeline
– Normalizes incoming tracks (audio/video)
– Negotiates codecs, may hand off to FFmpeg Manager for transcoding
- Media Pipeline → Output Modules
– Streams data to clients via RTSP/RTMP/WebRTC/HLS/MP4/MJPEG/WebTorrent/HomeKit
- Output Modules → Clients/External Services
– RTSP: clients at rtsp://…
– WebRTC: peer connections (UDP/TCP)
– HLS/MP4/MJPEG: HTTP endpoints
– RTMP: push to external RTMP URLs
– ngrok & STUN/TURN assist WebRTC NAT traversal

##### Architectural Patterns and Principles
- Layered modular monolith – clear separation of control plane (API) and data plane (streams)
- Plugin-style source/output modules under internal/ and pkg/
- Event-driven lifecycle – streams started on-demand, stopped when idle
- Zero-config “auto” streams via Home Assistant import or empty config

##### Technologies and Frameworks
- Go modules for: HTTP API (internal/api), WebSocket, RTSP, WebRTC (Pion), HLS, MJPEG, MP4, ngrok
- FFmpeg CLI spawned on demand for transcoding via internal/ffmpeg
- Static web UI in www/ served by API module
- OpenAPI spec in api/openapi.yaml for client integration
- Docker build definitions in docker/
- Examples in examples/ demonstrating client usage

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Clients["Clients: Browser / Home Assistant / FFmpeg / OBS"]:::external
    Clients -->|"REST / WebSocket"| API
    Clients -->|"RTSP pull"| StreamMgr
    Clients -->|"WebRTC Peer"| WebRTC_OUT

    %% Control Plane
    subgraph "Control Plane"
        API["API Module\n(HTTP API + WebSocket + static UI)"]:::core
        click API "https://github.com/alexxit/go2rtc/tree/master/internal/api"
    end

    API -->|"Control Plane"| StreamMgr
    StreamMgr -->|"Control Plane"| API

    %% Data Plane - Stream Manager
    subgraph "Data Plane"
        StreamMgr["Stream Manager"]:::core
        click StreamMgr "https://github.com/alexxit/go2rtc/tree/master/internal/streams"

        %% Source Plugins
        subgraph "Source Plugins" 
            S_RTSP_SRC["RTSP Source"]:::core
            click S_RTSP_SRC "https://github.com/alexxit/go2rtc/tree/master/internal/rtsp"
            S_RTMP_SRC["RTMP Source"]:::core
            click S_RTMP_SRC "https://github.com/alexxit/go2rtc/tree/master/internal/rtmp"
            S_HTTP["HTTP Source"]:::core
            click S_HTTP "https://github.com/alexxit/go2rtc/blob/master/internal/http/http.go"
            S_ONVIF["ONVIF Source"]:::core
            click S_ONVIF "https://github.com/alexxit/go2rtc/blob/master/internal/onvif/onvif.go"
            S_HASS["Home Assistant Source"]:::core
            click S_HASS "https://github.com/alexxit/go2rtc/blob/master/internal/hass/hass.go"
            S_OTHER["...other plugins"]:::core
        end

        StreamMgr -->|"subscribe/pull"| S_RTSP_SRC
        StreamMgr -->|"subscribe/pull"| S_RTMP_SRC
        StreamMgr -->|"subscribe/pull"| S_HTTP
        StreamMgr -->|"subscribe/pull"| S_ONVIF
        StreamMgr -->|"subscribe/pull"| S_HASS
        StreamMgr -->|"subscribe/pull"| S_OTHER

        %% FFmpeg Manager
        FFmpeg["FFmpeg Manager"]:::core
        click FFmpeg "https://github.com/alexxit/go2rtc/tree/master/internal/ffmpeg"
        S_OTHER -->|"hand off"| FFmpeg
        S_HTTP -->|"hand off"| FFmpeg
        S_RTSP_SRC -->|"negotiates codecs"| FFmpeg
    end

    %% Output Modules
    subgraph "Output Modules"
        RTSP_OUT["RTSP Server"]:::core
        click RTSP_OUT "https://github.com/alexxit/go2rtc/blob/master/internal/rtsp/rtsp.go"
        RTMP_OUT["RTMP Server"]:::core
        click RTMP_OUT "https://github.com/alexxit/go2rtc/blob/master/internal/rtmp/rtmp.go"
        WebRTC_OUT["WebRTC Server"]:::core
        click WebRTC_OUT "https://github.com/alexxit/go2rtc/tree/master/internal/webrtc"
        HLS_OUT["HLS Server"]:::core
        click HLS_OUT "https://github.com/alexxit/go2rtc/blob/master/internal/hls/hls.go"
        MP4_OUT["MP4/MSE Server"]:::core
        click MP4_OUT "https://github.com/alexxit/go2rtc/blob/master/internal/mp4/mp4.go"
        MJPEG_OUT["MJPEG Server"]:::core
        click MJPEG_OUT "https://github.com/alexxit/go2rtc/blob/master/internal/mjpeg/init.go"
        WT_OUT["WebTorrent"]:::core
        click WT_OUT "https://github.com/alexxit/go2rtc/blob/master/internal/webtorrent/init.go"
        HK_OUT["HomeKit Proxy"]:::core
        click HK_OUT "https://github.com/alexxit/go2rtc/blob/master/internal/homekit/homekit.go"
    end

    %% Data flow to outputs
    FFmpeg -->|"encoded streams"| RTSP_OUT
    FFmpeg -->|"encoded streams"| RTMP_OUT
    FFmpeg -->|"encoded streams"| WebRTC_OUT
    FFmpeg -->|"encoded streams"| HLS_OUT
    FFmpeg -->|"encoded streams"| MP4_OUT
    FFmpeg -->|"encoded streams"| MJPEG_OUT
    FFmpeg -->|"encoded streams"| WT_OUT
    FFmpeg -->|"encoded streams"| HK_OUT

    %% External Services and Dependencies
    subgraph "External Dependencies"
        FFmpegCLI["FFmpeg CLI"]:::extdep
        click FFmpegCLI "https://github.com/alexxit/go2rtc/tree/master/internal/ffmpeg"
        Ngrok["ngrok Integration"]:::extdep
        click Ngrok "https://github.com/alexxit/go2rtc/blob/master/internal/ngrok/ngrok.go"
        STUNTURN["STUN/TURN Servers"]:::extdep
    end

    WebRTC_OUT -->|"UDP/TCP ICE"| STUNTURN
    WebRTC_OUT -.->|"optional ngrok tunnel"| Ngrok

    %% Egress
    RTSP_OUT -->|"rtsp://... "| Clients
    RTMP_OUT -->|"RTMP push"| Clients
    WebRTC_OUT -->|"WebRTC Peer"| Clients
    HLS_OUT -->|"HTTP HLS"| Clients
    MP4_OUT -->|"HTTP MP4"| Clients
    MJPEG_OUT -->|"HTTP MJPEG"| Clients
    WT_OUT -->|"WebTorrent"| Clients
    HK_OUT -->|"HomeKit"| Clients

    %% Entry Point and Scripts
    Entry["main.go (Application Bootstrap)"]:::core
    click Entry "https://github.com/alexxit/go2rtc/blob/master/main.go"
    Scripts["CLI & Scripts"]:::core
    click Scripts "https://github.com/alexxit/go2rtc/tree/master/scripts/"
    Examples["Examples / Client Usage"]:::core
    click Examples "https://github.com/alexxit/go2rtc/tree/master/examples/"

    Entry --> API
    Entry --> StreamMgr
    Entry --> FFmpeg

    classDef external fill:#AEDFF7,stroke:#333,stroke-width:1px
    classDef core fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef extdep fill:#FFD0B2,stroke:#333,stroke-width:1px
```
