Wiki-home » About VastPark » Platform » VastWorlds platform » Developer's guide » Plugins » List of Plugins »

VoicePlugin

FAQ support on Vivox's service: http://www.vivox.com/troubleshooting.html

IMML example

<Plugin Name="VivoxPlugin" Enabled="True" Source="http://id.vastpark.com/VastParkWS/get.vpws?publisher=acascone&amp;name=VivoxPlugin&amp;domain=vastpark&amp;context=park"/>

Properties

bool FlipSound

  • Summary: Increases the rotation by 180, every time a new rotation value is given, therefore flipping the person's sound. This is false by default.

bool InvertSound

  • Summary: It inverts the sign from positive to negative or negative to positive on the x-axis every time the update of the position is called. This is false by default.

bool InvertZ_Axis

  • Summary: It inverts the sign from positive to negative or negative to positive on the z-axis, every time the update of the position is called. This is true by default.

double DistanceIgnore

  • Summary: This will ignore any updating calls when the distance from the last update to the new update is more than the DistanceIgnore. This is set to 0 by default. Therefore it will only update when it's greater than 0.

double RotationIgnore

  • Summary: This will ignore any updating calls when the rotation from the last update to the new update is more than the RotationIgnore. This is set to 0 by default. Therefore it will only update when it's greater than 0.

int Timeout

  • Summary: The Maximum amount of time given to process each request, to ensure it won't lock up. This is set to 20 seconds by default.

bool Enabled

  • Summary: Enabled is the property that allows the plug-in Update to be triggered.

Functions

void Load()

  • Summary: Load implements the IPluginComponent to Load. This is where the Vivox Wrapper will be initialised.
  • Parameters

void AddElement(ImmlElement element)

  • Summary: AddElement implements the IPluginComponent to hold and recognise these items. It's currently unused.
  • Parameters
    • element: The element added.

void Update()

  • Summary: Update is the called every frame. This is currently not used.
  • Parameters

void Dispose()

  • Summary: This implements IPluginComponent Dispose. This will dispose of the Vivox Wrapper.
  • Parameters

bool ConnectToServer(string serverUrl)

  • Summary: ConnectToServer is to specify which Vivox Account Management Server one wants to connect to, and to then give the ability to the start to log in to the designated account. To do this it makes a request to connect it to the specified server, then a connector handle should be established, and will then return true.
  • Parameters
    • serverUrl: This is the URL of the Account Management Server.
  • Returns: Returns true if the connecting to the server was successful.

bool ConnectServer(string server, int minPort, int maxPort)

  • Summary: ConnectToServer is to specify which Vivox Account Management Server one wants to connect to, and to then give the ability to the start to log in to the designated account. To do this it makes a request to connect it to the specified server, searching between min and max port numbers until it finds the first open port, then a connector handle should be established, and will then return true. It needs to at least give a range of 32 ports above port 1024.
  • Parameters
    • server: This is the URL of the Account Management Server.
    • minPort: The min port it starts from.
    • maxPort: The max port range where to stop searching.
  • Returns: Returns true if the connecting to the server was successful.

bool LogIn(string user, string password)

  • Summary: Used to login and logout of specific user account(s). It may only be called after connecting Vivox Account Management Server has completed successfully.
  • Parameters
    • user: The username of the Vivox account to be signed into.
    • password: The password of the Vivox account to be signed into.
  • Returns: Returns true if it was successful.

bool LogIn(string user, string password, int presence, int autoanswer, int text, int participantProperty, int buddySetting)

  • Summary: Used to login and logout of specific user account(s). It may only be called after connecting Vivox Account Management Server has completed successfully.
  • Parameters
    • user: The username of the Vivox account to be signed into.
    • password: The password of the Vivox account to be signed into.
    • presence: This determines how the SDK will handle incoming buddy subscriptions. Default Value is 1. Valid values are: 0 - mode_auto_accept, 1 - mode_auto_add, 2 - mode_block, 3 - mode_hide, 4 - mode_application.
    • autoanswer: This is used to determine if the user is going to enable text or not for all sessions. Default Value is 0. MODE_VERIFY_ANSWER = 0, MODE_AUTO_ANSWER = 1.
    • text: This specifies how often the SDK will send participant property events while in a channel. Default Value is 0. TEXT_MODE_DISABLED = 0 TEXT_MODE_ENABLED = 1
    • participantProperty: This sets how often it should send participant property information. Default Value is 100. Valid Values: 0 - Never, 5 - 10 times per second, 10 - 50 times per second, 50 - 100 times per second, 100 - on participant state change.
    • buddySetting: This flag has been deprecated. This is now a no-op and will not affect anything. Default Value is 0.
  • Returns: Returns true if it was successful.

