Getting-Started

Installation

On this page, there are two parts that are essential for the voice chat application to work properly. the first is hosting the voice chat server. the second is adding the files in your unity game and setting up some variables.

First, import the asset to your game. This will add all the files needed to get you started.

Setting it up with your unity game

After importing the asset, the main script that you need to learn about and use will go by the name "VoiceChatHandler.cs", this script is singelton, so you can use it directly in any class you make.

Tip: just make sure to add this script on a gameobject for the first scene, this is preferable to ensure running "SingletonAwakened" when your game start. this function initializes the voicechat script that will be loaded on the webpage that host the game.

the important thing that will need to change on the script editor will be the modification of two variables in the.

public string socketServer = "/";
public string clientJSFileURL = "/";

The first variable should contain the link to your website "https://your-server-domain", for it is used to communicate with the websocket server.

The second varialbe will be the link to the js file that contains the voice chat logic that is going to be imported into the webpage by unity. this file is important so that unity can start communicating with the server.

the link for the file should go like this (https://your-server-domain/js/client.js)

Hosting the server

pre-requisites (for the hosting device): -

• npm
• node
• server running on HTTPS (required to get access to the mic, this is enforced from the browsers)

note: hosting the server on heroku provides an easier experince and the server comes with an ssl.

To begin with, the server can be found in "Assets/WebGLVoiceChat/VoiceChatServer.zip" from the imported asset, this zip includes the server that can be started using node js.

the link below shows how to host the server on heroku. However, you can host ther server on any platform of your choice. How to deploy to heroku

to run the server use

npm run prod

after setting up the server and hosting it, accessing the main page of the website will be empty but the server is being hosted.

you can also check the demo here.

Allow Two way communitcation

starting from the update 0.7.0 the voice chat handler asset now uses two way communication. so the browser needs to have access to the unity instance.

in order to do this you need to modify the index.html file that comes with the webgl build where this line needs to be added

How The voice chat starts

After adding the unity files to your game and providing the required URLs, you will have access to all the functionality of the voice chat library. However, none of them will be functional in the editor, for the functionality itself is executed on the browser with JavaScript.

the way it works is that when the game loads, the VCH (VoiceChatHandler) will instantiate itself (if used) and stay persistent throughout the game. On Start, the class will use the provided URLs from the class (in the editor) to do two things.

the first URL will be used as the domain to connect to the voice chat server, and the other URL will be the location of the voice chat script which will be used to append the script to the current HTML page by unity.

when the file loads, the class will be ready to be used.

Admin Panel

Since update 0.8.0, there is an admin panel for the running server that can be accessed through "your-domain-name/Admin" e.g "localhost/Admin" the "A" in "Admin" is case sensitive.

once you enter the page, you should fill these three parameters

the first two should be somehting similar to the image above (the server url will change based on where it is hosted).

the password is defined from the server code, and should be chnaged from it

the image above showcases where the password can be changed. this code section can be found in the "index.js" file in the server zip.

the password should be encrypted with bcrypt and then inserted in the password property as in the picture above.

you can use a website like bcrypt-generator which will encrypt your password with the needed algorithm.

to learn more about the admin panel you can visit this link.

Home

Unity Webgl Voice Chat Solution

Welcome to the Docs of the Webgl Voice Chat Solution

this Documentation is meant to explain the mechanism of how does the software work, document it's functions and help you getting started.

to get started check the getting started page.

---

to learn more about the functions and functionality of the solution check the docs section

How it works

in simple terms, the voice chat is a separate application that runs on your browser. the twist is that scripts were written in unity, allowing communication between unity and the voice chat application itself (the js file from the server).

so unity communicates with it while the application handles rooms, and people, and fetches the voice from the microphone with transmission over the network, etc... .

the reason it was built this way is that the in-availability of access to the mic in unity for WebGL, alongside the limitation of only TCP/HTTP protocol on the browser prevents the development of a functional voice chat within the unity game on the browser and thus the current solution.

JavaScript-API-Documentation

VoiceChat Class

constructor

instantiate the class

var voiceChat = new VoiceChat();

Events

Nan

Attributes

voiceChat.io

contains the socket io connection of the current client. learn more here.

voiceChat.hark

contains an instance of hark (used for speech detection). learn more here.

voiceChat.isMute

the mute status of the current client.

voiceChat.rooms

contains a list of the current room(s) the client is connected to.

voiceChat.muteList

contains a list of the other clients the current client has muted locally.

voiceChat.timeInterval

the interval time used between recordings to be sent through the network.

voiceChat.tmpClientsInRoom

this is a temporary variable for storing the clients id of a requested specfic room and is only relevant when the function is called.

voiceChat.UnityInstance

this will be set by exposing the unity instance after it's creation in the window variable to enable access in this class.

it is used to allow communtication from the browser to Unity game build.

voiceChat.MicrohphoneManager

this is the microphone manager component / class that will take care of managing the microphone stream and change of the microphone

voiceChat.ChatManager

this is the Chat manager component / class that will take care of sending / receiving messages for the room/s the player is in.

---

Methods

Internal Functions (private)

the below functions are internally used within the class itself and does not need to be called.

voiceChat.Chat()

starts the voice stream and sends it to the server (only needs to run once, automatically runs with the constructor).

voiceChat.EmitVoice(ArrayBuffer)

will take an array buffer (base64 encoded audio) and emit it to the socket server, the socket server has a list of the rooms the player is in.

voiceChat.RecordAudio(MediaStream)

this function takes a mediaStream source starts the recording loop and returns an ArrayBuffer.

voiceChat.InitHark(MediaStream)

this function takes a MediaStream and initializes hark with it alongside registering speech detection events.

---

External Functions (public)

the below functions are meant to be used externally by other scripts.

voiceChat.IsSpeaking()

returns a boolean of whether the current client is speaking or not.

voiceChat.GetMySocketID()

returns a string of the current client socket id

voiceChat.SetMute(boolean)

takes a boolean to mute/unmute the current client from others

voiceChat.IsOtherClientMuted(string clientID)

takes a string of another client ID and checks it they are muted by the local client (local mute)

voiceChat.MuteClient(string clientID)

takes a string of another client ID and mutes them locally for the current client

voiceChat.UnmuteClient(string clientID)

takes a string of another client ID and unmutes them locally for the current client

voiceChat.UnmuteAllClients()

unmutes them locally for the current client

voiceChat.GetRooms()

returns a list of all the rooms the current user is currently at.

voiceChat.GetClientsInRoom(string roomID)

returns a list of all clients in the provided room.

voiceChat.JoinRoom(string roomID)

takes a room id and create/join the current user to the room id provided.

voiceChat.LeaveRoom(string roomID)

takes a room id and disconnects the current user from the room id provided if they are in that room.

voiceChat.LeaveAllRooms()

disconnects the current user from all the rooms they have joined.

---

Microphone Class

Constructor

this.MicrohphoneManager = new Microhphone(voiceChatInstance);

the constructor takes an instance of the voice chat class

Events

streamAvailable

this event will be triggerd whenever a stream is ready / changed and will send the stream as a parameter

Attributes

Microhphone.voiceChat

a refrence of the voicechat instance

Microhphone.localStream

a refrence of the current localStream (microphone stream)

Microhphone.microhphonesList

stores a list of the available devices of type "audioinput" so that the user/player can use it to switch / pick one to be used/changed with.

Microhphone.isPermited

stores a refrence of whethere the player/user have access to the microphone

---

Methods

CanAccessMicrophone()

this function returns a promise with a boolean of whethere is the user is permmited to access the microphone.

GetAvailableMicrophones()

returns a promise with a list of all the available audioinput devices

Promise<MediaDeviceInfo[]> 

HandleMicrophoneChange(stream, microphoneId)

changes the currently used stream. takes the current stream if available and the new audioinput device id as params and closes the current stream tracks than replace the current stream with the new one by the provided device id.

GetLocalStream()

fetches the current stream from the user using the default audioinput device set by the OS.

---

ChatManager Class

Constructor

this.ChatManager = new ChatManager(voiceChatInstance);

the constructor takes an instance of the voice chat class

Events

Nan

Attributes

Nan

Methods

SendMessage(message)

this funcition takes a string as a parameter for the message and emits it to the room/s the player is in.

OnUpdateChatHandler(message, clientID)

this fucntion takes two parameters, the message and the client id whom sent the message then sends it back to the unity instance. the function will work whenever a new message recived from the another client.

Unity-API-Documentation

VoiceChatHandler

this class is a singleton that can be used anywhere in a unity game project which handles communication with the voice chat instance of JavaScript in the browser, this is how the Singleton was achieved in unity with mono behavior functionality, here.

Attributes

socketServer

public string socketServer

This is going to be the variable that will hold the socket server URL which is going to be used in the build to connect the socket server

---

clientJSFileURL

public string clientJSFileURL

the URL link to the client js file that contains the voice chat logic for the browser. This will be used to append the code from the URL to the current page the game is hosted on.

---

clientsInCurrentRoom

private List<string> clientsInCurrentRoom

holds the list of of clients in the current joined room. (will be updated automatically from the browser).

---

availableMicrophones

private List<Microphone> availableMicrophones

stores a list of the availabe microphones

---

isSpeaking

private bool isSpeaking

an indicator of whether the client is speaking or not. (will be updated automatically from the browser).

---

Events

OnClientsInRoom

public UnityEvent<List<string>> OnClientsInRoom

this event will be triggered when the browser sends back the list of clients in the room

Returns

List<string>

---

onIsSpeaking

public UnityEvent<bool> onIsSpeaking

when invoked, returns a string of a JSON with the status of whether is the current client is talking or not.

tip: this value can be used with other networking framework solutions(mirror, fishnet, smartfox, etc...) to send the player status to other in-game players.

Returns

bool

---

OnAvailableMicrophones

public UnityEvent<List<Microphone>> OnAvailableMicrophones

this event is triggered when the browser sends back a list of available microphones (audioinput)

Returns

List<Microphone>

---

OnCanAccessMicrophone

public UnityEvent<bool> OnCanAccessMicrophone

this event is triggered when the browser sends back a response for whethere if you the player/user have provided access to the voice chat script.

Returns

bool

---

OnMessageReceived

public UnityEvent<string,string> OnMessageReceived

this event is triggered when the browser sends back a response with a message received. th first parameter represents the clientID who sent the message and the second parameter represents the actual message itself.

Returns

<string, string>

---

Methods

Public Methods

GetMySocketID()

public string GetMySocketID()

this function returns a string of the current client socket-io id which can be used directly as a string

e.g: -

"w2YTHXzcN2fJCuROAAAB"

Returns

string

---

IsVoiceChatReady()

public string IsVoiceChatReady()

this function returns a string of whether the voice chat browser app is ready to be used or not

e.g: -

"yes" or "no"

Returns

string

---

MuteMic()

public void MuteMic()

this function mutes your mic.

---

UnMuteMic()

public void UnMuteMic()

this function unmutes your mic.

---

IsMute()

public bool IsMute()

this function returns a bool indicating whether if the mic is mute or not

Returns

bool

---

SetIsSpeaking(string isSpeaking)

public void SetIsSpeaking(string isSpeaking)

sets the is speaking paramater and invokes the onIsSpeaking event. (the browser will update the list using the function)

---

IsSpeaking()

public bool IsSpeaking()

this function returns bool of whether the current user is speaking or not regardless of whether the mic is mute or not

Returns

bool

---

GetAvailableMicrophones()

public void GetAvailableMicrophones()

sends a request to the browser the fetch all the available microphones. the resoponse is sent back to "SetAvailableMicrophones()" function.

---

SetAvailableMicrophones()

public void SetAvailableMicrophones(string microphonesJson)

this funcition is called by the browser which sends back the list of microphones fetched.

the function itself populates "availableMicrophones" variable and triggers the "OnAvailableMicrophones" event, sending the list to whatever function is listening to it.

---

SetCurrentMicrophone()

public void SetCurrentMicrophone(Microphone microphone)

this function sends a request to the browser to change the currently used microphone from the browser. it takes a "VoiceChatSolution.Microphone" struct as a parameter.

---

CanAccessMicrophone()

public void CanAccessMicrophone()

sends a request to the browser about whether the browser has access to the microphone or not. the resoponse is set back in "CanAccessMicrophoneResponse" function.

---

CanAccessMicrophoneResponse()

public void CanAccessMicrophoneResponse(string canAccess)

this function is called by the browser where it is provided with an object that holds a boolean of whether the browser has access or not.

this function also triggers "OnCanAccessMicrophone" event sending the result back to whatever function is listening to it.

---

GetRooms()

public List<string> GetRooms()

this function returns a list of strings of the rooms the player is currently joined in.

furthermore, it refreshes the list of rooms. the new list of rooms is then set by browser through "SetRooms" function.

Returns

List<string>

---

SetRooms(string roomsJson)

public void SetRooms(string roomsJson)

sets the list of the rooms the client is in.

---

UpdateClientsInRoom(string roomID)

public void UpdateClientsInRoom(string roomID)

the function runs a process where it fetches the clients in a specified room, than the browser will update the list using "SetClientsInRoom" function

---

SetClientsInRoom(string clients)

public void SetClientsInRoom(string clients)

sets the list of clients in the current room the user/player is in. (the browser will excute this function)

the event "OnClientsInRoom" is triggered with list of the clients.

---

JoinRoom(string roomID)

public void JoinRoom(string roomID)

the function joins/creates and joins the player in the voice chat room

---

JoinOneRoom(string roomID)

public void JoinOneRoom(string roomID)

same as the one above but it makes sure that you leave rooms before joining the given one

---

LeaveRoom(string roomID)

public void LeaveRoom(string roomID)

disconnects the client from the room id given

---

LeaveAllRooms(string roomID)

public void LeaveAllRooms()

disconnects the client from all the rooms they are connected to.

---

MuteOtherClient(string clientID)

public void MuteOtherClient(string clientID)

locally mutes another client for the current client.

---

UnMuteOtherClient(string clientID)

public void UnMuteOtherClient(string clientID)

locally unmutes another client for the current client.

---

UnMuteAllClients(string clientID)

public void UnMuteAllClients()

locally unmutes all muted clients for the current client.

---

IsOtherClientMuted(string clientID)

public bool IsOtherClientMuted(string clientID)

this function returns a bool indicating whether if the provided client is muted locally or not by the current user.

Returns

bool

---

GetMuteList()

public List<string> GetMuteList()

returns a list of strings of all the locally muted other clients

Returns

List<string>

---

SendChatMessage(string message)

public void SendChatMessage(string message)

takes a string as the message and sends it to the browser to be sent to other clients of the same room.

---

ReceiveChatMessage(string jsonMessage)

public void ReceiveChatMessage(string jsonMessage)

this function is it triggerd by the browser which sends any message that is intended for the current client / player.

this function also triggers the "OnMessageReceived" event sending the data to whatever function is listening to it.

---

---

Structures

Microphone

public struct Microphone
{
    public string deviceId;
    public string kind;
    public string label;
    public string groupId;
}

this structure is used to allocate the microphone meta data within the VoiceChatHandler Script.