react-native-hapticlabs/lib/typescript/src/index.d.ts

A package to play back haptics developed using Hapticlabs Studio

/**
 * This command will play an HLA file from the specified `path`, including corresponding audio files.
 *
 * *Note*: This command is only supported on Android.
 * @param path The path to the HLA file. This can be a path relative to the assets directory or a fully qualified path.
 * @returns A promise that resolves when the HLA file has been played.
 */
export declare function playHLA(path: string): Promise<void>;
/**
 * This command will play an OGG file from the specified `path`, including encoded haptic feedback.
 * If the device's haptic support level is less than 3, the device will play the audio file without haptic feedback.
 * To automatically select adequate haptic feedback for the device, use `playAndroidHaptics` instead.
 *
 * *Note*: This command is only supported on Android.
 * @param path The path to the OGG file. This can be a path relative to the assets directory or a fully qualified path.
 * @returns A promise that resolves when the OGG file has been played.
 */
export declare function playOGG(path: string): Promise<void>;
/**
 * This command will play a HAC file from the specified `path`, including corresponding audio files.
 *
 * The HAC file itself contains multiple haptic patterns for different haptic support levels.
 * The device will automatically select and play the optimal haptic pattern based on its haptic support level.
 *
 * *Note*: This command is only supported on Android.
 * @param path The path to the HAC file. This can be a path relative to the assets directory or a fully qualified path.
 * @returns A promise that resolves when the HAC file has been played.
 */
export declare function playHAC(path: string): Promise<void>;
/**
 * This command will play a haptic pattern from the specified `directoryOrHACPath`.
 *
 * The type of input will be automatically detected:
 *
 * If a HAC file is specified, the function behaves like `playHAC`.
 *
 * If a directory is specified, the function will select and play the appropriate haptic pattern based on the device's haptic support level.
 * Depending on the device's haptic support level, different haptic feedback will be played.
 * For instance, if the device's haptic support level is 3, the device will play the haptic pattern
 * specified in the `lvl3` subdirectory. If the device's haptic support level is 0, no haptic feedback will be played.
 * Make sure that the directory follows the following structure:
 * ```
 * directoryPath
 * ├── lvl1
 * │   └── main.hla
 * ├── lvl2
 * │   └── main.hla
 * └── lvl3
 *     └── main.ogg
 * ```
 * *Note*: This command is only supported on Android.
 * @param directoryOrHACPath The path to the haptic pattern directory or HAC file. This can be a path relative to the assets directory or a fully qualified path.
 * @returns A promise that resolves when the haptic pattern has been played.
 */
export declare function playAndroidHaptics(directoryOrHACPath: string): Promise<void>;
/**
 * This command will preload the OGG file from the specified `path`.
 *
 * This is useful for reducing latency when playing haptic patterns. Currently,
 * OGG filse will only be preloaded and cached if their uncompressed size is
 * less than 1 MB
 * (see [Android's SoundPool documentation](https://developer.android.com/reference/android/media/SoundPool)).
 *
 * @param path The path to the haptic pattern directory to unload. The same
 * you would pass to `playOGG`.
 */
export declare function preloadOGG(path: string): void;
/**
 * This command will preload haptic patterns from the specified `directoryOrHACPath`.
 *
 * This is useful for reducing latency when playing haptic patterns. Currently,
 * only OGG files will be preloaded and cached, and only so if their
 * uncompressed size is less than 1 MB
 * (see [Android's SoundPool documentation](https://developer.android.com/reference/android/media/SoundPool)).
 *
 * @param directoryOrHACPath The path to the haptic pattern directory or HAC file. See the
 * `playAndroidHaptics` documentation for further details.
 */
export declare function preloadAndroidHaptics(directoryOrHACPath: string): void;
/**
 * This command will unload the OGG file from the specified `path`.
 *
 * This is useful for freeing up memory when the haptic patterns are no longer
 * needed, and to clear the cache and enforce a reload if the file has changed.
 *
 * @param path The path to the haptic pattern directory to unload. The same
 * you would pass to `playOGG`.
 */