bool AnonymousLogIn()

  • Summary: AnonymousLogIn is used to login anonymously to the Vivox network. This will allow a user to login and receive a temporary SIP Uri and a blank display name. It may only be called after connecting to a server has completed successfully.
  • Parameters
  • Returns: Returns true if it was successful.

bool AnonymousLogIn(string displayName)

  • Summary: AnonymousLogIn is used to login anonymously to the Vivox network. This will allow a user to login and receive a temporary SIP Uri and a user generated display name. It may only be called after connecting to a server has completed successfully.
  • Parameters
    • displayName: User's display name, this will be used as the display name that will be seen by others (Inside Vivox).
  • Returns: Returns true if it was successful.

bool AnonymousLogIn(string displayName, int pres, int participantPropertyFrequnecy, int buddyManagementMode)

  • Summary: AnonymousLogIn is used to login anonymously to the Vivox network. This will allow a user to login and receive a temporary SIP Uri and a user generated display name. It may only be called after connecting to a server has completed successfully.
  • Parameters
    • displayName: User's display name, this will be used as the display name that will be seen by others (Inside Vivox).
    • pres: RESERVED FOR FUTURE USE: This determines whether or not to enable and allow buddy and presence information. Default Value is 0. Setting to 1 will enable buddy and presense functionality.
    • participantPropertyFrequnecy: This sets how often it should send participant property information. Default Value is 100. Valid Values: 0 - Never, 5 - 10 times per second, 10 - 50 times per second, 50 - 100 times per second, 100 - on participant state change.
    • buddyManagementMode: RESERVED FOR FUTURE USE: This determines how the SDK will handle incoming buddy subscriptions.
  • Returns: Returns true if it was successful.

int CreateGroup()

  • Summary: Creates a Session Group that stores sessions that are either voice (usually only allows one in the whole program) or text or both. This is just a session holder on the local side, and not a group that shows who is connected in channels. Therefore this controls the focus and listening of different channels, and may focus channels upon request. This is required before creating a session and need to be logged in to get this request to be successful.
  • Parameters
  • Returns: Returns the local id of the group that was just created.

int CreateGroup(int playback)

  • Summary: Creates a Session Group that stores sessions that are either voice (usually only allows one in the whole program) or text or both. This is just a session holder on the local side, and not a group that shows who is connected in channels. Therefore this controls the focus and listening of different channels, and may focus channels upon request. This is required before creating a session and need to be logged in to get this request to be successful.
  • Parameters
    • playback: SessionGroup Type. Default value is 0. Valid Values: 0 Normal type for general use, 1 Playback type. Only use this for playing back a Vivox recording.
  • Returns: Returns the local id of the group that was just created, -1 if it has failed.

bool CreateSession(string uri, bool voice, bool text)

  • Summary: Create Session creates a request for a session of voice, text or both in the channels uri given. Sessions typically represent a connection to a media session with one or more participants. Used to generate an 'outbound' call to another user or channel. This method tries to make the request to the first group it can find and connects to the channel asked for. This means that you need a Group before you can successfully create a session connection. A session handle is required to control the local user functions within the session.
  • Parameters
    • uri: This is the URI of the terminating point of the session (i.e. who/what is being called).
    • voice: This flag is used to determine if the session is going to connect to audio or not.
    • text: This flag is used to determine if the session is going to connect to text or not.
  • Returns: Returns the session handle, -1 if it's unsuccessful.

