iOS Developer Library

Developer

GameKit Framework Reference GKVoiceChat Class Reference

Options
Deployment Target:

On This Page
Language:

GKVoiceChat

Inherits From


Conforms To


Import Statement


Swift

import GameKit

Objective-C

@import GameKit;

Availability


Available in iOS 4.1 and later

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 GameKit, 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 YEStrue. 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 setPlayer:muted: method to selectively mute other players in the channel.

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

  • Returns whether voice chat may be used on the device.

    Declaration

    Swift

    class func isVoIPAllowed() -> Bool

    Objective-C

    + (BOOL)isVoIPAllowed

    Return Value

    YEStrue 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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.1 and later

  • Starts communication with other participants in a channel.

    Declaration

    Swift

    func start()

    Objective-C

    - (void)start

    Discussion

    When start is called, the app first confirms that it has permission to use the microphone. If this is the first time that the app has tried to access the microphone, a pop-up queries the user for their permission to use voice chat. If the user declines permission, the active flag remains NOfalse and access is not granted.

    After permission is given by the user, 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 YEStrue, 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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • Ends communication with the channel.

    Declaration

    Swift

    func stop()

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • active active Property

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

    Declaration

    Swift

    var active: Bool

    Objective-C

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

    Discussion

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

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • A block that is called when a participant changes state.

    Declaration

    Swift

    var playerVoiceChatStateDidChangeHandler: ((GKPlayer!, GKVoiceChatPlayerState) -> Void)!

    Objective-C

    @property(copy, nonatomic) void (^playerVoiceChatStateDidChangeHandler)( GKPlayer *player, 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 GKPlayer object that identifies the player whose status changed.

    state

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

    Listing 1 shows an implementation of an update handler for the player state.

    Listing 1Receiving updates about the player
    • teamChat.playerVoiceChatStateDidChangeHandler = ^(GKPlayer *player, GKVoiceChatPlayerState state) {
    • switch (state)
    • {
    • case GKVoiceChatPlayerSpeaking:
    • // Insert code to highlight the player's picture.
    • break;
    • case GKVoiceChatPlayerSilent:
    • // Insert code to dim the player's picture.
    • break;
    • }
    • };

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later

  • A block that is called when a participant changes state.

    Declaration

    Swift

    var playerStateUpdateHandler: ((String!, GKVoiceChatPlayerState) -> Void)!

    Objective-C

    @property(copy, nonatomic) 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:

    playerID

    The player identifier for the player whose status changed.

    state

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.1 and later

    Deprecated in iOS 8.0

  • Mutes a participant in the chat.

    Declaration

    Swift

    func setMute(_ isMuted: Bool, forPlayer player: String!)

    Objective-C

    - (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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 5.0 and later

    Deprecated in iOS 8.0

  • Mutes a participant in the chat.

    Declaration

    Swift

    func setPlayer(_ player: GKPlayer!, muted isMuted: Bool)

    Objective-C

    - (void)setPlayer:(GKPlayer *)player muted:(BOOL)isMuted

    Parameters

    player

    The GKPlayer object identifying the player to be muted.

    isMuted

    Determines whether the player is to be muted or not.

    Discussion

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

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later

  • volume volume Property

    The volume level for the voice channel.

    Declaration

    Swift

    var volume: Float

    Objective-C

    @property(assign, nonatomic) 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.

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • name name Property

    The name of the voice chat (read-only)

    Declaration

    Swift

    var name: String! { get }

    Objective-C

    @property(readonly, copy, nonatomic) NSString *name

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later

  • players players Property

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

    Declaration

    Swift

    var players: [AnyObject]! { get }

    Objective-C

    @property(readonly, nonatomic) NSArray *players

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 8.0 and later

  • playerIDs playerIDs (iOS 8.0) Property

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

    Declaration

    Swift

    var playerIDs: [AnyObject]! { get }

    Objective-C

    @property(readonly, nonatomic) NSArray *playerIDs

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 5.0 and later

    Deprecated in iOS 8.0

Data Types

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

    Declaration

    Swift

    enum GKVoiceChatPlayerState : Int { case Connected case Disconnected case Speaking case Silent case Connecting }

    Objective-C

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

    Constants

    • Connected

      GKVoiceChatPlayerConnected

      The player connected to the channel.

      Available in iOS 4.0 and later

    • Disconnected

      GKVoiceChatPlayerDisconnected

      The player left the channel.

      Available in iOS 4.0 and later

    • Speaking

      GKVoiceChatPlayerSpeaking

      The player began speaking.

      Available in iOS 4.0 and later

    • Silent

      GKVoiceChatPlayerSilent

      The player stopped speaking.

      Available in iOS 4.0 and later

    • Connecting

      GKVoiceChatPlayerConnecting

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

      Available in iOS 6.0 and later

    Import Statement

    Objective-C

    @import GameKit;

    Swift

    import GameKit

    Availability

    Available in iOS 4.0 and later