Skip to main content

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 is a transcoding media server. When two endpoints negotiate different codecs during SDP offer/answer, FreeSWITCH decodes the audio from one codec and re-encodes it in the other, allowing incompatible devices to communicate seamlessly. Codec support is provided by loadable modules: audio codec modules register specific encoders and decoders, and video codec modules handle compressed video streams. Two foundational codecs — G.711 (PCMU/PCMA) and G.722 — are compiled directly into the FreeSWITCH core and are always available, requiring no additional module.

​
Built-in Codecs

These codecs are part of the FreeSWITCH core and are available without loading any module:
CodecDescriptionSample Rate
PCMU (G.711 µ-law)Uncompressed 8-bit µ-law PCM. North American PSTN standard.8 kHz
PCMA (G.711 A-law)Uncompressed 8-bit A-law PCM. European PSTN standard.8 kHz
G.722ITU-T wideband codec using ADPCM sub-band coding.16 kHz
Because PCMU and PCMA require no compression or decompression beyond simple PCM conversion, they have extremely low CPU overhead and are used as the universal fallback codec in almost all SIP deployments.

​
Audio Codecs

ModuleCodecSample RateBitrateNotes
mod_opusOpus8–48 kHz6–510 kbpsRoyalty-free; adaptive bitrate; DTX; FEC
mod_g729G.7298 kHz8 kbpsCommercial license required for encoding
mod_com_g729G.7298 kHz8 kbpsCommercial G.729 module from SignalWire
mod_g723_1G.723.18 kHz5.3 / 6.3 kbpsLegacy; low bandwidth
mod_amrAMR-NB8 kHz4.75–12.2 kbpsGSM mobile narrowband
mod_amrwbAMR-WB (G.722.2)16 kHz6.6–23.85 kbpsGSM mobile wideband
mod_ilbciLBC8 kHz13.3 / 15.2 kbpsGood quality at very low bitrates
mod_silkSILK8–24 kHzVariableSkype codec; predecessor to Opus
mod_bvBroadVoice (BV16/BV32)8 / 16 kHz16 / 32 kbpsBroadcom wideband codec
mod_codec2Codec28 kHz700–3200 bpsExtremely low bitrate; amateur radio / IoT
mod_sirenG.722.1 / Siren16 / 32 kHz16–32 kbpsPolycom-developed wideband codec
mod_b64Base64 audio——Encodes raw audio as base64; not for production voice

​
mod_opus

mod_opus wraps the libopus reference implementation and is the recommended codec for all WebRTC (mod_verto) and modern SIP deployments. It supports adaptive bitrate, in-band FEC (forward error correction) for packet loss resilience, and discontinuous transmission (DTX) to save bandwidth during silence. Default codec settings in mod_opus: 
/* from src/mod/codecs/mod_opus/mod_opus.c */
static opus_codec_settings_t default_codec_settings = {
    .useinbandfec     = 1,
    .usedtx           = 1,
    .maxaveragebitrate = 30000,   /* 30 kbps default */
    .maxplaybackrate  = 48000,   /* Up to 48 kHz */
    .stereo           = 0,
    .cbr              = 0,       /* Variable bitrate by default */
    .maxptime         = 40,
    .minptime         = 10,
};

​
mod_g729

mod_g729 implements G.729 in passthrough mode — it can relay G.729-encoded RTP streams between two endpoints without transcoding. Full transcoding (encoding and decoding G.729 audio) requires either a commercial G.729 license or the mod_com_g729 module.
G.729 licensing: The G.729 codec is covered by patents held by multiple companies. Using G.729 for encoding in production requires a commercial per-channel or per-server license. Passthrough (no decoding or re-encoding) generally does not require a license. Opus is a patent-free alternative with superior quality at comparable bitrates.

​
Video Codecs

ModuleCodecNotes
mod_openh264H.264Via Cisco’s OpenH264 library; baseline profile
Core (switch_vpx.c)VP8 and VP9Built into the FreeSWITCH core; no separate loadable module
mod_avH.264, VP8, VP9, othersVia libavcodec (FFmpeg); broader codec support

​
VP8 and VP9

VP8 and VP9 support is compiled directly into FreeSWITCH’s core (src/switch_vpx.c). There is no separate loadable mod_vpx module — the VP8 and VP9 codecs are registered by the core itself. VP8 is the standard WebRTC video codec and is required for mod_verto video calls. VP9 provides significantly better compression than VP8 at similar quality levels.

​
mod_openh264

