# SimpleSIP - Simple SIP Client Library
[](https://badge.fury.io/py/simplesip)
[](https://pypi.org/project/simplesip/)
[](https://opensource.org/licenses/MIT)
A lightweight, easy-to-use Python library for SIP (Session Initiation Protocol) communication with RTP audio streaming capabilities. Perfect for building VoIP applications, automated calling systems, and SIP-based integrations.
## Features
- **Simple API** - Easy-to-use interface for SIP operations
- **Full SIP Support** - Registration, calls, and session management
- **Real-time Audio** - RTP audio streaming with μ-law (PCMU) encoding
- **Audio Capture** - Built-in microphone support with PyAudio integration
- **Authentication** - Digest authentication support
- **Async Operations** - Non-blocking operations with threading
- **Call States** - Comprehensive call state management
- **Extensible** - Easy to extend and customize for your needs
## Quick Start
### Installation
```bash
pip install simplesip
```
For audio support, install with optional dependencies:
```bash
pip install simplesip[audio]
# or
pip install simplesip pyaudio
```
### Basic Usage
```python
from simplesip import SimpleSIPClient
import time
# Create a SIP client
client = SimpleSIPClient(
username="your_username",
password="your_password",
server="your_sip_server.com"
)
# Connect to the SIP server
client.connect()
# Make a call
client.call("1234567890")
# Wait for the call to be established
while client.call_state.value != 'connected':
time.sleep(0.1)
# Keep the call active for 10 seconds
time.sleep(10)
# Hang up
client.hangup()
# Disconnect from server
client.disconnect()
```
## API Reference
### SimpleSIPClient
The main class for SIP operations.
#### Constructor
```python
SimpleSIPClient(username, password, server, port=5060, local_port=None, timeout=5)
```
**Parameters:**
- `username` (str): SIP username
- `password` (str): SIP password
- `server` (str): SIP server hostname or IP
- `port` (int): SIP server port (default: 5060)
- `local_port` (int): Local port for SIP (default: random)
- `timeout` (int): Connection timeout in seconds (default: 5)
#### Methods
##### connect()
Connect to the SIP server and register.
```python
client.connect()
```
##### call(number)
Initiate a call to the specified number.
```python
client.call("1234567890")
```
##### hangup()
End the current call.
```python
client.hangup()
```
##### disconnect()
Disconnect from the SIP server.
```python
client.disconnect()
```
##### send_audio(audio_data)
Send audio data during an active call.
```python
client.send_audio(ulaw_audio_data)
```
##### set_audio_callback(callback, format='pcmu')
Set a callback function to handle incoming audio.
```python
def audio_handler(audio_data, format):
# Process incoming audio
pass
client.set_audio_callback(audio_handler, format='pcmu')
```
##### get_call_status()
Get the current call status.
```python
status = client.get_call_status()
print(f"State: {status['state']}")
print(f"Duration: {status['duration']}")
```
### Call States
The library uses an enum for call states:
- `CallState.IDLE` - No active call
- `CallState.INVITING` - Outgoing call in progress
- `CallState.RINGING` - Call is ringing
- `CallState.CONNECTED` - Call connected but no media
- `CallState.STREAMING` - Call with active audio streaming
## Audio Support
SimpleSIP supports real-time audio streaming using RTP protocol with μ-law (PCMU) encoding.
### Audio Formats
- **PCMU (μ-law)**: Primary format for SIP/RTP
- **PCM**: Linear 16-bit audio for processing
### Audio Callback
Set up an audio callback to handle incoming audio:
```python
def handle_audio(audio_data, format):
if format == 'pcmu':
# Handle μ-law encoded audio
pass
elif format == 'pcm':
# Handle linear PCM audio
pass
client.set_audio_callback(handle_audio, format='pcmu')
```
### Microphone Integration
```python
import pyaudio
import numpy as np
# Audio configuration
CHUNK = 1024
FORMAT = pyaudio.paInt16
CHANNELS = 1
RATE = 8000
# Initialize PyAudio
p = pyaudio.PyAudio()
stream = p.open(
format=FORMAT,
channels=CHANNELS,
rate=RATE,
input=True,
frames_per_buffer=CHUNK
)
# Capture and send audio
while client.call_state.value in ['connected', 'streaming']:
data = stream.read(CHUNK)
# Convert PCM to μ-law (implement conversion)
ulaw_data = pcm_to_ulaw(data)
client.send_audio(ulaw_data)
```
## Examples
### Complete Call Example
```python
from simplesip import SimpleSIPClient
import time
import threading
def audio_callback(audio_data, format):
"""Handle incoming audio data"""
print(f"Received {len(audio_data)} bytes of {format} audio")
# Create client
client = SimpleSIPClient(
username="1001",
password="secret123",
server="sip.example.com"
)
# Set up audio handling
client.set_audio_callback(audio_callback, format='pcmu')
try:
# Connect to server
print("Connecting to SIP server...")
client.connect()
print("Connected and registered!")
# Make a call
print("Making call to 1002...")
client.call("1002")
# Wait for call to be answered
timeout = 30
start_time = time.time()
while client.call_state.value not in ['connected', 'streaming']:
if time.time() - start_time > timeout:
print("Call timeout!")
break
status = client.get_call_status()
print(f"Call status: {status['state']}")
time.sleep(1)
if client.call_state.value in ['connected', 'streaming']:
print("Call connected! Audio streaming active.")
# Keep call active for 30 seconds
time.sleep(30)
# Hang up
print("Hanging up...")
client.hangup()
finally:
# Clean disconnect
client.disconnect()
print("Disconnected from server")
```
### Configuration Options
```python
# Create client with custom settings
client = SimpleSIPClient(
username="myuser",
password="mypass",
server="192.168.1.100",
port=5060, # Custom SIP port
local_port=5061, # Custom local port
timeout=10 # Custom timeout
)
# Set custom timeout
client.timeout = 30
# Enable debug logging
import logging
logging.basicConfig(level=logging.DEBUG)
```
## Development
### Requirements
- Python 3.8+
- numpy (for audio processing)
- pyaudio (optional, for microphone support)
### Running Tests
```bash
# Install development dependencies
pip install -e .[dev]
# Run tests
pytest
# Run tests with coverage
pytest --cov=simplesip
```
### Building Documentation
```bash
# Install docs dependencies
pip install sphinx sphinx-rtd-theme
# Build docs
cd docs
make html
```
## Contributing
Contributions are welcome! Please follow these steps:
1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes
4. Add tests for new functionality
5. Run tests: `pytest`
6. Commit changes: `git commit -am 'Add feature'`
7. Push to branch: `git push origin feature-name`
8. Submit a Pull Request
## Known Limitations
- Currently supports PCMU (μ-law) audio encoding only
- IPv4 only (IPv6 support planned)
- Basic SIP features (advanced features in development)
- No built-in STUN/TURN support yet
## Roadmap
- [ ] Additional audio codecs (G.711 A-law, G.722)
- [ ] IPv6 support
- [ ] STUN/TURN support for NAT traversal
- [ ] SIP over TLS (SIPS)
- [ ] Conference calling support
- [ ] Call transfer and hold functionality
- [ ] Advanced SDP negotiation
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Author
**Awais Khan**
- Email: [contact@awaiskhan.com.pk](mailto:contact@awaiskhan.com.pk)
- GitHub: [@Awaiskhan404](https://github.com/Awaiskhan404)
## Acknowledgments
- Built with Python's socket and threading libraries
- Audio processing powered by NumPy
- Inspired by the SIP protocol specification (RFC 3261)
## Support
- **Bug Reports**: [GitHub Issues](https://github.com/Awaiskhan404/simplesip/issues)
- **Discussions**: [GitHub Discussions](https://github.com/Awaiskhan404/simplesip/discussions)
- **Email**: [contact@awaiskhan.com.pk](mailto:contact@awaiskhan.com.pk)
---
*Made with ❤️ for the Python and VoIP communities*
Raw data
{
"_id": null,
"home_page": "https://github.com/Awaiskhan404/simplesip",
"name": "simplesip",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "sip, voip, rtp, audio, streaming, telephony, simple",
"author": "Awais Khan",
"author_email": "Awais khan <contact@awaiskhan.com.pk>",
"download_url": "https://files.pythonhosted.org/packages/df/50/6f381bf7ac90b7c7eec0a0b9b044b0fbaaa0da6e64586118a4a1ffd5f8a3/simplesip-0.1.1.tar.gz",
"platform": null,
"description": "# SimpleSIP - Simple SIP Client Library\n\n[](https://badge.fury.io/py/simplesip)\n[](https://pypi.org/project/simplesip/)\n[](https://opensource.org/licenses/MIT)\n\nA lightweight, easy-to-use Python library for SIP (Session Initiation Protocol) communication with RTP audio streaming capabilities. Perfect for building VoIP applications, automated calling systems, and SIP-based integrations.\n\n## Features\n\n- **Simple API** - Easy-to-use interface for SIP operations\n- **Full SIP Support** - Registration, calls, and session management\n- **Real-time Audio** - RTP audio streaming with \u03bc-law (PCMU) encoding\n- **Audio Capture** - Built-in microphone support with PyAudio integration\n- **Authentication** - Digest authentication support\n- **Async Operations** - Non-blocking operations with threading\n- **Call States** - Comprehensive call state management\n- **Extensible** - Easy to extend and customize for your needs\n\n## Quick Start\n\n### Installation\n\n```bash\npip install simplesip\n```\n\nFor audio support, install with optional dependencies:\n```bash\npip install simplesip[audio]\n# or\npip install simplesip pyaudio\n```\n\n### Basic Usage\n\n```python\nfrom simplesip import SimpleSIPClient\nimport time\n\n# Create a SIP client\nclient = SimpleSIPClient(\n username=\"your_username\",\n password=\"your_password\", \n server=\"your_sip_server.com\"\n)\n\n# Connect to the SIP server\nclient.connect()\n\n# Make a call\nclient.call(\"1234567890\")\n\n# Wait for the call to be established\nwhile client.call_state.value != 'connected':\n time.sleep(0.1)\n\n# Keep the call active for 10 seconds\ntime.sleep(10)\n\n# Hang up\nclient.hangup()\n\n# Disconnect from server\nclient.disconnect()\n```\n\n## API Reference\n\n### SimpleSIPClient\n\nThe main class for SIP operations.\n\n#### Constructor\n\n```python\nSimpleSIPClient(username, password, server, port=5060, local_port=None, timeout=5)\n```\n\n**Parameters:**\n- `username` (str): SIP username\n- `password` (str): SIP password\n- `server` (str): SIP server hostname or IP\n- `port` (int): SIP server port (default: 5060)\n- `local_port` (int): Local port for SIP (default: random)\n- `timeout` (int): Connection timeout in seconds (default: 5)\n\n#### Methods\n\n##### connect()\nConnect to the SIP server and register.\n\n```python\nclient.connect()\n```\n\n##### call(number)\nInitiate a call to the specified number.\n\n```python\nclient.call(\"1234567890\")\n```\n\n##### hangup()\nEnd the current call.\n\n```python\nclient.hangup()\n```\n\n##### disconnect()\nDisconnect from the SIP server.\n\n```python\nclient.disconnect()\n```\n\n##### send_audio(audio_data)\nSend audio data during an active call.\n\n```python\nclient.send_audio(ulaw_audio_data)\n```\n\n##### set_audio_callback(callback, format='pcmu')\nSet a callback function to handle incoming audio.\n\n```python\ndef audio_handler(audio_data, format):\n # Process incoming audio\n pass\n\nclient.set_audio_callback(audio_handler, format='pcmu')\n```\n\n##### get_call_status()\nGet the current call status.\n\n```python\nstatus = client.get_call_status()\nprint(f\"State: {status['state']}\")\nprint(f\"Duration: {status['duration']}\")\n```\n\n### Call States\n\nThe library uses an enum for call states:\n\n- `CallState.IDLE` - No active call\n- `CallState.INVITING` - Outgoing call in progress\n- `CallState.RINGING` - Call is ringing\n- `CallState.CONNECTED` - Call connected but no media\n- `CallState.STREAMING` - Call with active audio streaming\n\n## Audio Support\n\nSimpleSIP supports real-time audio streaming using RTP protocol with \u03bc-law (PCMU) encoding.\n\n### Audio Formats\n\n- **PCMU (\u03bc-law)**: Primary format for SIP/RTP\n- **PCM**: Linear 16-bit audio for processing\n\n### Audio Callback\n\nSet up an audio callback to handle incoming audio:\n\n```python\ndef handle_audio(audio_data, format):\n if format == 'pcmu':\n # Handle \u03bc-law encoded audio\n pass\n elif format == 'pcm':\n # Handle linear PCM audio\n pass\n\nclient.set_audio_callback(handle_audio, format='pcmu')\n```\n\n### Microphone Integration\n\n```python\nimport pyaudio\nimport numpy as np\n\n# Audio configuration\nCHUNK = 1024\nFORMAT = pyaudio.paInt16\nCHANNELS = 1\nRATE = 8000\n\n# Initialize PyAudio\np = pyaudio.PyAudio()\nstream = p.open(\n format=FORMAT,\n channels=CHANNELS,\n rate=RATE,\n input=True,\n frames_per_buffer=CHUNK\n)\n\n# Capture and send audio\nwhile client.call_state.value in ['connected', 'streaming']:\n data = stream.read(CHUNK)\n # Convert PCM to \u03bc-law (implement conversion)\n ulaw_data = pcm_to_ulaw(data)\n client.send_audio(ulaw_data)\n```\n\n## Examples\n\n### Complete Call Example\n\n```python\nfrom simplesip import SimpleSIPClient\nimport time\nimport threading\n\ndef audio_callback(audio_data, format):\n \"\"\"Handle incoming audio data\"\"\"\n print(f\"Received {len(audio_data)} bytes of {format} audio\")\n\n# Create client\nclient = SimpleSIPClient(\n username=\"1001\",\n password=\"secret123\",\n server=\"sip.example.com\"\n)\n\n# Set up audio handling\nclient.set_audio_callback(audio_callback, format='pcmu')\n\ntry:\n # Connect to server\n print(\"Connecting to SIP server...\")\n client.connect()\n print(\"Connected and registered!\")\n \n # Make a call\n print(\"Making call to 1002...\")\n client.call(\"1002\")\n \n # Wait for call to be answered\n timeout = 30\n start_time = time.time()\n \n while client.call_state.value not in ['connected', 'streaming']:\n if time.time() - start_time > timeout:\n print(\"Call timeout!\")\n break\n \n status = client.get_call_status()\n print(f\"Call status: {status['state']}\")\n time.sleep(1)\n \n if client.call_state.value in ['connected', 'streaming']:\n print(\"Call connected! Audio streaming active.\")\n \n # Keep call active for 30 seconds\n time.sleep(30)\n \n # Hang up\n print(\"Hanging up...\")\n client.hangup()\n \nfinally:\n # Clean disconnect\n client.disconnect()\n print(\"Disconnected from server\")\n```\n\n### Configuration Options\n\n```python\n# Create client with custom settings\nclient = SimpleSIPClient(\n username=\"myuser\",\n password=\"mypass\",\n server=\"192.168.1.100\",\n port=5060, # Custom SIP port\n local_port=5061, # Custom local port\n timeout=10 # Custom timeout\n)\n\n# Set custom timeout\nclient.timeout = 30\n\n# Enable debug logging\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n```\n\n## Development\n\n### Requirements\n\n- Python 3.8+\n- numpy (for audio processing)\n- pyaudio (optional, for microphone support)\n\n### Running Tests\n\n```bash\n# Install development dependencies\npip install -e .[dev]\n\n# Run tests\npytest\n\n# Run tests with coverage\npytest --cov=simplesip\n```\n\n### Building Documentation\n\n```bash\n# Install docs dependencies\npip install sphinx sphinx-rtd-theme\n\n# Build docs\ncd docs\nmake html\n```\n\n## Contributing\n\nContributions are welcome! Please follow these steps:\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes\n4. Add tests for new functionality\n5. Run tests: `pytest`\n6. Commit changes: `git commit -am 'Add feature'`\n7. Push to branch: `git push origin feature-name`\n8. Submit a Pull Request\n\n## Known Limitations\n\n- Currently supports PCMU (\u03bc-law) audio encoding only\n- IPv4 only (IPv6 support planned)\n- Basic SIP features (advanced features in development)\n- No built-in STUN/TURN support yet\n\n## Roadmap\n\n- [ ] Additional audio codecs (G.711 A-law, G.722)\n- [ ] IPv6 support\n- [ ] STUN/TURN support for NAT traversal\n- [ ] SIP over TLS (SIPS)\n- [ ] Conference calling support\n- [ ] Call transfer and hold functionality\n- [ ] Advanced SDP negotiation\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Author\n\n**Awais Khan**\n- Email: [contact@awaiskhan.com.pk](mailto:contact@awaiskhan.com.pk)\n- GitHub: [@Awaiskhan404](https://github.com/Awaiskhan404)\n\n## Acknowledgments\n\n- Built with Python's socket and threading libraries\n- Audio processing powered by NumPy\n- Inspired by the SIP protocol specification (RFC 3261)\n\n## Support\n\n- **Bug Reports**: [GitHub Issues](https://github.com/Awaiskhan404/simplesip/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/Awaiskhan404/simplesip/discussions)\n- **Email**: [contact@awaiskhan.com.pk](mailto:contact@awaiskhan.com.pk)\n\n---\n\n*Made with \u2764\ufe0f for the Python and VoIP communities*\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simple SIP client library with RTP audio streaming capabilities",
"version": "0.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/Awaiskhan404/simplesip/issues",
"Documentation": "https://simplesip.readthedocs.io/",
"Homepage": "https://github.com/Awaiskhan404/simplesip",
"Repository": "https://github.com/Awaiskhan404/simplesip.git"
},
"split_keywords": [
"sip",
" voip",
" rtp",
" audio",
" streaming",
" telephony",
" simple"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ecdb9b78b1efc49aaa47bfa40deade768a9e75f37613845d29dd67fef72c4bd3",
"md5": "5a5e52bf0309cdc41524fe2c5b8bb545",
"sha256": "625aa404da39d6687a1af99cf24ab0aca1c33498becc719fff870b53e3ca9684"
},
"downloads": -1,
"filename": "simplesip-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5a5e52bf0309cdc41524fe2c5b8bb545",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 37167,
"upload_time": "2025-07-24T13:44:40",
"upload_time_iso_8601": "2025-07-24T13:44:40.935873Z",
"url": "https://files.pythonhosted.org/packages/ec/db/9b78b1efc49aaa47bfa40deade768a9e75f37613845d29dd67fef72c4bd3/simplesip-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "df506f381bf7ac90b7c7eec0a0b9b044b0fbaaa0da6e64586118a4a1ffd5f8a3",
"md5": "fb18f661858b6c128da2bfac86f53733",
"sha256": "e67a9b6d941a975e9298898e91ff9bdb4497d19f820d2cf358796a3f17212700"
},
"downloads": -1,
"filename": "simplesip-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "fb18f661858b6c128da2bfac86f53733",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 39359,
"upload_time": "2025-07-24T13:44:42",
"upload_time_iso_8601": "2025-07-24T13:44:42.024802Z",
"url": "https://files.pythonhosted.org/packages/df/50/6f381bf7ac90b7c7eec0a0b9b044b0fbaaa0da6e64586118a4a1ffd5f8a3/simplesip-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-24 13:44:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Awaiskhan404",
"github_project": "simplesip",
"github_not_found": true,
"lcname": "simplesip"
}
JSON
