235 lines
9.6 KiB
Markdown
235 lines
9.6 KiB
Markdown
# 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](https://www.youtube.com/watch?v=nL78fieIFYg).
|
|
|
|
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](#Building): Build OpenSimulator with WebRTC voice service
|
|
- [Configuring Simulator for Voice Services](#Configure_Simulator)
|
|
- [Configuring Robust Grid Service](#Configure_Robust)
|
|
- [Configure Standalone Region](#Configure_Standalone)
|
|
- [Managing Voice Service](#Managing_Voice) (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.
|
|
|
|
<a id="Known_Issues"></a>
|
|
## 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](https://github.com/Misterblue/os-webrtc-janus/issues).
|
|
|
|
<a id="Building"></a>
|
|
## 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 `.dll`s
|
|
into an existing `/bin` directory. Just make sure the `WebRtc*.dll` files
|
|
were built on the same version of [OpenSimulator] you are running.
|
|
|
|
<a id="Configure_Simulator"></a>
|
|
## Configure a Region for Voice
|
|
|
|
The last step in [Building](#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.
|
|
|
|
<a id="Configure_Robust"></a>
|
|
## 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.
|
|
|
|
<a id="Configure_Standalone"></a>
|
|
## 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.
|
|
|
|
<a id="Managing_Voice"></a>
|
|
## 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
|
|
|
|
[SecondLife WebRTC Voice]: https://wiki.secondlife.com/wiki/WebRTC_Voice
|
|
[OpenSimulator]: http://opensimulator.org
|
|
[OpenSimulator Community Conference]: https://conference.opensimulator.org
|
|
[os-webrtc-janus]: https://github.com/Misterblue/os-webrtc-janus
|
|
[Janus-Gateway WebRTC server]: https://janus.conf.meetecho.com/
|
|
[os-webrtc-janus-docker]: https://github.com/Misterblue/os-webrtc-janus-docker
|