# Android export

For the export of haptic signals to use on Android devices, Hapticlabs Studio provides an exporter that generates .hla and .ogg files.

Select the project whose tracks you aim to export. Then, open the exporter in the menu under Export -> Export to Android . You have two options available:

Manual (Per level)

This mode allows you to specify a dedicated track for each haptic level.

Auto (All levels)

In this mode, selected tracks will be exported for all haptic levels.

In this mode, you can select individal tracks for each haptic level. This allows you to tailor haptic signals to the capabilities of each device.

For example, frequency modulations are a powerful design element on devices with level 3 haptic capabilities, but at lower levels they are not perceivable. This export mode allows you to select a second signal substituting frequency modulations for amplitude modulations for level 2, and a third signal, using timing modulations for level 1.

To execute the export in this mode, select one track for each haptic capability level. Note that you can select the same track for multiple levels, e.g. you can use one track for level 3 and another track for levels 2 and 1.

Once you have selected the tracks, choose an export destination and click "Export".

In this mode, each selected track will be exported for all haptic levels. The exporter will create separate files for each haptic level.

To execute the export in this mode, select the tracks you want to export, choose an export destination and click "Export".

After exporting, you will see new subdirectories in you export destination corresponding to the exported signals. Each subdirectory is structured as follows:

signalIdentifier/
├── lvl1/
│   ├── main.hla
│   ├── possiblyAudio.wav
├── lvl2/
│   ├── main.hla
│   ├── possiblyAudio.wav
└── lvl3/
    └── main.ogg

Note that the audio files will only be present if the exported track contains audio blocks.

When deploying your haptic signals on Android, you can choose to either have the app automatically select the appropriate signal based on the device's capabilities or to make that selection manually.

For both cases, our react-native-hapticlabs npm package and our hapticlabsplayer Android library provide simple ways to play back haptic signals on Android devices.

With the react-native-hapticlabs npm package playing back haptic signals on Android devices can be achieved with a single call:

import { playAndroidHaptics } from "react-native-hapticlabs";

// Play Android haptics
playAndroidHaptics("path/to/directory");

To use this command, simply move the exported directory to your Android project (e.g. android/app/src/main/assets/exportedTrack) and call the playAndroidHaptics('path') function with the path to the directory (e.g. playAndroidHaptics('exportedTrack')). Note that this path can be relative to the assets directory (as in the example) or a fully qualified path on the Android device's filesystem.

Internally, the playAndroidHaptics function will check the device's haptic capabilities and play the appropriate signal. For instance, if the app runs on a device with level 3 haptic capabilities, the function will play the lvl3/main.ogg file. If the same app runs on a device that has level 2 haptic capabilities, the function will play the lvl2/main.hla file. Associated audio files will be played back in sync with the haptic signals.

With the hapticlabsplayer Android library, playing back haptic signals is very simple:

import io.hapticlabs.hapticlabsplayer.HapticlabsPlayer

// Instantiate the player
val hapticlabsPlayer = remember { HapticlabsPlayer(context) }

// Play Android haptics
hapticlabsPlayer.play(
    "Android samples/button",
    completionCallback = { println("completed playback") })

To use this command, simply move the exported directory to your Android project (e.g. android/app/src/main/assets/exportedTrack) and call the playAndroidHaptics('path') function with the path to the directory (e.g. playAndroidHaptics('exportedTrack')). Note that this path can be relative to the assets directory (as in the example) or a fully qualified path on the Android device's filesystem.

Internally, the play method will check the device's haptic capabilities and play the appropriate signal. For instance, if the app runs on a device with level 3 haptic capabilities, the function will play the lvl3/main.ogg file. If the same app runs on a device that has level 2 haptic capabilities, the function will play the lvl2/main.hla file. Associated audio files will be played back in sync with the haptic signals.

If you choose to select the appropriate signal manually, please look into the HLA files and OGG files documentation for more information on how to play back haptic signals on Android devices.