export declare function unloadOGG(path: string): void;
/**
 * This command will unload the haptic patterns loaded from the specified
 * `directoryOrHACPath`.
 *
 * This is useful for freeing up memory when the haptic patterns are no longer
 * needed, and to clear the cache and enforce a reload if the files have
 * changed.
 *
 * @param directoryOrHACPath The path to the haptic pattern directory or HAC file. See the
 * `playAndroidHaptics` documentation for further details
 */
export declare function unloadAndroidHaptics(directoryOrHACPath: string): void;
/**
 * This command will unload all haptic patterns that have been preloaded or
 * played.
 *
 * Equivalent to calling `unloadAndroidHaptics()` for all directories and OGG
 * files that have been preloaded or played.
 */
export declare function unloadAllAndroidHaptics(): void;
/**
 * The device's haptic support level.
 * This value is a number between 0 and 4, where:
 * - 0: The device does not support haptics.
 * - 1: The device supports on / off haptic feedback.
 * - 2: The device supports amplitude control haptic feedback.
 * - 3: The device supports fully customizable audio-coupled haptic feedback.
 * - 4: The device supports parametric envelope-controlled haptic feedback.
 *
 * *Note*: This value is only supported on Android.
 */
export declare const androidHapticSupportLevel: 0 | 1 | 2 | 3 | 4;
/**
 * Whether the device supports on/off haptic feedback.
 *
 * On/Off haptic feedback is the most basic form of haptic feedback with timing
 * being the only controllable parameter.
 *
 * *Note**: This value is only supported on Android.
 */
export declare const areOnOffHapticsSupported: boolean;
/**
 * Whether the device supports amplitude control haptic feedback.
 *
 * Amplitude control haptic feedback allows for more nuanced haptic feedback
 * by controlling the amplitude of the haptic signal over time.
 *
 * **Note**: This value is only supported on Android.
 */
export declare const areAmplitudeControlHapticsSupported: boolean;
/**
 * Whether the device supports audio coupled haptic feedback.
 *
 * Audio coupled haptic feedback allows for full control over the haptic
 * feedback, while at the same time offering playback synchronized with audio.
 *
 * **Note**: This value is only supported on Android.
 */
export declare const areAudioCoupledHapticsSupported: boolean;
/**
 * Whether the device supports envelope-controlled haptic feedback.
 *
 * Similar to amplitude control haptic feedback, envelope-controlled haptic
 * feedback allows for controlling both the amplitude and the frequency of the
 * haptic signal over time.
 *
 * **Note**: This value is only supported on Android.
 */
export declare const areEnvelopeHapticsSupported: boolean;
/**
 * The device's haptic actuator's resonance frequency.
 *
 * This is the frequency at which the haptic actuator is driven for e.g. HLA
 * level 2 files. At this frequency, the actuator will resonate and produce
 * the strongest and most energy-efficient haptic feedback.
 *
 * **Note**: This value is only supported on Android.
 */
export declare const resonanceFrequency: number | null;
/**
 * The device's haptic actuator's q factor.
 *
 * See https://en.wikipedia.org/wiki/Q_factor for more information.
 *
 * **Note**: This value is only supported on Android.
 */
export declare const qFactor: number | null;
/**
 * The device's haptic actuator's self-reported minimum frequency.
 *
 * **Note**: This value is only supported on Android.
 *
 * **Note**: With audio-coupled haptics (OGG files), there are no frequency
 * limits.
 */
export declare const minFrequency: number | null;
/**
 * The device's haptic actuator's self-reported maximum frequency.
 *
 * **Note**: This value is only supported on Android.
 *
 * **Note**: With audio-coupled haptics (OGG files), there are no frequency
 * limits.
 */
export declare const maxFrequency: number | null;
/**
 * The device's haptic actuator's self-reported maximum acceleration (in Gs).
 *
 * **Note**: This value is only supported on Android.
 */
export declare const maxAcceleration: number | null;
/**
 * The device's haptic actuator's self-reported frequency response.
 *
 * This is a map from frequency (in Hz) to acceleration (in Gs) at that
 * frequency.
 *
 * **Note**: This value is only supported on Android.
 */
declare let frequencyResponse: Map<number, number> | null;
export { frequencyResponse };
/**
 * The minimum duration (in milliseconds) for an envelope control point.
 *
 * **Note**: This value is only supported on Android.
 */
