Playing Haptic Clips
🔥NOTE: The Studio library for Android is currently in beta and under development. Information on this page is subject to change.
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 library for Android uses to create an optimal haptic effect on playback devices. The playback of these haptic clips requires only three simple steps:
- Load the haptic clip into the
LofeltHaptics
object with theload()
method. - Start playback of the haptic clip with the
play()
method. - 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
public boolean deviceMeetsMinimumRequirements()
The deviceMeetsMinimumRequirements()
method allows you to easily check if the Android device meets the minimum requirements to playback haptics designed with Lofelt Studio. At the moment, the Android minimum requirements are:
- The device allows access to the hardware vibrator
- The device has amplitude control capability.
It will return true
if minimum requirements are met, or false
otherwise.
If the device does not the minimum requirements, play()
will throw an exception (see below). You can therefore bypass haptic calls in your application if the device doesn’t support the needed haptic abilities.
Load
public void load(byte[] clip)
The load()
method allows you to load the contents of a haptic clip into memory before triggering playback with play()
.
Play
public void play()
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.
play()
will throw a RuntimeException
if the device is not capable of advanced haptics.
❗NOTE: Playback of haptic clips with more than ~50 breakpoints might feel “stretched” during playback making clips play longer than designed. However, if your app is CPU load intensive, this might not happen. This is a current limitation of the Android Vibration API and it has been fixed by the Android team for future major platform releases (after API Level 30).
Stop
public void stop()
If a 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.
Clip duration
public float getClipDuration()
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 Example
LofeltHaptics haptics = new LofeltHaptics(this);
try {
// Load haptic clip
final InputStream stream = getResources().openRawResource(hapticClipResourceId);
final byte[] hapticClipBytes = IOUtils.toByteArray(stream);
haptics.load(hapticClipBytes);
// Play haptic clip
haptics.play();
} catch (Exception e) {
// ...
}
In this example, the haptic clip is loaded from an Android resource (of course, you can load it in any way you prefer).
Example Project
In the sdk/examples/android
folder within the Lofelt Studio download, there is an example project for playing haptic clips on a phone called LofeltHapticsExamplePreAuthored
. To run the example, open the project in Android Studio, target your phone, and build. The example provides two buttons that, when pressed and released, will trigger playback of audio files and accompanying haptic clips.