# headtrackr: A Browser-Based Head Tracker That Depends on Your Camera and Your Patience > headtrackr is a JavaScript library that estimates a user's head position from a webcam feed using WebRTC and getUserMedia, aimed at head-coupled perspective effects in the browser. It is simple to start but shows its age in setup friction and browser support. **auduno/headtrackr** — GitHub describes it as Javascript library for headtracking via webcam and WebRTC/getUserMedia. The repository metadata lists JavaScript as its primary language. This article stays within the project description and details documented in the GitHub repository README. - Repository: https://github.com/auduno/headtrackr - Stars: 3,690 · Forks: 500 - Language: JavaScript - License: not declared - Published: 2026-08-13 · Updated: 2026-08-18 · Language: en - Canonical page: https://hysenlabs.com/projects/auduno-headtrackr ## What headtrackr Actually Solves headtrackr addresses a narrow problem: determining where a person's head is relative to the screen, using only a webcam and JavaScript. It does not do full body tracking or gesture recognition. The target user is a web developer who wants to create a head-coupled perspective effect, where the 3D view shifts as the viewer moves, or a simple face-following interaction. The README points to examples like a canvas sprite that follows your face and a three.js integration for pseudo-3D scenes. This is not a general computer vision toolkit; it is a focused library that emits two event types and leaves the rendering to you. ## The Mechanism: From Video Frames to Position Events The core flow is straightforward. You provide a video element that receives the getUserMedia stream and a canvas element that receives copies of the video frames. The Tracker object, created with new headtrackr.Tracker(), runs an internal loop that grabs frames from the video, processes them to find a face, and then estimates the head's position. The output is delivered as DOM events on the document. The headtrackingEvent carries x, y, and z coordinates in centimeters relative to the screen center, which is the key data for head-coupled perspective. The facetrackingEvent gives x, y, width, height, and angle, describing the face's bounding box and rotation on the video frame. The separation of these two event types is useful: you can use one for 3D camera movement and the other for 2D overlays. The library also ships pre-packaged controllers for three.js, which handle the math of converting the head position into a camera offset, saving you from writing that code yourself. ## Getting It Running: Commands and Configuration The README gives a minimal setup. You download the minified headtrackr.js and include it with a script tag. Then you add a video element with autoplay and a hidden canvas, both sized 320 by 240. The JavaScript is three lines: get the video and canvas elements, create a Tracker, call init(videoInput, canvasInput), then start(). After that, you attach event listeners for headtrackingEvent and facetrackingEvent on the document. There are no configuration keys to tune in the basic usage; the library works out of the box. For building from source, you need Node.js and grunt. Run npm install to fetch dependencies and grunt to build. The README does not document any options for the Tracker constructor, such as detection thresholds or interval rates, so you are limited to the defaults unless you read the reference documentation linked in the README. ## The Browser Support Caveat The biggest limitation is the dependency on getUserMedia and WebRTC. The README links to caniuse.com/stream, which was relevant in 2012 but is now outdated. Modern browsers have changed their getUserMedia API, and the original specification that headtrackr was built against has evolved. The README also explicitly says you need a browser with camera support, which excludes older versions of Internet Explorer and Safari. If your audience uses a browser that does not support getUserMedia, the library will fail silently or throw an error. You must handle the absence of the API yourself. The project's default branch is dev, and the last push date is unknown, which suggests the code may not have been updated for the latest WebRTC changes. In practice, you should test headtrackr in your target browser before building anything on top of it. ## A Real Alternative: Three.js with a Different Approach A direct alternative is to use a more modern face tracking library such as clmtrackr or face-api.js, but the README does not mention these. However, a relevant alternative that shares the same goal is to use the WebVR or WebXR API for head tracking, which is built into browsers and does not rely on a webcam. That approach uses the device's sensors, such as an accelerometer or a VR headset, to get head position and orientation. The difference is fundamental: headtrackr uses computer vision on a 2D video feed and estimates 3D position with a single camera, which is inherently less accurate and requires good lighting. WebXR gives you hardware-accelerated tracking with sub-millimeter precision, but it requires a compatible device and does not work with a plain laptop webcam. For a desktop web app that must work with any camera, headtrackr's approach is the only option, but for a VR or AR experience, WebXR is the better fit. ## Maintenance and License Implications The repository has no archived flag, but the absence of recent releases and an unknown last push date indicate low activity. The README mentions building with grunt, which is a build tool that has fallen out of favor compared to webpack or esbuild, so the toolchain is dated. The license is MIT for the library itself, with portions under BSD-3 and MIT from other authors. This is permissive, meaning you can use it in commercial projects without paying or sharing your source code. However, you should keep the license notices intact, as required by the MIT and BSD-3 terms. There is no mention of maintenance commitments or issue response times. Given the age, you should treat the library as a stable but frozen codebase: it will not receive updates for new browser APIs, and you must be prepared to fork it if you need fixes. ## Conclusion Adopt headtrackr if you need a lightweight, MIT-licensed head tracker for a demo or a research prototype that runs entirely in the browser and you can accept the constraint of modern Chrome or Firefox with getUserMedia enabled. Do not use it for a production product that must support Safari or older browsers, or if you need precise millimeter accuracy; the README itself only promises estimated positions. Before committing, verify that your target browser still supports the getUserMedia API as headtrackr expects it, and check the repository's last commit date, because the project appears dormant and the API may not align with current WebRTC standards. ## FAQ ### What is headtrackr? It is a JavaScript library for real-time face and head tracking in the browser. It estimates the position of a user's head in relation to the centre of the screen, in centimetres, using a web camera through the browser's media capture standard, and it needs no runtime dependencies. Two document-level events report the results, and pre-packaged controllers are included for one three-dimensional library to produce head-coupled perspective effects. ### How do I use headtrackr on a page? Include the library with a script tag, give its tracker a video element for the media stream and a hidden canvas it copies frames to, then initialise and start it. The README's own snippet does this in eight lines, with the canvas set to 320 by 240 and hidden, and the video set to autoplay and loop. Note that the install sentence, the download link and the script tag name three different paths. ### Does headtrackr work in current browsers? The README says a browser with camera support for the media capture standard, and links a browser compatibility page, so the requirement is expressed as a capability rather than as versions. The library obtains its camera stream through that standard and needs a device with a camera. The README states no minimum browser version, and the build it was assembled with targets a module convention from the previous decade. ### How is headtrackr built from source? With a task runner. The README says to have the task runner and a Node runtime installed, to install development dependencies with a package manager, and to run the task runner in the root directory. There are three development dependencies, all plugins for that runner, all constrained to early 0.x releases, and the manifest declares no scripts, so there is no named build command. ### What licence is headtrackr under? The README states the library is distributed under the MIT licence and says it includes code from two named contributors, one under a three-clause BSD licence and one under MIT, with links to each. The repository's licence field reports nothing recognised, and there is no licence file among the seven entries at the root, so the README is the only statement of terms. ### Is this the head-tracking tool used in flight simulators and games? No. Those search questions concern a head-tracking utility that drives games and simulators from a phone or a webcam. This repository is a browser library that estimates a head position from a camera and dispatches two events on the document, with no runtime dependencies, a default branch named for development, and a last commit dated 2023-06-15. ## Sources - [Official README](https://github.com/auduno/headtrackr#readme) - [Project repository](https://github.com/auduno/headtrackr) - [README](https://github.com/auduno/headtrackr/blob/dev/README.md) - [Releases](https://github.com/auduno/headtrackr/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/auduno-headtrackr