setSpatialEnvironment method

Future<void> setSpatialEnvironment(
  1. SpatialScale scale,
  2. SpatialPosition forward,
  3. SpatialPosition up,
  4. SpatialPosition right
)

Configures a spatial environment of an application, so the audio renderer understands which directions the application considers forward, up, and right and which units it uses for distance. This method is available only for participants who joined a conference using the ConferenceService.join method with the ConferenceJoinOptions.spatialAudio parameter enabled. Otherwise, SDK triggers an error. To set a spatial environment for listeners, use the Set Spatial Listeners Audio REST API.

The method uses the following parameters:

  • scale: A scale that defines how to convert units from the coordinate system of an application (pixels or centimeters) into meters used by the spatial audio coordinate system. For example, if SpatialScale is set to (100,100,100), it indicates that 100 of the applications units (cm) map to 1 meter for the audio coordinates. In such a case, if the listener's location is (0,0,0)cm and a remote participant's location is (200,200,200)cm, the listener has an impression of hearing the remote participant from the (2,2,2)m location. The scale value must be greater than 0. For more information, see the Spatial Audio article.
  • forward: A vector describing the direction the application considers as forward. The value can be either +1, 0, or -1 and must be orthogonal to up and right.
  • up: A vector describing the direction the application considers as up. The value can be either +1, 0, or -1 and must be orthogonal to forward and right.
  • right: A vector describing the direction the application considers as right. The value can be either +1, 0, or -1 and must be orthogonal to forward and up.

If not called, the SDK uses the default spatial environment, which consists of the following values:

  • forward = (0, 0, 1), where +Z axis is in front
  • up = (0, 1, 0), where +Y axis is above
  • right = (1, 0, 0), where +X axis is to the right
  • scale = (1, 1, 1), where one unit on any axis is 1 meter

The default spatial environment is presented in the following diagram:

Implementation

Future<void> setSpatialEnvironment(
    SpatialScale scale,
    SpatialPosition forward,
    SpatialPosition up,
    SpatialPosition right) async {
  await _methodChannel.invokeMethod<void>("setSpatialEnvironment", {
    "scale": scale.toJson(),
    "forward": forward.toJson(),
    "up": up.toJson(),
    "right": right.toJson(),
  });
  return Future.value();
}