mumsi

mumsi - SIP to Mumble gateway

SIP to Mumble gateway based on PJSIP stack and mumlib library. It registers to SIP registrar and listens for incoming connections on the SIP account.

This enables the user to participate in Mumble conference using SIP client or perhaps ordinary telephone, by VoIP provider.

Dependencies

• Boost libraries
• log4cpp
• pjsua2 from Pjproject SIP stack
• CMake
• mumlib - https://github.com/slomkowski/mumlib

Build and usage

• Install all needed dependencies

• Clone and compile Mumlib library. Since it doesn't have any installer, clone it to common directory:

  mkdir mumsi-dist && cd mumsi-dist
  git clone https://github.com/slomkowski/mumlib.git
  mkdir mumlib/build && cd mumlib/build
  cmake ..
  make
  cd -
  

• Then clone and build mumsi:

  git clone https://github.com/slomkowski/mumsi.git
  mkdir mumsi/build && cd mumsi/build
  cmake ..
  make
  

• Copy example config.ini file and edit it according to your needs:

  cp config.ini.example config.ini
  

Remember to add URIs which you want to make calls from. Calls from other URIs won't be answered.

• To run the service, type:

  ./mumsi config.ini
  

Configuring

Multi-Line Support

If your SIP provider allows multiple simultaneous calls, mumsi can be configured to accept calls and map them to separate Mumble users. The max_calls is configure in config.ini:

[sip]
...
max_calls = 32
...

Currently, the Mumble connections are established at server start. For usability, the following options are recommended:

• caller_pin
• autodeaf
• channelAuthExpression

The maximum number of calls is set in main.hpp and should not exceed the PJSUA_MAX_CALLS in pjsua.h, which by default is 32. This can also be recompiled to more, if desired.

When mumsi logs into Mumble, it uses the user name from config.ini and appends the character '-', followed by the connection number (counter).

LIMITATIONS: The code is alpha and needs testing/debugging, especialy in the code that uses mumlib::Transport. Also, there is initial work on connecting the Mumble user only when the SIP call is active, so the UI for other users is better, but this code is still very buggy and therefore disabled.

Caller PIN

When the caller_pin is set, the incoming SIP connection is mute/deaf until the caller enters the correct PIN, followed by the '#' symbol. On three failed attempts, the SIP connection is hung up. On success, the Mumble user is moved into the channel matching channelAuthExpression, if specified, and then mute/deaf is turned off. As a courtesy to the other users, a brief announcement audio file is played in the Mumble channel.

The caller_pin is configured in config.ini in the app section:

[app]
caller_pin = 12345

In addition to the caller_pin, a channelAuthExpression can be set. After the caller authenticates with the PIN, the mumsi Mumble user will switch to the Mumble channel that matches this expression. When the call is completed, the mumsi Mumble user will return to the default channel that matches channelNameExpression.

This helps keep the unused SIP connections from cluttering your channel.

Autodeaf

By default (i.e. autodeaf=0), other Mumble users can only see whether the mumsi connection has an active caller if they are in the same channel. This is becaue the 'talking mouth' icon is not visible to users in other channels. The mute/deaf icons, on the other hand, can be seen by Mumble users when they are in different channels, making it easier to spot when a new caller has connected.

Setting `autodeaf=1' causes the mumsi Mumble user to be mute/deaf when there is no active SIP call.

Audio Files

When certain events occur, it is user-friendly to provide some sort of prompting confirmation to the user. An example set of WAV files is provided, but they can easily be customized or replaced with local versions, if needed. If the files are not found, no sound is played. The following events are supported:

• welcome: Played to caller when first connecting to mumsi
• prompt_pin: Prompt the caller to enter the PIN
• entering_channel: Caller entered PIN and is now entering the Mumble channel
• announce_new_caller: Played to the Mumble channel when adding a new caller
• invalid_pin: Let the caller know they entered the wrong PIN
• goodbye: Hanging up on the caller
• mute_on: Self-mute has been turned on (not implemented)
• mute_off: Self-mute has been turned off (not implemented)
• menu: Tell caller the menu options (not implemented)

Start at boot

mumsi provides no init.d scripts, but you can use great daemon mangaer, Supervisor. The sample configuration file:

[program:mumsi]
command=/home/mumsi/mumsi-dist/mumsi/build/mumsi config.ini
directory=/home/mumsi/mumsi-dist/mumsi
user=mumsi

stdout_logfile=/home/mumsi/console.log
stdout_logfile_maxbytes=1MB
stdout_logfile_backups=4
stdout_capture_maxbytes=1MB
redirect_stderr=true

Issues

Port and NAT

Remember to allow incoming connections on port 5060 UDP in your firewall. If you're connecting to public SIP provider from machine behind NAT, make sure your setup works using some generic SIP client. Since SIP is not NAT-friendly by design, PJSIP usually takes care of connection negotiation and NAT traversal, but might fail. The most reliable solution is to configure port forwarding on your home router to your PC.

PJ_EINVALIDOP error

You may encounter following error when running mumsi on older distros

pjsua_conf_add_port(mediaPool, (pjmedia_port *)port, &id) error: Invalid operation (PJ_EINVALIDOP)

Some older versions of PJSIP are affected (confirmed for 2.3). In this case you have to update PJSIP to most recent version (2.4.5).

mumlib::TrasportException

The multi-caller code is alpha and needs testing/debugging, especialy in the code that uses mumlib::Transport. Also, there is initial work on connecting the Mumble user only when the SIP call is active, so the UI for other users is better, but this code is still very buggy and therefore disabled.

TODO:

• multiple simultaneous connections
• outgoing connections
• text chat commands

Credits

2015, 2016 Michał Słomkowski. The code is published under the terms of Apache License 2.0.

Donations

If this project has helped you and you feel generous, you can donate some money to 14qNqXwqb6zsEKZ6vUhWVbuNLGdg8hnk8b.