Class

CHHapticEngine

An object that manages your app's requests to play haptic patterns.

Declaration

class CHHapticEngine : NSObject

Overview

If you want your app to play custom haptics, you need to create a haptic engine. The haptic engine establishes the connection between your app and the underlying device hardware. Even though you can define a haptic pattern without an engine, you need the engine to play that pattern.

A dictionary defines a pattern, from which the haptic engine creates a pattern player for playing the haptic.

Even though your app makes a request through the haptic engine, the operating system could still override the request with system services, like haptics from system notifications.

Prepare Your App To Play Haptics

To prepare your app to play haptics, follow these steps, as demonstrated in the code below:

  1. Create an instance of a haptic engine and maintain ownership through an instance variable or strong property, so it doesn't go out of scope while the haptic is playing.

  2. Call the haptic engine's start(completionHandler:) for an asynchronous start, or start() to start the engine synchronously (immediately).

  3. Stop the engine by calling stop(completionHandler:) when your app finishes haptic playback.

do {
    // (1.) Create an instance of a haptic engine.
    hapticEngine = try CHHapticEngine()

    // (2.) Start the haptic engine.
    try self.hapticEngine.start()
} catch let error {
    print("Engine Error: \(error)")
}

// (3.) Stop the engine.
self.hapticEngine.stop(completionHandler: { (_) -> Void in
    // Insert code to call after engine stops.
})

Although it's possible to create content—CHHapticPattern instances—independent of a CHHapticEngine, your app must use an engine to play that content.

Topics

Initializing a Haptic Engine

init()

Creates an instance of the haptic engine.

init(audioSession: AVAudioSession?)

Creates a haptic engine from an audio session.

Starting and Stopping the Haptic Engine

func start()

Synchronously starts the haptic engine.

func start(completionHandler: CHHapticEngine.CompletionHandler?)

Asynchronously starts the haptic engine and executes the completion handler once the engine has started.

func stop(completionHandler: CHHapticEngine.CompletionHandler?)

Asynchronously stops the haptic engine and executes the completion handler once the engine has stopped.

typealias CHHapticEngine.CompletionHandler

A typealias for the block that the engine calls after starting or stopping.

Creating Haptic Pattern Players

Factory methods for creating player objects for haptic playback.

protocol CHHapticPatternPlayer

A protocol that defines a standard pattern player capable of playing haptic patterns with fixed parameters.

func makePlayer(with: CHHapticPattern) -> CHHapticPatternPlayer

Creates a standard haptic pattern player from a haptic pattern.

protocol CHHapticAdvancedPatternPlayer

A protocol that defines an advanced pattern player capable of looping, seeking, pausing, and resuming haptic playback.

func makeAdvancedPlayer(with: CHHapticPattern) -> CHHapticAdvancedPatternPlayer

Creates an advanced haptic pattern player from a haptic pattern.

Modifying Playback Properties

var playsHapticsOnly: Bool

A Boolean that indicates whether the haptic engine ignores audio events.

var isMutedForAudio: Bool

A Boolean that indicates whether audio is muted for the haptic engine.

var isMutedForHaptics: Bool

A Boolean that indicates whether haptics is muted for the haptic engine.

Playing a Pattern

func playPattern(from: URL)

Plays a plist pattern from the specified URL.

func playPattern(from: Data)

Plays a plist pattern from the specified data.

Registering Audio Resources

func registerAudioResource(URL, options: [AnyHashable : Any]) -> CHHapticAudioResourceID

Registers an external audio file for use as a custom waveform.

func unregisterAudioResource(CHHapticAudioResourceID)

Unregisters a previously registered external audio file.

typealias CHHapticAudioResourceID

A type alias used to register an ID for a custom audio resource.

Monitoring Finished Playback

func notifyWhenPlayersFinished(finishedHandler: CHHapticEngine.FinishedHandler)

Notifies you when all haptic pattern players have finished playing their haptic patterns.

typealias CHHapticEngine.FinishedHandler

A type alias for a completion handler to execute after finishing haptic playback.

enum CHHapticEngine.FinishedAction

Possible actions to take after the haptic engine finishes execution.

Handling Haptic Engine Resets

var resetHandler: CHHapticEngine.ResetHandler

A block that the haptic engine calls after recovering from a haptic server error.

typealias CHHapticEngine.ResetHandler

A typealias for the block that the haptic engine calls after being reset.

Handling Haptic Engine Stoppages

var stoppedHandler: CHHapticEngine.StoppedHandler

A block that the haptic engine calls when it stops due to external causes.

typealias CHHapticEngine.StoppedHandler

A typealias for the block that the haptic engine calls after it stops due to external causes.

enum CHHapticEngine.StoppedReason

An enumeration of possible reasons the haptic engine stopped running.

Getting the Current Media Time

var currentTime: TimeInterval

The absolute time, in seconds, to use for scheduling haptic and audio events.

var CHHapticTimeImmediate: TimeInterval

A time constant used to schedule a command immediately.

Querying System Capabilities

class func capabilitiesForHardware() -> CHHapticDeviceCapability

Returns a device capability object that specifies the device's haptic support and limitations.

protocol CHHapticDeviceCapability

A protocol that defines haptics and audio capabilities of a device.

protocol CHHapticParameterAttributes

A protocol for providing default, mininum, and maximum values of a parameter.

func attributes(forDynamicParameter: CHHapticDynamicParameter.ID) -> CHHapticParameterAttributes

Requests the haptic device's attributes for a dynamic parameter.

Required.

Managing Power

var isAutoShutdownEnabled: Bool

Opt in for auto start and auto stop.

Relationships

Inherits From

Conforms To

See Also

Essentials

Preparing Your App to Play Haptics

Set up your app to play haptics.

Playing a Single-Tap Haptic Pattern

Create and play a transient haptic pattern from a dictionary literal inline.

class CHHapticPattern

An object representing a haptic waveform.