explaingit

auduno/headtrackr

Analysis updated 2026-07-03

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

TLDR

A JavaScript library that tracks a user's face position in real time via webcam in the browser, reporting 2D face location and 3D head coordinates so web apps can respond to head movement.

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
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

What do people build with it?

USE CASE 1

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

USE CASE 2

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

USE CASE 3

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

USE CASE 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 is it built with?

JavaScriptthree.jsNode.jsGruntgetUserMedia API

How does it compare?

auduno/headtrackrjin-yufeng/mp-htmlmumuy/relationship
Stars3,7073,7083,708
LanguageJavaScriptJavaScriptJavaScript
Setup difficultymoderateeasyeasy
Complexity3/52/52/5
Audiencedeveloperdeveloperdeveloper

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

How do you get it running?

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.

In plain English

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.

Copy-paste 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

What is headtrackr?

A JavaScript library that tracks a user's face position in real time via webcam in the browser, reporting 2D face location and 3D head coordinates so web apps can respond to head movement.

What language is headtrackr written in?

Mainly JavaScript. The stack also includes JavaScript, three.js, Node.js.

What license does headtrackr use?

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

How hard is headtrackr to set up?

Setup difficulty is rated moderate, with roughly 30min to a first successful run.

Who is headtrackr for?

Mainly developer.

Open on GitHub → Explain another repo

This repo across BitVibe Labs

Scan in gitsafehub Deploy in gitdeployhub auduno on gitmyhub

Verify against the repo before relying on details.

Alternatives & similar repos