mod_amd_ws: Native FreeSWITCH Module

Requirements

Install (one command)

On the FreeSWITCH server, as root:

curl -fsSL https://raw.githubusercontent.com/nikvb/mod_amd_ws/main/install.sh | bash -s -- -y

The installer detects the running FreeSWITCH, installs the compiler and OpenSSL headers, and finds the FreeSWITCH headers. It builds the module, checks it (no undefined symbols, only the module interface exported, same OpenSSL as the switch) and installs it with a backup of the old one. It then creates amd_ws.conf.xml if absent, adds the module to modules.conf.xml and loads it. It never hangs up calls and never restarts FreeSWITCH. Everything is logged to /var/log/mod_amd_ws-install.log.

Preview, custom endpoint, uninstall

# show the plan only, change nothing
curl -fsSL https://raw.githubusercontent.com/nikvb/mod_amd_ws/main/install.sh | bash -s -- --dry-run

# set the endpoint in a new amd_ws.conf.xml
curl -fsSL https://raw.githubusercontent.com/nikvb/mod_amd_ws/main/install.sh | bash -s -- -y --host api.amdy.io --port 2700

# remove the module (amd_ws.conf.xml is kept)
curl -fsSL https://raw.githubusercontent.com/nikvb/mod_amd_ws/main/install.sh | bash -s -- --uninstall

Installer options

Offline host: copy install.sh to it. It needs no network if the build packages and FreeSWITCH headers are present; otherwise pass --fs-src /path/to/freeswitch-<version>.

Verify the install

fs_cli -x 'module_exists mod_amd_ws'      # true
fs_cli -x 'amd_ws status'                 # endpoint, settings, counters
fs_cli -x 'show application' | grep amd_ws

Dialplan

<extension name="outbound_amd">
  <condition field="destination_number" expression="^amd$">
    <action application="amd_ws" data=""/>
    <action application="log" data="INFO AMD ${AMDSTATUS}/${AMDCAUSE} stats=${AMDSTATS}"/>
    <action application="execute_extension" data="amd_${AMDSTATUS} XML ${context}"/>
  </condition>
</extension>

With an empty argument the endpoint and timings come from amd_ws.conf.xml. The full form is the same as Asterisk's AMD_WS():

amd_ws [host[,port[,vid[,timeout_ms[,playfile[,options]]]]]]