export declare const envelopeControlPointMinDurationMillis: number | null;
/**
 * The maximum duration (in milliseconds) for an envelope control point.
 *
 * **Note**: This value is only supported on Android.
 */
export declare const envelopeControlPointMaxDurationMillis: number | null;
/**
 * The maximum duration (in milliseconds) for an envelope effect.
 *
 * **Note**: This value is only supported on Android.
 */
export declare const envelopeMaxDurationMillis: number | null;
/**
 * The maximum number of control points for an envelope effect.
 *
 * **Note**: This value is only supported on Android.
 */
export declare const envelopeMaxControlPointCount: number | null;
/**
 * This command will play an AHAP file from the specified `path`, including corresponding AHAP files and audio files.
 *
 * *Note*: This command is only supported on iOS.
 * @param path The path to the AHAP file.
 * @returns A promise that resolves when the AHAP file has been played.
 */
export declare function playAHAP(path: string): Promise<void>;
/**
 * This command will play the haptic pattern specified by the `iosPath` on iOS and the `androidPath` on Android.
 * @param iosPath The path to the AHAP file.
 * @param androidPath The path to the Android haptic pattern directory. This can be a path relative to the assets directory or a fully qualified path.
 * @returns A promise that resolves when the haptic pattern has finished playing.
 */
export declare function playHaptics({ iosPath, androidPath, }: {
    iosPath: string;
    androidPath: string;
}): Promise<void>;
/**
 * Predefined haptic signals available on Android.
 */
export declare enum AndroidPredefinedHaptics {
    CLICK = "Click",
    DOUBLE_CLICK = "Double Click",
    HEAVY_CLICK = "Heavy Click",
    TICK = "Tick"
}
/**
 * Predefined haptic signals available on iOS.
 */
export declare enum IOSPredefinedHaptics {
    LIGHT = "light",
    MEDIUM = "medium",
    HEAVY = "heavy",
    RIGID = "rigid",
    SOFT = "soft",
    SUCCESS = "success",
    WARNING = "warning",
    ERROR = "error",
    SELECTION = "selection"
}
/**
 * This command will play a predefined (built-in) haptic signal.
 *
 * For each platform, up to one predefined haptic signal can be specified.
 * If none is specified for the current platform, no haptic feedback will be played.
 *
 * @param android The predefined haptic signal to play on Android.
 * @param ios The predefined haptic signal to play on iOS.
 */
export declare function playPredefinedHaptics(signal: {
    android?: AndroidPredefinedHaptics;
    ios?: IOSPredefinedHaptics;
}): void;
/**
 * This command will mute or unmute haptic feedback from Hapticlabs.
 *
 * **Note**: This command is only supported on iOS.
 *
 * **Note**: This command will not affect predefined haptic signals played via `playPredefinedHaptics`.
 *
 * @param mute Whether to mute (true) or unmute (false) haptic feedback.
 */
export declare function setHapticsMute(mute: boolean): void;
/**
 * This command will return whether haptic feedback from Hapticlabs is muted.
 *
 * **Note**: This command is only supported on iOS.
 *
 * **Note**: This command will not reflect the mute state of predefined haptic signals played via `playPredefinedHaptics`.
 *
 * @returns A promise that resolves to whether haptic feedback is muted.
 */
export declare function isHapticsMuted(): Promise<boolean>;
/**
 * This command will mute or unmute audio playback from Hapticlabs.
 *
 * **Note**: This command is only supported on iOS.
 *
 * **Note**: This command exclusively affects audio playback associated with haptic patterns played via `playAHAP` or `playHaptics`.
 *
 * @param mute Whether to mute (true) or unmute (false) audio playback.
 */
export declare function setAudioMute(mute: boolean): void;
/**
 * This command will return whether audio playback from Hapticlabs is muted.
 *
 * **Note**: This command is only supported on iOS.
 *
 * **Note**: This command exclusively reflects the mute state of audio playback associated with haptic patterns played via `playAHAP` or `playHaptics`.
 *
 * @returns A promise that resolves to whether audio playback is muted.
 */
export declare function isAudioMuted(): Promise<boolean>;
//# sourceMappingURL=index.d.ts.map