FreeSWITCH Architecture: Core, Modules, and Sessions

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/signalwire/freeswitch/llms.txt

Use this file to discover all available pages before exploring further.

┌──────────────────────────────────────────────────────────────────┐
│                         FreeSWITCH Core                          │
│                                                                  │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────────────┐ │
│  │  XML Config  │  │ Session/Chan │  │     Event System        │ │
│  │  Preprocessor│  │  Manager     │  │  (APR FIFO + threads)   │ │
│  └──────┬──────┘  └──────┬───────┘  └──────────┬──────────────┘ │
│         │                │                      │                │
│  ┌──────▼──────┐  ┌──────▼───────┐  ┌──────────▼──────────────┐ │
│  │  SQLite DB   │  │  RTP Engine  │  │  Module Loader          │ │
│  │  (state, reg)│  │  Jitter Buf  │  │  (switch_loadable_module)│ │
│  └─────────────┘  └──────────────┘  └─────────────────────────┘ │
└─────────────────────────────┬────────────────────────────────────┘
                              │  dlopen / shared libs
        ┌──────────┬──────────┼──────────┬──────────┐
        ▼          ▼          ▼          ▼          ▼
   Endpoints   Codecs    Dialplans   Applications  Event
  (mod_sofia) (mod_opus)(mod_dialplan_xml)(mod_dptools)(mod_event_socket)

​

Core Switching Engine

• Memory management — every session allocates its own APR memory pool; the pool is destroyed when the call ends, reclaiming all resources at once.
• Session lifecycle — the core creates, tracks, and destroys switch_core_session_t objects and enforces the channel state machine.
• Thread management — each active session runs in its own thread; a configurable cap (max-sessions) prevents resource exhaustion.
• RTP / media engine — the core contains a built-in RTP stack, jitter buffer, and DTMF detection that endpoints use to send and receive media.
• Event FIFO — a thread-safe APR queue dispatches events to all registered listeners without blocking the originating thread.

/* From src/switch_core.c — global runtime structure */
struct switch_runtime runtime = { 0 };

/* Time duration breakdown used in heartbeat events */
struct switch_core_time_duration {
    uint32_t mms;   /* microseconds */
    uint32_t ms;    /* milliseconds */
    uint32_t sec;
    uint32_t min;
    uint32_t hr;
    uint32_t day;
    uint32_t yr;
};

​

Module Categories

​

Session Lifecycle

​

Media Handling

• Packetisation and de-packetisation of audio and video frames.
• Jitter buffering — adaptive jitter buffer to smooth out network timing variation.
• DTMF detection — both in-band (audio energy) and out-of-band (RFC 2833 / SIP INFO).
• SRTP / DTLS-SRTP — encrypted media for WebRTC and secure SIP trunks.
• Media bugs — the switch_core_media_bug_add() API lets any module tap into the raw audio or video stream of a session without interrupting the call. Used by recording, speech recognition, and analytics modules.

/* Attach a media tap to a live session (from switch_core.h) */
SWITCH_DECLARE(switch_status_t) switch_core_media_bug_add(
    switch_core_session_t *session,
    const char *function,
    const char *target,
    switch_media_bug_callback_t callback,
    void *user_data,
    time_t stop_time,
    switch_media_bug_flag_t flags,
    switch_media_bug_t **new_bug
);

​

Database Layer

• Active session state — fast lookups by UUID for API commands and ESL.
• SIP registrations — endpoint registration records written by mod_sofia.
• FIFO queue state — caller and agent positions maintained by mod_fifo.
• Limit counters — call counts used by mod_db and mod_hash for rate limiting.

​

XML Configuration

1. Reads freeswitch.xml (the root document).
2. Expands <X-PRE-PROCESS cmd="include" data="..."/> directives to pull in additional files.
3. Expands <X-PRE-PROCESS cmd="set" data="var=value"/> to create global variables available as $${var}.
4. Builds the XML registry — an in-memory tree consulted by all subsystems.