audio-to-haptics

Converts audio into haptic (vibration) feedback patterns using the Web Audio API and Vibration API. Analyzes an audio file, detects amplitude spikes and decay tails, and drives navigator.vibrate() in sync with a media element.

Only works on Android Chrome and some mobile browsers — no desktop vibration support.

Docs & demo → https://audio-to-haptics.pages.dev

Want to learn more? Read the full writeup on Dev.to →

Install

npm install audio-to-haptics

Usage

Vanilla JS / any framework:

import { HapticEngine } from 'audio-to-haptics'

const engine = new HapticEngine()
await engine.analyze(url)
engine.attach(audioElement, (time) => updateUI(time))
engine.detach()

React:

import { useHaptics } from 'audio-to-haptics/react'

const audioRef = useRef(null)
const { analyze, ready } = useHaptics(audioRef)

<audio ref={audioRef} controls />
<button onClick={() => analyze(url)}>{ready ? 'Re-analyze' : 'Analyze'}</button>

This Repository

This repo serves two purposes:

1. The npm library (src/audio/, src/index.ts, src/react.ts) — the actual published package
2. A dev playground (src/App.tsx, src/WaveformView.tsx, src/SimpleUsage/, src/MediaUsage/) — used during development for testing and tuning the algorithm on real audio. Not deployed anywhere.

Project Structure

src/
  index.ts             — library entry point (vanilla JS / any framework)
  react.ts             — library entry point (React)
  audio/
    HapticEngine.ts    — core class: analysis pipeline + RAF vibration loop
    useHaptics.ts      — React hook wrapping HapticEngine
    analyzeAudio.ts    — pure analysis functions and all exported types
    snapshots.test.ts  — snapshot tests (6 fixtures, 12 tests)
    fixtures.ts        — test fixtures with real audio trends and expected outputs

  App.tsx              — dev playground UI: URL input, play controls, waveform view
  WaveformView.tsx     — canvas waveform visualizer with haptic overlays
  SimpleUsage/         — minimal hook usage demo (audio element)
  MediaUsage/          — hook usage demo with video element

lib/                   — library build output (gitignored, generated by npm run build:lib)
public/                — local audio/video files for dev testing (gitignored)

Commands

npm run dev          # start dev server for the playground
npm run build:lib    # build the library to lib/
npm run test         # run snapshot tests
npm run lint         # run ESLint

Dev Playground

App.tsx is the main testing UI — paste an audio URL, analyze it, and play with haptic feedback on a real Android device. WaveformView.tsx visualizes the waveform with intensity-colored overlays showing exactly which sections will vibrate and how strongly.

SimpleUsage/ and MediaUsage/ are minimal demos built using the useHaptics hook directly, simulating how a library consumer would use it.

Drop local audio files in public/ and reference them as /filename.mp3 in the dev UI.

Build System

Two separate Vite configs:

• vite.config.ts — dev server only (React plugin, serves public/)
• vite.lib.config.ts — library build (publicDir: false, lib mode, React externalized)

Four TypeScript configs:

• tsconfig.json — root, references the others
• tsconfig.app.json — dev app type checking (src/, noEmit)
• tsconfig.node.json — Vite config files type checking
• tsconfig.lib.json — library declaration emit only (lib/, excludes test files)