rtphone/AGENTS.md

RTPhone Platform - Agent Guide

Project Overview

RTPhone is a comprehensive real-time communication (RTC) platform developed by VoIP Objects (Sevana) that provides a complete software stack for building VoIP/SIP-based communication applications. It delivers production-ready voice communication capabilities with extensive codec support and cross-platform compatibility.

The project produces a static library (librtphone.a) that can be integrated into larger telephony and communication systems. It provides a JSON-based command interface for easy integration and control.

Technology Stack

• Language: C++20
• Build System: CMake 3.20+
• License: Mozilla Public License Version 2.0 (see LICENSE_MPL.txt)
• Primary Platforms: Linux (x64, ARM/Raspberry Pi), Windows (32/64-bit), macOS, Android, iOS

Project Structure

/home/anand/works/sevana/platform/rtphone/
├── src/                          # Main source code
│   ├── CMakeLists.txt            # Main CMake configuration
│   ├── engine/                   # Core engine modules
│   │   ├── agent/                # JSON-based command interface
│   │   ├── audio/                # Cross-platform audio I/O handling
│   │   ├── endpoint/             # SIP user agent implementation
│   │   ├── helper/               # Utility functions (networking, logging, threading)
│   │   ├── media/                # Audio codec management and processing
│   │   └── engine_config.h       # Compile-time configuration
│   └── libs/                     # Third-party libraries
│       ├── resiprocate/          # SIP stack (git submodule)
│       ├── libsrtp/              # SRTP library (git submodule)
│       ├── libraries/            # Prebuilt platform libraries (git submodule)
│       ├── ice/                  # ICE (Interactive Connectivity Establishment)
│       ├── jrtplib/              # RTP library
│       ├── opus/                 # Opus codec
│       ├── webrtc/               # WebRTC components
│       ├── libg729/              # G.729 codec
│       ├── libgsm/               # GSM codec
│       ├── gsmhr/                # GSM HR codec
│       ├── g722/                 # G.722 codec
│       ├── speexdsp/             # Speex DSP
│       ├── libevs/               # EVS codec (optional)
│       ├── opencore-amr/         # AMR codec (optional)
│       ├── oboe/                 # Android low-latency audio
│       └── fmt/                  # Format library
├── build_linux.py                # Linux build script
├── build_android.py              # Android build script
├── build_android.sh              # Android build script (shell)
├── run_ci.sh                     # CI build script
└── README.txt                    # Human-readable README

Build Instructions

Prerequisites

• CMake 3.20+
• C++20 compatible compiler (GCC, Clang, MSVC)
• Python 3 (for build scripts)
• Ninja (recommended, used by build scripts)
• OpenSSL 1.1+ development libraries
• Platform-specific audio libraries

Linux Build

python3 build_linux.py

This creates a build_linux/ directory and outputs librtphone.a.

Android Build

# Ensure ANDROID_NDK_HOME environment variable is set
export ANDROID_NDK_HOME=/path/to/android-ndk
python3 build_android.py

Or use the shell script:

./build_android.sh

This creates a build_android/ directory with ARM64 libraries by default.

Manual CMake Build

mkdir build && cd build
cmake ../src -G Ninja
cmake --build . -j$(nproc)

Build Options

The following CMake options are available (defined in src/CMakeLists.txt):

• USE_AMR_CODEC (ON/OFF): Include AMR-NB/AMR-WB codec support. Default: ON
• USE_EVS_CODEC (ON/OFF): Include EVS codec support. Default: ON
• USE_MUSL (ON/OFF): Build with MUSL library. Default: OFF

Module Architecture

1. Agent Module (src/engine/agent/)

Provides a JSON-based command interface for controlling the engine.

Key Classes:

• AgentImpl: Main agent implementation, processes JSON commands
• Agent_AudioManager: Manages audio devices and streams

Interface Pattern: Commands are sent as JSON strings and responses are returned as JSON.

2. Endpoint Module (src/engine/endpoint/)

SIP user agent implementation based on reSIProcate.

Key Classes:

• UserAgent (in EP_Engine.h): Main SIP stack wrapper, handles registration, sessions, presence
• Account (EP_Account): SIP account management
• Session (EP_Session): Call/session management
• EP_AudioProvider: Audio data provider for sessions
• EP_DataProvider: Generic data provider interface

Key Concepts:

• Implements resiprocate handlers: ClientRegistrationHandler, InviteSessionHandler, etc.
• Supports multiple transport types: UDP, TCP, TLS
• ICE integration for NAT traversal

3. Media Module (src/engine/media/)

Audio codec management, RTP/RTCP handling, and media processing.

Key Classes:

• MT::AudioCodec: Codec management
• MT::AudioStream: Audio streaming
• MT::AudioReceiver: RTP packet receiving
• MT::CodecList: Codec negotiation
• MT::SrtpHelper: SRTP encryption
• MT::Dtmf: DTMF tone handling
• MT::AmrCodec: AMR codec wrapper
• MT::EvsCodec: EVS codec wrapper

4. Audio Module (src/engine/audio/)

Cross-platform audio I/O abstraction.

Key Classes:

• Audio::Interface: Audio interface abstraction
• Audio::DevicePair: Input/output device pair
• Audio::Resampler: Audio resampling
• Audio::Mixer: Multi-channel audio mixing
• Audio::CoreAudio: macOS/iOS implementation
• Audio::DirectSound: Windows DirectSound implementation
• Audio::AndroidOboe: Android Oboe implementation
• Audio::Null: Null/no-op implementation for testing

5. Helper Module (src/engine/helper/)

Utility classes and platform abstractions.

Key Classes:

