AirMotion 🎧⚡

Spatial Motion Telemetry & 3D Head Tracking Studio for macOS

AirMotion is a high-performance native macOS developer tool and spatial telemetry studio that streams, visualizes, graphs, and records live 3D head-tracking motion data from Apple headphones (AirPods Pro/Max, Beats Fit/Studio Pro) in real time.

Features • Supported Hardware • Quick Start • Data Export Format • Architecture

---

💡 Why AirMotion?

Most consumer motion tools wrap head tracking in closed fitness or audio spatializer demos. AirMotion is designed explicitly as an open-source, developer-first telemetry studio for researchers, game developers, spatial audio engineers, and robotics builders who need:

• Raw, unfiltered hardware sensor streams directly from Apple's H1/H2 motion coprocessors (CMHeadphoneMotionManager).
• Zero simulated/dummy data fallback — strictly reflects physical hardware states.
• High-frequency CSV / JSON recording with sub-millisecond precision ISO8601 timestamps.
• 100% Native Swift Architecture — 60 FPS SwiftUI + SceneKit + Apple Charts with zero Electron or web wrappers.

---

✨ Key Features

🧊 1. Interactive 3D Head Pose Visualizer

• Dark Obsidian Cyber Bust: Procedural SceneKit 3D mannequin head paired with an anodized Space Grey AirPods Max model.
• Spatial Gimbal Rings: High-contrast, color-coded orientation rings:
  • 🔴 Pitch (Lateral X-Axis)
  • 🔵 Roll (Longitudinal Y-Axis)
  • 🟢 Yaw (Vertical Z-Axis)
• 100% Unobstructed Viewport: All sensitivity sliders and orientation telemetry live in a dedicated glassmorphic bottom control tray that never covers the 3D model.
• Zero Boresight Calibration: One-click reference angle reset (Zero Boresight) for relative orientation tracking.

🎧 2. Dynamic CoreAudio Device Detection

• Automatically queries the active system audio output name via macOS CoreAudio (AudioObjectGetPropertyData).
• Displays exact connected hardware (e.g. "Soham's AirPods Pro", "AirPods Max").
• Surface explicit hardware status badges (Connected, Disconnected, Worn In-Ear Prompt).

📈 3. Live Multi-Series Scrolling Charts

• Real-time line graphs built with Apple's native Charts framework for:
  • Euler Angles (Pitch / Roll / Yaw in Degrees or Radians)
  • User Acceleration ($X / Y / Z$ in Gs)
  • Rotation Rate / Gyroscope ($X / Y / Z$ in rad/s or °/s)
  • Attitude Quaternions ($W / X / Y / Z$)
• Features: Time window selection ($5\text{s}$ to $60\text{s}$), Pause / Resume freeze frame, and Export PNG graph snapshot via ImageRenderer.

💾 4. High-Precision Motion Data Recorder

• Record continuous raw telemetry streams at up to $100\text{ Hz}$.
• Export directly to CSV or JSON using macOS native NSSavePanel.

⚡ 5. Real-Time Telemetry & Performance HUD

• Always-visible bottom status overlay monitoring:
  • Update Frequency (Hz)
  • Stream Latency (ms)
  • UI Frame Rate (60 FPS)
  • Total Samples & Received Packets Counter

---

🎧 Supported Hardware

AirMotion works out of the box with all Apple motion-enabled headphones:

• 🎧 AirPods Pro (1st & 2nd Generation)
• 🎧 AirPods Max
• 🎧 AirPods (3rd & 4th Generation with Head Tracking)
• 🎧 Beats Fit Pro
• 🎧 Beats Studio Pro

---

🚀 Quick Start

Prerequisites

• macOS 14.0 (Sonoma) or later.
• Swift 5.9+ (installed with Xcode Command Line Tools).

1. One-Line Build & Run

# Clone repository
git clone https://github.com/ombichave999/AirMotion.git
cd AirMotion

# Build executable & run app bundle
chmod +x Scripts/*.sh
./Scripts/compile_and_run.sh

2. Manual SPM Build & Packaging

# Compile release binary
swift build -c release

# Package standalone .app bundle
./Scripts/package_app.sh

# Open application
open build/AirMotion.app

---

📊 Data Recording & Export Format

Exported CSV files contain the following fields per sample:

Column Header	Description	Data Type / Unit
Timestamp	ISO8601 UTC timestamp with fractional seconds	String (e.g. 2026-07-26T00:15:30.123Z)
RelativeTimestamp	Elapsed seconds since session start	Float (Seconds)
Pitch_Rad / Pitch_Deg	Lateral X-axis pitch rotation	Radians / Degrees
Roll_Rad / Roll_Deg	Longitudinal Y-axis roll rotation	Radians / Degrees
Yaw_Rad / Yaw_Deg	Vertical Z-axis yaw rotation	Radians / Degrees
Quat_X, Quat_Y, Quat_Z, Quat_W	Normalized 3D attitude quaternion	Float (0.0 to 1.0)
Gravity_X, Gravity_Y, Gravity_Z	Gravity vector acceleration components	Gs ($1\text{G} \approx 9.81\text{ m/s}^2$)
UserAccel_X, UserAccel_Y, UserAccel_Z	Linear acceleration excluding gravity	Gs
RotRate_X, RotRate_Y, RotRate_Z	Angular rotation rate	rad/s or °/s

---

🏛️ Architecture

AirMotion/
├── Package.swift               # SwiftPM manifest (Zero Xcode project file required)
├── Scripts/
│   ├── package_app.sh          # Application bundle packager & codesign script
│   └── compile_and_run.sh      # Build & launch script
└── Sources/AirMotion/
    ├── App/                    # App entrypoint & Navigation split view
    ├── Core/                   # Motion Manager, Audio Helper, Recorder & Telemetry
    ├── Models/                 # Immutable MotionSample & Status structs
    └── Views/
        ├── Common/             # GlassCard, PerformanceOverlay, StatusBadge
        ├── Dashboard/          # Main dashboard cards & telemetry metrics
        ├── Graphs/             # Multi-series scrolling Charts & PNG export
        ├── LiveMotion/         # Real-time numerical gauges
        ├── Recording/          # Session recording & export panel
        ├── Settings/           # App settings & sampling rate toggles
        └── Visualizer3D/       # SceneKit 3D mannequin & spatial gimbal rings

---

📜 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Built with ❤️ for the macOS Spatial Audio & Developer Community.