# illuspas/node-media-server architecture

> Architecture diagram of the GitHub repository illuspas/node-media-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/illuspas/node-media-server
- Repository: https://github.com/illuspas/node-media-server

## Overview

##### Project Type and Purpose
- This is a specialized full-stack Node.js application: a high-performance live streaming server (Node-Media-Server v4).
- It implements RTMP/RTMPS, HTTP/HTTP2-FLV push/play, static file serving, recording to FLV, notifications, and authentication.

##### File Structure Analysis
- bin/ : CLI entry point and TLS cert/config files.
- src/index.js : main bootstrap.
- src/core/ : core media abstractions (avcodec, avpacket, context, logger).
- src/protocol/ : protocol parsers/serializers (AMF, FLV, RTMP).
- src/server/ : server modules for each protocol and feature (rtmp_server, http_server, notify_server, broadcast_server, record_server).
- src/session/ : per-connection session logic (RTMP, FLV, record, base).
- src/vendor/ : third-party or compiled modules.
- Configuration: package.json, Dockerfile, GitHub workflows.

##### README Insights
- Describes supported protocols, features, clients, and configuration options (static files, recording path).
- Emphasizes high-performance/low-latency streaming and lack of external database.

##### Main Components & Interactions
a. Ingest Clients
- OBS/FFmpeg → push streams via RTMP/RTMPS or HTTP-FLV to the server.
b. Protocol Layer
- RTMP Server (port 1935), HTTP/HTTP2-FLV Server (port 8000/8443)
- Uses src/protocol modules to parse incoming chunks.
c. Session Layer
- Creates a Session object for each connection (rtmp_session, flv_session).
- Manages handshakes, authentication, and lifecycle.
d. Core Processing
- src/core/context: coordinates publishers, subscribers, GOP cache.
- src/core/avpacket & avcodec: encapsulate video/audio frames.
- Logger for diagnostics.
e. Server Features
- Broadcast Server: routes packets from publisher to subscribers.
- Record Server: writes FLV files for VOD.
- Notify Server: sends callbacks on events (connect, publish, done).
- Static File Server: serves HTML/static assets and recorded FLV.
f. Clients & Playback
- Subscribers pull via RTMP or HTTP-FLV.
- NodePlayer.js/WebDemo as sample clients.
g. External Integrations
- Notification Webhooks (user-configurable URLs).
- Filesystem for static and recording storage.

