GKVoiceChat Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/GameKit.framework
Availability
Available in iOS 4.1 and later.
Companion guide
Game Center Programming Guide
Declared in
GKVoiceChat.h

Overview

A GKVoiceChat object provides a voice channel that allows a set of players in a match to speak with each other.

In an iOS game, before you can use voice chat, your game must configure an audio session that allows for both play and recording (kAudioSessionCategory_PlayAndRecord). For more information on audio sessions, see Audio Session Programming Guide.

You use the GKMatch object to create a voice chat channel by calling its voiceChatWithName: method, passing in a string that identifies the name of the channel you want to join. The name is never displayed by Game Kit, and you are free to name the channels however you like. You can create multiple channels for the same match. For example, if the match has multiple teams, you might create a separate channel for each team, and an additional channel that holds all of the players in the match.

To connect a player to a channel, call the voice chat object’s start method. After a channel is started, it receives voice data from other players already in the channel. To allow the player to speak in a channel, set the voice chat object’s active property to YES. A player can listen to multiple channels simultaneously but may only speak on one channel at any given time.

Your game uses the volume property to set the volume level for an entire channel, and the setMute:forPlayer: method to selectively mute other players in the channel.

If there is insufficient bandwidth over wi-fi to maintain a voice chat, Game Kit may disconnect individual players from the channel or disband the channel entirely.

Tasks

Determining Whether Voice Chat Is Available

Starting and Stopping Voice Chat

Transmitting to Other Players

Receiving Updates About Other Participants

Controlling Chat Volume

Channel Properties

Properties

active

A Boolean value that states whether the channel is sampling the microphone.

@property(nonatomic, assign, getter=isActive) BOOL active
Discussion

When active is YES, the voice chat samples the microphone and transmits the voice data to other players connected to the channel. Default value is NO.

Only one GKVoiceChat object is allowed to sample the microphone at any given time. When your game sets the active property to YES on a voice chat object, the previous voice chat object that owned the microphone (if there was one) sets its active property to NO.

Availability
  • Available in iOS 4.1 and later.
Declared In
GKVoiceChat.h

name

The name of the voice chat (read-only)

@property(nonatomic, readonly) NSString *name
Availability
  • Available in iOS 4.1 and later.
Declared In
GKVoiceChat.h

playerIDs

An array of player identifiers for the players connected to the channel. (read-only)

@property(nonatomic, readonly) NSArray *playerIDs
Availability
  • Available in iOS 5.0 and later.
Declared In
GKVoiceChat.h

playerStateUpdateHandler

A block that is called when a participant changes state.

@property(nonatomic, copy) void(^playerStateUpdateHandler)(NSString *playerID, GKVoiceChatPlayerState state)
Discussion

Your game sets this property with a block to be called when the state of any participant in the chat changes (including the local player). The block receives the following parameters:

player

The player identifier for the player whose status changed.

state

The new state of the player. See Player Voice Chat States.

Availability
  • Available in iOS 4.1 and later.
Declared In
GKVoiceChat.h

volume

The volume level for the voice channel.

@property(nonatomic, assign) float volume
Discussion

All voice data received from other participants is mixed and then scaled by the volume property. The volume property has a range between 0.0 and 1.0, inclusive. A volume level of 0.0 means the entire channel is muted; a value of 1.0 plays voice samples at full volume. The default value is 1.0.

Availability
  • Available in iOS 4.1 and later.
Declared In
GKVoiceChat.h

Class Methods

isVoIPAllowed

Returns whether voice chat may be used on the device.

+ (BOOL)isVoIPAllowed
Return Value

YES if voice chat is available to the game.

Discussion

Some countries or phone carriers may restrict the availability of voice over IP services. Before creating a GKVoiceChat object, your game should first check to see whether voice over IP is permitted on the device.

Availability
  • Available in iOS 4.1 and later.
Declared In
GKVoiceChat.h

Instance Methods

setMute:forPlayer:

Mutes a participant in the chat.

- (void)setMute:(BOOL)isMuted forPlayer:(NSString *)player
Parameters
isMuted

Determines whether the player is to be muted or not.

player

The player identifier string for a player in the match.

Discussion

When a player is muted, the local player does not hear voice data transmitted by that player.

Availability
  • Available in iOS 4.1 and later.
Declared In
GKVoiceChat.h

start

Starts communication with other participants in a channel.

- (void)start
Discussion

When start is called, the voice chat object connects to the channel and notifies other players connected to the channel that the local player joined the chat. While connected, voice data from other players is played automatically. If the player is connected to the channel and the voice chat object’s active property is YES, then the microphone is sampled and the data sent to the channel.

A device only connects to a channel when the device has a microphone and is connected via wi-fi. However, your game may configure and start a voice chat channel when the device is not currently capable of using voice chat. If conditions change to allow voice chat—for example, the device connects to a wi-fi network—the GKVoiceChat object then automatically connects to the channel.

Availability
  • Available in iOS 4.1 and later.
See Also
Declared In
GKVoiceChat.h

stop

Ends communication with the channel.

- (void)stop
Discussion

When stop is called, the voice chat object disconnects from the channel. You should call stop on a channel before the voice chat object is disposed.

Availability
  • Available in iOS 4.1 and later.
See Also
Declared In
GKVoiceChat.h

Constants

Player Voice Chat States

The states returned to your game about other players in a voice chat.

enum {
   GKVoiceChatPlayerConnected,
   GKVoiceChatPlayerDisconnected,
   GKVoiceChatPlayerSpeaking,
   GKVoiceChatPlayerSilent,
   GKVoiceChatPlayerConnecting
};
typedef NSInteger GKVoiceChatPlayerState;
Constants
GKVoiceChatPlayerConnected

The player connected to the channel.

Available in iOS 4.1 and later.

Declared in GKVoiceChat.h.

GKVoiceChatPlayerDisconnected

The player left the channel.

Available in iOS 4.1 and later.

Declared in GKVoiceChat.h.

GKVoiceChatPlayerSpeaking

The player began speaking.

Available in iOS 4.1 and later.

Declared in GKVoiceChat.h.

GKVoiceChatPlayerSilent

The player stopped speaking.

Available in iOS 4.1 and later.

Declared in GKVoiceChat.h.

GKVoiceChatPlayerConnecting

The player is connecting to the channel, but is not yet connected.

Available in iOS 6.0 and later.

Declared in GKVoiceChat.h.

Availability
  • Available in iOS 4.1 and later.
Declared In
GKVoiceChat.h


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)

Did this document help you? Yes It's good, but... Not helpful...