Apple Haptic Creator

A powerful Go library and command-line tools for creating Apple Haptic pattern files (AHAP). Features include a beautiful fluent API, musical timing support (BPM, bars, beats, time signatures), and MIDI to haptics conversion.

What are AHAP files?

AHAP files are JSON-formatted Apple Haptic pattern files used in iOS games and applications to create immersive haptic experiences. They can be played directly from the Files app or any apps that support Apple's Quick Look API, making them shareable via WhatsApp, Telegram, and other platforms.

For more information, see this article on AppleVis.

✨ Features

• Beautiful Fluent API - Chain methods for intuitive haptic creation
• Musical Timing - Support for BPM, bars, beats, and time signatures
• Sequence Builder - Create complex patterns across multiple bars with ease
• Haptrack DSL - Musical notation-inspired language for haptic composition
• MIDI Conversion - Convert MIDI files to haptic patterns
• High Performance - Fast Go implementation
• Zero Dependencies - Core library uses only Go standard library
• Clean Architecture - Reusable package with multiple CLI utilities

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/denizsincar29/apple_haptic_creator.git
cd apple_haptic_creator

# Build all commands
go build -o bin/makeahap cmd/makeahap/main.go
go build -o bin/midi2ahap cmd/midi2ahap/main.go
go build -o bin/ahapgen cmd/ahapgen/main.go
go build -o bin/haptrack cmd/haptrack/main.go

Using as a Library

package main

import "github.com/denizsincar29/apple_haptic_creator/pkg/ahap"

func main() {
    // Simple example
    builder := ahap.NewBuilder("My Haptic", "Me")
    builder.
        Transient(0.0).Intensity(1.0).Sharpness(0.5).Add().
        Continuous(1.0, 2.0).Intensity(0.8).Sharpness(0.7).Add().
        Export("example.ahap", true)
}

Musical Timing Example

// Create a drum beat pattern at 120 BPM
builder := ahap.NewBuilder("Drum Beat", "Creator").
    WithBPM(120).
    WithTimeSignature(4, 4)

// Add kick drum on beats 0 and 2 of bar 0
builder.At(0, 0).Transient().Intensity(1.0).Sharpness(0.2).Add()
builder.At(0, 2).Transient().Intensity(1.0).Sharpness(0.2).Add()

// Add snare on beats 1 and 3 of bar 0
builder.At(0, 1).Transient().Intensity(0.9).Sharpness(0.8).Add()
builder.At(0, 3).Transient().Intensity(0.9).Sharpness(0.8).Add()

builder.Export("drumbeat.ahap", true)

🎯 Command Line Tools

makeahap - Motorcycle Sound Example

go run cmd/makeahap/main.go -output bike.ahap -indent

Creates a realistic motorcycle engine sound using haptics.

midi2ahap - MIDI to Haptics Converter

go run cmd/midi2ahap/main.go -input song.mid -output song.ahap -indent

Converts MIDI files to haptic patterns with intelligent drum detection:

• Melodic notes: Converted to continuous events, mapping frequency to sharpness
• Drum channel (10): Converted to transient events with optimized characteristics
• Drum mapping: 50+ General MIDI drum sounds mapped to appropriate haptic profiles
  • Bass drums: High intensity, low sharpness
  • Snares: High intensity, high sharpness
  • Hi-hats: Medium intensity, very high sharpness
  • Cymbals: High intensity, high sharpness with decay
  • Percussion: Varied profiles based on sound type

Options:

• -drums=true/false: Enable/disable drum detection (default: true)
• -indent: Pretty-print JSON output

ahapgen - Interactive Haptic Generator

go run cmd/ahapgen/main.go -bpm 120 -time 4/4 -o output.ahap

Interactive command-line tool with support for musical timing.

haptrack - Haptic Pattern DSL

go run cmd/haptrack/main.go -input pattern.hap -output pattern.ahap

Domain-specific language for creating haptic patterns using musical notation. Define "instruments" with letters and compose them into tracks.

Example pattern file:

bpm = 120
time = 4/4
s = snare, 1.0, 0.9, down, 60
k = kick, 1.0, 0.2
h = hihat, 0.6, 1.0

begin
track1
k8k8s8k8k8k8s8k8
track2
h8h8h8h8h8h8h8h8

See cmd/haptrack/README.md for complete documentation.

📚 Documentation

For complete API documentation and advanced examples, see README_GO.md.

📁 Project Structure

.
├── pkg/ahap/              # Core library package
│   ├── ahap.go           # Core AHAP types
│   ├── events.go         # Event creation
│   ├── curves.go         # Parameter curves
│   ├── musical.go        # Musical timing (BPM, bars, beats)
│   ├── builder.go        # Fluent API builder
│   └── ahap_test.go      # Tests
├── cmd/                   # Command-line utilities
│   ├── makeahap/         # Motorcycle sound example
│   ├── midi2ahap/        # MIDI converter
│   ├── ahapgen/          # Interactive generator
│   └── haptrack/         # Haptic pattern DSL
├── examples/              # Example code and patterns
├── ahaps/                 # Example AHAP files
└── demo/                  # Demo files (including MIDI)

🧪 Testing

go test ./pkg/ahap/        # Run tests
go test -cover ./pkg/ahap/ # With coverage

📖 Examples

The ahaps/ folder contains example AHAP files:

• bike.ahap - Motorcycle engine sound
• interval.ahap - Simple interval pattern
• music.ahap - Musical pattern
• notes.ahap - Musical notes

Demo MIDI files for testing:

• demo/themeters.mid - Example MIDI file
• demo/donnalee.mid - Example MIDI file

🤝 Contributing

Contributions are welcome! Areas for improvement:

• Additional curve interpolation methods
• More MIDI conversion options
• Haptic pattern templates library
• Visualization tools
• Pattern analysis utilities

📄 License

See IMPLEMENTATION_SPEC.md for complete implementation details.

🙏 Credits

• Original Python implementation by Deniz Sincar
• Go rewrite with enhanced features and musical timing support