Link Search Menu Expand Document

Playing Haptic Clips

Haptic clips are created with either the Studio desktop app or the Studio web app. A haptic clip contains high-definition, device-agnostic haptic data that the Studio framework for iOS uses to create an optimal haptic effect on playback devices. The playback of these haptic clips requires only three simple steps:

  1. Load the haptic clip into the LofeltHaptics object with the load() method.
  2. Start playback of the haptic clip with the play() method.
  3. Stop playback of the haptic clip with the stop() method (which is only needed when you wish to stop the haptic clip before it has finished playing).

Checking if device meets haptic requirements

func deviceMeetsMinimumRequirements() -> Bool

The deviceMeetsMinimumRequirements() method allows you to easily check if the iOS device meets the minimum requirements to playback haptics designed with Lofelt Studio. At the moment, the iOS minimum requirements are: - iOS 13+ - iPhone 8 or newer

Load

func load(data: String) throws

The load() method allows you to load the contents of a haptic clip into memory before triggering playback with play(). This preloading procedure is crucial for achieving tight synchronization between a haptic clip and its associated audio sample.

Play

func play() throws

The play() method initiates haptic playback of the haptic clip currently loaded into the LofeltHaptics instance.

Playback of the haptic effect always starts from the beginning of the haptic clip and automatically stops when playback reaches the end of the haptic clip. However, you can stop playback of the haptic effect prematurely with the stop() method.

Stop

func stop() throws

If the LofeltHaptics object is currently playing a haptic clip, the stop() method terminates playback. If a haptic clip is not playing, the stop() method will have no effect.

Using the stop() method leaves the currently loaded haptic clip in memory. A subsequent play() method will play the same haptic clip again starting from the beginning.

Seek

func seek(time: float) throws

Once a haptic clip has been loaded with load(), the seek() method moves playback to the given time position within the haptic. The playback state (playing or stopped) will not be changed unless seeking beyond the end of the haptic clip which will stop playback. Seeking to a position before the start of the clip (a negative time position) will simply move playback to the start of the clip leaving the playback state unchanged.

Clip duration

func getClipDuration() -> float

Once a haptic clip has been loaded with load(), it is possible to get its duration in seconds. If no clip is loaded and getClipDuration is called, the returned value will be 0.0.

Code Examples

Play haptic with audio

let haptics = try? LofeltHaptics.init()

// Fetch a Haptic Clip from the asset catalog.
let hapticClip = NSDataAsset(name: "haptic_clip.haptic")

// Load its data into an NSString.
let hapticData = NSString(data: hapticClip!.data , encoding: String.Encoding.utf8.rawValue)

// Load it into the LofeltHaptics object as a String.
try? haptics.load(hapticData! as String)

// Play audio and haptics (audio must be played first).
audioPlayer?.play()
haptics?.play()

Where:

  • hapticData is of type String and is the contents of a haptic clip created with Studio.
  • audioPlayer is some kind of audio player, for example, AVAudioPlayer.

It is important to play the audio before the haptic effect for optimal audio/haptic synchronicity.

Seek to a position in haptic

let haptics = try? LofeltHaptics.init()

// Fetch a Haptic Clip from the asset catalog.
let hapticClip = NSDataAsset(name: "haptic_clip.haptic")

// Load its data into an NSString.
let hapticData = NSString(data: hapticClip!.data , encoding: String.Encoding.utf8.rawValue)

// Load it into the LofeltHaptics object as a String.
try? haptics.load(hapticData! as String)

haptics?.play()

try! haptics.seek(1.0)

Where:

  • hapticData is of type String and is the contents of a haptic clip created with Studio.

Example Project

In thesdk/examples/ios folder within the Lofelt Studio download, there is an example project for playing haptic clips on iPhone called LofeltHapticsExamplePreAuthored. To run the example, open the project in Xcode, target your iPhone, and build. The example provides two buttons that, when pressed and released, will trigger audio files and accompanying haptic clips.

< Prev Next >


Copyright © 2020-2021 Lofelt GmbH. All rights reserved.