mod_openh264 provides H.264 encoding and decoding using Cisco’s OpenH264 library, which Cisco licenses royalty-free for certain use cases. H.264 (MPEG-4 AVC) is the dominant video codec for SIP video calls and is widely supported across hardware endpoints, browsers, and conferencing systems. The module source is in src/mod/codecs/mod_openh264/mod_openh264.cpp.

​
mod_av

mod_av (in src/mod/applications/mod_av/) uses libavcodec from FFmpeg to provide a broader set of video codecs beyond H.264 and VP8. It also supports audio/video file recording in standard container formats (MP4, MKV, WebM).

​
Configuring Codec Preferences

FreeSWITCH uses a priority-ordered list of codec names to negotiate codecs with remote endpoints. This list is consulted during SDP offer/answer: FreeSWITCH offers codecs in the specified order and selects the highest-priority mutually supported codec.

​
Global Codec Preferences

The primary codec preference list is set in conf/vars.xml and applies system-wide: 
<!-- conf/vars.xml -->
<X-PRE-PROCESS cmd="set" data="global_codec_prefs=OPUS,G722,PCMU,PCMA,H264,VP8"/>
<X-PRE-PROCESS cmd="set" data="outbound_codec_prefs=OPUS,G722,PCMU,PCMA,H264,VP8"/>

​
Per-Profile Codec Preferences

SIP profiles can override the global list for all calls through that profile: 
<!-- conf/sip_profiles/internal.xml -->
<param name="inbound-codec-prefs" value="$${global_codec_prefs}"/>
<param name="outbound-codec-prefs" value="$${global_codec_prefs}"/>

​
Per-User / Per-Gateway Codec Override

Individual users in the directory or outbound gateways can specify their own codec list. For a user entry: 
<!-- conf/directory/default/1001.xml -->
<user id="1001">
  <params>
    <param name="codec-prefs" value="PCMU,PCMA"/>
  </params>
</user>

​
Transcoding

FreeSWITCH performs transcoding automatically when the codec on the A-leg differs from the codec on the B-leg. For example, if a WebRTC caller using Opus calls a SIP phone that only supports G.711, FreeSWITCH decodes the Opus RTP from the browser, converts the PCM audio, and re-encodes it as G.711 RTP for the phone — and vice versa for audio flowing in the other direction.

​
Performance Considerations

1

Codec matching reduces CPU load

When both legs negotiate the same codec, FreeSWITCH can operate in bypass media mode — RTP packets are forwarded directly between endpoints without being decoded. This eliminates transcoding CPU cost entirely.
2

Narrowband↔Wideband conversion is expensive

Transcoding between narrowband (8 kHz) and wideband (16 kHz) codecs requires resampling in addition to codec conversion. Minimize these paths in high-concurrency environments.
3

Prefer Opus for WebRTC legs

Opus natively supports both narrowband and wideband sample rates in a single stream. If the far end supports Opus, FreeSWITCH can avoid resampling entirely by selecting the appropriate Opus mode.
4

Benchmark before scaling

A single CPU core can typically handle 100–200 simultaneous transcoded calls (PCMU↔G.729 or PCMU↔Opus) depending on hardware. Profile under realistic load before choosing a server specification.

​
Codec Negotiation

FreeSWITCH follows the SIP SDP offer/answer model (RFC 3264) for codec negotiation:
  1. Inbound call (UAS mode): FreeSWITCH receives an INVITE with an SDP offer from the remote party. It selects codecs from the offer that appear in its own inbound-codec-prefs list, in preference order, and sends them back in the 200 OK SDP answer.
  2. Outbound call (UAC mode): FreeSWITCH sends an INVITE with an SDP offer listing its outbound-codec-prefs. The remote party responds with the subset it accepts.

​
Forcing a Specific Codec

Use the absolute_codec_string channel variable to override all codec preference lists and force a specific codec for a call leg. This is evaluated before the SDP offer is generated: 
<!-- Force Opus only for this outbound call -->
<action application="set"
  data="absolute_codec_string=OPUS"/>
<action application="bridge"
  data="sofia/external/+15551234567@carrier.example.com"/>

<!-- Force G.711 µ-law on the B-leg only -->
<action application="export"
  data="absolute_codec_string=PCMU"/>
<action application="bridge"
  data="user/1001@${domain_name}"/>
The export application (rather than set) ensures the variable is copied to the B-leg session, affecting the codec negotiation for that leg’s SDP.

Build docs developers (and LLMs) love

Get started for freeTalk to us