SpatialAudioParams

Spatial audio parameters.

class SpatialAudioParams {
  const SpatialAudioParams(
      {this.speakerAzimuth,
      this.speakerElevation,
      this.speakerDistance,
      this.speakerOrientation,
      this.enableBlur,
      this.enableAirAbsorb,
      this.speakerAttenuation,
      this.enableDoppler});

  @JsonKey(name: 'speaker_azimuth')
  final double? speakerAzimuth;

  @JsonKey(name: 'speaker_elevation')
  final double? speakerElevation;

  @JsonKey(name: 'speaker_distance')
  final double? speakerDistance;

  @JsonKey(name: 'speaker_orientation')
  final int? speakerOrientation;

  @JsonKey(name: 'enable_blur')
  final bool? enableBlur;

  @JsonKey(name: 'enable_air_absorb')
  final bool? enableAirAbsorb;

  @JsonKey(name: 'speaker_attenuation')
  final double? speakerAttenuation;

  @JsonKey(name: 'enable_doppler')
  final bool? enableDoppler;

  factory SpatialAudioParams.fromJson(Map<String, dynamic> json) =>
      _$SpatialAudioParamsFromJson(json);

  Map<String, dynamic> toJson() => _$SpatialAudioParamsToJson(this);
}

Properties

speaker_azimuth
The horizontal angle of the remote user or media player relative to the local user. Value range: [0,360], in degrees:
  • 0: (default) 0°, directly in front.
  • 90: 90°, directly to the left.
  • 180: 180°, directly behind.
  • 270: 270°, directly to the right.
  • 360: 360°, same as 0°, directly in front.
speaker_elevation
The vertical angle of the remote user or media player relative to the local user. Value range: [-90,90], in degrees:
  • 0: (default) 0°, no tilt.
  • -90: -90°, tilted downward.
  • 90: 90°, tilted upward.
speaker_distance
The distance between the remote user or media player and the local user. Value range: [1,50], in meters. Default is 1 meter.
speaker_orientation
The orientation of the remote user or media player relative to the local user. Value range: [0,180], in degrees:
  • 0: (default) 0°, facing the same direction.
  • 180: 180°, facing each other.
enable_blur
Whether to enable sound blur processing:
  • true: Enable blur.
  • false: (default) Disable blur.
enable_air_absorb
Whether to enable air absorption, which simulates the attenuation of sound timbre as it travels through air: high frequencies attenuate faster than low frequencies over distance.
  • true: (default) Enable air absorption. Make sure speaker_attenuation is not 0, otherwise this setting has no effect.
  • false: Disable air absorption.
speaker_attenuation
The sound attenuation coefficient of the remote user or media player. Value range: [0,1]:
  • 0: Broadcast mode. Volume and timbre do not attenuate with distance.
  • (0,0.5): Weak attenuation. Slight attenuation of volume and timbre (requires enable_air_absorb) during transmission. Sound travels farther than in real environments.
  • 0.5: (default) Simulates real-world volume attenuation. Equivalent to not setting speaker_attenuation.
  • (0.5,1]: Strong attenuation. Rapid attenuation of volume and timbre (requires enable_air_absorb) during transmission.
enable_doppler
Note:
  • This parameter is suitable for scenarios with fast-moving sound sources (e.g., racing games). It is not recommended for standard audio/video interaction scenarios (voice chat, co-hosting, online KTV).
  • When enabled, it is recommended to update the relative distance between source and receiver periodically (e.g., every 30 ms) using updatePlayerPositionInfo, updateSelfPosition, and updateRemotePosition. The Doppler effect may not work as expected or may cause jitter if updates are infrequent, irregular, or affected by network issues such as packet loss or latency.
Whether to enable Doppler effect: when there is relative motion between the sound source and receiver, the pitch heard by the receiver changes.
  • true: Enable Doppler effect.
  • false: (default) Disable Doppler effect.