# HLA Files (Android)

# Concept

HLA (Hapticlabs Android) files are used to express haptic signals in a format that corresponds to Androids VibrationEffect.createWaveform.

In addition, HLA files define which audio signals are played corresponding to the haptic signals, if any.

Furthermore, these files contain metadata regarding the haptic signal, such as its title and duration.

# Structure

HLA files are JSON files that contain the following fields:

ProjectName: [string]; The title of the haptic project.
TrackName: [string]; The title of the haptic track.
Duration: [number]; The duration of the haptic signal in milliseconds.
Timings: [array<number>]; An array of integers that define the timing of the haptic signal as required by VibrationEffect.createWaveform.
Amplitudes: [array<number>]; An array of integers, range 0-255, that define the amplitude of the haptic signal as required by VibrationEffect.createWaveform.
Repeat: [number]; The number of times the haptic signal is repeated or -1 to indicate no repetition, as required by VibrationEffect.createWaveform.
RequiredAudioFiles: [array<string>]; An array of strings that define the audio files that are referenced by this HLA file.
Audios: [array<AudioFile>]; An array of objects that define the audio files that are referenced by this HLA file:
AudioFile: [{Filename: string, Time: number}]; An object that defines an audio file and the timestamp when it is played, relative to the start of the signal.
Filename: [string]; The relative path (from the .hla location) to the audio file.
Time: [number]; The timestamp in milliseconds when the audio file is played.

# Playback

Note: The haptic and audio signals are handled separately when using HLA files. Perfect synchronization can not be guaranteed due to the unpredictable latency of the audio playback. We strongly recommend using OGG files for synchronised haptics and audio playback if your target devices have high haptic capabilities as that approach handles haptic and audio signals as one signal and thus provides the best possible synchronization.

# React Native

The react-native-hapticlabs npm package provides a simple way to play back HLA files on Android devices:

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

// Play an HLA file
playHLA("path/to/file.hla");

# Kotlin

To play back haptic signals encoded in HLA files using Kotlin, use our hapticlabsplayer Android library:

import io.hapticlabs.hapticlabsplayer.HapticlabsPlayer

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

// Play HLA file
hapticlabsPlayer.playHLA(
    "path/to/file.hla",
    completionCallback = { println("completed playback") })