# nisrulz/sensey: sensor and gesture detection for Android without the boilerplate

> Sensey is an Apache-2.0 Kotlin library that turns Android sensor callbacks into named gesture events. It is a good fit for prototypes and small apps, but the version on Maven Central is 1.9.0 from 2020-12-11, so check the develop branch before planning around it.

**nisrulz/sensey** — :zap: [Android Library] Play with sensor events & detect gestures in a breeze.

- Repository: https://github.com/nisrulz/sensey
- Stars: 2,658 · Forks: 267
- Language: Kotlin
- License: Apache-2.0
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/nisrulz-sensey

## The boilerplate Sensey removes

Android's sensor APIs are low level by design. You implement SensorEventListener, register and unregister it against the right SensorManager, convert raw float arrays into something meaningful, and then decide for yourself when a sequence of readings counts as a shake rather than a bump. Sensey's stated purpose is to remove that setup work: the README describes it as an Android library that "makes sensor event and gesture detection a breeze" and that "eliminates boilerplate for setting up sensor-based gesture detection."

The audience is therefore Android developers who want a gesture as a callback, not as a physics problem. A fitness app that reacts to wrist twists, an accessibility feature triggered by a chop, a media app that pauses on flip: these are the shapes of use the library targets. It is a convenience layer over platform sensors, not a replacement for them.

## How the plugin registration model works

The current API shown in the README is a registration block. You call senseyRegister with a Lifecycle, and inside the block you declare plugins. Each plugin receives an event object, and you branch on its sealed cases. The example in the README registers shakePlugin and flipPlugin, and handles ShakeEvent.Detected, ShakeEvent.Stopped, FlipEvent.FaceUp and FlipEvent.FaceDown.

There is a second path built on Kotlin coroutines. senseyFlow exposes events as Flow<T> with lifecycle-aware collection: the README states it auto-collects on STARTED, pauses on STOP and cleans up on DESTROY, and that all gestures support it. For Compose there is a SenseyFlowEffect wrapper. The repository also documents context-specific usage for Compose, Service and WorkManager in docs/usage/context-specific-usage.md, which suggests the maintainers treat non-Activity hosts as a supported case rather than an afterthought.

The gesture list is long and partly unusual. Beyond shake and flip there are Chop, TapOnBack, WristTwist, Wave, Scoop, PickupDevice, TiltDirection, RotationAngle, PinchScale, TouchType, EdgeSwipe, DiagonalSwipe, SoundLevel, Step, TurnOver, DeviceSpin, RaiseToEar, Clap, NodGesture and HeadShake. Several of these are heuristics layered on accelerometer or gyroscope patterns rather than distinct hardware sensors, which is worth remembering when you evaluate reliability for your own use case.

## Installing Sensey and registering a first gesture

The README gives a single Gradle line for the dependency, published under the com.github.nisrulz group on Maven Central. The README writes the version as a placeholder, so resolve the concrete version from Maven Central rather than copying it from the snippet.

```gradle
implementation 'com.github.nisrulz:sensey:{latest version}'
```

Sensey declares its own dependencies as compileOnly. That is a deliberate choice: the library does not drag transitive dependencies into your build, but it also means you must add what you use. The README's table maps lifecycle-aware registration to androidx.lifecycle:lifecycle-common, the Flow-based API to kotlinx-coroutines-core, and touch gesture plugins to androidx.compose.ui and androidx.compose.foundation. Sensor-only plugins such as shake, flip, light and proximity, in the README's words, "work with just sensey alone."

With the dependency in place, registration is a block inside your Activity's onCreate. This is the README's own example, trimmed to one plugin.

```kt
import com.github.nisrulz.sensey.senseyRegister
import com.github.nisrulz.sensey.gesture.shake.ShakeEvent

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        senseyRegister(lifecycle) {
            shakePlugin { event ->
                when (event) {
                    ShakeEvent.Detected -> println("Shake detected!")
                    ShakeEvent.Stopped  -> println("Shake stopped")
                }
            }
        }
    }
}
```

What you should see is the Detected branch firing when the device is shaken and Stopped when the motion ends. The Lifecycle argument is what ties registration to the Activity's state, so you do not manage unregister calls yourself. If you prefer Flow, the README's alternative is context.senseyFlow(lifecycle) with the same plugin block inside it.

## Version drift between Maven Central and the develop branch

This is the part to check before you commit. The most recent release listed is 1.9.0, published on 2020-12-11. The previous entries are 1.8.0 from 2017-12-05 and 1.7.0 from 2017-03-12. The repository's last push was on 2026-06-08, and the default branch is develop, not main.

That gap matters because the README documents an API that may not match the artifact you resolve. The senseyRegister and senseyFlow registration style, the sealed event types like ShakeEvent.Detected, and the Compose SenseyFlowEffect are what the README shows today. A developer who copies the README snippet and resolves the newest Maven Central release may find a different surface. The README itself does not state which release corresponds to the documented API, and the changelog is a link to GitHub releases rather than a table in the repository.