int CreateSession(int group, string uri, bool voice, bool text)

  • Summary: Create Session creates a request for a session of voice, text or both in the channels uri given. Sessions typically represent a connection to a media session with one or more participants. Used to generate an 'outbound' call to another user or channel. This needs a Group before you can successfully create a session connection. A session handle is required to control the local user functions within the session. NOTE: For positional/spatial channels, one needs to set the position of where one is listening to. Call MoveToOrigin after successful creation to properly connect.
  • Parameters
    • group: The Session Groups that will contain the sessions.
    • uri: This is the URI of the terminating point of the session (i.e. who/what is being called).
    • voice: This flag is used to determine if the session is going to connect to audio or not.
    • text: This flag is used to determine if the session is going to connect to text or not.
  • Returns: Returns the session handle, -1 if it's unsuccessful.

int CreateSession(int group, string uri, bool voice, bool text, int font, string pw, int jitter)

  • Summary: Create Session creates a request for a session of voice, text or both in the channels uri given. Sessions typically represent a connection to a media session with one or more participants. Used to generate an 'outbound' call to another user or channel. This needs a Group before you can successfully create a session connection. A session handle is required to control the local user functions within the session. NOTE: For positional/spatial channels, one need to set the position of where one is listening to. Call MoveToOrigin after successful creation to properly connect.
  • Parameters
    • group: The Session Groups that will contain the sessions.
    • uri: This is the URI of the terminating point of the session (i.e. who/what is being called).
    • voice: This flag is used to determine if the session is going to connect to audio or not.
    • text: This flag is used to determine if the session is going to connect to text or not.
    • font: The ID of the voice font to apply to the session. DEFAULT_SESSION_FONT_ID = 0 (for none).** pw: This is the password used if the user is joining a password protected channel.
    • jitter: The jitter buffer compensation for this SIP session. Valid values are 1 - 150 ms. DEFAULT_JITTER_COMPENSATION = 0 (60 ms for Morpheus Sessions, 80 ms for P2P sessions).
  • Returns: Returns the session handle, -1 if it's unsuccessful.

void QuickConnection(string serverUrl, string user, string password, string uri, bool voice, bool text, bool spatial)

  • Summary: Quick Connection is used to make a connection in the background and allow the rest of the execution to continue. This just does the 4 steps, ConnectToServer(serverUrl), LogIn(user, password), CreateGroup(), CreateSession(group, uri, voice, text). If the channel is spatial it will make a call to MoveToOrigin(sess).
  • Parameters
    • serverUrl: This is the URL of the Account Management Server.
    • user: The username of the Vivox account to be signed into.
    • password: The password of the Vivox account to be signed into.
    • uri: This is the URI of the terminating point of the session (i.e. who/what is being called).
    • voice: This flag is used to determine if the session is going to connect to audio or not.
    • text: This flag is used to determine if the session is going to connect to text or not.
    • spatial: To ensure a position is given if spatial is set to true.

void QuickConnection(string serverUrl, string user, string password, string uri, bool voice, bool text, bool spatial, VastPark.Imml.Proxy.ImmlElement scriptProxy)

  • Summary: Quick Connection is used to make a connection in the background and allow the rest of the execution to continue. This just does the 4 steps, ConnectToServer(serverUrl), LogIn(user, password), CreateGroup(), CreateSession(group, uri, voice, text). If the channel is spatial it will make a call to MoveToOrigin(sess).
  • Parameters
    • serverUrl: This is the URL of the Account Management Server.
    • user: The username of the Vivox account to be signed into.
    • password: The password of the Vivox account to be signed into.
    • uri: This is the URI of the terminating point of the session (i.e. who/what is being called).
    • voice: This flag is used to determine if the session is going to connect to audio or not.
    • text: This flag is used to determine if the session is going to connect to text or not.
    • spatial: To ensure a position is given if spatial is set to true.
    • scriptProxy: It will call back the script given with the session handle in args.data.

