SIP Player

A SIP-based music player with DTMF IVR control. Answer incoming calls automatically and play audio tracks to the caller. Control playback via DTMF tones or GUI.

Features

• SIP Registration: Register to any SIP server
• Auto-Answer: Automatically answer incoming calls
• Audio Playback: Play WAV audio files to SIP calls
• DTMF Control: Control playback with DTMF tones (1/2/3/4)
• Multi-Session: Support multiple concurrent calls
• Bilingual UI: English and Chinese (Simplified) interface
• Import: Convert MP3/M4A/FLAC to WAV via ffmpeg

Requirements

• Python: 3.12 or higher
• uv: Fast Python package installer (recommended)
• PJSIP: 2.16+ (with pjsua2 Python bindings)
• tkinter: GUI framework
• ffmpeg: For audio format conversion (optional, for import feature)

Platform Setup

Choose your platform below for detailed setup instructions:

• Windows
• macOS
• Linux

---

Windows Setup

Step 1: Install Python

1. Download Python 3.12+ from python.org
2. During installation, check "Add Python to PATH"
3. Verify installation:

   python --version

Step 2: Install tkinter

tkinter is included with Python on Windows. Verify it works:

python -c "import tkinter; print('tkinter OK')"

If you get an error, reinstall Python and ensure tcl/tk is selected.

Step 3: Install Build Tools

Download and install Visual Studio Community:

• During installation, select "Desktop development with C++"
• Or install Build Tools for Visual Studio

Step 4: Install SWIG

1. Download SWIG from swig.org
2. Extract to a path without spaces (e.g., C:\swigwin)
3. Add SWIG to PATH:
   • Press Win+R, type sysdm.cpl
   • Go to Advanced → Environment Variables
   • Add C:\swigwin to Path

Verify:

swig -version

Step 5: Install uv

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Step 6: Compile PJSIP

1. Download PJSIP from pjsip.org or GitHub:

   git clone https://github.com/pjsip/pjproject.git
   cd pjproject

2. Configure and build:

   cd pjproject
   python ./configure.py

3. Open the generated solution in Visual Studio:

   • For Visual Studio 2022: pjsip-apps\build\vs2022\pjsua_vc2022.sln
   • Build the entire solution in Release mode

4. Build SWIG Python bindings:

   cd pjsip-apps\src\swig
   python setup.py build
   python setup.py install

Step 7: Install ffmpeg (Optional)

For audio import feature:

1. Download from ffmpeg.org
2. Extract and add bin folder to PATH

Step 8: Install sip-player

cd sip-player

# Create virtual environment
uv venv

# Activate virtual environment
.venv\Scripts\activate

# Install project in editable mode
uv pip install -e .

---

macOS Setup

Step 1: Install Python

Using Homebrew:

brew install python@3.12

Or download from python.org.

Verify:

python3 --version

Step 2: Install tkinter

For Homebrew Python:

brew install python-tk@3.12

For official Python installer: tkinter is included. Verify:

python3 -c "import tkinter; print('tkinter OK')"

If using pyenv, reinstall with tcl-tk support:

brew install tcl-tk
export LDFLAGS="-L$(brew --prefix tcl-tk)/lib"
export CPPFLAGS="-I$(brew --prefix tcl-tk)/include"
export PKG_CONFIG_PATH="$(brew --prefix tcl-tk)/lib/pkgconfig"
pyenv install 3.12.0

Step 3: Install Dependencies

brew install swig ffmpeg

Step 4: Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Step 5: Compile PJSIP

# Clone PJSIP
git clone https://github.com/pjsip/pjproject.git
cd pjproject

# Configure with -fPIC for shared library
./configure CFLAGS="-fPIC"

# Build (5-10 minutes)
make dep && make

# Build SWIG Python bindings
cd pjsip-apps/src/swig
make

# Install pjsua2 module
cd python
python3 setup.py install

Verify installation:

python3 -c "import pjsua2; print('pjsua2 OK')"

Step 6: Install sip-player

cd sip-player

# Create virtual environment
uv venv

# Activate virtual environment
source .venv/bin/activate

# Install project in editable mode
uv pip install -e .

---

Linux Setup

Tested on Ubuntu/Debian and Fedora/RHEL.

Ubuntu/Debian

# Install Python, tkinter, and build tools
sudo apt update
sudo apt install -y python3 python3-tk python3-venv python3-dev build-essential swig ffmpeg curl

# Install PJSIP dependencies
sudo apt install -y libssl-dev libsrtp2-dev libopus-dev libspeex-dev libgsm1-dev

# Clone and build PJSIP
git clone https://github.com/pjsip/pjproject.git
cd pjproject
./configure CFLAGS="-fPIC"
make dep && make

# Build SWIG Python bindings
cd pjsip-apps/src/swig
make
cd python
python3 setup.py install --user

# Verify
python3 -c "import pjsua2; print('pjsua2 OK')"

Fedora/RHEL

# Install dependencies
sudo dnf install -y python3 python3-tkinter python3-devel gcc gcc-c++ make swig ffmpeg openssl-devel opus-devel speex-devel gsm-devel curl

# Clone and build PJSIP
git clone https://github.com/pjsip/pjproject.git
cd pjproject
./configure CFLAGS="-fPIC"
make dep && make

# Build SWIG Python bindings
cd pjsip-apps/src/swig
make
cd python
python3 setup.py install --user

Install sip-player

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and navigate to project
cd sip-player

# Create virtual environment
uv venv

# Activate virtual environment
source .venv/bin/activate

# Install project in editable mode
uv pip install -e .

---

Running the Application

GUI Mode

# Activate virtual environment first (if not already activated)
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

# Run the application
python -m src

Or use the installed command:

sip-player

DTMF Controls

During a call, use DTMF tones to control playback:

Key	Action
1	Next track
2	Play/Pause
3	Cycle play mode
4	Previous track

Play Modes

1. Sequential - Play tracks in order, stop at end
2. List Loop - Loop through all tracks
3. Single Loop - Repeat current track
4. Random - Shuffle playback

---

Configuration

Settings are automatically saved to:

• Windows: %APPDATA%\sip_player\settings.json
• macOS: ~/Library/Application Support/sip_player/settings.json
• Linux: ~/.config/sip_player/settings.json

Imported audio files are stored in:

• Windows: %LOCALAPPDATA%\sip_player\imported_tracks\
• macOS: ~/Library/Application Support/sip_player/imported_tracks/
• Linux: ~/.local/share/sip_player/imported_tracks/

---

Troubleshooting

PJSIP Installation Issues

"build.mak: No such file or directory"

• Ensure you ran ./configure and make dep && make in pjproject root

"pjsua2_wrap.cpp: No such file or directory"

• Run make in pjsip-apps/src/swig directory

"Cannot determine JDK include path"

• Safe to ignore if you only need Python bindings

macOS: "tkinter not found"

If using pyenv, reinstall Python with tcl-tk support (see Step 2 above).

Windows: Build Errors

• Ensure Visual Studio with C++ tools is installed
• Run commands from x64 Native Tools Command Prompt
• Verify SWIG is in PATH

Virtual Environment Issues

"Module not found" errors

• Ensure virtual environment is activated before running
• Reinstall with uv pip install -e .

uv command not found

• Close and reopen terminal after installing uv
• Or add uv to PATH manually

---

License

MIT License - see LICENSE file.

References

• PJSIP Documentation
• PJSIP GitHub
• SWIG Documentation
• uv Documentation