Quickstart
Visualhandpan is a browser-based visual companion for handpan players. It listens to the handpan through a microphone, recognizes notes and scales, tracks hand movement through a camera, and turns this information into responsive visual scenes.
This quickstart describes two ways to use the current application:
– Practice: use a computer or laptop to explore how your playing, notes, and hand movements affect the visuals.
– Performance: connect an additional screen or projector and prepare a stable visual setup for rehearsal or live use.
These are usage workflows, not separate switches inside the application. Visualhandpan always opens on its clean performance canvas. The small settings button at the top opens Setup whenever configuration is needed.
What You Need
For both workflows:
– the published Visualhandpan web address and an access token
– a modern computer or laptop with a current web browser
– a camera, either built in or connected externally
– a microphone, either built in or connected externally
– your handpan
– a reasonably well-lit playing area so the camera can see your hands
– a reasonably quiet sound environment during initial note and scale setup
For performance use, also prepare:
– a projector or second screen and the correct video cable or adapter
– reliable power for the computer and display
– enough setup time for a short camera, sound, and visual check
Visualhandpan must be opened through an `https://` address for normal camera and microphone access. The current application processes camera and microphone input in the browser. Scene presets are stored in that browser and are not automatically shared with another computer or browser profile.
First Launch
1. Connect any external camera, microphone, screen, or projector before opening Visualhandpan.
2. Open the published Visualhandpan address in the browser.
3. Enter the access token supplied by the site operator and submit it.
4. Allow camera access when the browser asks.
5. Allow microphone access when the browser asks.
6. Wait for the handpan layout scene and its welcome sequence to appear. The camera, sound analysis, and hand tracking start automatically after access is granted.
7. Find the small settings button at the top of the screen. This opens and closes Setup.
If camera or microphone access was denied, open the browser’s permissions for the site, allow the device, and reload the page.
Practice Mode
Practice mode is the easiest way to learn what Visualhandpan hears and how each visual reacts. Start with the default settings and change only one thing at a time.
Minimal Practice Setup
1. Place the laptop on a stable surface in front of you. Position it so the camera can see both hands while you play. Avoid a bright window directly behind you.
2. Place the handpan where you can play naturally and where the microphone can hear it clearly. A built-in laptop microphone is enough for a first test.
3. Complete First Launch, then open Setup with the button at the top.
4. Open the Input tab and expand Camera Input. Use the preview to check your position. Adjust Camera Zoom only if your hands are too small or are being cropped.
5. Expand Tracking. Move both hands over the instrument and check that the detected-hand count responds. Enable Mirror tracking horizontally only if left and right movement feels reversed.
6. Open the Instrument tab. The Sound Analysis summary should react when you strike the handpan, and its recognized-note display should begin showing stable notes.
7. In Handpan Recognition, set Tonefields to the total number of playable fields on your instrument, including the center Ding. Leave Automated scale recognition enabled for the first session.
8. Play the center Ding and then each surrounding tone field clearly, leaving a little space between strikes. Repeat the notes until a scale name and useful confidence appear.
9. Open the Visuals tab. Keep handpan layout selected for the first test. Its default mapped note highlight is intended to connect recognized notes to the corresponding tone fields.
10. Close Setup with the top close button or by clicking outside the setup panel. Play normally and watch each detected note flash, decay, and leave its scale-colored trail.
If You Already Know Your Scale
For more predictable practice feedback, open Instrument > Handpan Recognition and turn off Automated scale recognition. Then select:
1. the total number of tone fields
2. the Base Note, which is normally the center Ding and lowest note
3. the matching Scale Family
Check the displayed scale-note sequence before closing Setup. In manual mode, Visualhandpan uses the known scale to map detected pitches to its available notes, which is often more stable than discovering the scale again.
A First Practice Exercise
1. Play the Ding alone several times and confirm the center field responds.
2. Play each outer tone field slowly from low to high and compare the sound with the visual position.
3. Play a short repeating phrase and watch how overlapping highlights decay.
4. Reopen Instrument > Sound Analysis and look at Recorded Notes to see which notes received the most playing time.
5. Optionally open Recording > Note Capture, select Start Capture, play a short phrase, and stop the capture. This provides a simple note and scale overview; Export MIDI is available when captured note events exist.
Experiment With Scenes
Open Visuals > Scene Settings and try one scene at a time. Good starting choices are:
– handpan layout for the clearest note-to-tonefield relationship
– handpan 3D for a more physical instrument view with note and fingertip highlights
– note timeline for watching recognized notes develop over time
– bubbles, neon graphics, or falling points for more movement-led hand interaction
Drag to orbit a scene, use the mouse wheel or trackpad to zoom, and double-click to reset its view. Touch devices can use one-finger orbit and two-finger pinch zoom. Camera distance remains limited to the safe range shown under Scene Calibration.
Performance Mode
Performance mode uses the same application but prioritizes repeatability, a clean projected image, and fewer changes during the set. Prepare the configuration during a soundcheck and close Setup before playing.
Prepare The Computer And Display
1. Connect the projector or second screen before opening the browser.
2. Use the computer’s display settings to choose mirroring or an extended desktop. With an extended desktop, move the Visualhandpan browser window onto the projector screen.
3. Use the browser’s own full-screen mode for the cleanest output.
4. Connect the preferred camera and microphone before opening the page so the browser can use the intended devices.
5. Connect the computer to power, disable automatic sleep, and silence notifications before the performance.
The current application uses one browser window. Setup therefore appears on the same screen as the visuals while it is open. Complete configuration before the audience view is needed, then close Setup for the performance canvas.
Stage Soundcheck
1. Open Visualhandpan, enter the supplied access token, and allow camera and microphone access.
2. Open Setup > Input > Camera Input. Frame the playing area so both hands remain visible throughout normal playing movements.
3. Open Tracking and confirm that left and right hands are detected reliably under the actual stage lighting.
4. Open Instrument > Sound Analysis. Play soft and strong notes and confirm the sound bars and recognized note respond without needing excessive volume.
5. Set Tuning Reference to match the instrument, normally `432 Hz` or `440 Hz`.
6. For a known performance handpan, turn off Automated scale recognition in Handpan Recognition. Select the instrument’s total tone-field count, Ding base note, and scale family. Confirm the displayed note sequence.
7. Play every tone field once or twice. Confirm that the center Ding and each outer note highlight the expected field before moving on.
Manual scale selection is recommended on stage because room noise, monitors, other instruments, and reverberation can make automatic scale discovery less stable. Automatic recognition remains useful when the scale is genuinely unknown.
Prepare The Visual Output
1. Open Visuals > Scene Settings and select the scene for the performance. handpan layout is the clearest and most predictable starting scene; handpan 3D provides a more realistic instrument surface.
2. Use Scene Calibration or direct orbit and zoom controls to frame the scene for the projector.
3. Leave Post Processing disabled for the first test. Enable it only after confirming the scene remains smooth on the connected display. Bloom and trails can add intensity but also require more graphics performance.
4. If the projection must fit a handpan-shaped area, open Handpan Projection Shape, enable the shape, and use Set, move, zoom, and orbit controls to align it. Leave this disabled for normal full-screen projection.
5. Open Scene Presets and choose Save Current. Give the setup a short name such as the song, mood, or venue. Note the keyboard shortcut shown with the saved preset.
6. Prepare only a small number of tested presets for the first performance. Presets are stored in the current browser, so use the same computer and browser profile at the venue.
Final Performance Check
1. Open System and confirm the runtime says Running.
2. Play a short phrase while watching the projected result. Confirm note highlights, hand response, scene movement, and display smoothness.
3. If the image stutters, disable Post Processing first and return to handpan layout before changing more settings.
4. Close Setup by clicking its close button or outside the panel.
5. Keep the browser focused and in full-screen mode during the performance.
6. Use the displayed preset keyboard shortcuts only for presets that were tested during soundcheck.
Troubleshooting
| Symptom | Solution |
| The app does not pass the token screen | Check the supplied token carefully. A failed token submission leaves the app and opens the public website. |
| The camera or microphone does not start | Open the browser’s site permissions, allow camera and microphone, then reload the page. |
| Hands are not detected | Open Input > Camera Input and Tracking, improve front lighting, keep both hands inside the preview, and reduce camera zoom if they are cropped. |
| Movement feels reversed | Toggle Input > Tracking > Mirror tracking horizontally |
| Sound bars do not move | Check microphone permission and the computer’s selected input device. Move the microphone closer, but not so close that strong notes distort. |
| Notes are unstable or incorrect | Reduce background noise, play one clear note at a time, check the `432 Hz` or `440 Hz` tuning reference, and use a manually selected known scale. |
| Tone fields highlight in the wrong order | Confirm the total tone-field count, Ding base note, and scale family under Handpan Recognition. Use the default mapped note highlight source. |
| The projected scene is slow | Disable Post Processing, use handpan layout, close other graphics-heavy applications, and test at a lower projector/display resolution. |
| A saved preset is missing on another device | Presets are browser-local. Return to the computer and browser profile where the preset was created. By default presets are only stored in one open browser session. When closed then the presets are lost. |
| Setup is visible on the projector | Finish configuration, close Setup, and return the browser to full-screen mode. The current version has no separate control window. |