If an argument contains commas (a tone_stream:// spec, for example), use FreeSWITCH's delimiter prefix and separate with |:

<action application="amd_ws" data="^^|api.amdy.io|2700||10000|tone_stream://%(500,500,440);loops=20|d(800)"/>

Options

Channel variables read

amd_ws_host, amd_ws_port, amd_ws_vid, amd_ws_timeout_ms, amd_ws_connect_timeout_ms, amd_ws_tls, amd_ws_trace, amd_ws_mode (ws/local/compare), amd_ws_local_fallback, amd_ws_compare_wait_local, amd_ws_phone, amd_ws_country_code, amd_ws_caller_id, amd_ws_playdelay_ms. They override amd_ws.conf.xml; dialplan arguments and options override them. Set them in an originate string, for example:

{amd_ws_phone=3125551212,amd_ws_country_code=1}sofia/gateway/...

caller_id is sent automatically as the number the callee sees: effective_caller_id_number, else origination_caller_id_number, else caller_id_number. It is never sent empty or as Unknown, and not at all with send_caller_id=false.

Results: channel variables

The three error causes return HUMAN so a call is never lost when the service is down. Branch on them to use a local fallback in the dialplan:

<action application="execute_extension" data="${cond(${AMDCAUSE} == CONNECTION_ERROR ? amd_fallback : amd_${AMDSTATUS})} XML ${context}"/>

or let the module do it with local_fallback=true or option F.

Background detection (bridge or IVR keeps running)

fs_cli -x 'uuid_amd_ws <uuid> start api.amdy.io,2700,,10000'
fs_cli -x 'uuid_amd_ws <uuid> stop'

The detection runs on a media bug while the channel does whatever it is doing: a bridge, an IVR or playback. When the verdict is known, the module sets the same variables and fires the event below. It also runs every channel variable named api_on_amd_ws_result* as an API command. Its arguments are expanded when it runs. set expands its value once more, so write \\\${...} for a variable that must be expanded only when the command runs:

<action application="set" data="api_on_amd_ws_result=uuid_transfer ${uuid} amd_\\\${AMDSTATUS} XML default"/>
<action application="set" data="r=${uuid_amd_ws(${uuid} start)}"/>
<action application="bridge" data="..."/>

Event

CUSTOM amd_ws::result, once per detection, with the channel's standard headers plus AMD-Status, AMD-Cause, AMD-Response, AMD-Source, AMD-Mode, AMD-VID, AMD-Elapsed, AMD-Stats, AMD-Connect-MS, AMD-First-Audio-MS, AMD-Background, and when the local detector ran AMD-Local-Status, AMD-Local-Cause, AMD-Local-MS, AMD-Fallback-From.

fs_cli -x '/event plain CUSTOM amd_ws::result'

Configuration

<conf_dir>/autoload_configs/amd_ws.conf.xml. Every parameter, with its default and meaning, is in the sample conf/amd_ws.conf.xml. Apply changes with fs_cli -x 'amd_ws reload'; calls in progress keep their settings.

How it works

• amd_ws answers the channel if needed and attaches a read-only media bug. Each frame the callee sends is resampled to 8 kHz if needed. Frames the core fills because no RTP arrived count as "no audio".
• A worker thread per call connects to ws://host:port/, sends the config frame and sends the audio collected at each schedule mark as one binary frame. A reply containing HUMAN means human, then AMD or MACHINE means machine; anything else is an acknowledgement.
• The channel thread only moves media or runs the playback. It never waits on the network, so a slow or dead service cannot stall a call beyond connect_timeout_ms / timeout_ms.
• On every exit the worker sends {"eof":1} and CLOSE 1000 and releases the socket.

Native mod_amd vs streaming

Measured on real FreeSWITCH calls (1.10.12, Xeon E5-2420 @ 1.90 GHz) with the benchmark in the repository. Full tables and method: performance.md.

Worst case on a 2012 CPU. A detection lasts about 1.5–3 s at the start of an answered call, so 200 concurrent detections is a very large dialer.

Bottom line. Neither approach is expensive for the media server. The difference that matters is accuracy: an energy detector has failure modes you cannot tune away, and a content classifier does not share them. The widely used seanbright/mod_amd also has a frame-energy bug that makes its verdicts wrong and unrepeatable; amd_ws option L runs the same algorithm with the same parameter names, without that bug.

Recommendation

• Stream for accuracy: amd_ws in ws mode, with a fallback branch on CONNECTION_ERROR / PROCESSING_ERROR / FATAL_ERROR, or local_fallback=true.
• Prove it on your traffic first: run mode=compare on some campaigns for a few days, then compare AMDSTATUS with amd_ws_local_result and with agent dispositions.
• Replace mod_amd with amd_ws … L if you need a network-free detector.
• Size the uplink at 128 kbit/s per concurrent detection.

Troubleshooting

fs_cli -x 'amd_ws status'                        # settings, calls in progress, worker threads, counters
fs_cli -x 'console loglevel debug'               # + trace=true or option v for per-call event lines
grep 'AMD_WS:' /var/log/freeswitch/freeswitch.log | tail

Full reference

Source, tests and benchmark: github.com/nikvb/mod_amd_ws. Detailed documents:

• Performance report: latency, false positives, CPU, resilience, how to reproduce
• Wire protocol: config frame, audio schedule, replies, EOF finalisation, timeouts
• Architecture: threads, media bug, foreground vs background
• Installer: what it does, options, tested platforms, offline hosts

Support

Need help? Email [email protected] with:

• FreeSWITCH version (fs_cli -x version)
• Installer log (/var/log/mod_amd_ws-install.log)
• The output of fs_cli -x 'amd_ws status'
• The AMD_WS: log lines for one call, or its trace (option v)