##### Architectural Patterns & Principles
- Modular layering: protocol → session → core → feature servers.
- Event-driven, non-blocking I/O (Node.js).
- Separation of concerns: each server type in its own module.
- In-memory GOP cache for low-latency replay.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Entry
    subgraph "CLI Entry" 
        CLI["CLI Entry Point\n(bin/app.js)"]:::cli
        CERTPEM["TLS Cert\n(cert.pem)"]:::cli
        KEY["TLS Key\n(key.pem)"]:::cli
        CFG["Config\n(config.json)"]:::cli
    end

    %% Protocol Layer
    subgraph "Protocol Layer" 
        AMF["AMF Parser\n(src/protocol/amf.js)"]:::protocol
        FLV_PROTO["FLV Parser\n(src/protocol/flv.js)"]:::protocol
        RTMP_PROTO["RTMP Parser\n(src/protocol/rtmp.js)"]:::protocol
        RTMP_SRV["RTMP Server\n(src/server/rtmp_server.js)"]:::protocol
        HTTP_SRV["HTTP/HTTP2-FLV & Static Server\n(src/server/http_server.js)"]:::protocol
    end

    %% Session Layer
    subgraph "Session Layer"
        BASE_SESS["Base Session\n(src/session/base_session.js)"]:::session
        RTMP_SESS["RTMP Session\n(src/session/rtmp_session.js)"]:::session
        FLV_SESS["FLV Session\n(src/session/flv_session.js)"]:::session
        REC_SESS["Record Session\n(src/session/record_session.js)"]:::session
    end

    %% Core Engine
    subgraph "Core Engine"
        CONTEXT["Context\n(src/core/context.js)"]:::core
        AVCODEC["AV Codec\n(src/core/avcodec.js)"]:::core
        AVPACKET["AV Packet\n(src/core/avpacket.js)"]:::core
        LOGGER["Logger\n(src/core/logger.js)"]:::core
    end

    %% Feature Services
    subgraph "Feature Services"
        BROADCAST["Broadcast Server\n(src/server/broadcast_server.js)"]:::feature
        RECORD["Record Server\n(src/server/record_server.js)"]:::feature
        NOTIFY["Notify Server\n(src/server/notify_server.js)"]:::feature
        STATIC["Static File Server\n(src/server/http_server.js)"]:::feature
    end

    %% External & Storage
    subgraph "External & Storage"
        FS["Filesystem Storage"]:::external
        WEBHOOK["Webhook Endpoint"]:::external
        VENDOR["Vendor Modules\n(src/vendor/)"]:::external
        CONFIGFILES["Config & Deploy\n(package.json, Dockerfile,\n.github/workflows/)"]:::external
    end

    %% Clients
    subgraph "Clients"
        OBS["OBS/FFmpeg Ingest"]:::client
        PLAY["Playback Clients\n(RTMP, HTTP-FLV)"]:::client
    end

    %% Main Bootstrap
    INDEX["Main Bootstrap\n(src/index.js)"]:::core

    %% Connections
    OBS -->|"RTMP/RTMPS\nor HTTP-FLV"| RTMP_SRV
    OBS -->|HTTP-FLV| HTTP_SRV
    CLI -->|starts| INDEX
    INDEX -->|load protocols| AMF & FLV_PROTO & RTMP_PROTO
    INDEX -->|init servers| RTMP_SRV & HTTP_SRV
    RTMP_SRV -->|create| RTMP_SESS
    HTTP_SRV -->|create| FLV_SESS
    RTMP_SESS & FLV_SESS & BASE_SESS & REC_SESS -->|use| CONTEXT
    CONTEXT -->|frame data| AVCODEC & AVPACKET
    AVCODEC & AVPACKET -->|stream packets| BROADCAST
    BROADCAST -->|RTMP packets\nor FLV chunks| PLAY
    CONTEXT -->|chunk stream| RECORD
    RECORD -->|write FLV| FS
    CONTEXT -->|event triggers| NOTIFY
    NOTIFY -->|HTTP callbacks| WEBHOOK
    HTTP_SRV -->|serve| PLAY
    HTTP_SRV -->|serve static| PLAY

    %% Vendor & Config
    INDEX --> VENDOR
    INDEX --> CONFIGFILES

    %% Click Events
    click CLI "https://github.com/illuspas/node-media-server/blob/main/bin/app.js"
    click CERTPEM "https://github.com/illuspas/node-media-server/blob/main/bin/cert.pem"
    click KEY "https://github.com/illuspas/node-media-server/blob/main/bin/key.pem"
    click CFG "https://github.com/illuspas/node-media-server/blob/main/bin/config.json"
    click INDEX "https://github.com/illuspas/node-media-server/blob/main/src/index.js"
    click AMF "https://github.com/illuspas/node-media-server/blob/main/src/protocol/amf.js"
    click FLV_PROTO "https://github.com/illuspas/node-media-server/blob/main/src/protocol/flv.js"
    click RTMP_PROTO "https://github.com/illuspas/node-media-server/blob/main/src/protocol/rtmp.js"
    click BASE_SESS "https://github.com/illuspas/node-media-server/blob/main/src/session/base_session.js"
    click RTMP_SESS "https://github.com/illuspas/node-media-server/blob/main/src/session/rtmp_session.js"
    click FLV_SESS "https://github.com/illuspas/node-media-server/blob/main/src/session/flv_session.js"
    click REC_SESS "https://github.com/illuspas/node-media-server/blob/main/src/session/record_session.js"
    click AVCODEC "https://github.com/illuspas/node-media-server/blob/main/src/core/avcodec.js"
    click AVPACKET "https://github.com/illuspas/node-media-server/blob/main/src/core/avpacket.js"
    click CONTEXT "https://github.com/illuspas/node-media-server/blob/main/src/core/context.js"
    click LOGGER "https://github.com/illuspas/node-media-server/blob/main/src/core/logger.js"
    click RTMP_SRV "https://github.com/illuspas/node-media-server/blob/main/src/server/rtmp_server.js"
    click HTTP_SRV "https://github.com/illuspas/node-media-server/blob/main/src/server/http_server.js"
    click BROADCAST "https://github.com/illuspas/node-media-server/blob/main/src/server/broadcast_server.js"
    click RECORD "https://github.com/illuspas/node-media-server/blob/main/src/server/record_server.js"
    click NOTIFY "https://github.com/illuspas/node-media-server/blob/main/src/server/notify_server.js"
    click VENDOR "https://github.com/illuspas/node-media-server/tree/main/src/vendor/"
    click CONFIGFILES "https://github.com/illuspas/node-media-server/blob/main/package.json"

    %% Styles
    classDef cli fill:#f9f,stroke:#333,stroke-width:1px;
    classDef protocol fill:#bbdefb,stroke:#333,stroke-width:1px;
    classDef session fill:#d1c4e9,stroke:#333,stroke-width:1px;
    classDef core fill:#c8e6c9,stroke:#333,stroke-width:1px;
    classDef feature fill:#ffe0b2,stroke:#333,stroke-width:1px;
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:1px;
    classDef client fill:#fff9c4,stroke:#333,stroke-width:1px;
```
