DEV Community

Cover image for Building a click wheel in Flutter: atan2, detents and a 1.8 KB click sound
Felix Helleckes
Felix Helleckes

Posted on Fully Autonomous

Building a click wheel in Flutter: atan2, detents and a 1.8 KB click sound

I'm a QA engineer by day, and in my spare time I build small apps. The latest one is Clickwheel, an offline music player for Android and iPhone with one control: a round click wheel. You drag your thumb around the ring, the list scrolls, and every step clicks.

It sounds like a weekend project. The wheel itself was. Making it feel right took much longer, and almost none of the work was where I expected it. Here are the three parts that mattered, with the real code from the app (Flutter).

1. Turning a finger into steps

A drag gesture gives you x/y positions. A wheel needs "one step forward" or "one step back". The bridge is the angle of the finger around the wheel's center:

double _angleOf(Offset local, Size size) {
  final v = local - _center(size);
  return math.atan2(v.dy, v.dx);
}
Enter fullscreen mode Exit fullscreen mode

On every update I compare the new angle with the previous one and add the difference to an accumulator. The catch: atan2 jumps from +π to −π when the finger crosses the left side of the circle. Without a fix, crossing that seam produces a "delta" of almost a full turn, and the list flies 25 items in one frame. The fix is to always take the short way round:

var delta = current - last;
// Across the 180° seam, normalise to the short way round.
if (delta > math.pi) {
  delta -= 2 * math.pi;
} else if (delta < -math.pi) {
  delta += 2 * math.pi;
}
_lastAngle = current;
_accumulated += delta;
Enter fullscreen mode Exit fullscreen mode

Then the accumulator is converted into discrete steps (detents):

final step = _radiansPerDetent; // 2π / detentsPerTurn
while (_accumulated.abs() >= step) {
  final direction = _accumulated > 0 ? 1 : -1;
  _accumulated -= direction * step;
  _ipod.scroll(direction);
}
Enter fullscreen mode Exit fullscreen mode

Two details I only learned from testing on real phones:

  • It has to be a while, not an if. A fast flick can cover two or three detents between two frames. With if, fast spins feel sticky because steps get lost.
  • The number of detents is a setting. The app offers 18, 26 or 36 steps per full turn (default 26). Small phones and big thumbs want fewer steps, people who scroll through thousands of songs want more. There is no single correct value, so I stopped looking for one.

The four buttons (menu, back, play/pause, forward) use the same geometry, just rotated so that 0° is at the top: everything between 315° and 45° is "menu", and so on in 90° slices.

2. The click is a 1.8 KB file, and it was the hardest part

My first version used the system click sound. On Android it depends on the "touch sounds" setting, which many people have turned off. On iOS it was practically silent. So the click is now its own file in the bundle: click.wav, 1,806 bytes.

Playing a tiny sound dozens of times per second turned out to be its own problem:

One player is not enough. When you spin quickly, detents arrive faster than the click decays. Reloading the file on each tick means opening and decoding it again, dozens of times per second, across the platform channel. The app keeps a pool of four preloaded players and just rotates through them:

static const int _voices = 4;
final List<AudioPlayer> _pool = [
  for (var i = 0; i < _voices; i++)
    AudioPlayer(playerId: 'clickwheel_tick_$i'),
];
Enter fullscreen mode Exit fullscreen mode

Some clicks must be dropped on purpose. Below a 28 ms gap, a new click would cut the previous one off and sound like static. So the click is skipped instead:

static const Duration _minGap = Duration(milliseconds: 28);
...
if (now.difference(_lastClick) < _minGap) return;
Enter fullscreen mode Exit fullscreen mode

Haptics still fire on every detent, so you don't notice the skipped sound. You'd only notice the crackle.

The click must not interrupt the music. That sounds obvious, but by default a new sound takes audio focus, and the song ducks or pauses on every tick. On Android the click player uses the media stream with AndroidAudioFocus.none, so it shares the volume slider with the music and never takes focus.

On iOS the audio session is global. This one bit me. setAudioContext in the audioplayers package sounds like it configures one player, but on iOS there is only one audio session per app. I had given the click an "ambient" category, which quietly switched the whole app to a category that is not allowed to play in the background. Result: the music stopped as soon as the app left the screen. The fix is to use the same category as the music player plus mixWithOthers.

I also use a separate audio package for the click than for the music. The background playback plugin requires a media item (title, artist) for every player it manages, and a click showing up as "now playing" in the notification shade would be silly.

3. An offline player that is actually offline

Clickwheel plays files you already own: MP3, FLAC and other formats you copy onto the phone. It has no account, no streaming and no ads, so it doesn't need the internet. I wanted the Android build to prove that, not just promise it.

The problem: the Play Billing library (needed for the one-time upgrade) pulls in a transport component that adds the INTERNET permission through manifest merging. The purchase itself runs through the Play Store app and doesn't need it. So the release manifest removes it explicitly:

<uses-permission android:name="android.permission.INTERNET"
    tools:node="remove"/>
Enter fullscreen mode Exit fullscreen mode

Debug and profile builds keep it (they have their own manifests). The release APK has no internet permission at all, which anyone can check in the Play Store's permission list.

What I'd tell my past self

  • Test the feel on hardware early. Emulators are fine for logic, but the detent count, the click timing and the haptics were all decided with a phone in my hand.
  • Read what "set" really sets. The iOS audio session bug came from an API name that suggested a local change when it was global.
  • Removing things is a feature. No network, no account and no recommendations made the app smaller and easier to test.

If you want to try the wheel without installing anything, there's a browser version on the website: clickwheel-app.pages.dev. The app is free on Android and iPhone.

Questions about the gesture math or the audio setup are welcome in the comments.


Clickwheel by Felix Helleckes, indie developer and QA engineer from Cologne. More apps: felix-helleckes.github.io/apps

Disclosure: this post was drafted by an AI agent working for me. The code, numbers and bugs are taken from the actual Clickwheel repository.

Top comments (1)

Collapse
 
hasnan_khan_dev_0 profile image
Hasnan Khan •

Really impressive implementation! I like how you've combined mathematical precision with thoughtful UI interactions to recreate the classic Click Wheel experience in Flutter. Details like angle-based gesture detection, detents, and even optimizing the click sound show how much difference small engineering decisions can make in the overall user experience.

At Octacer, we appreciate practical Flutter engineering approaches that bring creativity and performance together. Great work! 👏