367 lines
12 KiB
Markdown
367 lines
12 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
python3 build_linux.py
|
|
```
|
|
|
|
This creates a `build_linux/` directory and outputs `librtphone.a`.
|
|
|
|
### Android Build
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
./build_android.sh
|
|
```
|
|
|
|
This creates a `build_android/` directory with ARM64 libraries by default.
|
|
|
|
### Manual CMake Build
|
|
|
|
```bash
|
|
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:
|
|
|
|
```cpp
|
|
/* 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:
|
|
|
|
```cpp
|
|
// 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:
|
|
|
|
```cpp
|
|
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:
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
./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/`
|