Ball Bells — Help & Troubleshooting Guide

A complete guide to playing, tuning, recording, and connecting Ball Bells on Apple Vision Pro. If you run into trouble, jump to the Troubleshooting section near the bottom.

Getting Started

1. Launch Ball Bells. You’ll see a welcome screen with a quick tour.
2. Tap “Let’s Make Some Bells.” This opens the immersive space and places a tuned arc of eight bells within arm’s reach.
3. Ring a bell two ways:
   • Look and pinch — glance at a bell and pinch your thumb and index finger together.
   • Reach and touch — extend your hand and tap the bell directly with a fingertip.
4. The bell lights up, animates, and rings. The harder/faster you move, the louder it sounds.

Tip: You don’t need to sign in, create an account, or connect anything. Everything works offline, out of the box.

The Control Panel

The window next to your bells has four tabs:

Tab	What it does
Play	Switch between Play/Edit mode, add or delete bells, and open/close the immersive space.
Tune	Pick a root note and scale, retune your bells, and save/open bell setups.
Record	Record performances, loop, overdub, set tempo, quantize, and export.
MIDI	Send notes to other apps and devices.

The transport bar (Record / Play buttons) stays visible at the bottom of the panel at all times.

Playing & Arranging Bells

Play mode vs. Edit mode

Use the Mode switch on the Play tab:

• Play mode — touching or pinching a bell rings it.
• Edit mode — pinch-grab a bell and move it anywhere in your space. Bells don’t ring while you’re arranging them.

Moving bells

• In Edit mode: reach toward a bell, pinch to grab it, and drag it wherever you like — build a wide arc, stack a chord, or place bells above your desk.
• Precisely: select a bell and use the Position (X/Y/Z) sliders in the bell editor. Tap Reset in Front of Me to bring a lost bell back into view.

Adding & removing bells

• Add Bell (Play tab) drops in a new bell tuned to the next note in your scale.
• Swipe a bell in the list to Delete it, or use Remove All to clear everything (this can’t be undone).

Customizing a bell

Select any bell to open its editor, where you can set:

• Name, Color (12 choices), and Visual Size
• Pitch (MIDI note) — the frequency updates automatically
• Timbre — Classic Bell, Glass, Warm Chime, Gong, or Marimba
• Decay (how long it rings) and Brightness (how much high-frequency shimmer)
• Animation when rung — Bounce, Pulse, or Jiggle
• MIDI channel and velocity

Tap Test Ring to preview without reaching out.

Tuning to a Scale

On the Tune tab:

1. Choose a Root note and a Scale (Major, Natural Minor, Major Pentatonic, Minor Pentatonic, Blues, or Chromatic).
2. Then apply it:
   • Load Default Scale — replaces your bells with a fresh, tuned preset.
   • Retune Bells to Scale — keeps your current bells but reassigns their pitches to the scale, in order.
   • Snap Existing Pitches — nudges each bell to the nearest note in the scale, keeping them close to their current pitch.

Recording, Looping & Overdubbing

On the Record tab (and the transport bar):

1. Set your Tempo (BPM).
2. Tap Record, play your bells, then tap Stop.
3. Tap Play to hear it back. Tap Clear to discard it.

Options:

• Loop playback — repeats your recording continuously. Set the Loop length in beats.
• Overdub while looping — with a loop playing, tap Overdub to layer new bells on top of the existing pattern.
• Metronome — a click track while recording or playing.
• Quantize — automatically snaps your strikes to Quarter, Eighth, or Sixteenth notes for a tighter feel. Set to Off to keep your exact timing.

Saving & Sharing Your Work

• Save/Open Bells (Tune tab) — save a bell arrangement as a file and reload it later.
• Save/Open (Record tab) — save a full performance (bells + recorded notes) as a file.
• Export MIDI (Record tab) — turn any recording into a standard .mid file you can drop into Logic, Ableton, GarageBand, or any DAW. Each bell’s channel, note, and velocity are preserved.

Your current bells, recording, and settings are also saved automatically and restored the next time you open the app.

Connecting MIDI (Advanced, Optional)

