Documentation

Support

Vivox Core SDK

Vivox Core SDK

Positional channel parameters

Configure positional audio for 3D voice.
Read time 2 minutesLast updated 20 hours ago
Developers can optionally specify parameters for positional (d) channels by using an extended syntax in the channelid portion of the channel URI. Immediately following the channelid, and before the "@", add "!p-" followed by hyphen-delimited parameters that indicate 3D channel property values in the following format: 
!p-{max_range}-{clamping_distance}-{rolloff}-{distance_model}
The channel parameters are: 
  • {max_range}
    : The maximum distance from the listener at which you can hear a speaker. This must be an integer > 0.
    • If you want a lower 
      max_range
      (For example, to limit the range of received texts), you can increase rolloff accordingly.
  • {clamping_distance}
    : The distance from the listener at which a speaker’s voice is heard at its original volume. This must be an integer in the range 0 <= 
    clamping_distance
    <= 
    max_range
    . Consider this to be the expected close-by conversational distance.
    • The 
      clamping_distance
      sounds the most realistic when it is half the height of a typical speaking entity in your game. Consider adjusting this value if your players are shorter or taller than typical adult humans.
  • {rolloff}
    : The strength of the audio fade effect as the speaker moves away from the listener. This must be a floating point value >= 0 that is rounded to three decimal places. The best starting point for each 
    distance_model
    is a rolloff of 1.0.     
  • {distance_model}
    : The model that determines voice volume at different distances.
    • 1 = inverse-clamped (Default, most acoustically accurate.)
    • 2 = linear-clamped
    • 3 = exponent-clamped
      • When using the default 
        distance_model
        value, if you want voice chat to naturally fade to near zero loudness at the edge of the 
        max_range
        instead of being abruptly cut off, then set the 
        max_range
        to a minimum of: 32 × 
        clamping_distance
        ÷ 
        rolloff
        .
Depending on the amount of ambient game noise or music, you might want to adjust the parameter values to ensure that voice chat is heard only at the distances you want. When using the exponent-clamped 
distance_model
, we recommend keeping the 
clamping_distance
value at 1 or greater. We also recommend that you adjust the value of the rolloff parameter based on the following formula: rolloff = 3 ÷ (1 + 1.75 × log10(
clamping_distance
)). The following code displays an example string with parameter syntax. You can construct the string manually or by using the method 
vx_get_positional_channel_uri()
: 
// The Vivox SDK must be initializedchar *uri = vx_get_positional_channel_uri("channelid", "domain.vivox.com", 30, 1, 1.000, channel_rolloff_curve_type_inverse_distance_clamped, "issuer");// returns "sip:confctl-d-issuer.channelid!p-30-1-1.000-1@domain.vivox.com". . .vx_free(uri);
The following channel name is an example of what is passed to the Vivox servers when working with access tokens: 
sip:confctl-d-blindmelon-AppName.match72-team1-prox!p-30-1-1.000-1@tla.vivox.com
For more information, refer to the Access Token Developer Guide.