# bluenviron/gortsplib architecture

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

- Interactive diagram: https://gitdiagram.com/bluenviron/gortsplib
- Repository: https://github.com/bluenviron/gortsplib

## Overview

The gortsplib project is a robust RTSP 1.0/2.0 client and server library written in Go. Its primary purpose is to provide both client and server capabilities for media streaming via RTSP, including reading (“play”) and writing (“record”) media streams over various transport protocols (UDP, multicast, TCP, and TLS), as well as handling codec-specific operations for a wide range of audio and video formats.

##### Main Components Identification
- Client Component – Contains modules for querying RTSP servers, playing media streams, handling transport protocols (UDP, multicast, TCP, TLS), and extra features (such as pause, seek, back channels, timestamps, etc.). Files like client.go and numerous examples (e.g., client-play, client-record) illustrate this.
- Server Component – Manages incoming RTSP requests from clients, validates credentials, processes “record” streams from clients, and serves “play” streams. Files such as server.go and server_session*.go represent this part.
- Protocol & Message Handling – Modules that parse and create RTSP messages, headers, and SDP elements (e.g., pkg/base, pkg/headers, pkg/sdp). This layer is responsible for interpreting requests/responses and generating proper messages.
- RTP & Media Format Processing – Encompasses the handling of RTP packet encoding/decoding and media format-specific logic (see pkg/format). This covers diverse media codecs such as H264, H265, VP8, AV1, and many audio formats.
- Auxiliary/Utility Libraries – Supporting components that handle connection management (pkg/conn), authentication (pkg/auth), error handling (pkg/liberrors), and additional functionalities like ring buffers, multicast, and multitasking (async_processor.go, pkg/multibuffer, pkg/ringbuffer).

##### Relationships and Interactions
- The Client and Server components both rely on the underlying protocol handling layers to encode, decode, and route RTSP messages.
- The Client makes requests (via functions in client.go and related example modules) that are parsed and routed on the Server side, which then uses session management (server_session*, server_stream*) to interact with media streams.
- The media stream processing layer (RTP and media format packages) interacts with network transport modules (e.g., server_udp_listener.go, server_tcp_listener.go, client_udp_listener.go) to send/receive packets.
- Authentication and header libraries work within both Client and Server to manage secure connections and protocol consistency.
- The examples folder reflects usage patterns that tie together the high-level API with the underlying packages.

##### Architectural Patterns and Design Principles
- Modular Design: The project is divided into clearly separated packages that encapsulate specific responsibilities (protocol parsing, media formats, session management, etc.).
- Layered Architecture: There is a high-level API (client/server) that uses lower-level utility libraries and protocol handlers. This layered approach eases both maintenance and extension.
- Separation of Concerns: For example, packages in pkg/base deal solely with the basic RTSP request/response structure; pkg/headers encapsulate header parsing; pkg/format handles codec-specific encoding/decoding.
- Extensibility: With clear modular boundaries, the library can be extended—for instance, to support new codecs or transport protocols—without rewriting the core logic.