• HL::Types: Type definitions and BiMap template
• HL::Sync: Threading primitives (Mutex, Event, etc.)
• HL::ByteBuffer: Binary data buffer
• HL::VariantMap: Key-value configuration storage
• HL::Rtp: RTP packet utilities
• HL::IuUP: Iu User Plane protocol (3G)
• HL::NetworkSocket: Network socket abstraction
• HL::ThreadPool: Thread pool implementation

Code Style Guidelines

Naming Conventions

1. Classes: PascalCase with module prefix

   • AgentImpl, UserAgent, MT::AudioCodec, HL::Sync

2. Files: Prefix indicates module

   • Agent_*.cpp/h - Agent module
   • EP_*.cpp/h - Endpoint module
   • MT_*.cpp/h - Media module
   • Audio_*.cpp/h - Audio module
   • HL_*.cpp/h - Helper module

3. Member Variables: Hungarian notation with m prefix

   • mAgentMutex, mSessionMap, mShutdown

4. Type Aliases: P prefix for smart pointers

   • PAccount, PSession, PVariantMap

File Header Template

All source files must include the MPL license header:

/* Copyright(C) 2007-YYYY VoIP objects (voipobjects.com)
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

Include Order

1. Corresponding header file (for .cpp files)
2. Project headers (using "...")
3. Third-party library headers
4. Standard library headers
5. System headers

Platform Abstraction

Use preprocessor defines for platform-specific code:

• TARGET_WIN - Windows
• TARGET_LINUX - Linux
• TARGET_OSX - macOS
• TARGET_ANDROID - Android
• TARGET_MUSL - MUSL libc

Configuration

Compile-Time Configuration (src/engine/engine_config.h)

Key configuration constants:

// Audio settings
#define AUDIO_SAMPLE_WIDTH 16
#define AUDIO_CHANNELS 1
#define AUDIO_SAMPLERATE 48000
#define AUDIO_RESAMPLER_QUALITY 1

// SIP settings
#define UA_REGISTRATION_TIME 3600
#define UA_MEDIA_PORT_START  20000
#define UA_MEDIA_PORT_FINISH 30000

// Codec payload types
#define MT_AMRNB_PAYLOADTYPE 112
#define MT_AMRWB_PAYLOADTYPE 96
#define MT_EVS_PAYLOADTYPE 127
#define MT_OPUS_CODEC_PT 106

Runtime Configuration

Configuration is passed via VariantMap objects to the UserAgent:

enum
{
    CONFIG_IPV4 = 0,            // Use IP4
    CONFIG_IPV6,                // Use IP6
    CONFIG_USERNAME,            // Username
    CONFIG_DOMAIN,              // Domain
    CONFIG_PASSWORD,            // Password
    CONFIG_STUNSERVER_NAME,     // STUN server hostname
    CONFIG_STUNSERVER_PORT,     // STUN server port
    CONFIG_TRANSPORT,           // 0=all, 1=UDP, 2=TCP, 3=TLS
    // ... see EP_Engine.h for full list
};

Dependencies

Git Submodules

The project uses Git submodules for some dependencies:

• src/libs/resiprocate - SIP stack (sevana branch)
• src/libs/libsrtp - SRTP library
• src/libs/libraries - Prebuilt platform libraries

To initialize:

git submodule update --init --recursive

Third-Party Libraries

Prebuilt libraries are provided in src/libs/libraries/:

• OpenSSL 1.1 (crypto, SSL)
• Opus codec
• Opencore AMR (NB/WB)
• Boost (headers)
• PortAudio
• libevent2

Testing

There is no dedicated test suite in the main project. Testing is typically done through:

1. Integration with the final application
2. The run_ci.sh script for build verification
3. Unit tests in individual library submodules (e.g., oboe)

CI Build

./run_ci.sh

This configures with CMake and builds with make (2 parallel jobs).

Security Considerations

1. OpenSSL Integration: Uses OpenSSL 1.1+ for TLS and certificate handling
2. SRTP Support: Media encryption via libsrtp
3. Certificate Management: Root certificates can be added at runtime via addRootCert()
4. AMR/EVS Patents: The project does NOT include patent licenses for AMR and EVS codecs. Users must acquire these independently.

Integration Guide

Basic Usage Pattern

1. Create AgentImpl instance
2. Send JSON commands via command() method
3. Poll for events via waitForData() and read()
4. Process JSON event responses

Example Commands

• config - Configure the engine
• start - Start the engine
• createAccount - Create SIP account
• startAccount - Register account
• createSession - Create call session
• startSession - Make/accept call
• waitForEvent - Poll for events

Development Workflow

1. Making Changes: Edit files in appropriate src/engine/<module>/ directory
2. Building: Use build_linux.py for quick Linux builds
3. Testing: Integrate with test application or use existing CI
4. Commits: Follow existing commit message style (visible in git log)

Common Tasks

Adding a New Codec

1. Create MT_<Codec>Codec.cpp/h in src/engine/media/
2. Derive from MT::Codec base class
3. Register in MT_CodecList.cpp
4. Add to src/CMakeLists.txt if external library needed

Adding Platform Audio Support

1. Create Audio_<Platform>.cpp/h in src/engine/audio/
2. Implement Audio::Interface methods
3. Add platform detection in src/CMakeLists.txt
4. Include in build conditionally

Modifying Build Configuration

• Edit src/CMakeLists.txt for main build changes
• Edit src/libs/libraries/platform_libs.cmake for platform library paths
• Edit src/engine/engine_config.h for compile-time constants

Notes

• The codebase uses C++20 features - ensure compiler compatibility
• Thread safety: Use std::recursive_mutex (e.g., mAgentMutex) for thread-safe access
• Memory management: Uses smart pointers (std::shared_ptr) extensively
• The JSON library is embedded in src/libs/json/