os-webrtc-janus

Addon-module for OpenSimulator to provide webrtc voice support using Janus-gateway.

For an explanation of background and architecture, this project was presented at the OpenSimulator Community Conference 2024 in the presentation WebRTC Voice for OpenSimulator.

This addon works by taking viewer requests for voice service and using a separate, external Janus-Gateway WebRTC server. This can be configured to allow local region spatial voice and grid-wide group and spatial voice. See the sections below.

For running that separate Janus server, check out os-webrtc-janus-docker which has instructions for running Janus-Gateway on Linux and Windows WSL using Docker.

Instructions for:

• Building into OpenSimulator: Build OpenSimulator with WebRTC voice service
• Configuring Simulator for Voice Services
• Configuring Robust Grid Service
• Configure Standalone Region
• Managing Voice Service (console commands, etc)

Note: as of January 2024, this solution does not provide true spatial voice service using Janus. There are people working on additions to Janus to provide this but the existing solution provides only non-spatial voice services using the AudioBridge Janus plugin. Additionally, features like muting and individual avatar volume are not yet implemented.

Known Issues

• No spatial audio
• One can see your own "white dot" but you don't see other avatar's white dots
• No muting
• No individual volume control

And probably more found at os-webrtc-janus issues.

Building Plugin into OpenSimulator

os-webrtc-janus is integrated as a source build into OpenSimulator. It uses the OpenSimulator addon-module feature which makes the build as easy as cloning the os-webrtc-janus sources into the OpenSimulator source tree, running the build configuration script, and then building OpenSimulator.

The steps are:

# Get the OpenSimulator sources
git clone git://opensimulator.org/git/opensim
cd opensim     # cd into the top level OpenSim directory

# Fetch the WebRtc addon
cd addon-modules
git clone https://github.com/Misterblue/os-webrtc-janus.git
cd ..

# Build the project files
./runprebuild.sh

# Compile OpenSimulator with the webrtc addon
./compile.sh

# Copy the INI file for webrtc into a config dir that is read at boot
mkdir bin/config
cp addon-modules/os-webrtc-janus/os-webrtc-janus.ini bin/config

These building steps create several .dll files for os-webrtc-janus in bin/WebRtc*.dll. Some adventurous people have found that, rather than building the OpenSimulator sources, you can just copy the .dlls into an existing /bin directory. Just make sure the WebRtc*.dll files were built on the same version of OpenSimulator you are running.

Configure a Region for Voice

The last step in Building copied os-webrtc-janus.ini into the bin/config directory. OpenSimulator reads all the .ini files in that directory so this copy operation adds the configuration for os-webrtc-janus and this is what needs to be configured for the simulator and region.

The sample .ini file has two sections: [WebRtcVoice] and [JanusWebRtcVoice]. The WebRtcVoice section configures the what services the simulator uses for WebRtc voice. The [JanusWebRtcVoice] section configures any connection the simulator makes to the Janus server. The latter section is only updated if this simulator is using a local Janus server for spatial voice.

The values for SpatialVoiceService and NonSpatialVoiceService point either directly to a Janus service or to a Robust grid server that is providing the grid voice service. Both these options are in the sample os-webrtc-janus.ini file and the proper one should be uncommented.

The viewer makes requests for either spatial voice (used in the region and parcels) or non-spatial voice (used for group chats or person-to-person voice conversations). os-webrtc-janus allows these two types of voice connections to be handled by different voice services. Thus there are two different configurations:

• all voice service is provided by the grid (both spatial and non-spatial point to a robust service), and
• the region simulator provides a local Janus server for region spatial voice while the grid service is used for group chats

Grid Only Voice Services

The most common configuration will be for a simulator that uses the grid supplied voice services. For this configuration, os-webrtc-janus.ini would look like:

[WebRtcVoice]
    Enabled = true
    SpatialVoiceService = WebRtcVoice.dll:WebRtcVoiceServiceConnector
    NonSpatialVoiceService = WebRtcVoice.dll:WebRtcVoiceServiceConnector
    WebRtcVoiceServerURI = ${Const|PrivURL}:${Const|PrivatePort}