##### Relevant Technologies, Frameworks, and Libraries
- Go (Go ≥ 1.21) is the implementation language, and the project follows Go project layout best practices.
- Testing is robust (as shown by test files across packages and workflows in .github/workflows) ensuring reliability.
- Integration with related projects such as MediaMTX and usage of third-party libraries like pion/rtp, pion/rtcp, and pion/sdp.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Module Subgraph
    subgraph "Client Module"
        C1["client.go (Client Main)"]:::client
        C2["client_media.go (Media Handler)"]:::client
        C3["client_format.go (Format Handler)"]:::client
        C4["client_reader.go (Reader)"]:::client
        C5["client_udp_listener.go (UDP Listener)"]:::client
        C6["Examples: client-play"]:::client
    end

    %% Shared Layers Subgraph
    subgraph "Shared Layers"
        subgraph "Protocol & Message Handling"
            P1["RTSP Parsing (pkg/base)"]:::protocol
            P2["Header Parsing (pkg/headers)"]:::protocol
            P3["SDP Handling (pkg/sdp)"]:::protocol
        end
        subgraph "RTP & Media Processing"
            M1["Media Codec & RTP Processing (pkg/format)"]:::media
        end
        subgraph "Auxiliary/Utility Libraries"
            U1["Connection Mgmt (pkg/conn)"]:::utility
            U2["Authentication (pkg/auth)"]:::utility
            U3["Error Handling (pkg/liberrors)"]:::utility
            U4["Async Processor (async_processor.go)"]:::utility
            U5a["Buffering: Multibuffer (pkg/multibuffer)"]:::utility
            U5b["Buffering: Ringbuffer (pkg/ringbuffer)"]:::utility
        end
    end

    %% Server Module Subgraph
    subgraph "Server Module"
        S1["server.go (Main Server)"]:::server
        S2["server_session.go & server_stream.go (Session Management)"]:::server
        S3["server_conn.go & server_handler.go (Connection Handler)"]:::server
        S4["server_tcp_listener.go (TCP Listener)"]:::server
        S5["server_udp_listener.go (UDP Listener)"]:::server
    end

    %% Interactions and Data Flow
    C1 -->|"sendsRTSP"| P1
    S1 -->|"receivesRTSP"| P1
    P1 -->|"triggersMedia"| M1
    C5 ---|"UDPstream"| S5

    %% Client and Server Direct Interaction
    C1 ---|"calls"| S1
    S1 ---|"sendsResponse"| C1

    %% Utility Library Usage
    C1 ---|"uses"| U1
    C1 ---|"uses"| U2
    S3 ---|"uses"| U1
    S3 ---|"uses"| U3
    S3 ---|"uses"| U4
    S1 ---|"uses"| U5a
    S1 ---|"uses"| U5b

    %% Class Definitions
    classDef client fill:#A7D3F5,stroke:#333,stroke-width:2px;
    classDef server fill:#F5A7A7,stroke:#333,stroke-width:2px;
    classDef protocol fill:#CCE5CC,stroke:#333,stroke-width:2px;
    classDef media fill:#FFF2CC,stroke:#333,stroke-width:2px;
    classDef utility fill:#D3CCE5,stroke:#333,stroke-width:2px;

    %% Click Events for Client Component
    click C1 "https://github.com/bluenviron/gortsplib/blob/main//client.go"
    click C2 "https://github.com/bluenviron/gortsplib/blob/main//client_media.go"
    click C3 "https://github.com/bluenviron/gortsplib/blob/main//client_format.go"
    click C4 "https://github.com/bluenviron/gortsplib/blob/main//client_reader.go"
    click C5 "https://github.com/bluenviron/gortsplib/blob/main//client_udp_listener.go"
    click C6 "https://github.com/bluenviron/gortsplib/tree/main//examples/client-play"

    %% Click Events for Server Component
    click S1 "https://github.com/bluenviron/gortsplib/blob/main//server.go"
    click S2 "https://github.com/bluenviron/gortsplib/blob/main//server_session.go"
    click S3 "https://github.com/bluenviron/gortsplib/blob/main//server_conn.go"
    click S4 "https://github.com/bluenviron/gortsplib/blob/main//server_tcp_listener.go"
    click S5 "https://github.com/bluenviron/gortsplib/blob/main//server_udp_listener.go"

    %% Click Events for Protocol & Message Handling
    click P1 "https://github.com/bluenviron/gortsplib/tree/main//pkg/base"
    click P2 "https://github.com/bluenviron/gortsplib/tree/main//pkg/headers"
    click P3 "https://github.com/bluenviron/gortsplib/tree/main//pkg/sdp"

    %% Click Event for RTP & Media Processing
    click M1 "https://github.com/bluenviron/gortsplib/tree/main//pkg/format"

    %% Click Events for Auxiliary/Utility Libraries
    click U1 "https://github.com/bluenviron/gortsplib/tree/main//pkg/conn"
    click U2 "https://github.com/bluenviron/gortsplib/tree/main//pkg/auth"
    click U3 "https://github.com/bluenviron/gortsplib/tree/main//pkg/liberrors"
    click U4 "https://github.com/bluenviron/gortsplib/blob/main//async_processor.go"
    click U5a "https://github.com/bluenviron/gortsplib/tree/main//pkg/multibuffer"
    click U5b "https://github.com/bluenviron/gortsplib/tree/main//pkg/ringbuffer"
```
