react-native-nitro-compass 1.0.9 → 1.1.0

package/README.md

@@ -52,6 +52,7 @@ NitroCompass.isStarted(): boolean
 NitroCompass.hasCompass(): boolean
 
 NitroCompass.setFilter(degrees: number): void
+NitroCompass.setSmoothing(alpha: number): void
 NitroCompass.getCurrentHeading(): CompassSample | undefined
 NitroCompass.getDiagnostics(): SensorDiagnostics | undefined
 NitroCompass.setDeclination(degrees: number): void
@@ -70,6 +71,7 @@ interface SensorDiagnostics { sensor: SensorKind }
 ```
 
 - `filterDegrees` — minimum change between successive samples before the next one is delivered. Pass `0` for "every event"; typical UI values are `1`–`3`. Use `setFilter()` to change live without tearing down the subscription.
+- `setSmoothing(alpha)` — low-pass smoothing factor (EMA α) applied to heading samples on Android. Range `(0, 1]`, default `0.2` (~100 ms time constant at 50 Hz). `1.0` disables smoothing; smaller values smooth more (kills jitter, adds a touch of latency). **No-op on iOS** — `CLLocationManager` filters internally with Apple's own algorithm, so layering an EMA on top would only add latency. See [Smoothing](#smoothing) below.
 - `start()` is idempotent in the destructive sense — calling it while already started silently replaces the previous subscription with the new callback. `stop()` is idempotent and safe from inside the `onHeading` callback.
 - `getDiagnostics()` reports which sensor would produce headings on this device — useful for explaining quality differences (e.g. a phone falling back to `geomagneticRotationVector` will be more susceptible to magnetic interference than one using `rotationVector`). Safe to call before `start()`.
 - `accuracy` is a numeric uncertainty (degrees). On iOS it comes from `CLHeading.headingAccuracy` directly. On Android it comes from `event.values[4]` of the rotation-vector sensor; if the sensor stack does not publish that (rare), the module falls back to a coarse degree estimate from `SensorManager.SENSOR_STATUS_*` (`HIGH→5°`, `MEDIUM→15°`, `LOW→30°`).
@@ -77,7 +79,12 @@ interface SensorDiagnostics { sensor: SensorKind }
 
 ### Calibration
 
-`setOnCalibrationNeeded(cb)` registers a callback fired whenever the calibration bucket transitions. Buckets are derived from numeric accuracy on both platforms using the same thresholds, so values agree across iOS and Android: `<5°` → `'high'`, `<15°` → `'medium'`, `<30°` → `'low'`, otherwise `'unreliable'`. On iOS, the system's "wave the device in a figure-8" prompt is suppressed and reported to your callback as `'unreliable'` — show your own UI when you receive that bucket.
+`setOnCalibrationNeeded(cb)` registers a callback fired whenever the calibration bucket transitions. Each platform's bucket is derived from its **native** accuracy semantics, since the underlying values are not directly comparable:
+
+- **iOS** uses `CLHeading.headingAccuracy` (degrees). Apple is conservative — even well-calibrated iPhones typically report `10–15°` and rarely below `5°` (per [Apple staff on the developer forums](https://developer.apple.com/forums/thread/79687)). Buckets: `<20°` → `'high'`, `<35°` → `'medium'`, `<55°` → `'low'`, otherwise `'unreliable'`. The system's "wave the device in a figure-8" prompt is suppressed and reported to your callback as `'unreliable'` — show your own UI when you receive that bucket.
+- **Android** uses `SensorManager.SENSOR_STATUS_*` from `onAccuracyChanged` directly (`HIGH` / `MEDIUM` / `LOW` / `UNRELIABLE`); when `event.values[4]` of the rotation vector publishes a per-sample degree estimate, that's used with thresholds `<5°` / `<15°` / `<30°`. **When magnetic interference is currently detected, the surfaced bucket is downgraded by one notch** (`HIGH→MEDIUM`, `MEDIUM→LOW`, `LOW→UNRELIABLE`) — Android's gyro+accel sensor fusion can keep the OS rotation-vector bucket high even while the magnetometer is being skewed, and surfacing `quality='high'` alongside `interfering=true` is contradictory UX.
+
+Both platforms can plausibly emit `'high'` on a clean device — the threshold split just reflects each OS's reporting style.
 
 ```ts
 NitroCompass.setOnCalibrationNeeded((q) => {
@@ -87,7 +94,9 @@ NitroCompass.setOnCalibrationNeeded((q) => {
 
 ### Magnetic interference
 
-`setOnInterferenceDetected(cb)` fires `true` when the raw magnetic field magnitude leaves the normal Earth band (~20–70 µT) and `false` when it returns. Typical sources are laptops, monitors, car engines, and large steel structures — these can skew heading by tens of degrees while the calibration bucket still reads `'medium'` or better, so this is complementary to the calibration callback rather than a replacement.
+`setOnInterferenceDetected(cb)` fires `true` when the raw magnetic field magnitude leaves the normal Earth band (~20–70 µT) and `false` when it returns. Typical sources are laptops, monitors, car engines, and large steel structures — these can skew heading by tens of degrees.
+
+Interference is surfaced two ways: (1) directly via this callback, and (2) on Android, the calibration bucket emitted by `setOnCalibrationNeeded` is downgraded by one notch while interference is detected (see the Calibration section above). On iOS, only the direct callback fires — `CLLocationManager`'s own accuracy reporting already responds to magnetometer disturbance, so a separate downgrade would double-count.
 
 ```ts
 NitroCompass.setOnInterferenceDetected((interfering) => {
@@ -116,6 +125,20 @@ NitroCompass.setDeclination(declination)
 
 Pass `0` to revert to magnetic. Declination survives `stop()`/`start()` cycles.
 
+### Smoothing
+
+Android's raw `TYPE_ROTATION_VECTOR` output jitters by `±1–3°` even at rest, which produces a visibly twitchy compass dial. iOS's `CLLocationManager` filters internally; Android does not. The library applies a circular EMA low-pass filter on `(sin θ, cos θ)` (handles `359°→0°` wraparound cleanly) before delivering samples, with `α = 0.2` by default — the same value used in [phishman3579/android-compass](https://github.com/phishman3579/android-compass/blob/master/src/com/jwetherell/compass/common/LowPassFilter.java) and within the range used by [Trail Sense](https://github.com/kylecorry31/Trail-Sense)'s production compass code.
+
+Tune live:
+
+```ts
+NitroCompass.setSmoothing(0.2)   // default — kills jitter, ~100 ms latency
+NitroCompass.setSmoothing(0.4)   // snappier, more visible jitter
+NitroCompass.setSmoothing(1.0)   // disabled — every sample passes through
+```
+
+`setSmoothing` is a no-op on iOS — Apple's stack already filters heading internally, so layering an EMA on top would only add latency without removing noise.
+
 ### Background pause
 
 By default the underlying sensor / location-manager subscription is silently paused while the app is backgrounded and resumed when it returns to the foreground; the JS callback and any declination set via `setDeclination` are preserved across the pause. To opt out (e.g. for a fitness tracker that needs heading while screen-off):
@@ -134,6 +157,7 @@ import { useCompass } from 'react-native-nitro-compass'
 function CompassView() {
   const { reading, quality, interfering, hasCompass } = useCompass({
     filterDegrees: 1,
+    smoothingAlpha: 0.2,
     declination: 0,
     pauseOnBackground: true,
     enabled: true,
@@ -161,11 +185,12 @@ function useCompass(options?: UseCompassOptions): UseCompassResult
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
 | `filterDegrees` | `number` | `1` | Minimum change between successive samples in degrees. Pass `0` for "every event". Updated live via `NitroCompass.setFilter()` whenever the prop changes. |
+| `smoothingAlpha` | `number` | `0.2` | Low-pass smoothing factor (EMA α) on Android. `1.0` disables smoothing; smaller values smooth more. No-op on iOS. See [Smoothing](#smoothing). |
 | `declination` | `number` | `0` | Magnetic-to-true offset in signed degrees. Pull from a model like [`geomagnetism`](https://github.com/kahirokunn/geomagnetism) keyed on the user's lat/lon. When non-zero, every emitted sample is true-north. |
 | `pauseOnBackground` | `boolean` | `true` | Pause the underlying sensor / location-manager subscription while the app is backgrounded and resume on foreground. |
 | `enabled` | `boolean` | `true` | Toggle the heading subscription without unmounting. When `false`, `reading` stops updating but calibration and interference observation continue (so you can still show warnings). |
 
-`filterDegrees`, `declination`, and `pauseOnBackground` map to global state on `NitroCompass` — if multiple hooks set them, last-write-wins.
+`filterDegrees`, `smoothingAlpha`, `declination`, and `pauseOnBackground` map to global state on `NitroCompass` — if multiple hooks set them, last-write-wins.
 
 #### Result
 

package/android/src/main/java/com/margelo/nitro/nitrocompass/HybridNitroCompass.kt

@@ -56,6 +56,16 @@ class HybridNitroCompass : HybridNitroCompassSpec() {
     // structural steel routinely push readings well above 100 µT.
     private const val EARTH_FIELD_MIN_UT = 20.0
     private const val EARTH_FIELD_MAX_UT = 70.0
+
+    // Default low-pass smoothing for the rotation-vector output. iOS's
+    // CLLocationManager already filters heading internally; the raw
+    // Android rotation vector does not, so the dial visibly jitters
+    // by 1–3° at rest. Smoothing (sin θ, cos θ) instead of θ avoids
+    // 359°→0° wraparound artifacts. α=0.2 gives a ~5-sample time
+    // constant — at SENSOR_DELAY_GAME (~20ms) that's ~100ms of lag,
+    // imperceptible compared to the noise it removes. Tunable live
+    // via setSmoothing().
+    private const val DEFAULT_SMOOTHING_ALPHA = 0.2
   }
 
   @Volatile private var filterDeg: Double = 1.0
@@ -70,6 +80,17 @@ class HybridNitroCompass : HybridNitroCompassSpec() {
   @Volatile private var lastEventNs: Long = 0L
   @Volatile private var lastInterference: Boolean? = null
   @Volatile private var currentActivityRef: WeakReference<Activity>? = null
+  @Volatile private var smoothedSin: Double = Double.NaN
+  @Volatile private var smoothedCos: Double = Double.NaN
+  @Volatile private var smoothingAlpha: Double = DEFAULT_SMOOTHING_ALPHA
+  // Tracks whether the rotation-vector sensor publishes a per-sample
+  // accuracy in `event.values[4]`. Many devices don't, in which case the
+  // synthetic degree floor derived from SENSOR_STATUS_* is the only
+  // accuracy signal available — and we have to keep it updated.
+  @Volatile private var hasPerSampleAccuracy: Boolean = false
+  // Last raw quality from the OS, before the interference downgrade is
+  // applied. Used to re-derive `lastQuality` when interference toggles.
+  @Volatile private var lastRawQuality: AccuracyQuality? = null
 
   private val rotationMatrix = FloatArray(16)
   private val remappedMatrix = FloatArray(16)
@@ -131,6 +152,8 @@ class HybridNitroCompass : HybridNitroCompassSpec() {
       lastSample = null
       lastQuality = null
 
+      hasPerSampleAccuracy = false
+      lastRawQuality = null
       registerLifecycleCallbacks()
       subscribeLocked()
     }
@@ -155,6 +178,10 @@ class HybridNitroCompass : HybridNitroCompassSpec() {
     filterDeg = degrees.coerceAtLeast(0.0)
   }
 
+  override fun setSmoothing(alpha: Double) {
+    smoothingAlpha = alpha.coerceIn(0.0, 1.0)
+  }
+
   override fun getDiagnostics(): SensorDiagnostics? {
     val sm = NitroModules.applicationContext?.getSystemService(Context.SENSOR_SERVICE) as? SensorManager
       ?: return null
@@ -254,6 +281,8 @@ class HybridNitroCompass : HybridNitroCompassSpec() {
     activeListener = listener
     isSubscribed = true
 
+    smoothedSin = Double.NaN
+    smoothedCos = Double.NaN
     lastEventNs = 0L
     watchdogHandler.removeCallbacks(watchdogRunnable)
     watchdogHandler.postDelayed(watchdogRunnable, WATCHDOG_PERIOD_MS)
@@ -380,9 +409,11 @@ class HybridNitroCompass : HybridNitroCompassSpec() {
 
     var heading = Math.toDegrees(orientation[0].toDouble())
     if (heading < 0.0) heading += 360.0
+    heading = smoothHeading(heading)
 
     if (event.values.size > 4 && event.values[4] >= 0f) {
       val acc = Math.toDegrees(event.values[4].toDouble())
+      hasPerSampleAccuracy = true
       lastAccuracyDeg = acc
       fireCalibration(qualityFor(acc))
     }
@@ -409,6 +440,14 @@ class HybridNitroCompass : HybridNitroCompassSpec() {
     if (lastInterference == isInterference) return
     lastInterference = isInterference
     interferenceCb?.invoke(isInterference)
+    // External interference makes the heading less trustworthy even when
+    // the OS rotation-vector accuracy hasn't downgraded (gyro+accel can
+    // keep its bucket high while the magnetometer is being skewed). Pump
+    // the last raw quality back through fireCalibration so the
+    // interference-aware downgrade is applied, and refresh the synthetic
+    // degree value to match.
+    lastRawQuality?.let { fireCalibration(it) }
+    if (!hasPerSampleAccuracy) refreshSyntheticAccuracy()
   }
 
   private fun handleAccuracyChanged(accuracy: Int) {
@@ -418,15 +457,34 @@ class HybridNitroCompass : HybridNitroCompassSpec() {
       SensorManager.SENSOR_STATUS_ACCURACY_LOW -> AccuracyQuality.LOW
       else -> AccuracyQuality.UNRELIABLE
     }
-    if (lastAccuracyDeg < 0.0) {
-      lastAccuracyDeg = when (quality) {
-        AccuracyQuality.HIGH -> 5.0
-        AccuracyQuality.MEDIUM -> 15.0
-        AccuracyQuality.LOW -> 30.0
-        AccuracyQuality.UNRELIABLE -> -1.0
-      }
-    }
     fireCalibration(quality)
+    if (!hasPerSampleAccuracy) refreshSyntheticAccuracy()
+  }
+
+  private fun smoothHeading(degrees: Double): Double {
+    val rad = Math.toRadians(degrees)
+    val s = Math.sin(rad)
+    val c = Math.cos(rad)
+    val ss = smoothedSin
+    val cs = smoothedCos
+    if (ss.isNaN() || cs.isNaN()) {
+      smoothedSin = s
+      smoothedCos = c
+      return degrees
+    }
+    val a = smoothingAlpha
+    if (a >= 1.0) {
+      smoothedSin = s
+      smoothedCos = c
+      return degrees
+    }
+    val newSin = a * s + (1.0 - a) * ss
+    val newCos = a * c + (1.0 - a) * cs
+    smoothedSin = newSin
+    smoothedCos = newCos
+    var deg = Math.toDegrees(Math.atan2(newSin, newCos))
+    if (deg < 0.0) deg += 360.0
+    return deg
   }
 
   private fun qualityFor(accuracyDeg: Double): AccuracyQuality {
@@ -439,10 +497,44 @@ class HybridNitroCompass : HybridNitroCompassSpec() {
     }
   }
 
+  private fun degreesFor(quality: AccuracyQuality): Double = when (quality) {
+    AccuracyQuality.HIGH -> 5.0
+    AccuracyQuality.MEDIUM -> 15.0
+    AccuracyQuality.LOW -> 30.0
+    AccuracyQuality.UNRELIABLE -> -1.0
+  }
+
+  // Magnetic interference is a separate signal from rotation-vector
+  // accuracy on Android — gyro+accel can keep the OS bucket "HIGH" even
+  // while the magnetometer is being skewed by a laptop / car / steel.
+  // Reporting `quality=high` while `interfering=true` is contradictory
+  // UX, so we downgrade the surfaced bucket by one notch when
+  // interference is currently detected.
+  private fun effectiveQuality(raw: AccuracyQuality): AccuracyQuality {
+    if (lastInterference != true) return raw
+    return when (raw) {
+      AccuracyQuality.HIGH -> AccuracyQuality.MEDIUM
+      AccuracyQuality.MEDIUM -> AccuracyQuality.LOW
+      AccuracyQuality.LOW -> AccuracyQuality.UNRELIABLE
+      AccuracyQuality.UNRELIABLE -> AccuracyQuality.UNRELIABLE
+    }
+  }
+
+  // For devices that don't publish a per-sample accuracy in
+  // event.values[4], the only accuracy signal is the OS bucket. Map the
+  // current effective bucket back to a representative degree value so
+  // CompassSample.accuracy reflects interference too.
+  private fun refreshSyntheticAccuracy() {
+    val raw = lastRawQuality ?: return
+    lastAccuracyDeg = degreesFor(effectiveQuality(raw))
+  }
+
   private fun fireCalibration(quality: AccuracyQuality) {
-    if (quality == lastQuality) return
-    lastQuality = quality
-    calibrationCb?.invoke(quality)
+    lastRawQuality = quality
+    val effective = effectiveQuality(quality)
+    if (effective == lastQuality) return
+    lastQuality = effective
+    calibrationCb?.invoke(effective)
   }
 
   private fun currentSurfaceRotation(): Int {

package/ios/HybridNitroCompass.swift

@@ -183,6 +183,11 @@ class HybridNitroCompass: HybridNitroCompassSpec {
     }
   }
 
+  // CLLocationManager filters heading internally with Apple's own
+  // algorithm; layering an EMA on top would only add latency. Kept as a
+  // no-op so cross-platform JS callers can call it unconditionally.
+  func setSmoothing(alpha: Double) throws {}
+
   func getDiagnostics() throws -> SensorDiagnostics? {
     guard CLLocationManager.headingAvailable() else { return nil }
     return SensorDiagnostics(sensor: .corelocation)
@@ -363,14 +368,19 @@ class HybridNitroCompass: HybridNitroCompassSpec {
     let sample = CompassSample(heading: heading, accuracy: accuracy)
     lastSample = sample
 
+    // CLLocationManager.headingAccuracy is conservative — even a
+    // well-calibrated compass usually reports 5–15°, and values under
+    // 5° are basically never produced. Bucket against the realistic
+    // distribution so `.high` is reachable, mirroring how Android maps
+    // SENSOR_STATUS_ACCURACY_HIGH.
     let quality: AccuracyQuality
     if accuracy < 0 {
       quality = .unreliable
-    } else if accuracy < 5 {
+    } else if accuracy < 20 {
       quality = .high
-    } else if accuracy < 15 {
+    } else if accuracy < 35 {
       quality = .medium
-    } else if accuracy < 30 {
+    } else if accuracy < 55 {
       quality = .low
     } else {
       quality = .unreliable

package/lib/commonjs/hook.js

@@ -17,6 +17,7 @@ var _multiplex = require("./multiplex");
 function useCompass(options = {}) {
   const {
     filterDegrees = 1,
+    smoothingAlpha = 0.2,
     declination = 0,
     pauseOnBackground = true,
     enabled = true
@@ -35,6 +36,9 @@ function useCompass(options = {}) {
   (0, _react.useEffect)(() => {
     _native.NitroCompass.setFilter(filterDegrees);
   }, [filterDegrees]);
+  (0, _react.useEffect)(() => {
+    _native.NitroCompass.setSmoothing(smoothingAlpha);
+  }, [smoothingAlpha]);
   (0, _react.useEffect)(() => {
     _native.NitroCompass.setDeclination(declination);
   }, [declination]);

package/lib/commonjs/hook.js.map

@@ -1 +1 @@
-{"version":3,"names":["_react","require","_native","_multiplex","useCompass","options","filterDegrees","declination","pauseOnBackground","enabled","reading","setReading","useState","quality","setQuality","interfering","setInterfering","hasCompass","NitroCompass","diagnostics","getDiagnostics","filterRef","useRef","current","useEffect","setFilter","setDeclination","setPauseOnBackground","addCalibrationListener","addInterferenceListener","off","addHeadingListener"],"sourceRoot":"../../src","sources":["hook.ts"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AAMA,IAAAC,OAAA,GAAAD,OAAA;AACA,IAAAE,UAAA,GAAAF,OAAA;AA+CA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASG,UAAUA,CACxBC,OAA0B,GAAG,CAAC,CAAC,EACb;EAClB,MAAM;IACJC,aAAa,GAAG,CAAC;IACjBC,WAAW,GAAG,CAAC;IACfC,iBAAiB,GAAG,IAAI;IACxBC,OAAO,GAAG;EACZ,CAAC,GAAGJ,OAAO;EAEX,MAAM,CAACK,OAAO,EAAEC,UAAU,CAAC,GAAG,IAAAC,eAAQ,EAAuB,IAAI,CAAC;EAClE,MAAM,CAACC,OAAO,EAAEC,UAAU,CAAC,GAAG,IAAAF,eAAQ,EAAyB,IAAI,CAAC;EACpE,MAAM,CAACG,WAAW,EAAEC,cAAc,CAAC,GAAG,IAAAJ,eAAQ,EAAC,KAAK,CAAC;EAErD,MAAM,CAACK,UAAU,CAAC,GAAG,IAAAL,eAAQ,EAAC,MAAMM,oBAAY,CAACD,UAAU,CAAC,CAAC,CAAC;EAC9D,MAAM,CAACE,WAAW,CAAC,GAAG,IAAAP,eAAQ,EAAC,MAAMM,oBAAY,CAACE,cAAc,CAAC,CAAC,CAAC;;EAEnE;EACA;EACA;EACA,MAAMC,SAAS,GAAG,IAAAC,aAAM,EAAChB,aAAa,CAAC;EACvCe,SAAS,CAACE,OAAO,GAAGjB,aAAa;EAEjC,IAAAkB,gBAAS,EAAC,MAAM;IACdN,oBAAY,CAACO,SAAS,CAACnB,aAAa,CAAC;EACvC,CAAC,EAAE,CAACA,aAAa,CAAC,CAAC;EAEnB,IAAAkB,gBAAS,EAAC,MAAM;IACdN,oBAAY,CAACQ,cAAc,CAACnB,WAAW,CAAC;EAC1C,CAAC,EAAE,CAACA,WAAW,CAAC,CAAC;EAEjB,IAAAiB,gBAAS,EAAC,MAAM;IACdN,oBAAY,CAACS,oBAAoB,CAACnB,iBAAiB,CAAC;EACtD,CAAC,EAAE,CAACA,iBAAiB,CAAC,CAAC;EAEvB,IAAAgB,gBAAS,EAAC,MAAM;IACd,IAAI,CAACP,UAAU,EAAE;IACjB,OAAO,IAAAW,iCAAsB,EAACd,UAAU,CAAC;EAC3C,CAAC,EAAE,CAACG,UAAU,CAAC,CAAC;EAEhB,IAAAO,gBAAS,EAAC,MAAM;IACd,IAAI,CAACP,UAAU,EAAE;IACjB,OAAO,IAAAY,kCAAuB,EAACb,cAAc,CAAC;EAChD,CAAC,EAAE,CAACC,UAAU,CAAC,CAAC;EAEhB,IAAAO,gBAAS,EAAC,MAAM;IACd,IAAI,CAACP,UAAU,IAAI,CAACR,OAAO,EAAE;IAC7B,MAAMqB,GAAG,GAAG,IAAAC,6BAAkB,EAACpB,UAAU,CAAC;IAC1C;IACA;IACAO,oBAAY,CAACO,SAAS,CAACJ,SAAS,CAACE,OAAO,CAAC;IACzC,OAAOO,GAAG;IACV;EACF,CAAC,EAAE,CAACb,UAAU,EAAER,OAAO,CAAC,CAAC;EAEzB,OAAO;IAAEC,OAAO;IAAEG,OAAO;IAAEE,WAAW;IAAEE,UAAU;IAAEE;EAAY,CAAC;AACnE","ignoreList":[]}
+{"version":3,"names":["_react","require","_native","_multiplex","useCompass","options","filterDegrees","smoothingAlpha","declination","pauseOnBackground","enabled","reading","setReading","useState","quality","setQuality","interfering","setInterfering","hasCompass","NitroCompass","diagnostics","getDiagnostics","filterRef","useRef","current","useEffect","setFilter","setSmoothing","setDeclination","setPauseOnBackground","addCalibrationListener","addInterferenceListener","off","addHeadingListener"],"sourceRoot":"../../src","sources":["hook.ts"],"mappings":";;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AAMA,IAAAC,OAAA,GAAAD,OAAA;AACA,IAAAE,UAAA,GAAAF,OAAA;AAyDA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASG,UAAUA,CACxBC,OAA0B,GAAG,CAAC,CAAC,EACb;EAClB,MAAM;IACJC,aAAa,GAAG,CAAC;IACjBC,cAAc,GAAG,GAAG;IACpBC,WAAW,GAAG,CAAC;IACfC,iBAAiB,GAAG,IAAI;IACxBC,OAAO,GAAG;EACZ,CAAC,GAAGL,OAAO;EAEX,MAAM,CAACM,OAAO,EAAEC,UAAU,CAAC,GAAG,IAAAC,eAAQ,EAAuB,IAAI,CAAC;EAClE,MAAM,CAACC,OAAO,EAAEC,UAAU,CAAC,GAAG,IAAAF,eAAQ,EAAyB,IAAI,CAAC;EACpE,MAAM,CAACG,WAAW,EAAEC,cAAc,CAAC,GAAG,IAAAJ,eAAQ,EAAC,KAAK,CAAC;EAErD,MAAM,CAACK,UAAU,CAAC,GAAG,IAAAL,eAAQ,EAAC,MAAMM,oBAAY,CAACD,UAAU,CAAC,CAAC,CAAC;EAC9D,MAAM,CAACE,WAAW,CAAC,GAAG,IAAAP,eAAQ,EAAC,MAAMM,oBAAY,CAACE,cAAc,CAAC,CAAC,CAAC;;EAEnE;EACA;EACA;EACA,MAAMC,SAAS,GAAG,IAAAC,aAAM,EAACjB,aAAa,CAAC;EACvCgB,SAAS,CAACE,OAAO,GAAGlB,aAAa;EAEjC,IAAAmB,gBAAS,EAAC,MAAM;IACdN,oBAAY,CAACO,SAAS,CAACpB,aAAa,CAAC;EACvC,CAAC,EAAE,CAACA,aAAa,CAAC,CAAC;EAEnB,IAAAmB,gBAAS,EAAC,MAAM;IACdN,oBAAY,CAACQ,YAAY,CAACpB,cAAc,CAAC;EAC3C,CAAC,EAAE,CAACA,cAAc,CAAC,CAAC;EAEpB,IAAAkB,gBAAS,EAAC,MAAM;IACdN,oBAAY,CAACS,cAAc,CAACpB,WAAW,CAAC;EAC1C,CAAC,EAAE,CAACA,WAAW,CAAC,CAAC;EAEjB,IAAAiB,gBAAS,EAAC,MAAM;IACdN,oBAAY,CAACU,oBAAoB,CAACpB,iBAAiB,CAAC;EACtD,CAAC,EAAE,CAACA,iBAAiB,CAAC,CAAC;EAEvB,IAAAgB,gBAAS,EAAC,MAAM;IACd,IAAI,CAACP,UAAU,EAAE;IACjB,OAAO,IAAAY,iCAAsB,EAACf,UAAU,CAAC;EAC3C,CAAC,EAAE,CAACG,UAAU,CAAC,CAAC;EAEhB,IAAAO,gBAAS,EAAC,MAAM;IACd,IAAI,CAACP,UAAU,EAAE;IACjB,OAAO,IAAAa,kCAAuB,EAACd,cAAc,CAAC;EAChD,CAAC,EAAE,CAACC,UAAU,CAAC,CAAC;EAEhB,IAAAO,gBAAS,EAAC,MAAM;IACd,IAAI,CAACP,UAAU,IAAI,CAACR,OAAO,EAAE;IAC7B,MAAMsB,GAAG,GAAG,IAAAC,6BAAkB,EAACrB,UAAU,CAAC;IAC1C;IACA;IACAO,oBAAY,CAACO,SAAS,CAACJ,SAAS,CAACE,OAAO,CAAC;IACzC,OAAOQ,GAAG;IACV;EACF,CAAC,EAAE,CAACd,UAAU,EAAER,OAAO,CAAC,CAAC;EAEzB,OAAO;IAAEC,OAAO;IAAEG,OAAO;IAAEE,WAAW;IAAEE,UAAU;IAAEE;EAAY,CAAC;AACnE","ignoreList":[]}

package/lib/module/hook.js

@@ -13,6 +13,7 @@ import { addCalibrationListener, addHeadingListener, addInterferenceListener } f
 export function useCompass(options = {}) {
   const {
     filterDegrees = 1,
+    smoothingAlpha = 0.2,
     declination = 0,
     pauseOnBackground = true,
     enabled = true
@@ -31,6 +32,9 @@ export function useCompass(options = {}) {
   useEffect(() => {
     NitroCompass.setFilter(filterDegrees);
   }, [filterDegrees]);
+  useEffect(() => {
+    NitroCompass.setSmoothing(smoothingAlpha);
+  }, [smoothingAlpha]);
   useEffect(() => {
     NitroCompass.setDeclination(declination);
   }, [declination]);

package/lib/module/hook.js.map

@@ -1 +1 @@
-{"version":3,"names":["useEffect","useRef","useState","NitroCompass","addCalibrationListener","addHeadingListener","addInterferenceListener","useCompass","options","filterDegrees","declination","pauseOnBackground","enabled","reading","setReading","quality","setQuality","interfering","setInterfering","hasCompass","diagnostics","getDiagnostics","filterRef","current","setFilter","setDeclination","setPauseOnBackground","off"],"sourceRoot":"../../src","sources":["hook.ts"],"mappings":";;AAAA,SAASA,SAAS,EAAEC,MAAM,EAAEC,QAAQ,QAAQ,OAAO;AAMnD,SAASC,YAAY,QAAQ,UAAU;AACvC,SACEC,sBAAsB,EACtBC,kBAAkB,EAClBC,uBAAuB,QAClB,aAAa;AA2CpB;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,UAAUA,CACxBC,OAA0B,GAAG,CAAC,CAAC,EACb;EAClB,MAAM;IACJC,aAAa,GAAG,CAAC;IACjBC,WAAW,GAAG,CAAC;IACfC,iBAAiB,GAAG,IAAI;IACxBC,OAAO,GAAG;EACZ,CAAC,GAAGJ,OAAO;EAEX,MAAM,CAACK,OAAO,EAAEC,UAAU,CAAC,GAAGZ,QAAQ,CAAuB,IAAI,CAAC;EAClE,MAAM,CAACa,OAAO,EAAEC,UAAU,CAAC,GAAGd,QAAQ,CAAyB,IAAI,CAAC;EACpE,MAAM,CAACe,WAAW,EAAEC,cAAc,CAAC,GAAGhB,QAAQ,CAAC,KAAK,CAAC;EAErD,MAAM,CAACiB,UAAU,CAAC,GAAGjB,QAAQ,CAAC,MAAMC,YAAY,CAACgB,UAAU,CAAC,CAAC,CAAC;EAC9D,MAAM,CAACC,WAAW,CAAC,GAAGlB,QAAQ,CAAC,MAAMC,YAAY,CAACkB,cAAc,CAAC,CAAC,CAAC;;EAEnE;EACA;EACA;EACA,MAAMC,SAAS,GAAGrB,MAAM,CAACQ,aAAa,CAAC;EACvCa,SAAS,CAACC,OAAO,GAAGd,aAAa;EAEjCT,SAAS,CAAC,MAAM;IACdG,YAAY,CAACqB,SAAS,CAACf,aAAa,CAAC;EACvC,CAAC,EAAE,CAACA,aAAa,CAAC,CAAC;EAEnBT,SAAS,CAAC,MAAM;IACdG,YAAY,CAACsB,cAAc,CAACf,WAAW,CAAC;EAC1C,CAAC,EAAE,CAACA,WAAW,CAAC,CAAC;EAEjBV,SAAS,CAAC,MAAM;IACdG,YAAY,CAACuB,oBAAoB,CAACf,iBAAiB,CAAC;EACtD,CAAC,EAAE,CAACA,iBAAiB,CAAC,CAAC;EAEvBX,SAAS,CAAC,MAAM;IACd,IAAI,CAACmB,UAAU,EAAE;IACjB,OAAOf,sBAAsB,CAACY,UAAU,CAAC;EAC3C,CAAC,EAAE,CAACG,UAAU,CAAC,CAAC;EAEhBnB,SAAS,CAAC,MAAM;IACd,IAAI,CAACmB,UAAU,EAAE;IACjB,OAAOb,uBAAuB,CAACY,cAAc,CAAC;EAChD,CAAC,EAAE,CAACC,UAAU,CAAC,CAAC;EAEhBnB,SAAS,CAAC,MAAM;IACd,IAAI,CAACmB,UAAU,IAAI,CAACP,OAAO,EAAE;IAC7B,MAAMe,GAAG,GAAGtB,kBAAkB,CAACS,UAAU,CAAC;IAC1C;IACA;IACAX,YAAY,CAACqB,SAAS,CAACF,SAAS,CAACC,OAAO,CAAC;IACzC,OAAOI,GAAG;IACV;EACF,CAAC,EAAE,CAACR,UAAU,EAAEP,OAAO,CAAC,CAAC;EAEzB,OAAO;IAAEC,OAAO;IAAEE,OAAO;IAAEE,WAAW;IAAEE,UAAU;IAAEC;EAAY,CAAC;AACnE","ignoreList":[]}
+{"version":3,"names":["useEffect","useRef","useState","NitroCompass","addCalibrationListener","addHeadingListener","addInterferenceListener","useCompass","options","filterDegrees","smoothingAlpha","declination","pauseOnBackground","enabled","reading","setReading","quality","setQuality","interfering","setInterfering","hasCompass","diagnostics","getDiagnostics","filterRef","current","setFilter","setSmoothing","setDeclination","setPauseOnBackground","off"],"sourceRoot":"../../src","sources":["hook.ts"],"mappings":";;AAAA,SAASA,SAAS,EAAEC,MAAM,EAAEC,QAAQ,QAAQ,OAAO;AAMnD,SAASC,YAAY,QAAQ,UAAU;AACvC,SACEC,sBAAsB,EACtBC,kBAAkB,EAClBC,uBAAuB,QAClB,aAAa;AAqDpB;AACA;AACA;AACA;AACA;AACA;AACA;AACA,OAAO,SAASC,UAAUA,CACxBC,OAA0B,GAAG,CAAC,CAAC,EACb;EAClB,MAAM;IACJC,aAAa,GAAG,CAAC;IACjBC,cAAc,GAAG,GAAG;IACpBC,WAAW,GAAG,CAAC;IACfC,iBAAiB,GAAG,IAAI;IACxBC,OAAO,GAAG;EACZ,CAAC,GAAGL,OAAO;EAEX,MAAM,CAACM,OAAO,EAAEC,UAAU,CAAC,GAAGb,QAAQ,CAAuB,IAAI,CAAC;EAClE,MAAM,CAACc,OAAO,EAAEC,UAAU,CAAC,GAAGf,QAAQ,CAAyB,IAAI,CAAC;EACpE,MAAM,CAACgB,WAAW,EAAEC,cAAc,CAAC,GAAGjB,QAAQ,CAAC,KAAK,CAAC;EAErD,MAAM,CAACkB,UAAU,CAAC,GAAGlB,QAAQ,CAAC,MAAMC,YAAY,CAACiB,UAAU,CAAC,CAAC,CAAC;EAC9D,MAAM,CAACC,WAAW,CAAC,GAAGnB,QAAQ,CAAC,MAAMC,YAAY,CAACmB,cAAc,CAAC,CAAC,CAAC;;EAEnE;EACA;EACA;EACA,MAAMC,SAAS,GAAGtB,MAAM,CAACQ,aAAa,CAAC;EACvCc,SAAS,CAACC,OAAO,GAAGf,aAAa;EAEjCT,SAAS,CAAC,MAAM;IACdG,YAAY,CAACsB,SAAS,CAAChB,aAAa,CAAC;EACvC,CAAC,EAAE,CAACA,aAAa,CAAC,CAAC;EAEnBT,SAAS,CAAC,MAAM;IACdG,YAAY,CAACuB,YAAY,CAAChB,cAAc,CAAC;EAC3C,CAAC,EAAE,CAACA,cAAc,CAAC,CAAC;EAEpBV,SAAS,CAAC,MAAM;IACdG,YAAY,CAACwB,cAAc,CAAChB,WAAW,CAAC;EAC1C,CAAC,EAAE,CAACA,WAAW,CAAC,CAAC;EAEjBX,SAAS,CAAC,MAAM;IACdG,YAAY,CAACyB,oBAAoB,CAAChB,iBAAiB,CAAC;EACtD,CAAC,EAAE,CAACA,iBAAiB,CAAC,CAAC;EAEvBZ,SAAS,CAAC,MAAM;IACd,IAAI,CAACoB,UAAU,EAAE;IACjB,OAAOhB,sBAAsB,CAACa,UAAU,CAAC;EAC3C,CAAC,EAAE,CAACG,UAAU,CAAC,CAAC;EAEhBpB,SAAS,CAAC,MAAM;IACd,IAAI,CAACoB,UAAU,EAAE;IACjB,OAAOd,uBAAuB,CAACa,cAAc,CAAC;EAChD,CAAC,EAAE,CAACC,UAAU,CAAC,CAAC;EAEhBpB,SAAS,CAAC,MAAM;IACd,IAAI,CAACoB,UAAU,IAAI,CAACP,OAAO,EAAE;IAC7B,MAAMgB,GAAG,GAAGxB,kBAAkB,CAACU,UAAU,CAAC;IAC1C;IACA;IACAZ,YAAY,CAACsB,SAAS,CAACF,SAAS,CAACC,OAAO,CAAC;IACzC,OAAOK,GAAG;IACV;EACF,CAAC,EAAE,CAACT,UAAU,EAAEP,OAAO,CAAC,CAAC;EAEzB,OAAO;IAAEC,OAAO;IAAEE,OAAO;IAAEE,WAAW;IAAEE,UAAU;IAAEC;EAAY,CAAC;AACnE","ignoreList":[]}

package/lib/typescript/src/hook.d.ts

@@ -7,6 +7,16 @@ export interface UseCompassOptions {
      * the library — last-write-wins.
      */
     filterDegrees?: number;
+    /**
+     * Low-pass smoothing factor (EMA α) applied to heading samples.
+     * Range `(0, 1]`. Default `0.2` ≈ 100ms time constant at typical
+     * Android sample rates. `1.0` disables smoothing. Smaller values
+     * smooth more (kills jitter, adds a touch of latency).
+     *
+     * No-op on iOS — CLLocationManager filters internally.
+     * Shared global state — last-write-wins.
+     */
+    smoothingAlpha?: number;
     /**
      * Magnetic-to-true offset in signed degrees. Default `0` (magnetic).
      * Pull from a model like `geomagnetism` keyed on the user's lat/lon.

package/lib/typescript/src/hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../../src/hook.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,iBAAiB,EAClB,MAAM,4BAA4B,CAAA;AAQnC,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,OAAO,EAAE,aAAa,GAAG,IAAI,CAAA;IAC7B,oEAAoE;IACpE,OAAO,EAAE,eAAe,GAAG,IAAI,CAAA;IAC/B,oEAAoE;IACpE,WAAW,EAAE,OAAO,CAAA;IACpB,yDAAyD;IACzD,UAAU,EAAE,OAAO,CAAA;IACnB,sDAAsD;IACtD,WAAW,EAAE,iBAAiB,GAAG,SAAS,CAAA;CAC3C;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB,CAsDlB"}
+{"version":3,"file":"hook.d.ts","sourceRoot":"","sources":["../../../src/hook.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,iBAAiB,EAClB,MAAM,4BAA4B,CAAA;AAQnC,MAAM,WAAW,iBAAiB;IAChC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,gEAAgE;IAChE,OAAO,EAAE,aAAa,GAAG,IAAI,CAAA;IAC7B,oEAAoE;IACpE,OAAO,EAAE,eAAe,GAAG,IAAI,CAAA;IAC/B,oEAAoE;IACpE,WAAW,EAAE,OAAO,CAAA;IACpB,yDAAyD;IACzD,UAAU,EAAE,OAAO,CAAA;IACnB,sDAAsD;IACtD,WAAW,EAAE,iBAAiB,GAAG,SAAS,CAAA;CAC3C;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,OAAO,GAAE,iBAAsB,GAC9B,gBAAgB,CA2DlB"}

package/lib/typescript/src/specs/NitroCompass.nitro.d.ts

@@ -95,6 +95,22 @@ export interface NitroCompass extends HybridObject<{
      * effect until `start()` is called.
      */
     setFilter(degrees: number): void;
+    /**
+     * Set the low-pass smoothing factor (EMA α) applied to heading samples
+     * before delivery. Range `(0, 1]`. Default `0.2` ≈ 100ms time constant
+     * at Android's typical 50 Hz sample rate.
+     *
+     * - `1.0` disables smoothing (every sample passes through unfiltered).
+     * - Smaller values smooth more — eliminates rotation-vector jitter at
+     *   the cost of a small amount of latency.
+     *
+     * Implemented as a circular EMA on `(sin θ, cos θ)` so the 359°→0°
+     * wraparound doesn't bias the average. Survives `start`/`stop`.
+     *
+     * **No-op on iOS.** `CLLocationManager` filters heading internally with
+     * Apple's own algorithm; layering EMA on top would only add latency.
+     */
+    setSmoothing(alpha: number): void;
     /**
      * Describe which underlying sensor / framework would produce headings on
      * this device. Returns `undefined` if the device has no compass hardware

package/lib/typescript/src/specs/NitroCompass.nitro.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NitroCompass.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/NitroCompass.nitro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAE9D;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,YAAY,CAAA;AAEtE;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,GAClB,gBAAgB,GAChB,2BAA2B,GAC3B,cAAc,CAAA;AAElB,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,UAAU,CAAA;CACnB;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAA;AAE/D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,YAAa,SAAQ,YAAY,CAAC;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,QAAQ,CAAA;CAAE,CAAC;IACrF;;;;;;;;;;OAUG;IACH,KAAK,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI,CAAA;IAE9E,8GAA8G;IAC9G,IAAI,IAAI,IAAI,CAAA;IAEZ,qEAAqE;IACrE,SAAS,IAAI,OAAO,CAAA;IAEpB;;;;OAIG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAEhC;;;;OAIG;IACH,cAAc,IAAI,iBAAiB,GAAG,SAAS,CAAA;IAE/C;;;;OAIG;IACH,UAAU,IAAI,OAAO,CAAA;IAErB;;;;OAIG;IACH,iBAAiB,IAAI,aAAa,GAAG,SAAS,CAAA;IAE9C;;;;;OAKG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAErC;;;;OAIG;IACH,sBAAsB,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,GAAG,IAAI,CAAA;IAE1E;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,yBAAyB,CAAC,QAAQ,EAAE,CAAC,oBAAoB,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAA;IAElF;;;;;;;OAOG;IACH,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IAE5C;;;;OAIG;IACH,mBAAmB,IAAI,gBAAgB,CAAA;IAEvC;;;;;;;OAOG;IACH,iBAAiB,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAA;CAC/C"}
+{"version":3,"file":"NitroCompass.nitro.d.ts","sourceRoot":"","sources":["../../../../src/specs/NitroCompass.nitro.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAA;AAE9D;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,YAAY,CAAA;AAEtE;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,GAClB,gBAAgB,GAChB,2BAA2B,GAC3B,cAAc,CAAA;AAElB,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,UAAU,CAAA;CACnB;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAA;AAE/D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,YAAa,SAAQ,YAAY,CAAC;IAAE,GAAG,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,QAAQ,CAAA;CAAE,CAAC;IACrF;;;;;;;;;;OAUG;IACH,KAAK,CAAC,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,GAAG,IAAI,CAAA;IAE9E,8GAA8G;IAC9G,IAAI,IAAI,IAAI,CAAA;IAEZ,qEAAqE;IACrE,SAAS,IAAI,OAAO,CAAA;IAEpB;;;;OAIG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAEhC;;;;;;;;;;;;;;OAcG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IAEjC;;;;OAIG;IACH,cAAc,IAAI,iBAAiB,GAAG,SAAS,CAAA;IAE/C;;;;OAIG;IACH,UAAU,IAAI,OAAO,CAAA;IAErB;;;;OAIG;IACH,iBAAiB,IAAI,aAAa,GAAG,SAAS,CAAA;IAE9C;;;;;OAKG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAErC;;;;OAIG;IACH,sBAAsB,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,GAAG,IAAI,CAAA;IAE1E;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,yBAAyB,CAAC,QAAQ,EAAE,CAAC,oBAAoB,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAA;IAElF;;;;;;;OAOG;IACH,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;IAE5C;;;;OAIG;IACH,mBAAmB,IAAI,gBAAgB,CAAA;IAEvC;;;;;;;OAOG;IACH,iBAAiB,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAA;CAC/C"}

package/nitrogen/generated/android/c++/JHybridNitroCompassSpec.cpp

@@ -87,6 +87,10 @@ namespace margelo::nitro::nitrocompass {
     static const auto method = _javaPart->javaClassStatic()->getMethod<void(double /* degrees */)>("setFilter");
     method(_javaPart, degrees);
   }
+  void JHybridNitroCompassSpec::setSmoothing(double alpha) {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<void(double /* alpha */)>("setSmoothing");
+    method(_javaPart, alpha);
+  }
   std::optional<SensorDiagnostics> JHybridNitroCompassSpec::getDiagnostics() {
     static const auto method = _javaPart->javaClassStatic()->getMethod<jni::local_ref<JSensorDiagnostics>()>("getDiagnostics");
     auto __result = method(_javaPart);

package/nitrogen/generated/android/c++/JHybridNitroCompassSpec.hpp

@@ -58,6 +58,7 @@ namespace margelo::nitro::nitrocompass {
     void stop() override;
     bool isStarted() override;
     void setFilter(double degrees) override;
+    void setSmoothing(double alpha) override;
     std::optional<SensorDiagnostics> getDiagnostics() override;
     bool hasCompass() override;
     std::optional<CompassSample> getCurrentHeading() override;

package/nitrogen/generated/android/kotlin/com/margelo/nitro/nitrocompass/HybridNitroCompassSpec.kt

@@ -50,6 +50,10 @@ abstract class HybridNitroCompassSpec: HybridObject() {
   @Keep
   abstract fun setFilter(degrees: Double): Unit
   
+  @DoNotStrip
+  @Keep
+  abstract fun setSmoothing(alpha: Double): Unit
+  
   @DoNotStrip
   @Keep
   abstract fun getDiagnostics(): SensorDiagnostics?

package/nitrogen/generated/ios/c++/HybridNitroCompassSpecSwift.hpp

@@ -108,6 +108,12 @@ namespace margelo::nitro::nitrocompass {
         std::rethrow_exception(__result.error());
       }
     }
+    inline void setSmoothing(double alpha) override {
+      auto __result = _swiftPart.setSmoothing(std::forward<decltype(alpha)>(alpha));
+      if (__result.hasError()) [[unlikely]] {
+        std::rethrow_exception(__result.error());
+      }
+    }
     inline std::optional<SensorDiagnostics> getDiagnostics() override {
       auto __result = _swiftPart.getDiagnostics();
       if (__result.hasError()) [[unlikely]] {

package/nitrogen/generated/ios/swift/HybridNitroCompassSpec.swift

@@ -17,6 +17,7 @@ public protocol HybridNitroCompassSpec_protocol: HybridObject {
   func stop() throws -> Void
   func isStarted() throws -> Bool
   func setFilter(degrees: Double) throws -> Void
+  func setSmoothing(alpha: Double) throws -> Void
   func getDiagnostics() throws -> SensorDiagnostics?
   func hasCompass() throws -> Bool
   func getCurrentHeading() throws -> CompassSample?

package/nitrogen/generated/ios/swift/HybridNitroCompassSpec_cxx.swift

@@ -174,6 +174,17 @@ open class HybridNitroCompassSpec_cxx {
     }
   }
   
+  @inline(__always)
+  public final func setSmoothing(alpha: Double) -> bridge.Result_void_ {
+    do {
+      try self.__implementation.setSmoothing(alpha: alpha)
+      return bridge.create_Result_void_()
+    } catch (let __error) {
+      let __exceptionPtr = __error.toCpp()
+      return bridge.create_Result_void_(__exceptionPtr)
+    }
+  }
+  
   @inline(__always)
   public final func getDiagnostics() -> bridge.Result_std__optional_SensorDiagnostics__ {
     do {

package/nitrogen/generated/shared/c++/HybridNitroCompassSpec.cpp

@@ -18,6 +18,7 @@ namespace margelo::nitro::nitrocompass {
       prototype.registerHybridMethod("stop", &HybridNitroCompassSpec::stop);
       prototype.registerHybridMethod("isStarted", &HybridNitroCompassSpec::isStarted);
       prototype.registerHybridMethod("setFilter", &HybridNitroCompassSpec::setFilter);
+      prototype.registerHybridMethod("setSmoothing", &HybridNitroCompassSpec::setSmoothing);
       prototype.registerHybridMethod("getDiagnostics", &HybridNitroCompassSpec::getDiagnostics);
       prototype.registerHybridMethod("hasCompass", &HybridNitroCompassSpec::hasCompass);
       prototype.registerHybridMethod("getCurrentHeading", &HybridNitroCompassSpec::getCurrentHeading);

package/nitrogen/generated/shared/c++/HybridNitroCompassSpec.hpp

@@ -65,6 +65,7 @@ namespace margelo::nitro::nitrocompass {
       virtual void stop() = 0;
       virtual bool isStarted() = 0;
       virtual void setFilter(double degrees) = 0;
+      virtual void setSmoothing(double alpha) = 0;
       virtual std::optional<SensorDiagnostics> getDiagnostics() = 0;
       virtual bool hasCompass() = 0;
       virtual std::optional<CompassSample> getCurrentHeading() = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-compass",
-  "version": "1.0.9",
+  "version": "1.1.0",
   "engines": {
     "node": ">=18"
   },

package/src/hook.ts

@@ -19,6 +19,16 @@ export interface UseCompassOptions {
    * the library — last-write-wins.
    */
   filterDegrees?: number
+  /**
+   * Low-pass smoothing factor (EMA α) applied to heading samples.
+   * Range `(0, 1]`. Default `0.2` ≈ 100ms time constant at typical
+   * Android sample rates. `1.0` disables smoothing. Smaller values
+   * smooth more (kills jitter, adds a touch of latency).
+   *
+   * No-op on iOS — CLLocationManager filters internally.
+   * Shared global state — last-write-wins.
+   */
+  smoothingAlpha?: number
   /**
    * Magnetic-to-true offset in signed degrees. Default `0` (magnetic).
    * Pull from a model like `geomagnetism` keyed on the user's lat/lon.
@@ -64,6 +74,7 @@ export function useCompass(
 ): UseCompassResult {
   const {
     filterDegrees = 1,
+    smoothingAlpha = 0.2,
     declination = 0,
     pauseOnBackground = true,
     enabled = true,
@@ -86,6 +97,10 @@ export function useCompass(
     NitroCompass.setFilter(filterDegrees)
   }, [filterDegrees])
 
+  useEffect(() => {
+    NitroCompass.setSmoothing(smoothingAlpha)
+  }, [smoothingAlpha])
+
   useEffect(() => {
     NitroCompass.setDeclination(declination)
   }, [declination])

package/src/specs/NitroCompass.nitro.ts

@@ -105,6 +105,23 @@ export interface NitroCompass extends HybridObject<{ ios: 'swift'; android: 'kot
    */
   setFilter(degrees: number): void
 
+  /**
+   * Set the low-pass smoothing factor (EMA α) applied to heading samples
+   * before delivery. Range `(0, 1]`. Default `0.2` ≈ 100ms time constant
+   * at Android's typical 50 Hz sample rate.
+   *
+   * - `1.0` disables smoothing (every sample passes through unfiltered).
+   * - Smaller values smooth more — eliminates rotation-vector jitter at
+   *   the cost of a small amount of latency.
+   *
+   * Implemented as a circular EMA on `(sin θ, cos θ)` so the 359°→0°
+   * wraparound doesn't bias the average. Survives `start`/`stop`.
+   *
+   * **No-op on iOS.** `CLLocationManager` filters heading internally with
+   * Apple's own algorithm; layering EMA on top would only add latency.
+   */
+  setSmoothing(alpha: number): void
+
   /**
    * Describe which underlying sensor / framework would produce headings on
    * this device. Returns `undefined` if the device has no compass hardware