This directs both spatial and non-spatial voice to the grid service connector and WebRtcVoiceServerURI points to the configured Robust grid service.

There is no need for a [JanusWebRtcVoice] section because all that is handled by the grid services.

Local Simulator Janus Service

In a grid setup, there might be a need for a single simulator/region to use its own Janus server for either privacy or to off-load the grid voice service. In this configuration, spatial voice is directed to the local Janus service while the non-spatial voice goes to the grid services to allow grid wide group chat and region independent person-to-person chat.

This is done with a os-webrtc-janus.ini that looks like:

[WebRtcVoice]
    Enabled = true
    SpatialVoiceService = WebRtcJanusService.dll:WebRtcJanusService
    NonSpatialVoiceService = WebRtcVoice.dll:WebRtcVoiceServiceConnector
    WebRtcVoiceServerURI = ${Const|PrivURL}:${Const|PrivatePort}
[JanusWebRtcVoice]
    JanusGatewayURI = http://janus.example.org:14223/voice
    APIToken = APITokenToNeverCheckIn
    JanusGatewayAdminURI = http://janus.example.org/admin
    AdminAPIToken = AdminAPITokenToNeverCheckIn

Notice that, since the simulator has its own Janus service, it must configure the connection parameters to access that Janus service. The details of running and configuring a Janus service is provided at os-webrtc-janus-docker but, the configuration here needs to specify the URI to address the Janus server and the API keys to allow this simulator access to its interfaces. The example above contains just sample entries.

Configure Robust Server for WebRTC Voice

For the grid services side, os-webrtc-janus is configured as an additional service in the Robust OpenSimulator server. The additions to Robust.ini are:

...
[ServiceList]
    ...
    VoiceServiceConnector = "${Const|PrivatePort}/WebRtcVoice.dll:WebRtcVoiceServerConnector"
    ...

[WebRtcVoice]
    Enabled = true
    SpatialVoiceService = WebRtcJanusService.dll:WebRtcJanusService
    NonSpatialVoiceService = WebRtcJanusService.dll:WebRtcJanusService
[JanusWebRtcVoice]
    JanusGatewayURI = http://janus.example.org:14223/voice
    APIToken = APITokenToNeverCheckIn
    JanusGatewayAdminURI = http://janus.example.org/admin
    AdminAPIToken = AdminAPITokenToNeverCheckIn
...

This adds VoiceServiceConnector to the list of services presented by this Robust server and adds the WebRtcVoice configuration that says to do both spatial and non-spatial voice using the Janus server, and the configuration for the Janus server itself.

One can configure multiple Robust services to distribute the load of services and a Robust server with only VoiceServiceConnector in its ServiceList is possible.

Configure Standalone Region

OpenSimulator can be run "standalone" where all the grid services and regions are run in one simulator instance. Adding voice to this configuration is sometimes useful for very private meetings or testing. For this configuration, a Janus server is set up and the standalone simulator is configured to point all voice to that Janus server:

[WebRtcVoice]
    Enabled = true
    SpatialVoiceService = WebRtcJanusService.dll:WebRtcJanusService
    NonSpatialVoiceService = WebRtcJanusService.dll:WebRtcJanusService
    WebRtcVoiceServerURI = ${Const|PrivURL}:${Const|PrivatePort}
[JanusWebRtcVoice]
    JanusGatewayURI = http://janus.example.org:14223/voice
    APIToken = APITokenToNeverCheckIn
    JanusGatewayAdminURI = http://janus.example.org/admin
    AdminAPIToken = AdminAPITokenToNeverCheckIn

This directs both spatial and non-spatial voice to the Janus server and configures the URI address of the Janus server and the API access keys for that server.

Managing Voice (Console commands)

There are a few console commands for checking on and controlling the voice system. The current list of commands for the simulator can be listed with the console command help webrtc.

This is a growing section and will be added to over time.

webrtc list sessions -- not implemented

janus info -- list many details of the Janus-Gateway configuration. Very ugly, non-formated JSON.

janus list rooms -- list the rooms that have been allocated in the AudioBridge Janus plugin