In-Game Voice

A GKVoiceChatService object allows your application to easily create a voice chat between two iPhones, as shown in Figure 1. The voice chat service samples the microphone and plays audio received from the other participant. In-game voice relies on your application to provide a client that implements the GKVoiceChatClient protocol. The primary responsibility of the client is to connect the two participants together so that the voice chat service can exchange configuration data.

Configuring a Voice Chat

Participant Identifiers

Each participant in a voice chat is identified by a unique participant identifier string provided by your client. The format and meaning of a participant identifier string is left to your client to decide.

Discovering other Participants

The voice chat service uses the client’s network connection to exchange configuration data between the participants in order to create its direct connection between the two. However, the voice chat service does not provide a mechanism to discover the participant identifier of other participants. Your application is responsible for providing the participant identifiers of other users and translating these identifiers into connections to other participants.

For example, if your application is already connected to another device through a GKSession object (see ‚ÄúPeer to Peer Connectivity‚Äù), then each peer on the network is already uniquely identified by a peerID string. The session already knows the peerID string of the other participant. The client could reuse each peer‚Äôs ID as the participant identifier and use the session to send and receive data, as shown in Figure 2

If the two devices are not directly aware of each other, your application needs another service to allow the two participants to discover each other and connect. In Figure 3, the server identifies participants with their email addresses and can route data between them.

Depending on the design of the server, it may either provide the list of participant identifiers to the clients or the user may need to provide the participant identifier (email address) of another user. In either case, the server is an intermediary that transmits data between the two users.

When the voice chat service wants to send its configuration data to another participant, it calls the client‚Äôs voiceChatService:sendData:toParticipantID: method. The client must be able to reliably and promptly send the data to the other participant. When the other client receives the data, it forwards it to the service by calling the service‚Äôs receivedData:fromParticipantID: method. The voice chat service uses this connection to configure its own real-time network connection between the two participants. The voice chat service uses the client‚Äôs connection only to create its own connection.

Real-time Data Transfer

Occasionally, a firewall or NAT-based network may prevent the voice chat service from establishing its own network connection. Your application can implement an optional method in the client to provide real-time transfer of data between the participants. When your client implements the voiceChatService:sendRealTimeData:toParticipantID: method, if the voice chat service is unable to create its own real-time connection, it falls back and calls your method to transfer its data.

Starting a Chat

To start a voice chat, one of the participants calls the voice chat service‚Äôs startVoiceChatWithParticipantID:error: method with the participantID of another participant. The service uses the client‚Äôs network as described above to request a new chat.

When a service receives a connection request, the client‚Äôs voiceChatService:didReceiveInvitationFromParticipantID:callID: method is called to handle it. The client accepts the chat request by calling the service‚Äôs acceptCallID:error: method, or rejects it by calling denyCallID:. Your application may wish to prompt users to see if they want to accept the connection.

Once a connection has been established and accepted, the client receives a call to its voiceChatService:didStartWithParticipantID: method.

Disconnecting from Another Participant

Your application calls the service‚Äôs stopVoiceChatWithParticipantID: method to end a voice chat. Your application should also stop the chat if it discovers that the other user is no longer available.

Controlling the Chat

Once the participants are connected, speech is automatically transmitted between the two iPhones. Your application can mute the local microphone by setting the service‚Äôs microphoneMuted property, and it can adjust the volume of the remote participant by setting the service‚Äôs remoteParticipantVolume property.

Your application can also enable monitoring of the volume level at either end of the connection. For example, you might use this to set an indicator in your user interface when a participant is talking. For local users, your application sets inputMeteringEnabled to YES to enable the meter, and reads the inputMeterLevel property to retrieve microphone data. Similarly, your application can monitor the other participant by setting outputMeteringEnabled to YES and reading the outputMeterLevel property. To improve application performance, your application should only enable metering when it expects to read the meter levels of the two participants.

---