{"id":41889619,"url":"https://github.com/facebook/meta-haptics-sdk","last_synced_at":"2026-01-25T14:01:19.217Z","repository":{"id":334239839,"uuid":"1110819018","full_name":"facebook/meta-haptics-sdk","owner":"facebook","description":"A low-level haptic rendering and data processing library based on a universal format.","archived":false,"fork":false,"pushed_at":"2026-01-23T16:33:09.000Z","size":1407,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-01-24T06:32:49.241Z","etag":null,"topics":["games","haptics","middleware"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/facebook.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-05T19:13:43.000Z","updated_at":"2026-01-23T16:33:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/facebook/meta-haptics-sdk","commit_stats":null,"previous_names":["facebook/meta-haptics-sdk"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/facebook/meta-haptics-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebook%2Fmeta-haptics-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebook%2Fmeta-haptics-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebook%2Fmeta-haptics-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebook%2Fmeta-haptics-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/facebook","download_url":"https://codeload.github.com/facebook/meta-haptics-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facebook%2Fmeta-haptics-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28754087,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T13:59:49.818Z","status":"ssl_error","status_checked_at":"2026-01-25T13:59:33.728Z","response_time":113,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["games","haptics","middleware"],"created_at":"2026-01-25T14:01:03.622Z","updated_at":"2026-01-25T14:01:12.638Z","avatar_url":"https://github.com/facebook.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"resources/images/logo/Transparent/Banner-SDK-Transparent.png\" alt=\"Haptics SDK Logo\" style=\"width:95%; max-width:800px; display:block; margin-left:auto; margin-right:auto;\"\u003e\n\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nA low-level haptic rendering and data processing library based on a universal\nformat. Designed as a core component for integration into game engines, audio\nmiddleware, and other systems, Haptics SDK runs in production across millions of\ndevices daily.\n\n---\n\n## Table of Contents\n\n- [Feature overview](#feature-overview)\n- [Industry Adoption](#industry-adoption)\n- [Getting Started](#getting-started)\n  - [Prerequisites](#prerequisites)\n  - [Quick Start](#quick-start)\n  - [Building](#building)\n- [Examples](#examples)\n- [How It Works](#how-it-works)\n- [Design Philosophy](#design-philosophy)\n- [Documentation](#documentation)\n- [FAQ](#faq)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Feature overview\n\n![Conceptual System Diagram](resources/images/Feature-Overview-Transparent.png)\n\n### 🎨 Platform-Agnostic Haptic Input Data\n\nWorks with normalized haptic parameters such as amplitude, frequency, and\ntransients, rather than raw waveforms. This approach aligns with the broader\nindustry shift toward standardized, device-agnostic haptic data structures (not\nonly via the `.haptic` format in this repo but also Apple's `.ahap` format). By\nseparating haptic design intent from device playback capabilities, you can\nensure consistent experiences across diverse hardware.\n\n### ⚙️ Configuration-Based Render Output\n\nActuator Configuration Files (ACF) define how abstract haptic data maps to\nspecific hardware. This makes it easy to support multiple output platforms\nwithout modifying your code, streamlining integration and maintenance.\n\n### 🎛️ Dual Rendering Modes\n\nSupports a wide range of platform API and device capabilites, including both\nPCM-based systems and those based on simple amplitude curves.\n\n### 🔧 Integration Friendly\n\n- **No external dependencies** - Standalone C/C++ source code\n- **Minimal API surface** - Simple, easy-to-understand integration points\n- **Cross-platform** - Windows, macOS, Linux, consoles \u0026 firmware\n\n---\n\n## Industry Adoption\n\nMeta Haptics SDK serves as the core haptic rendering technology in major tools\nand platforms:\n\n### Audio Middleware\n\nNatively integrated into professional audio middleware:\n\n- **[FMOD Haptics Instrument](https://www.fmod.com/docs/2.03/studio/instrument-reference.html#haptics-instrument)** -\n  Native haptic authoring for PlayStation® (including DualSense™), Xbox, and\n  Meta Quest\n- **Wwise Motion** - Audiokinetic's native haptic authoring integration _(in\n  progress)_\n\n### Game Engines\n\n- **[Meta Haptics SDK for Unity](https://developers.meta.com/horizon/documentation/unity/unity-haptics-sdk/)** -\n  Quest and PCVR haptics for Unity applications\n- **[Meta Haptics SDK for Unreal](https://developers.meta.com/horizon/documentation/unreal/unreal-haptics-sdk/)** -\n  Quest and PCVR haptics for Unreal Engine applications\n\n### Design Tools\n\n- **[Meta Haptics Studio](https://developers.meta.com/horizon/resources/haptics-studio)** -\n  Professional haptic design tool using this SDK as its core renderer on\n  Windows, Mac and Meta Quest's Android based runtime.\n\n---\n\n## Getting Started\n\n### Prerequisites\n\n#### Build Tools\n\n- **[CMake](https://cmake.org/)** 3.10 or higher\n- **[just](https://github.com/casey/just)** (optional, makes building and\n  testing more convenient)\n- C/C++ compiler (GCC, Clang, MSVC, or other)\n\n#### Supported Platforms\n\n- Windows (MSVC, MinGW)\n- macOS (Clang)\n- Linux (GCC, Clang)\n- VR headsets (Quest, PCVR)\n- Consoles (PlayStation®, Xbox)\n\n### Quick Start\n\n```bash\n# Clone the repository\ngit clone git@github.com:facebook/meta-haptics-sdk.git\ncd meta-haptics-sdk\n\n# Initialize submodules\ngit submodule init\ngit submodule update\n```\n\n### Building\n\n#### Using `just` (Recommended)\n\n```bash\njust            # Build and test all components\njust build-all  # Build all components without testing\n```\n\n#### Using CMake\n\nThe justfile in the directory of each component contains the CMake commands.\n\n---\n\n## Examples\n\n### 1. Authoring a .haptic file\n\n.haptic files contain the contents of a haptic effect.\n\n#### Example .haptic File\n\n```json\n{\n  \"version\": {\"major\": 1, \"minor\": 0, \"patch\": 0},\n  \"metadata\": {\n    \"editor\": \"Meta Haptics Studio\",\n    \"description\": \"Button click effect\"\n  },\n  \"signals\": {\n    \"continuous\": {\n      \"envelopes\": {\n        \"amplitude\": [\n          {\"time\": 0.0, \"amplitude\": 0.0},\n          {\n            \"time\": 0.05,\n            \"amplitude\": 1.0,\n            \"emphasis\": {\"amplitude\": 1.0, \"frequency\": 1.0}\n          },\n          {\"time\": 0.1, \"amplitude\": 0.0}\n        ],\n        \"frequency\": [\n          {\"time\": 0.0, \"frequency\": 0.7},\n          {\"time\": 0.1, \"frequency\": 0.3}\n        ]\n      }\n    }\n  }\n}\n```\n\n#### Key Concepts\n\n- **Amplitude Envelope** - Controls intensity over time (0.0 = silent, 1.0 =\n  strong)\n- **Frequency Envelope** - Controls pitch/texture (0.0 = round, 1.0 = sharp)\n- **Emphasis** - Short, transient events (clicks, impacts) attached to amplitude\n  points\n- **Normalized Values** - All values are 0.0-1.0; the renderer maps to hardware\n  via ACF\n\n**Design Tools:** Create `.haptic` files visually using\n[Meta Haptics Studio](https://developers.meta.com/horizon/resources/haptics-studio)\nor author them by hand.\n\n**.haptic Specification:**\n[`resources/haptic-file-spec.md`](resources/haptic-file-spec.md)\n\n### 2. Authoring an Actuator Configuration File (ACF)\n\nACF files define device-specific characteristics, translating normalized haptic\ndata (0.0-1.0) into hardware-appropriate parameters.\n\n#### Example ACF (Generic PCM Console)\n\n```json5\n{\n  metadata: {\n    version: '1.0.0',\n    device: 'Generic console PCM',\n    author: 'Author name',\n  },\n  continuous: {\n    gain: 0.8, // Master volume for continuous vibration\n    emphasis_ducking: 0.5, // Reduce continuous by 50% during transients\n    frequency_min: 55.0, // Map 0.0 frequency → 55 Hz\n    frequency_max: 200.0, // Map 1.0 frequency → 200 Hz\n  },\n  emphasis: {\n    gain: 1.0, // Full strength transients\n    fade_out_percent: 0.0,\n    frequency_min: {\n      output_frequency: 55.0, // Low sharpness: 55 Hz\n      duration_ms: 27.0, // ~1.5 cycles\n      shape: 'sine', // Smooth waveform\n    },\n    frequency_max: {\n      output_frequency: 130.0, // High sharpness: 130 Hz\n      duration_ms: 20.0, // As short as possible\n      shape: 'square', // Sharp waveform\n    },\n  },\n}\n```\n\n#### Provided ACF Templates\n\n- **[`Generic-Console-PCM.acf`](resources/acf/Generic-Console-PCM.acf)** - Full\n  waveform synthesis (PlayStation® DualSense, etc.)\n- **[`Generic-Console-SimpleHaptics.acf`](resources/acf/Generic-Console-SimpleHaptics.acf)** -\n  Amplitude-only output (Xbox, etc.)\n- **[`Meta-Quest.acf`](resources/acf/MetaQuest.acf)** - Meta Quest controller\n  tuning\n\n**Tuning Your ACF:** Start with a template and tune by feel. Adjust frequency\nranges based on your actuator's datasheet and perceptual testing.\n\n**ACF Specification:** [`resources/acf/README.md`](resources/acf/README.md)\n\n### 3. Parsing and Rendering Haptic Data in C++\n\nTo parse and render haptic data you need a `.haptic` file and an ACF (see\nexamples above). Then do the following:\n\n1. Convert the `.haptic` to a ParametricHapticClip using the Parametric Haptic\n   Data library.\n2. Initialize ParametricHapticRenderer with the render settings from the ACF and\n   the ParametricHapticClip.\n3. From an update loop or callback, preferably running at a fixed clock rate,\n   drive ParametricHapticRenderer in realtime.\n\n**[View Parametric Haptic Renderer Example](core/renderer_parametric/README.md)**\n\n### 4. PCM Haptics for Unity and Unreal\n\nComplete integration examples for Unity and Unreal demonstrating how to render haptics on\ndevices that implement OpenXR PCM haptics (Meta Quest).\n\n**[View Unity Example](interfaces/unity/PCMHaptics/README.md)**\n\n**[View Unreal Example](interfaces/unreal/PCMHaptics/README.md)**\n\n---\n\n## How It Works\n\nMeta Haptics SDK is a haptic rendering library with a five-component\narchitecture that separates content from hardware.\n\n### Core Components\n\nThe SDK consists of five main components that work together:\n\n1. **.haptic Files (Specification: `resources/haptic-file-spec.md`)**: The\n   `.haptic` format is a JSON-based, device-agnostic representation of\n   vibrotactile effects. This repository open-sources the `.haptic` file\n   specification, but the underlying renderer is **file format agnostic** and\n   easily compatible with similar parametric formats like Apple's AHAP. The\n   format is designed for interchange between design tools, game engines, and\n   runtime systems.\n\n2. **Parametric Haptic Data (`core/haptic_data_parametric`)**: A C++ library for\n   the file format used by Parametric Haptic Renderer (below). It takes .haptic\n   files as input and converts them to Parametric Haptic Data.\n\n3. **Actuator Configuration Files (ACF) (`resources/acf`)**: JSON5 configuration\n   files that define how normalized haptic data (0.0-1.0) within .haptic files\n   (and Parametric Haptic Data) maps to specific hardware characteristics. They\n   contain device-specific parameters like frequency ranges, gain curves, and\n   transient waveform shapes.\n\n4. **Parametric Renderer (`core/renderer_parametric`)**: A realtime rendering\n   C++ library. You initialize it with Parametric Haptic Data and ACF data and\n   then drive it from update loop or callback. In turn it has Haptic Renderer\n   (see below) render slices of parametric data to a the format required by the\n   platform haptic API.\n\n5. **Haptic Renderer (`core/renderer_c`)**: A lightweight C library that\n   processes parametric control points (amplitude and frequency ramps,\n   transients) and generates output samples according to the ACF at a target\n   sample rate. It operates in real-time, maintaining internal state for smooth\n   interpolation between control points.\n\n### Rendering Process\n\nMeta Haptics SDK interpolates between hardware-agnostic parametric control\npoints, and based on the ACF, renders the optimal output for the platform API or\ndevice hardware.\n\n![Haptics SDK Rendering Process](resources/images/haptic_file_spec/system-overview-rendering.png)\n\n_The renderer processes time-based control points (amplitude, frequency,\ntransients) and generates device-specific output samples._\n\nThis separation enables:\n\n- Targeting any configured hardware with the same content\n- Tuning haptic feel per-device via ACF configuration\n- Using the same content pipeline across all platforms\n\n---\n\n## Design Philosophy\n\nMeta Haptics SDK uses **normalized, parametric data** to distinctly separate\ndesign-time concerns from runtime implementation. This approach provides\nsignificant benefits for both content creators and system integrators.\n\n### A Low-Level Building Block for Haptic Systems\n\nMeta Haptics SDK is a **haptic rendering and data processing library** designed\nto be integrated into larger systems. It focuses on a single responsibility:\nefficiently converting device-agnostic vibrotactile data into device and\nplatform-specific output.\n\n**What it provides:**\n\n- Real-time rendering of parametric haptic data (amplitude/frequency envelopes,\n  transients)\n- Device-specific adaptation through Actuator Configuration Files (ACF)\n- Pure C/C++ implementation with zero external dependencies\n- File format agnostic renderer compatible with `.haptic`, AHAP, or similar\n  formats\n\n**What it doesn't provide:**\n\n- High-level playback APIs (play, stop, pause, seek) or playback location.\n- Haptic prioritization or mixing systems\n- Threading models or process communication\n- Asset management or file I/O\n\nThis design allows integration into systems that already have their own models\nfor playback control, threading, and resource management—such as game engines,\naudio middleware, and platform runtimes.\n\n### For Haptic Designers\n\nHardware capabilities vary widely across platforms—from high-end console\ncontrollers to simple gamepads. Requiring designers to create platform-specific\nhaptic assets is highly inefficient:\n\n- **Haptics typically has the lowest priority and smallest budget** in most\n  projects\n- **Rework is cost-prohibitive** - designers need to author once and deploy\n  everywhere\n- **Design intent, not hardware specifics** - normalized envelopes (0.0-1.0)\n  capture what designers want to express, not how specific motors should vibrate\n\nBy storing only design intent in normalized primitives, the system enables:\n\n- **Graceful degradation** on lower-capability hardware\n- **High-quality output** on advanced systems\n- **Cross-platform compatibility** - haptics work on new platforms without\n  rework\n- **Forward and backward compatibility** - content remains valid as systems\n  evolve\n\n### For System Integrators\n\nMiddleware and game engine creators need maintainable solutions across numerous\nplatforms. This SDK provides:\n\n- **Configuration-based rendering** - add new platforms with ACF files, not code\n  changes\n- **No upstream content changes** - existing `.haptic` files work on new\n  platforms automatically\n- **Cost-effective maintenance** - minimal engineering effort for platform\n  support\n\n### Why Not PCM?\n\nMany systems use PCM (Pulse Code Modulation) as their haptic data format, but\n**PCM leaks hardware abstraction into the design**:\n\n- PCM waveforms encode frequency information specific to target hardware\n- Designers must re-render PCM files for every platform with different motor\n  characteristics\n- Changes in hardware require re-authoring all content\n\n**Parametric data** solves this by describing _what_ to feel (amplitude,\nfrequency, transients), not _how_ motors should move. The renderer handles\nhardware translation at runtime.\n\n---\n\n## Documentation\n\n### Complete Documentation Set\n\n| Document                                                             | Description                                    |\n| -------------------------------------------------------------------- | ---------------------------------------------- |\n| **[Parametric Haptic Renderer](core/renderer_parametric/README.md)** | Complete documentation and integration example |\n| **[Parametric Haptic Data](core/haptic_data_parametric/README.md)**  | Short description                              |\n| **[.haptic File Spec](resources/haptic-file-spec.md)**               | Format specification with validation rules     |\n| **[ACF Specification](resources/acf/README.md)**                     | Tuning guide and parameter reference           |\n| **[Unity PCM Haptics](interfaces/unity/PCMHaptics/README.md)**       | Complete integration example                   |\n| **[Unreal PCM Haptics](interfaces/unreal/PCMHaptics/README.md)**     | Complete integration example                   |\n\n### External Resources\n\n- **[Meta Haptics Studio](https://developers.meta.com/horizon/resources/haptics-studio)** -\n  Design tool for creating .haptic files\n\n---\n\n## FAQ\n\n### General Questions\n\n**Q: What platforms does Meta Haptics SDK support?**\n\n**A: The SDK is platform-agnostic C/C++ code.** It runs on Windows, macOS,\nLinux, and consoles. Integration examples focus on Meta Quest via OpenXR.\n\n**Q: Can I use this with my existing game engine?**\n\n**A: Yes!** The SDK integrates into Unity, Unreal, FMOD, and Wwise. You can also\nintegrate directly into custom engines—it's just C/C++.\n\n**Q: Do I need Meta hardware to use this?**\n\n**A: No.** While the SDK powers Meta Quest haptics, it's designed to work with\nany vibrotactile actuator. Use the ACF system to tune for your target hardware.\n\n**Q: Is this only for VR?**\n\n**A: No.** The SDK works with any haptic-enabled device: VR controllers, PCVR,\ngame console controllers (PlayStation® DualSense™, Xbox), and more.\n\n### Technical Questions\n\n**Q: When should I use Synthesis vs Amplitude Curve mode?**\n\n**A:**\n\n- **Synthesis Mode** - When the platform supports PCM waveforms (Quest,\n  DualSense). Provides full frequency control.\n- **Amplitude Curve Mode** - When the platform only accepts amplitude values\n  (some Android APIs, simpler consoles).\n\n**Q: How do I tune an ACF for my hardware?**\n\n**A:**\n\n1. Start with a template ACF (e.g., `Generic-Console-PCM.acf`)\n2. Consult your actuator's datasheet for frequency response\n3. Set `frequency_min`/`frequency_max` to the usable range (e.g., 55-200 Hz)\n4. Tune emphasis settings around the resonant frequency (f₀)\n5. Test with real content and adjust by feel\n\nSee the [ACF specification](resources/acf/README.md) for detailed guidance.\n\n**Q: Can I create .haptic files programmatically?**\n\n**A: Yes.** The [.haptic specification](resources/haptic-file-spec.md) defines\nthe data format. You can generate files in any language and validate against the\nspec.\n\n**Q: What's the difference between emphasis and transients?**\n\n**A: They're the same concept, different terminology.** \"Emphasis\" is the term\nused in the renderer API, \"transient\" is used in haptic design (short,\nclick-like events).\n\n### Compatibility Questions\n\n**Q: Can I use .haptic files created in Meta Haptics Studio?**\n\n**A: Absolutely!** That's the primary design workflow. Studio exports .haptic\nfiles that this SDK renders at runtime.\n\n---\n\n## Contributing\n\nWe welcome contributions! Whether you're fixing bugs, adding platform examples,\nor improving documentation, your help is greatly appreciated. To set\nexpectations: the maintainers of this repository are committed to strong\nstewardship of its technical direction and feature set. As a result, not every\nsuggestion or contribution may be accepted. However, please don't let that\ndiscourage you: we're a friendly team and always happy to discuss your ideas for\nimprovements!\n\nThank you for your interest in making this project better.\n\nSee our [Contribution Guidelines](CONTRIBUTING.md) for more information.\n\n### Code of Conduct\n\nSee our [Code of Conduct](CODE_OF_CONDUCT.md)\n\n---\n\n## License\n\nMeta Haptics SDK is released under the MIT License. See [LICENSE](LICENSE) for\ndetails.\n\n---\n\n**Need help?**\n\nOpen an issue or check our [documentation](#documentation).\n\n**Ready to design haptics?**\n\nDownload\n[Meta Haptics Studio](https://developers.meta.com/horizon/resources/haptics-studio).\n\n---\n\nBuilt with love by Meta's IxI Haptics team (formerly Lofelt ❤️)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacebook%2Fmeta-haptics-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffacebook%2Fmeta-haptics-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacebook%2Fmeta-haptics-sdk/lists"}