Skip to content
Swift

Redesign the README with the icon, connect animation and screens.

Andy Gaodc9f277f71ae
diff --git a/Assets/README.md b/Assets/README.md
index 2117542..cd48b5c 100644
--- a/Assets/README.md
+++ b/Assets/README.md
@@ -1,7 +1,7 @@
# Assets
-The images and sounds that the build copies into the app, and the 3D model that
-the case images come from.
+The images and sounds that the build copies into the app, the 3D model that the
+case images come from, and the README's images.
| File | What it is | Used for |
|---|---|---|
@@ -11,14 +11,15 @@ the case images come from.
| `CaseLid/lid-00.png` to `lid-11.png` | The lid going from open to closed | The connection steps |
| `TapClick/click.wav` | A mouse button going down and up (96 ms) | The sound of a tap that clicks |
| `NotchShimmer.wav` | Air and two glass bells (652 ms) | The sound of the notch opening |
-| `AppIcon.icns` | The closed case, upright, on a dark tile | The app icon |
+| `AppIcon.icns` | AirPointer's mark: the closed case, upright, on a dark tile | The app icon |
+| `Readme/` | The icon, the connect animation, and the app's screens | The project README |
## Sources and licenses
The MIT License at the top of this project does not cover this folder.
-- The case images and app icon are renders of Apple's AirPods Pro 3 AR model. Apple
- owns the model and its materials.
+- The case images are renders of Apple's AirPods Pro 3 AR model. Apple owns the
+ model and its materials. The images in `Readme/` include these renders.
[Download it from Apple](https://www.apple.com/105/media/us/airpods-pro/2025/7acffb13-4adb-40b1-9393-8f1c99bc6c90/ar/airpods-pro.usdz),
linked from the [AirPods Pro specs page](https://www.apple.com/airpods-pro/specs/).
- The two sounds use parts from cuelume, MIT license, (c) 2026 Daniel Belyi. See
@@ -31,12 +32,21 @@ to change them. Run this command from the project folder. It writes to
`work/case-renders`.
```sh
-/Applications/Blender.app/Contents/MacOS/Blender --background --factory-startup --threads 8 --python render-closed-case.py -- --only open,closed,pointer,lid,review
+/Applications/Blender.app/Contents/MacOS/Blender --background --factory-startup --threads 8 --python Scripts/render-closed-case.py -- --only open,closed,pointer,lid,review
```
Then copy `work/case-renders/case-pointer.png` to `Assets/CaseFront.png`, and copy
`work/case-renders/lid/*` to `Assets/CaseLid/`.
All the images use one camera, 12° above the front of the case, so the frames line
-up. `seat-earbuds.py` moves the earbuds from Apple's display position into their
-seats, so they fit under the closed lid.
+up. `Scripts/seat-earbuds.py` moves the earbuds from Apple's display position into
+their seats, so they fit under the closed lid.
+
+## Make the README images again
+
+You need Pillow and ffmpeg. Run this from the project folder after a build:
+
+```sh
+AirPointer.app/Contents/MacOS/AirPointer --check-home --preview-directory /tmp/previews
+python3 Scripts/make-readme-images.py /tmp/previews
+```
diff --git a/Assets/Readme/connect.gif b/Assets/Readme/connect.gif
new file mode 100644
index 0000000..b3e4088
Binary files /dev/null and b/Assets/Readme/connect.gif differ
diff --git a/Assets/Readme/icon.png b/Assets/Readme/icon.png
new file mode 100644
index 0000000..b229daa
Binary files /dev/null and b/Assets/Readme/icon.png differ
diff --git a/Assets/Readme/screens.png b/Assets/Readme/screens.png
new file mode 100644
index 0000000..0fdea47
Binary files /dev/null and b/Assets/Readme/screens.png differ
diff --git a/Assets/Readme/setup.png b/Assets/Readme/setup.png
new file mode 100644
index 0000000..75cd2f7
Binary files /dev/null and b/Assets/Readme/setup.png differ
diff --git a/README.md b/README.md
index 5f87b33..4321f7d 100644
--- a/README.md
+++ b/README.md
@@ -1,27 +1,27 @@
-# AirPointer
+<p align="center">
+ <img src="Assets/Readme/icon.png" width="112" alt="The AirPointer icon: the closed case, upright, on a dark tile">
+</p>
-AirPointer turns AirPods Pro in their closed case into a pointer for your Mac.
-Move the case to move the cursor. Tap the front of the case to click.
+<h1 align="center">AirPointer</h1>
-All processing happens on your Mac. The app has no network code.
+<p align="center">
+ <strong>Turn your AirPods case into a pointer for your Mac.</strong><br>
+ Move the closed case to move the cursor. Tap its front to click.
+</p>
+
+<p align="center">
+ <img src="Assets/Readme/connect.gif" width="100%" alt="The connect steps: open the lid, close the lid, turn the case upright, and point">
+</p>
## Before you use it
-AirPointer is an early build. Apple did not make it and does not support it. It
-uses private Apple protocols, so a macOS or AirPods update can stop it working.
-
-- **Case analytics:** Ending a session uses up the diagnostic analytics stored on
- the case.
-- **AirPods settings:** Some AirPods connection settings stay as the session set
- them. We do not know yet if this effect, or the analytics effect, continues
- after the link resets.
-- **Audio:** Each connection drops the AirPods' Bluetooth link for a moment.
- Audio through the AirPods stops. Do not connect during a call.
-- **Microphone:** During a session, the app keeps Mac sound and the microphone off
- all AirPods. The app restores them when the session ends.
-- **Cursor size:** A cursor smaller than 2× grows to 2× while you point. It returns
- to its size when you pause or disconnect. After a force quit, it returns when
- you next open the app. This uses a private macOS call.
+| Effect | What happens |
+|---|---|
+| **Case data** | Ending a session uses up the diagnostic data stored on the case. |
+| **AirPods settings** | Some AirPods connection settings stay as the session set them. We do not know yet if this change, or the case data change, lasts after the Bluetooth link resets. |
+| **Audio** | Each connection drops the AirPods' Bluetooth link for a moment, and their audio stops. Do not connect during a call. |
+| **Microphone** | During a session, the app keeps Mac sound and the microphone off all AirPods. It restores them when the session ends. |
+| **Cursor size** | A cursor smaller than 2× grows to 2× while you point. It returns to its size when you pause or disconnect. After a force quit, it returns when you next open the app. This uses a private macOS call. |
## Requirements
@@ -29,6 +29,7 @@ uses private Apple protocols, so a macOS or AirPods update can stop it working.
|---|---|
| AirPods Pro 3, macOS 26, Apple Silicon | Tested on one Mac with one pair |
| AirPods Pro 2 | Recognized, not tested |
+| AirPods paired with your Mac | Required |
| Xcode | Required to build |
Normal connect and disconnect have run many times on that Mac and pair. These
@@ -54,9 +55,13 @@ If AirPointer does not appear in the Accessibility list after a rebuild, run:
tccutil reset Accessibility local.airpointer
```
-## How to use it
+## Set it up
+
+The first time you open the app, setup has four steps.
-The first time you open the app, setup has four steps:
+<p align="center">
+ <img src="Assets/Readme/setup.png" width="100%" alt="The four setup steps: Allow, Connect, Calibrate and Tap">
+</p>
1. **Allow:** Drag AirPointer into the Accessibility list. This lets it move the
cursor and click.
@@ -65,8 +70,19 @@ The first time you open the app, setup has four steps:
3. **Calibrate:** Point at three dots to show the app where your screen is.
4. **Tap:** Tap the front of the case three times.
-After that, press **fn ⌃** in any app to connect. Press it again to pause or
-resume. To use a different shortcut, go to Settings.
+## Use it
+
+Press **fn ⌃** in any app to connect. Press it again to pause or resume. To use a
+different shortcut, go to Settings.
+
+<p align="center">
+ <img src="Assets/Readme/screens.png" width="100%" alt="The AirPointer window, the menu bar panel, and the notch while pointing">
+</p>
+
+A session ends 30 minutes after the lid closes. To continue, open and close the lid.
+
+<details>
+<summary><strong>The connect steps as a chart</strong></summary>
```mermaid
flowchart TD
@@ -84,6 +100,19 @@ flowchart TD
Paused -->|"fn ⌃"| Pointing
```
+</details>
+
+## Troubleshooting
+
+| Problem | What to do |
+|---|---|
+| The app does not connect | Turn off Bluetooth on your iPhone. Your iPhone can hold the AirPods. |
+| "Connecting" does not end | Open the lid and keep it open until the app tells you to close it. |
+| The pointer lags or motion stops | Make sure no other app, such as OBS or a browser call, uses the AirPods as a microphone. |
+| The pointer stutters just after you connect | This is normal for about 20 seconds. |
+| "Set it down" takes a long time | Use a firm, flat surface and do not touch the case. |
+| Taps do not click | Go to Settings > Teach Tap. Do this again if you change how you hold the case. |
+
## How it works
```mermaid
@@ -133,35 +162,36 @@ flowchart LR
If motion stops for less than two seconds, the pointer stops and then continues.
If motion stops for longer, the pointer pauses and continues when motion returns.
-A session ends 30 minutes after the lid closes. To continue, open and close the lid.
-## Code map
+## Project layout
+
+```text
+Sources/
+ AirPointer/ The app
+ App/ Startup, the link to the windows, and the shortcut
+ Session/ The session, motion math, taps, audio guard, cursor size
+ Interface/ The window, menu bar, notch, setup and Tap Test
+ Checks/ Offline checks, built into the app
+ ClosedCaseMotion/ The helper that talks to the AirPods
+ ClosedCaseRestore/ The helper that brings the Bluetooth link up
+Tests/ Recorded taps and handling for the tap check
+Assets/ Images, sounds and the 3D case model
+Scripts/ Make the case and README images
+Docs/ The design system
+build.sh Builds AirPointer.app and runs the checks
+```
-| File | Purpose |
-|---|---|
-| `ClosedCase/CaseSustainedRenewal.m` | Builds `ClosedCaseMotion.bin`, the helper that talks to the AirPods. Lists its exit codes at the top. |
-| `ClosedCaseRestore.swift` | Brings the ordinary Bluetooth link up. |
-| `ClosedCaseAirPods.swift` | Finds the paired AirPods. |
-| `ClosedCaseSession.swift` | Runs a session, reads motion data, and moves the cursor. |
-| `ClosedCase/Orientation.js`, `MotionLearning.swift` | Motion math. |
-| `ClosedCaseTap.swift` | Finds taps and learns their direction. |
-| `AudioOutputGuard.swift` | Keeps sound and the microphone off the AirPods during a session. |
-| `CursorSize.swift` | Grows a small cursor while you point. |
-| `PointerShortcut.swift` | The shortcut and its control in Settings. |
-| `AirPointer.swift`, `AppHome.swift` | Start the app and connect the session to its windows. |
-| `AirPointerHome.swift`, `StatusBarUI.swift`, `NotchFlow.swift` | The window and Settings, the menu bar, and the notch. |
-| `SetupAssistant.swift`, `AccessibilityGuide.swift`, `CaseLessons.swift` | Setup, the panel over System Settings, and calibration. |
-| `RemoteKit.swift` | Shared interface components. |
-| `TapTest.swift` | The Tap Test, for developers. |
-| `Checks.swift`, `HomeChecks.swift`, `ClosedCase/TapFixtures.csv` | Offline checks and their test data. |
-| `Assets/` | Images, sounds and the 3D case model. See [Assets/README.md](Assets/README.md). |
-| `render-closed-case.py`, `seat-earbuds.py` | Make the onboarding case images from the 3D model. These need Blender. The app uses the finished images. |
-
-[DESIGN-SYSTEM.md](DESIGN-SYSTEM.md) has the rules for the interface.
-
-## Data on your Mac
-
-The app keeps its data in `~/Library/Application Support/AirPointer/`.
+`Sources/ClosedCaseMotion/CaseSustainedRenewal.m` lists the helper's exit codes at
+the top. [Docs/DESIGN-SYSTEM.md](Docs/DESIGN-SYSTEM.md) has the rules for the
+interface. [Assets/README.md](Assets/README.md) explains the images and sounds.
+
+## For developers
+
+<details>
+<summary><strong>Data on your Mac</strong></summary>
+
+The app keeps its data in `~/Library/Application Support/AirPointer/`. It does not
+send any of this anywhere.
| File | Contents |
|---|---|
@@ -171,8 +201,6 @@ The app keeps its data in `~/Library/Application Support/AirPointer/`.
| `PointerSessions/` | Logs from the newest ten sessions |
| `TapTests.jsonl` | Tap Test scores |
-The app does not send any of this anywhere.
-
In a session's `native.log`:
- `STEP` lines show the time of each connection step.
@@ -180,18 +208,10 @@ In a session's `native.log`:
- `tap` lines explain each tap.
- The `EXIT` line shows why the session ended.
-## Troubleshooting
+</details>
-| Problem | What to do |
-|---|---|
-| The app does not connect | Turn off Bluetooth on your iPhone. Your iPhone can hold the AirPods. |
-| "Connecting" does not end | Open the lid and keep it open until the app tells you to close it. |
-| The pointer lags or motion stops | Make sure no other app, such as OBS or a browser call, uses the AirPods as a microphone. |
-| The pointer stutters just after you connect | This is normal for about 20 seconds. |
-| "Set it down" takes a long time | Use a firm, flat surface and do not touch the case. |
-| Taps do not click | Go to Settings > Teach Tap. Do this again if you change how you hold the case. |
-
-## Tap Test
+<details>
+<summary><strong>Tap Test</strong></summary>
Taps are tuned on one person so far, so your score may differ.
@@ -205,7 +225,10 @@ records up to about 20 MB.
defaults write local.airpointer recordMotion -bool true
```
-## Offline checks
+</details>
+
+<details>
+<summary><strong>Offline checks</strong></summary>
These checks do not use Bluetooth.
@@ -214,10 +237,12 @@ AirPointer.app/Contents/MacOS/AirPointer --check-home
AirPointer.app/Contents/MacOS/AirPointer --check-pointer-settings
AirPointer.app/Contents/MacOS/AirPointer --check-closed-case-native
AirPointer.app/Contents/MacOS/AirPointer --check-audio-output-policy
-AirPointer.app/Contents/MacOS/AirPointer --check-closed-case-tap ClosedCase/TapFixtures.csv
+AirPointer.app/Contents/MacOS/AirPointer --check-closed-case-tap Tests/TapFixtures.csv
AirPointer.app/Contents/Resources/ClosedCaseMotion.bin --self-test
```
+</details>
+
## Uninstall
Quit AirPointer, delete this folder, then run:
@@ -232,5 +257,5 @@ tccutil reset BluetoothAlways local.airpointer
## License
The code uses the [MIT License](LICENSE). The license does not cover `Assets/`.
-Apple owns the AirPods model that the case images and app icon are made from, and
-the sounds have their own license. See [Assets/README.md](Assets/README.md).
+Apple owns the AirPods model that the case images are made from, and the sounds
+have their own license. See [Assets/README.md](Assets/README.md).
diff --git a/Scripts/make-readme-images.py b/Scripts/make-readme-images.py
new file mode 100644
index 0000000..0d28190
--- /dev/null
+++ b/Scripts/make-readme-images.py
@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""Make the README's images from the case renders and the app's own previews.
+
+Needs Pillow and ffmpeg. Run this from the project folder after a build:
+
+AirPointer.app/Contents/MacOS/AirPointer --check-home --preview-directory /tmp/previews
+python3 Scripts/make-readme-images.py /tmp/previews
+"""
+import math
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from PIL import Image, ImageDraw, ImageFilter, ImageFont
+
+root = Path(__file__).resolve().parent.parent
+assets = root / 'Assets'
+out = assets / 'Readme'
+previews = Path(sys.argv[1])
+stage = (28, 28, 30, 255)
+
+
+def font(size, weight):
+ face = ImageFont.truetype('/System/Library/Fonts/SFNS.ttf', size)
+ # San Francisco's axes: width, optical size, grade, weight.
+ face.set_variation_by_axes([100, max(17, size), 400, weight])
+ return face
+
+
+def rounded(size, radius, fill=255):
+ mask = Image.new('L', (size[0] * 2, size[1] * 2), 0)
+ ImageDraw.Draw(mask).rounded_rectangle((0, 0, size[0] * 2 - 1, size[1] * 2 - 1), radius * 2, fill=fill)
+ return mask.resize(size, Image.LANCZOS)
+
+
+def banner(size, radius=36):
+ image = Image.new('RGBA', size, (0, 0, 0, 0))
+ image.paste(stage, (0, 0), rounded(size, radius))
+ return image
+
+
+def place(canvas, image, x, y, radius=24):
+ """A window on the stage: rounded corners and a soft shadow."""
+ w, h = image.size
+ shadow = Image.new('L', canvas.size, 0)
+ shadow.paste(rounded((w, h), radius, 150), (x, y + 14))
+ canvas.paste((0, 0, 0, 255), (0, 0), shadow.filter(ImageFilter.GaussianBlur(24)))
+ canvas.paste(image.convert('RGB'), (x, y), rounded((w, h), radius))
+
+
+def fit(name, width, crop_height=None):
+ image = Image.open(previews / f'{name}.png').convert('RGBA')
+ if crop_height:
+ image = image.crop((0, 0, image.width, crop_height))
+ return image.resize((width, round(image.height * width / image.width)), Image.LANCZOS)
+
+
+def icon():
+ with tempfile.TemporaryDirectory() as folder:
+ png = Path(folder) / 'icon.png'
+ subprocess.run(['sips', '-s', 'format', 'png', str(assets / 'AppIcon.icns'), '--out', str(png)], check=True, capture_output=True)
+ Image.open(png).convert('RGBA').resize((256, 256), Image.LANCZOS).save(out / 'icon.png', optimize=True)
+
+
+def screens():
+ canvas = banner((2000, 960), 48)
+ place(canvas, fit('pointer-running', 660, 1040), 90, 90)
+ place(canvas, fit('menu-bar', 560), 800, 82)
+ # The notch's "Pointing" panel, without the desktop around it.
+ notch = Image.open(previews / 'notch-steps.png').convert('RGBA')
+ place(canvas, notch.crop((80, 2578, 797, 2978)).resize((500, 279), Image.LANCZOS), 1420, 340, 34)
+ canvas.save(out / 'screens.png', optimize=True)
+
+
+def setup():
+ names = ['setup-allow', 'setup-connect', 'setup-calibrate', 'setup-tap']
+ canvas = banner((2000, 600), 48)
+ for index, name in enumerate(names):
+ place(canvas, fit(name, 440), 60 + index * 480, 56, 14)
+ canvas.save(out / 'setup.png', optimize=True)
+
+
+def connect_animation():
+ size = (1200, 560)
+ title, detail = font(40, 650), font(26, 400)
+ lid = [Image.open(path).convert('RGBA').resize((400, 400), Image.LANCZOS) for path in sorted((assets / 'CaseLid').glob('lid-*.png'))]
+ front = Image.open(assets / 'CaseFront.png').convert('RGBA').resize((400, 400), Image.LANCZOS)
+
+ def frame(art, heading, words, pips, live=False):
+ image = banner(size)
+ image.alpha_composite(art, ((size[0] - 400) // 2, 16))
+ draw = ImageDraw.Draw(image)
+ for index in range(3):
+ x = size[0] // 2 - 75 + index * 54
+ draw.rounded_rectangle((x, 410, x + 42, 415), 3, fill=(245, 245, 247, 255) if index < pips else (90, 90, 94, 255))
+ width = draw.textlength(heading, font=title) + (34 if live else 0)
+ x = (size[0] - width) / 2
+ if live:
+ draw.ellipse((x, 448, x + 20, 468), fill=(240, 74, 56, 255))
+ x += 34
+ draw.text((x, 432), heading, font=title, fill=(245, 245, 247, 255))
+ draw.text((size[0] / 2, 500), words, font=detail, fill=(170, 170, 176, 255), anchor='ma')
+ return image
+
+ frames = [frame(lid[0], 'Open the lid', 'Keep both AirPods inside.', 1)] * 12
+ frames += [frame(art, 'Close the lid', 'AirPointer goes on by itself.', 2) for art in lid for _ in range(2)]
+ frames += [frame(lid[-1], 'Close the lid', 'AirPointer goes on by itself.', 2)] * 8
+ for step in range(18):
+ t = step / 17
+ turn = (1 - math.cos(t * math.pi)) / 2
+ art = lid[-1].rotate(-90 * turn, Image.BICUBIC)
+ frames.append(frame(Image.blend(art, front, max(0, turn - 0.75) * 4), 'Turn it upright', 'A quarter turn clockwise.', 3))
+ frames += [frame(front, 'Pointing', 'Aim with the case. Tap its front to click.', 3, True)] * 28
+
+ with tempfile.TemporaryDirectory() as folder:
+ for index, image in enumerate(frames):
+ image.save(Path(folder) / f'{index:03}.png')
+ subprocess.run(['ffmpeg', '-y', '-loglevel', 'error', '-framerate', '15', '-i', f'{folder}/%03d.png', '-filter_complex',
+ '[0:v]scale=880:-1:flags=lanczos,split[a][b];[a]palettegen=reserve_transparent=1:stats_mode=full[p];[b][p]paletteuse=dither=bayer:bayer_scale=4:alpha_threshold=128',
+ '-loop', '0', str(out / 'connect.gif')], check=True)
+
+
+out.mkdir(exist_ok=True)
+icon()
+screens()
+setup()
+connect_animation()