HeadPedal

HeadPedal turns your camera into a hands-free MIDI controller. It tracks head movement in real time and maps pitch, yaw, and roll to MIDI Control Change (CC) messages. Use it to control wah, whammy, volume, pan, or any other MIDI-compatible parameter without a physical expression pedal.

Features

• Real-time face and head-pose tracking with MediaPipe
• Independent pitch, yaw, and roll mappings
• Configurable MIDI channel and CC numbers
• One-way and two-way control modes
• Sensitivity, dead zone, response curve, direction, and smoothing controls
• Built-in Whammy, Wah, Volume, and Multi-axis profiles
• Custom profiles stored locally in the browser
• Live camera overlay and MIDI value monitoring
• Panic/reset control for returning mapped parameters to neutral values

Requirements

• Node.js 18 or later
• npm
• A camera
• A Chromium-based browser with Web MIDI support, such as Google Chrome, Microsoft Edge, or Opera
• A virtual MIDI port or a physical MIDI output

Camera access requires a secure context. Run HeadPedal on localhost during development or serve it over HTTPS in production.

Installation

Clone the repository and install the dependencies:

git clone <repository-url>
cd camera-midi-controller
npm install

Start the development server:

npm run dev

Open the local URL printed by Vite, usually http://localhost:5173.

MIDI Setup

HeadPedal sends messages to a MIDI output port. To route those messages into a DAW, standalone plug-in, or other music software, create a virtual MIDI port first.

macOS

1. Open Audio MIDI Setup.
2. Choose Window > Show MIDI Studio.
3. Open IAC Driver.
4. Enable Device is online.
5. Add or rename a port if needed.

Windows

Install loopMIDI, create a virtual port, and keep loopMIDI running while using HeadPedal.

Linux

Create a virtual MIDI port with ALSA or JACK. One option is the snd-virmidi kernel module.

After creating the port, enable it as a MIDI input in your DAW or plug-in.

Usage

1. Open HeadPedal in a supported browser.
2. Select a MIDI output and MIDI channel.
3. Click Start and allow camera access. The MediaPipe model is downloaded the first time tracking starts.
4. Face the camera in a comfortable neutral position while the initial calibration completes.
5. Enable the axis you want to use and choose its MIDI CC number.
6. Use MIDI Learn in your DAW or plug-in, then move your head along the selected axis.
7. Adjust sensitivity, dead zone, smoothing, and response curve until the control feels natural.
8. Click Calibrate again whenever your seating position or camera angle changes.

Click Stop or Panic/Reset to return active controls to their neutral MIDI values.

Axis Settings

Setting	Description
Mode	One-way maps the center to 0 and movement in one direction up to 127. Two-way maps the center to 64 and uses both directions.
Sensitivity	Sets the head angle required to reach the full MIDI range. Lower values produce a faster response.
Dead zone	Ignores small movements around the calibrated center.
Curve	Shapes the response. Values below 1 react faster near the center; values above 1 react more gradually.
Invert	Reverses the direction of the mapping.
Smoothing	Reduces tracking jitter. Higher values are steadier but can add latency.

Profiles

HeadPedal includes built-in profiles for Whammy, Wah, Volume, and multi-axis control. Built-in profiles are marked with a star and cannot be deleted. You can save your own settings as custom profiles and load them later. The most recently used settings are restored from browser local storage after a refresh.

Production Build

Create an optimized build:

npm run build

Preview the production build locally:

npm run preview

The generated files are written to dist/. Deploy that directory to any static host that supports HTTPS.

Project Structure

src/
  camera/       Camera discovery and stream lifecycle
  config/       Default settings, axes, CC presets, and profiles
  core/         Shared math utilities
  midi/         Web MIDI output and rate-limited CC delivery
  processing/   Filtering and head-angle-to-MIDI mapping
  profiles/     Built-in and local profile storage
  tracking/     MediaPipe face tracking and pose estimation
  ui/           Controls, camera overlay, and styles
  main.js       Application orchestration

How It Works

The camera feed is processed by MediaPipe Face Landmarker. Head rotation is converted into pitch, yaw, and roll angles, passed through a One Euro filter, measured relative to the calibrated center, and mapped to MIDI values from 0 to 127. MIDI messages are sent only when values change and are rate-limited to avoid flooding the selected output.

The MediaPipe WASM runtime and face landmark model are loaded from remote URLs configured in src/config/defaults.js. For offline use, download those assets and replace the configured URLs with local paths.

Troubleshooting

• No MIDI outputs appear: Confirm that the virtual MIDI port exists, refresh the page, and grant MIDI access if the browser asks for it.
• The camera does not start: Check browser camera permissions and make sure the page is running on localhost or HTTPS.
• The plug-in does not react: Enable the virtual port as a MIDI input, verify the selected channel and CC number, and repeat MIDI Learn.
• Values jitter: Increase smoothing or the dead zone, improve lighting, and keep your face clearly visible.
• Movement feels reversed: Enable the axis inversion setting.
• The center has shifted: Return to a neutral pose and calibrate again.

Privacy

Camera processing runs in the browser. HeadPedal does not upload or store camera frames. Custom profiles and the latest settings are saved only in the browser's local storage.