void QuickConnection(string serverUrl, int minport, int maxport, string user, string password, string uri, bool voice, bool text, bool spatial)

  • Summary: Quick Connection is used to make a connection in the background and allow the rest of the execution to continue. This just does the 4 steps, ConnectServer(serverUrl, minport, maxport), LogIn(user, password), CreateGroup(), CreateSession(group, uri, voice, text). If the channel is spatial it will make a call to MoveToOrigin(sess).
  • Parameters
    • serverUrl: This is the URL of the Account Management Server.
    • minPort: The min port range to start looking for an open port.
    • maxPort: The max port range where to stop searching.
    • user: The username of the Vivox account to be signed into.
    • password: The password of the Vivox account to be signed into.
    • uri: This is the URI of the terminating point of the session (i.e. who/what is being called).
    • voice: This flag is used to determine if the session is going to connect to audio or not.
    • text: This flag is used to determine if the session is going to connect to text or not.
    • spatial: To ensure a position is given if spatial is set to true.

void QuickConnection(string serverUrl, int minport, int maxport, string user, string password, string uri, bool voice, bool text, bool spatial, VastPark.Imml.Proxy.ImmlElement scriptProxy)

  • Summary: Quick Connection is used to make a connection in the background and allow the rest of the execution to continue. This just does the 4 steps, ConnectServer(serverUrl, minport, maxport), LogIn(user, password), CreateGroup(), CreateSession(group, uri, voice, text). If the channel is spatial it will make a call to MoveToOrigin(sess).
  • Parameters
    • serverUrl: This is the URL of the Account Management Server.
    • minPort: The min port range to start looking for an open port.
    • maxPort: The max port range where to stop searching.
    • user: The username of the Vivox account to be signed into.
    • password: The password of the Vivox account to be signed into.
    • uri: This is the URI of the terminating point of the session (i.e. who/what is being called).
    • voice: This flag is used to determine if the session is going to connect to audio or not.
    • text: This flag is used to determine if the session is going to connect to text or not.
    • spatial: To ensure a position is given if spatial is set to true.
    • scriptProxy: It will call back the script given with the session handle in args.data.

void QuickAnonymousConnection(string serverUrl, string uri, bool voice, bool text, bool spatial)

  • Summary: Quick Connection is used to make a connection in the background and allow the rest of the execution to continue. This just does the 4 steps, ConnectToServer(serverUrl), AnonymousLogIn(), CreateGroup(), CreateSession(group, uri, voice, text). If the channel is spatial it will make a call to MoveToOrigin(sess).
  • Parameters
    • serverUrl: This is the URL of the Account Management Server.
    • uri: This is the URI of the terminating point of the session (i.e. who/what is being called).
    • voice: This flag is used to determine if the session is going to connect to audio or not.
    • text: This flag is used to determine if the session is going to connect to text or not.
    • spatial: To ensure a position is given if spatial is set to true.

void QuickAnonymousConnection(string serverUrl, string uri, bool voice, bool text, bool spatial, VastPark.Imml.Proxy.ImmlElement scriptProxy)

  • Summary: Quick Connection is used to make a connection in the background and allow the rest of the execution to continue. This just does the 4 steps, ConnectToServer(serverUrl), AnonymousLogIn(), CreateGroup(), CreateSession(group, uri, voice, text). If the channel is spatial it will make a call to MoveToOrigin(sess).
  • Parameters
    • serverUrl: This is the URL of the Account Management Server.
    • uri: This is the URI of the terminating point of the session (i.e. who/what is being called).
    • voice: This flag is used to determine if the session is going to connect to audio or not.
    • text: This flag is used to determine if the session is going to connect to text or not.
    • spatial: To ensure a position is given if spatial is set to true.
    • scriptProxy: It will call back the script given with the session handle in args.data.

void QuickAnonymousConnection(string serverUrl, int minPort, int maxport, string uri, bool voice, bool text, bool spatial)

  • Summary: Quick Connection is used to make a connection in the background and allow the rest of the execution to continue. This just does the 4 steps, ConnectServer(serverUrl, minport, maxport), AnonymousLogIn(), CreateGroup(), CreateSession(group, uri, voice, text). If the channel is spatial it will make a call to MoveToOrigin(sess).
  • Parameters
    • serverUrl: This is the URL of the Account Management Server.
    • minPort: The min port range to start looking for an open port.
    • maxPort: The max port range where to stop searching.
    • uri: This is the URI of the terminating point of the session (i.e. who/what is being called).
    • voice: This flag is used to determine if the session is going to connect to audio or not.
    • text: This flag is used to determine if the session is going to connect to text or not.
    • spatial: To ensure a position is given if spatial is set to true.

