- start checks with Kimi + many fixes
This commit is contained in:
366
AGENTS.md
Normal file
366
AGENTS.md
Normal file
@@ -0,0 +1,366 @@
|
||||
# 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/`
|
||||
Reference in New Issue
Block a user