How signalwire/freeswitch works
1. FreeSWITCH is a telecom application server with a central C/C++ core in src/ and a large plugin surface in src/mod/. The core owns session lifecycle, channel state, media handling, event dispatch, scheduling, logging, XML config parsing, and module loading.
2. The main runtime boundary is between the core and loadable modules. Core code lives in files like switch_core.c, switch_channel.c, switch_rtp.c, switch_ivr*.c, switch_event.c, and switch_loadable_module.c; modules are compiled independently and loaded at runtime as shared objects/DLLs.
3. Configuration is XML-driven and organized by deployment profile under conf/ (vanilla, minimal, testing, sbc, softphone, etc.). The key config files define autoloaded modules, SIP profiles, directories/users, dialplans, language prompts, variables, and feature-specific routing.
4. The signaling ingress/egress layer is primarily in endpoint modules under src/mod/endpoints/. The dominant SIP stack is mod_sofia, but the repo also includes other endpoint integrations such as mod_skinny, mod_verto, mod_rtmp, mod_h323, mod_opal, mod_loopback, and mod_alsa. These modules create/accept calls and hand them to the core session engine.
5. Media processing is split across core media code and specialized modules. The core handles RTP/session media control; codec and format support is provided by modules under src/mod/codecs/ and src/mod/formats/, while audio/video utilities are backed by vendored libraries like libvpx, libyuv, libsrtp, spandsp, libsndfile, opus, sofia-sip, and others in libs/.
6. Call behavior is implemented through application modules in src/mod/applications/ and related core IVR helpers. This includes conferencing, voicemail, callcenter, FIFO, limit/rate control, directory lookup, dialing tools, recording, fax/modem support, HTTP API-driven apps, and routing helpers like LCR/distributor/easyroute.
7. Scriptable call control is a major subsystem. Language bindings under src/mod/languages/ and src/mod/asr_tts/ expose the core to Lua, Python 3, Perl, Java, managed/.NET, V8/JavaScript, basic scripting, and TTS/ASR engines. These modules typically embed an interpreter or bind into the core via SWIG-generated wrappers.
8. External integration is centered on the event bus and API surfaces. mod_event_socket, mod_event_multicast, mod_amqp, mod_erlang_event, mod_snmp, and the CDR modules publish or consume call events. XML and HTTP-facing integration is provided by mod_xml_curl, mod_xml_rpc, mod_xml_scgi, mod_httapi, and mod_signalwire for SignalWire cloud connectivity.
9. Data persistence and lookup are isolated into database and cache modules. src/mod/databases/ and src/mod/event_handlers/ include PostgreSQL, MariaDB, ODBC, SQLite, Redis, Memcache, Mongo, and Hiredis integrations. These are used for CDR storage, directory/dialplan lookup, billing, routing, and cached state.
10. The repository also contains the client/tooling ecosystem around the core. libs/esl/ is the Event Socket Library with bindings for Java, Lua, Perl, PHP, Python3, Ruby, C#, and Tcl; fs_cli, fscomm, and the web portal in htdocs/portal/ are example clients and UIs that talk to the server rather than being part of the telephony core itself.
11. Build and packaging are first-class concerns. The repo supports autotools, CMake, and platform-specific project files for Visual Studio and Windows installers. There are extensive Docker definitions under docker/ and .github/docker/, plus Debian/RPM packaging under debian/, scripts/packaging/, and yum/.
12. Test coverage is organized by subsystem. tests/unit/ exercises core call control, SIP/RTP, XML, codecs, VAD, and media behaviors, while individual modules often carry their own test directories and sample configs. CI is driven by GitHub Actions workflows for Linux, macOS, Windows, Docker-in-Docker, and static analysis.
13. In architecture-diagram terms, the main flow is: signaling enters through endpoint modules, the core creates/controls sessions, media flows through codec/format and RTP processing, dialplan/app modules implement call logic, and events/CDRs/API calls flow outward to sockets, databases, message buses, HTTP/XML services, and external cloud services like SignalWire.
14. The libs/ tree is mostly vendored dependencies and companion libraries rather than business logic. It matters architecturally because many features are optional at build time and are wired in through module/link-time boundaries instead of being implemented inside the core daemon.
Main entry points: switch_loadable_module.c Module loader · switch_core.c Core runtime · mod_sofia.c mod_sofia · switch_core_media.c Media engine
Components 21
Core
Central daemon runtime and session engine
- FreeSWITCH · Top-level application server and module ecosystem
- Core runtime · Session lifecycle, state machine, scheduling, logging, module loading
src/switch_core.c - Sessions & channels · Per-call session, channel state, and control primitives
src/switch_core_session.c - Media engine · RTP, media bugs, jitter, packetization, and core media plumbing
src/switch_core_media.c - IVR flow · Bridge/originate/play-say/menu helpers that implement call behavior
src/switch_ivr.c - Event bus · Event creation, dispatch, and hook integration for call state and telemetry
src/switch_event.c - XML config · XML profile and directory parsing used by the runtime and modules
src/switch_xml_config.c - Module loader · Dynamic loading and lifecycle management for runtime modules
src/switch_loadable_module.c
Modules
Loadable feature subsystems
- mod_sofia · Primary SIP signaling stack and SIP profile handler
src/mod/endpoints/mod_sofia/mod_sofia.c - Other endpoints · Alternate call ingress/egress modules such as skinny, verto, h323, rtmp, loopback, alsa, opal
src/mod/endpoints/mod_skinny/mod_skinny.c - Codecs · Codec and transcoding modules for AMR, Opus, G.729, G.722.1, VPX, and related formats
src/mod/codecs/mod_opus/mod_opus.c - Formats · Audio/video format and stream handlers such as sndfile, shout, local_stream, webm, png
src/mod/formats/mod_sndfile/mod_sndfile.c - Applications · Dialplan apps like conference, voicemail, callcenter, FIFO, LCR, directory, limit, curl, db
src/mod/applications/mod_conference/mod_conference.c - Script bindings · Lua, Python, Perl, Java, managed, V8, basic scripting, and ASR/TTS integration
src/mod/languages/mod_lua/mod_lua.cpp - Event/API I/O · Event socket, multicast, AMQP, Erlang event, SNMP, and XML/HTTP integration points
src/mod/event_handlers/mod_event_socket/mod_event_socket.c - Data store · Persistence and lookup integrations for PostgreSQL, MariaDB, SQLite, Redis, Memcache, Mongo, ODBC
src/mod/databases/mod_pgsql/mod_pgsql.c
Support
Configuration, clients, libraries, build and test
- Deployment profiles · Profile-specific autoload configs, SIP profiles, dialplans, directories, vars, and language menus
conf/vanilla/freeswitch.xml - ESL clients · Event Socket Library plus CLI and sample programmatic clients
libs/esl/src/esl.c - Build & packaging · Autotools/CMake, Docker, Debian/RPM, Windows solutions, and packaging scripts
configure.ac - Tests · Unit and module tests for core call control, SIP/RTP, XML, codecs, VAD, and media behaviors
tests/unit/Makefile.am - Vendored libs · Embedded dependencies such as APR, SRTP, libvpx, libyuv, opus, sofia-sip, spandsp, sndfile
libs/srtp/CMakeLists.txt
Connections 31
- FreeSWITCH → Core runtime: contains · The daemon is implemented around the central runtime
- FreeSWITCH → Module loader: loads · Core loads runtime modules from shared libraries
- Core runtime → Sessions & channels: orchestrates · Core owns session lifecycle and channel state
- Core runtime → Media engine: controls · Core manages RTP and media processing
- Core runtime → IVR flow: invokes · IVR helpers implement call behavior on top of core session control
- Core runtime → Event bus: emits · Runtime state changes are published onto the event bus
- Core runtime → XML config: reads · Configuration and deployment data are XML-driven
- Module loader → mod_sofia: loads · SIP endpoint is a loadable module
- Module loader → Other endpoints: loads · Alternate endpoint stacks are pluggable
- Module loader → Codecs: loads · Codec implementations are built as modules
- Module loader → Formats: loads · Format and stream handlers are pluggable
- Module loader → Applications: loads · Call apps are implemented as modules
- Module loader → Script bindings: loads · Scriptable control surfaces are runtime modules
- Module loader → Event/API I/O: loads · Event and API bridges are modular
- Module loader → Data store: loads · Database and cache integrations are modular
- mod_sofia → Sessions & channels: creates · SIP ingress/egress creates sessions and channels
- Other endpoints → Sessions & channels: creates · Non-SIP endpoints hand calls into the core session engine
- Codecs → Media engine: extends · Codec modules feed the media pipeline
- Formats → Media engine: feeds · Media/file handlers supply and consume media streams
- Applications → IVR flow: implements · Applications build higher-level call logic on IVR helpers
- Script bindings → Event bus: consumes · Language bindings frequently subscribe to or emit events
- Event/API I/O → Event bus: bridges · Socket, bus, and XML/HTTP modules move events and API calls out of core
- Data store → Event bus: persists · CDR and related integrations persist event-derived data
- Deployment profiles → mod_sofia: configures · Deployment profiles define SIP profiles and module autoloading
- Deployment profiles → Applications: routes · Dialplan and directory XML steer application behavior
- ESL clients → Event/API I/O: connects · ESL clients talk to event socket and related APIs
- Build & packaging → Module loader: produces · Build system compiles the core and modules into packages
- Build & packaging → Vendored libs: vendors · Optional features depend on bundled third-party libraries
- Tests → Core runtime: verifies · Unit tests exercise the core runtime and call control
- Tests → mod_sofia: verifies · Dedicated tests cover SIP behavior and signaling flows
- Tests → Media engine: verifies · Tests cover RTP, media, codecs, and VAD behaviors