void QuickAnonymousConnection(string serverUrl, int minport, int maxport, string uri, bool voice, bool text, bool spatial, VastPark.Imml.Proxy.ImmlElement scriptProxy)

  • Summary: Quick Connection is used to make a connection in the background and allow the rest of the execution to continue. This just does the 4 steps, ConnectServer(serverUrl, minport, maxport), AnonymousLogIn(), CreateGroup(), CreateSession(group, uri, voice, text). If the channel is spatial it will make a call to MoveToOrigin(sess).
  • Parameters
    • serverUrl: This is the URL of the Account Management Server.
    • minPort: The min port range to start looking for an open port.
    • maxPort: The max port range where to stop searching.
    • uri: This is the URI of the terminating point of the session (i.e. who/what is being called).
    • voice: This flag is used to determine if the session is going to connect to audio or not.
    • text: This flag is used to determine if the session is going to connect to text or not.
    • spatial: To ensure a position is given if spatial is set to true.
    • scriptProxy: It will call back the script given with the session handle in args.data.

bool RemoveSession(int group, int sess)

  • Summary: Remove Session removes the session and the group you have specified. This mainly issues a request to disconnect the session.
  • Parameters
    • group: The group the session belongs to.
    • sess: The session that is about to remove.
  • Returns: Whether if it was successful or not.

bool RemoveGroup(int group)

  • Summary: RemoveGroup issues out a request that tries to remove group. It also should automatically disconnect you from any session that this group is holding.
  • Parameters
    • group: The group handle of the group to delete.
  • Returns: Whether if it was successful or not.

void RemoveAllSessions()

  • Summary: Goes through to all of the Groups and removes all sessions in each group. It requests each session to be removed inside the group.
  • Parameters

void RemoveAllSessionAndGroups()

  • Summary: This removes all the groups. In doing so, each session should be automatically be removed.
  • Parameters

bool LogOut()

  • Summary: This issues the requests to log out and waits for it to log out. (All Session Groups will be removed before logging out by the SDK)
  • Parameters
  • Returns: Returns whether it seems successful or not.

bool ServerDisconnect()

  • Summary: This issues to disconnect from the server and waits until that happens. (You will be logged out before disconnecting from server by the SDK)
  • Parameters
  • Returns: Returns whether it seems successful or not.

Vector3 GetPosition()

  • Summary: Gives a vector3 that shows the position of the where the listener is located.
  • Parameters
  • Returns: The listener position Vector3.

Vector3 GetRotation()

  • Summary: Gets the rotation of the person in a vector3 of how Vivox interprets the things (only y rotation is taken into account).
  • Parameters
  • Returns: The rotation (in degrees) as a Vector3 (just the y rotation is set).

int GetNumOustandingRequests()

  • Summary: Gives the number of requests that are still supposed to be done.
  • Parameters
  • Returns: The amount of outstanding requests the SDK has.

void MoveToOrigin(int sess)

  • Summary: Move to origin method is needed for the positional channels to orientate themselves, to get some voice going.
  • Parameters
    • sess: The session placed at the origin, in position (0, 0, 0). This allows sound in spatial channels.

bool Mute()

  • Summary: This issues a request to mute the local speaker.
  • Parameters
  • Returns: The request was submitted.

bool Unmute()

  • Summary: Issues out a request to remove mute the local speaker.
  • Parameters
  • Returns: Returns true if the request was successful.

bool SpeakerMute(bool status)

  • Summary: SpeakerMute issues out a request to mute the local speaker.
  • Parameters
    • status: Change the muting of the local speaker.
  • Returns: The request was submitted.

bool MicrophoneMute(bool status)

  • Summary: MicrophoneMute issues out the request of mute or not the local microphone.
  • Parameters
    • status: Change the status mute the speaker inside Vivox.
  • Returns: The request was submitted.

bool LocallyMuteUser(bool status, string user_uri)

  • Summary: LocallyMuteUser issues out the request of muting the user locally via user uri, in the current session that is connected to voice/media. This does not mute it for everybody, just for the person who requested it.
  • Parameters
    • status: Change the muting of the in the locally on user.
    • user_uri: The sip code of the user e.g. the user is example1 and he is in vpd.vivox.com server then its sip: (without api2).
  • Returns: The request was submitted.