On the MIDI tab. Both options are off by default.

CoreMIDI virtual source

Turn on CoreMIDI virtual source to make Ball Bells appear as a MIDI source named “BallBells” to other apps and connected devices. Each bell sends on its own channel with its configured note and velocity.

Raw MIDI over UDP

Turn on Raw MIDI over UDP to stream MIDI bytes to another device on your local network (for example, an ipMIDI client on a Mac).

• Enter the Host (IP address) and Port of the receiving device.
• The default port is 21928 (a common ipMIDI base port).
• The status line shows the current connection state (ready, waiting, failed, etc.).

MIDI Panic

If a note gets stuck on a connected instrument, tap MIDI Panic to send an “all notes off” across every channel.

Troubleshooting

I don’t see any bells

• Make sure the immersive space is open: on the Play tab, use the Open Immersive Space button.
• A bell may have been moved out of view. Select it and tap Reset in Front of Me, or use Load Default Scale on the Tune tab to start fresh.
• If the list is empty, tap Add Bell or Load Default Scale.

I can’t ring bells by touching them with my finger

• Fingertip touch and pinch-to-grab require Hand Tracking permission. The app asks for this when you open the immersive space.
• If you declined it, you can still play by looking at a bell and pinching.
• To grant it later: Settings → Privacy & Security → Hand Tracking, and enable Ball Bells. Then reopen the immersive space.

Bells are too sensitive / not sensitive enough to touch

• Bells ring the moment a fingertip enters them. If you’re triggering them accidentally, switch to Edit mode while arranging, or space your bells farther apart.
• Strike volume follows how fast you move — tap gently for soft notes, move quickly for loud ones.

No sound

• Check the Vision Pro volume with the Digital Crown, and make sure you’re not in a Focus/mute state.
• Ring a bell after the immersive space has fully opened — audio starts up with the space.
• If audio was interrupted (a phone call, Siri, another app), the engine restarts automatically. If it stays silent, close and reopen the immersive space.
• Try Test Ring in a bell’s editor to confirm sound independently of hand tracking.

The sound distorts, or some strikes don’t play

• This is expected protection, not a bug. To keep audio clean, Ball Bells limits how many bells ring at once and how rapidly a single bell can retrigger. Very fast swipes across many bells will intentionally drop some strikes rather than overload and distort.
• For a cleaner sound with dense playing, lower each bell’s Brightness and shorten its Decay in the editor.

Playback sounds different from what I played

• If Quantize is on, your timing is snapped to the grid. Set Quantize to Off to preserve your exact performance.
• Check that Tempo and Loop length match what you intended before recording.

I can’t tap Record

• Recording is disabled during playback unless Overdub while looping is turned on. Stop playback first, or enable overdub.

My MIDI device isn’t receiving notes

• Confirm the correct option is enabled on the MIDI tab and check the on-screen status line.
• CoreMIDI: the virtual source is named “BallBells” — select it as an input in the receiving app.
• UDP: double-check the Host IP and Port, and that both devices are on the same network. A failed status usually means the address or port is wrong or the receiver isn’t listening.
• Note: MIDI features are not available in the visionOS Simulator — test on a device.
• If notes get stuck, tap MIDI Panic.

A file won’t open

• Ball Bells opens its own bell setup and recording files (and plain .json files it created). Files from other apps, or edited by hand, may not load.

I want to see the intro tour again

• On the transport bar, tap Show Intro Again.

I want to start completely over

• Use Remove All (Play tab) to clear your bells, then Load Default Scale (Tune tab) for a fresh set. Use Clear on the transport bar to delete the current recording.

Privacy

Ball Bells collects no personal data, has no accounts, and makes no network connections — except the optional Raw MIDI over UDP feature, which only sends MIDI data to the address you enter, and only when you turn it on. Hand-tracking data is used solely on-device to detect when you touch a bell and is never stored or transmitted.

Still need help?

Contact us at info@mickeydesigns.com and include your Vision Pro’s visionOS version and a short description of what happened. If it’s about sound or MIDI, let us know how many bells you were playing and which features (loop, overdub, CoreMIDI, UDP) were active.