There is also a maintenance signal worth reading plainly. The last push was on 2026-06-08, which is inside six months of the current date, so the repository is not dormant. But a six-year gap between named releases means the published artifact and the working tree have diverged, and the release notes do not explain how. Treat the version you depend on as something to verify, not assume.

## Where Sensey is the wrong tool

The minimum API level is 23, per the badge in the README. If you support older devices, this library is simply out, and no configuration changes that.

More importantly, gesture heuristics are not guarantees. A shake detector that works on a phone in a hand behaves differently when the device is in a pocket, on a car mount or on a table. The README documents the events and parameters but does not publish accuracy figures, false-positive rates or tuning guidance in the documentation available here. If your feature needs a specific detection rate, you will be measuring it yourself.

There is also a scope question. Sensey covers motion, proximity, light and touch-derived gestures. It is not a step counter with health-grade accuracy, and it is not a replacement for the platform's own sensor fusion or for a dedicated activity-recognition API. If your requirement is "count steps accurately across device models," a gesture convenience library is the wrong layer to solve it in.

Finally, the compileOnly dependency strategy is a trade-off, not a free win. It keeps your dependency graph clean, but it converts a missing dependency from a build error into a runtime failure. A team that adds a touch plugin without adding the Compose artifacts will find out at runtime, not at compile time.

## Sensey against writing your own SensorEventListener

The honest alternative is not another library. It is registering a SensorManager listener yourself, or using Android's activity recognition APIs for higher-level motion classification.

The difference in approach is where the logic lives. Hand-rolled code gives you direct control of the sensor type, the sampling rate and the threshold constants, and it has no third-party version to track. The cost is that you write and maintain the state machine that decides when a stream of accelerometer readings becomes a shake, and you handle registration and unregistration against the lifecycle yourself. Sensey's value proposition is exactly that state machine plus the lifecycle wiring, delivered as named plugins.

Android's own activity recognition sits at a different level again: it classifies what the user is doing rather than what the device just did, and it is a platform service rather than an in-process library. If your need is "is the user walking or driving," that is a better fit than a shake detector. If your need is "fire a callback when the phone is flipped face down," Sensey is closer to the shape you want.

## Licence and upgrade cost

Sensey is licensed under the Apache License, Version 2.0, with copyright held by Nishant Srivastava since 2016. Apache-2.0 is a permissive licence that permits commercial use and modification and includes an explicit patent grant. It also requires that you retain the licence and notice files and state significant changes you make. This is a description of the licence text, not legal advice; check LICENSE.txt in the repository and your own counsel for your situation.

The upgrade cost is the practical concern. Because the newest named release is 1.9.0 from 2020-12-11 and the default branch is develop, you have two options: depend on the published artifact and accept that it may lag the documented API, or track the develop branch and accept that you are following an unreleased tree. The README does not document a rollback path or a migration guide between the older registration style and the current one, so an upgrade is something you would validate against your own gesture handling rather than against a published changelog table.

## Conclusion

Adopt Sensey if you are building an Android app on API 23 or above and want shake, flip, wave or similar gestures without writing your own SensorEventListener plumbing, and if you can pin to a known build. Do not adopt it if you need a guaranteed support contract, if your app must run below API 23, or if the gesture you want is not in the published list. Before committing, verify which artifact version your build actually resolves from Maven Central, since the newest listed release is 1.9.0 from 2020-12-11 while the develop branch has a newer registration API that the README documents.

## FAQ

### What is Sensey?

Sensey is an Android library written in Kotlin that handles sensor event and gesture detection, removing the boilerplate of setting up sensor-based gestures. It is published under the com.github.nisrulz group on Maven Central and licensed under Apache-2.0.

### Which Android API level does Sensey require?

The README carries an API 23+ badge, so devices below API 23 are not supported.

### Which gestures does Sensey detect?

The README lists Shake, Flip, Light, Proximity, Movement, Orientation, Chop, TapOnBack, WristTwist, Wave, Scoop, PickupDevice, TiltDirection, RotationAngle, PinchScale, TouchType, EdgeSwipe, DiagonalSwipe, SoundLevel, Step, TurnOver, DeviceSpin, RaiseToEar, Clap, NodGesture and HeadShake.

### Do I need to add coroutines or Compose dependencies to use Sensey?

Only for the features that need them. The README states that sensor-only plugins such as shake, flip, light and proximity work with just sensey alone, while the Flow API needs kotlinx-coroutines-core and touch gesture plugins need androidx.compose.ui and androidx.compose.foundation.

### How do I add Sensey to my project?

The README gives a single Gradle dependency, implementation 'com.github.nisrulz:sensey:{latest version}', published on Maven Central. The README writes the version as a placeholder, so resolve the concrete version from Maven Central.

## Sources

- [Issues](https://github.com/nisrulz/sensey/issues)
- [License: Apache-2.0](https://github.com/nisrulz/sensey/blob/develop/LICENSE)
- [nisrulz/sensey on GitHub](https://github.com/nisrulz/sensey)
- [README](https://github.com/nisrulz/sensey/blob/develop/README.md)
- [Releases](https://github.com/nisrulz/sensey/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nisrulz-sensey