bool LocallyMuteUser(int sess, bool status, string user_uri)

  • Summary: Locally Mute User requests the specified session where to locally mute the user specified. This is much quicker than the other LocallyMuteUser as it does not have to search for a connected session.
  • Parameters
    • sess: The session handle of the session you want to mute the user.
    • status: Change the muting of the in the locally on user.
    • user_uri: The sip code of the user e.g. the user is example1 and he is in vpd.vivox.com server then its sip: (without api2).
  • Returns: The request was submitted.

bool SetVolume(int vol)

  • Summary: SetVolume issues out a request for the volume of the Vivox speakers.
  • Parameters
    • vol: The value between 0 - 100
  • Returns: The request was submitted.

bool SetMicrophoneVolume(int vol)

  • Summary: SetMicrophoneVolume issues out a request for changing the microphone volume.
  • Parameters
    • vol: Change the volume between 0 - 100.
  • Returns: The request was submitted.

bool Update(Vector3 position)

  • Summary: Update issues out a request on the voice connection session to move the listening position of the person and speaker to the specified position of the character. This checks whether the invert sound is enabled and automatically inverts the x coordinate, and ignores it if the distance between the last update and this new one has changed more than the ignore step.
  • Parameters
    • position: The x, y, z coordinates vector3 position of the character.
  • Returns: The request was submitted.

bool Update(int sess, Vector3 position)

  • Summary: Update, updates the session passed in with the coordinates given by the vector3. If the sound needs to be inverted (make the x axis negative), it will send in the inverted coordinates, and it checks the distance between the previously updated point, and only updates of it difference in distance is greater than the distance ignore.
  • Parameters
    • sess: The target session that will be updated with this position.
    • position: What to change the position to.
  • Returns: Returns true if the request was successful.

bool Update(Vector3 position, Vector3 rotation)

  • Summary: This method issues out a single request that updates both location and rotation of the character. It first needs to finds an open connection channel and updates the new position and rotation if it bigger than the ignoring of distance or rotation. This also performs flipping for the rotation and inverting for the distance if they are enabled.
  • Parameters
    • position: What to change the position to.
    • rotation: The rotation of the character we are modelling.
  • Returns: Returns true if successful.

bool Update(int sess, Vector3 position, Vector3 rotation)

  • Summary: This method issues out a single request that updates both location and rotation of the character. It updates the session given to the new position and rotation if it bigger than the ignoring of distance or rotation. This also performs flipping for the rotation and inverting for the distance if they are enabled.
  • Parameters
    • sess: The target session that will be updated with this position.
    • position: What to change the position to.
    • rotation: What to change the rotation to.
  • Returns: The request was submitted.

bool UpdateRotation(Vector3 rotation)

  • Summary: The rotation updates needs to find a voice connection like the other updates. This just updates the rotation or the way the character is facing. It flips the sound if it is enabled and only updates the rotates if it is bigger than the ignore value specified.
  • Parameters
    • rotation: What to change the rotation to.
  • Returns: The request was submitted.

bool UpdateRotation(int sess, Vector3 rotation)

  • Summary: The rotation updates needs to find a voice connection like the other updates. This just updates the rotation or the way the character is facing. It flips the sound if it is enabled and only updates the rotates if it is bigger than the ignore value specified.
  • Parameters
    • sess: The target session that will be updated with this rotation.
    • rotation: The Vector3 rotation of the character.
  • Returns: Returns if it was successful or not.

void ChangeChannel(string uri, bool voice, bool text, bool spatial)

  • Summary: Change channel will connect you to another channel to talk and listen to. This is done in the background and will continue execution. This essentially calls RemoveAllSessionAndGroups(), CreateGroup(), CreateSession(group, uri, voice, text). It will call MoveToOrigin(sess) if the spatial is true.
  • Parameters
    • uri: This is the URI of the terminating point of the session (i.e. who/what is being called).
    • voice: This flag is used to determine if the session is going to connect to audio or not.
    • text: This flag is used to determine if the session is going to connect to text or not.
    • spatial: To ensure a position is given if spatial is set to true.