CMHeadphoneMotionManager¶

Streams fused head motion data from AirPods Pro / AirPods Max / AirPods 3rd gen and later.

Description¶

Wraps Apple’s CMHeadphoneMotionManager. Provides CMDeviceMotion samples representing head pose when compatible headphones are connected. Useful for head-tracked audio, spatial UI, or letting the user look around with their head while their hands are free.

Requires the ``NSMotionUsageDescription`` Info.plist key (and on macOS, the matching entitlement).

Platform availability: Real implementation on iOS 14+ and macOS 14+. On other platforms is_device_motion_available is false and start_device_motion_updates() emits update_failed.

See Apple’s CMHeadphoneMotionManager reference.

Tutorials¶

CoreMotion Integration Guide

Properties¶

CMDeviceMotion	device_motion
bool	is_device_motion_active
bool	is_device_motion_available

Methods¶

int	authorization_status() static
void	start_device_motion_updates()
void	stop_device_motion_updates()

Signals¶

connected() 🔗

Emitted when compatible headphones connect and begin providing motion data.

device_motion_updated(deviceMotion: CMDeviceMotion) 🔗

Emitted on the main thread when a new headphone motion sample is available.

disconnected() 🔗

Emitted when the previously connected headphones disconnect.

update_failed(message: String) 🔗

Emitted when CoreMotion reports an error or when the API is unavailable on the current platform.

Property Descriptions¶

CMDeviceMotion device_motion 🔗

CMDeviceMotion get_device_motion()

The most recent headphone motion sample, or null if none is available.

bool is_device_motion_active 🔗

bool get_is_device_motion_active()

true when updates are currently being delivered.

bool is_device_motion_available 🔗

bool get_is_device_motion_available()

true when compatible headphones are currently connected and providing motion data.

Method Descriptions¶

int authorization_status() static 🔗

Returns Apple’s CMAuthorizationStatus integer (0 = notDetermined, 1 = restricted, 2 = denied, 3 = authorized). Available on iOS 17.4 / macOS 14.4 and later; returns 0 on earlier versions.

void start_device_motion_updates() 🔗

Begins delivering CMDeviceMotion samples for the connected headphones via device_motion_updated. If no compatible headphones are connected, samples will begin to arrive once a pair connects.

void stop_device_motion_updates() 🔗

Stops headphone motion updates.