Swift
Redesign the README with the icon, connect animation and screens.
Andy Gaodc9f277f71ae
diff --git a/Assets/README.md b/Assets/README.mdindex 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 licensesThe 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.gifnew file mode 100644index 0000000..b3e4088Binary files /dev/null and b/Assets/Readme/connect.gif differdiff --git a/Assets/Readme/icon.png b/Assets/Readme/icon.pngnew file mode 100644index 0000000..b229daaBinary files /dev/null and b/Assets/Readme/icon.png differdiff --git a/Assets/Readme/screens.png b/Assets/Readme/screens.pngnew file mode 100644index 0000000..0fdea47Binary files /dev/null and b/Assets/Readme/screens.png differdiff --git a/Assets/Readme/setup.png b/Assets/Readme/setup.pngnew file mode 100644index 0000000..75cd2f7Binary files /dev/null and b/Assets/Readme/setup.png differdiff --git a/README.md b/README.mdindex 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 thecursor 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>```mermaidflowchart TD@@ -84,6 +100,19 @@ flowchart TDPaused -->|"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 LRIf 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-homeAirPointer.app/Contents/MacOS/AirPointer --check-pointer-settingsAirPointer.app/Contents/MacOS/AirPointer --check-closed-case-nativeAirPointer.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.csvAirPointer.app/Contents/Resources/ClosedCaseMotion.bin --self-test```+</details>+## UninstallQuit AirPointer, delete this folder, then run:@@ -232,5 +257,5 @@ tccutil reset BluetoothAlways local.airpointer## LicenseThe 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.pynew file mode 100644index 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()