node.js-sip

Node.js SIP and RTP toolbox used for building a User Agent Client (UAC), a User Agent Server (UAS), routers, IVR flows, and small VoIP test applications.

Current status

This workspace has been hardened for the available test flow:

• npm test passes: 17 tests.
• examples/b2bua_local_ivr_test.js proves a local 127.0.0.1 client-to-IVR call can be acknowledged and kept alive past the 4-second range observed on the external CallCentric test.
• The IVR environment test in examples/ivr_env_test.js uses UDP, direct G.711 uLaw RTP, RTCP sender reports, and loopback-safe NAT binding via the local configured SIP_LOCAL_IP.

Features

• UDP SIP transport.
• UAC registration and outbound calls.
• UAS handling for registration, INVITE, ACK, and BYE.
• Route-based dispatch through SIP Router.
• User endpoint support through SIP UserManager.
• IVR endpoint support through SIP IVRManager.
• RTP sessions that can bind to a local IPv4 address and advertise a different IPv4 RTP IP.
• Direct raw ulaw media streaming as RTP.
• RFC 2833 DTMF detection and duplicate-event suppression.
• Local loopback test that removes carrier/NAT/handset behavior from the SIP media test.

Requirements

• Node.js 18 or newer.
• ffmpeg for regenerating or converting prompt media.
• Shell environment variables or examples/.env credentials.
• Network UDP permissions for SIP and RTP.

Quick start

Install dependencies if needed:

npm install

Check credentials in examples/.env or your .env:

SIP_USERNAME=...
SIP_PASSWORD=...
SIP_SERVER=sip.callcentric.net
SIP_TARGET=...
SIP_PORT=5060
SIP_LOCAL_IP=192.168.1.215

Run the built-in test suite:

npm test

Run the integration suite:

node --test tests/integration.test.js

Run the local no-carrier IVR test:

node --test examples/b2bua_local_ivr_test.js

Run the external IVR environment test:

SIP_HANGUP_AFTER_MS=0 SIP_TIMEOUT_MS=60000 node examples/ivr_env_test.js 2>/dev/null

Examples

External IVR test

examples/ivr_env_test.js registers a UAC, makes one call, and connects a raw RTP session. Its diagnostics include:

• INVITE/ACK/200 signaling.
• Outbound raw ulaw streaming.
• RTCP sender reports.
• Inbound packet counts.
• Remote BYE timing.
• DTMF acceptance.

Useful environment values:

SIP_HANGUP_AFTER_MS=0
SIP_TIMEOUT_MS=60000
SIP_LOCAL_IP=<advertised_or_local_IP>
SIP_LOCAL_PORT=0

Local B2BUA-style IVR test

examples/b2bua_local_ivr_test.js creates a 127.0.0.1 UAS, routes a local client to an IVR endpoint, and verifies the call remains alive beyond the external 4-second symptom. This test isolates the library from carrier and handset behavior.

RTP notes

• Direct raw media uses 160-byte, 20 ms, 8 kHz, G.711 uLaw payloads.
• RTCP basic sender report timing is used to keep the media stream identifiable to providers.
• Inbound RTP DTMF packets are deduplicated to suppress RFC 2833 retransmission noise.
• Media examples assume PCMU for the direct IVR path.

Troubleshooting

• npm test and node --test tests/integration.test.js are the fastest confidence checks.
• For IVR external calls, logs containing DTMF accepted: 1 indicate that digit traffic is reaching the application.
• Logs containing Remote BYE received are generated by the far side. They are useful for separating carrier/handset hangs from local failures.
• Inbound packet counts help determine whether RTP is arriving even when audio is not audible.
• A local b2bua_local_ivr_test.js run isolates library behavior from network and phone behavior.

Known limitations

• Transport is UDP IPv4 only.
• SIP authentication and digest handling are basic.
• TCP, TLS, STUN/TURN, ICE, SRTP, video, and full B2BUA media bridging are not implemented.
• The IVR environment example does not maintain multiple concurrent calls.
• Registration retry handling may still require more work for strict or changing proxy nonce sequences.

Architecture

• index.js: top-level VOIP construction in client or server mode.
• SIP/: SIP parsing, building, auth, routing, transport, trunk, user, and IVR support.
• RTP/: RTP listeners, SDP/Session handling, and raw ulaw streaming.
• SDP/: SDP parser.
• examples/: client, server, and IVR test programs.
• tests/: regression tests for auth, builders, parsers, routing, RTP, and integration behavior.

License

MIT License.