wtf is headtrackr?

auduno/headtrackr — explained in plain English

Analysis updated 2026-07-03

★ 3,707JavaScriptAudience · developerComplexity · 3/5LicenseSetup · moderate

Mindmap

mindmap
  root((headtrackr))
    What it does
      Face detection in browser
      3D head position tracking
      Real-time coordinates
    How it works
      getUserMedia API
      Video and canvas elements
      Fires DOM events
    Outputs
      Face bounding box
      X Y Z coordinates
      Rotation angle
    Integrations
      three.js controllers
      Perspective shift effect
    Setup
      Include minified JS
      Serve over HTTPS
      Node and Grunt to build

mindmap root((headtrackr)) What it does Face detection in browser 3D head position tracking Real-time coordinates How it works getUserMedia API Video and canvas elements Fires DOM events Outputs Face bounding box X Y Z coordinates Rotation angle Integrations three.js controllers Perspective shift effect Setup Include minified JS Serve over HTTPS Node and Grunt to build

Why would anyone build with this?

REASON 1

Create a parallax 3D scene in the browser that shifts perspective as the user moves their head left or right

REASON 2

Build a web-based game that responds to the player's physical head movement without mouse or keyboard

REASON 3

Add a face-tracking overlay to a webcam feed on a webpage that shows a bounding box around the user's face

REASON 4

Connect headtrackr to three.js to make a 3D model appear to exist in real space as the viewer moves closer or further away

What's in the stack?

JavaScriptthree.jsNode.jsGruntgetUserMedia API

How it stacks up

	auduno/headtrackr	jin-yufeng/mp-html	mumuy/relationship
Stars	3,707	3,708	3,708
Language	JavaScript	JavaScript	JavaScript
Setup difficulty	moderate	easy	easy
Complexity	3/5	2/5	2/5
Audience	developer	developer	developer

Figures from each repo's GitHub metadata at analysis time.

How do you spin it up?

Difficulty · moderate Time to first run · 30min

Page must be served over HTTPS for Chrome to grant camera access.

Use freely for any purpose, including commercial use, as long as you keep the copyright notice.

Wtf does this do

headtrackr is a JavaScript library that uses a laptop or desktop webcam to track the position of a person's face in real time, inside a web browser. It relies on a browser standard called getUserMedia, which gives web pages permission to access the camera without any plugins or installs. The library does two things. First, it locates the user's face in the webcam feed and reports its position on screen, including the bounding box size and rotation angle. Second, it estimates where the user's head is in three-dimensional space relative to the center of the screen, reporting x, y, and z coordinates in centimeters. As the person moves their head closer, further, or to the side, those numbers update continuously. To use it, you include the minified JavaScript file in a webpage, create a video element and a hidden canvas element, then pass both to the tracker. The tracker fires events on the page that your own code can listen to. One event type carries the face position data, the other carries the head position in 3D space. You can also connect it to the three.js 3D graphics library using pre-built controllers included in the repo, which creates a perspective-shift effect where the 3D scene appears to respond to the viewer's physical head movement. The project was built at a time when webcam access in browsers was new technology. Chrome now requires the page to be served over HTTPS for camera access to work. The library is distributed under the MIT license, with small portions under the BSD-3 license. Building from source requires Node.js and the Grunt task runner.

Yoink these prompts

Prompt 1

I want to build a web page where a three.js 3D scene shifts perspective based on the viewer's real head position using headtrackr. Show me how to include the library, set up the video and canvas elements, and connect it to the three.js controller.

Prompt 2

Using headtrackr in my webpage, how do I listen for face position events and display the x, y, and bounding box data on screen as the user moves in front of their webcam?

Prompt 3

I want to build a head-tracking demo that shows the user's 3D head coordinates (x, y, z in centimeters) in real time. Walk me through setting up headtrackr on an HTTPS page.

Prompt 4

How do I use the pre-built three.js controllers in headtrackr to create a perspective-shift effect that makes a 3D object look like it's sitting on a desk in front of the viewer?

Frequently asked questions