Overview

Face Light is a browser-native face enhancement app that takes a live webcam feed, runs face landmark detection with MediaPipe, and composites a corrected output stream in real time using a GPU-oriented rendering pipeline.

The project is designed as both:

• a working user-facing demo for webcam lighting and portrait enhancement
• a diagnostics-heavy prototype for tuning a face-processing pipeline in production-like browser conditions

It runs entirely on the client, which means there is no server-side image processing step. Camera access, face tracking, rendering, snapshots, and recordings all happen in the browser.

Highlights

• Real-time split preview showing original and processed output side by side
• Lighting and portrait controls for brightness balancing, smoothing, warmth, saturation, sharpening, background blur, vignette, and grain
• Preset system with Natural, Video Call, Portrait, Cinematic, and Studio
• MediaPipe Face Landmarker integration for live face tracking
• WebGL2 compositor with multi-pass processing, timing support, and adaptive quality hooks
• Diagnostics export with structured log entries for app, camera, UI, and pipeline events
• Performance HUD and pass visualizer for GPU timing inspection
• Snapshot capture and short recording export from the processed stream
• Capability probing for browser features and WebGL2 hardware limits
• Vercel-ready static deployment with cross-origin isolation headers

What The App Actually Does

At runtime, Face Light:

1. Requests webcam access.
2. Detects browser and GPU capabilities.
3. Starts a face landmark worker using MediaPipe.
4. Samples face regions such as the forehead, cheeks, and chin.
5. Runs a compositor that balances luminance and applies enhancement passes.
6. Displays a live before/after split preview.
7. Exposes diagnostics, performance panels, and capture tools for inspection.

This makes it useful both as a product demo and as a development harness for experimenting with browser-native beauty and lighting correction.

UI Surface

The current app shell includes:

• Resolution selector with 480p, 720p, and 1080p
• Capability badge showing detected GPU backend information
• Split preview for original versus corrected output
• Capture toolbar for snapshots and recordings
• Preset bar for one-click looks
• Correction controls for manual tuning
• Face mesh overlay toggle for debugging landmark placement
• Luminance waveform for region brightness feedback
• Pipeline visualizer for pass timings
• Diagnostics panel for structured event logging
• Performance HUD for runtime metrics

Controls

Available correction sliders:

• Brightness Balance
• Skin Smoothing
• Warm / Cool
• Saturation
• Sharpening
• Background Blur
• Vignette
• Film Grain

The app also exposes:

• a master Corrections toggle
• a Show Mesh toggle
• automatic startup using the Video Call preset for a more visible default result

Presets

Built-in looks:

• Natural: light-touch correction
• Video Call: brighter, smoother, more flattering conferencing look
• Portrait: stronger blur and richer styling
• Cinematic: cooler tone, heavier vignette, visible grain
• Studio: stronger brightness equalization and sharper output

Architecture

Main pieces

• Vue 3 + Vite front-end app shell
• MediaPipe Face Landmarker worker for face detection and tracking
• WebGL2 compositor worker for post-processing and final composition
• Capture pipeline for snapshots and recordings
• Diagnostics + performance tools for debugging, export, and tuning

Render flow

The compositor is structured as a multi-pass GPU pipeline. In broad terms:

1. Camera frames are read from the input video track.
2. Face landmarks are produced in a dedicated worker.
3. Face-region masks are generated for skin and depth-like guidance.
4. Correction passes run for brightness balancing and skin smoothing.
5. Optional passes run for bokeh-style blur, sharpening, vignette, and grain.
6. A final composite pass produces the processed stream shown in the UI.

Production-oriented additions already in the repo

• WebGL2 capability tiers with startup policy recommendations
• Runtime quality configuration and adaptive-degradation hooks
• Render target validation and framebuffer completeness checks
• Landmark texture-atlas upload path to reduce per-frame uniform traffic
• Context-loss handling and compositor rebuild logic
• GPU pass timing support for diagnostics and tuning

Tech Stack

• Vue 3
• Vite
• TypeScript
• PrimeVue
• Tailwind CSS
• MediaPipe Tasks Vision
• WebGL2
• WebCodecs
• OffscreenCanvas
• Vercel

Repository Layout

src/
  components/             UI panels, controls, overlays, diagnostics
  composables/            camera, capture, diagnostics, and pipeline hooks
  pipeline/
    compositor/           WebGL2 compositor and shader passes
    frame-capture/        output stream capture utilities
    landmark-buffer/      landmark interpolation and buffering
    workers/              compositor and facemesh workers
  utils/                  feature detection and supporting utilities
public/
  models/                 MediaPipe face model assets
  wasm/                   MediaPipe wasm runtime assets
scripts/
  download-assets.sh      build-time asset fetcher

Getting Started

Prerequisites

• Node.js 20+ recommended
• a modern Chromium-based browser
• webcam access
• HTTPS in production, or localhost for local camera development

Install

npm install

The postinstall step downloads the MediaPipe model and WASM assets automatically.

Run locally

npm run dev

Open the local URL printed by Vite, grant camera access, and the app should auto-start.

Production build

npm run build

Preview the production bundle

npm run preview

Deployment

Vercel

This repo is already configured for Vercel in vercel.json.

• build command: npm run build
• output directory: dist
• cross-origin headers are set so the app can run with crossOriginIsolated

You can deploy directly with the button at the top of this README, or import the repo into Vercel manually.

Important deployment caveat

Builds currently fetch MediaPipe assets during install/build using scripts/download-assets.sh.

That works on Vercel, but it does mean builds depend on external network availability:

• Google Cloud Storage for face_landmarker.task
• jsDelivr for the MediaPipe WASM files

If you want fully deterministic builds, vendor those assets into the repo or move them to a storage location you control.

Browser Requirements

The app targets modern browsers with:

• WebGL2
• OffscreenCanvas
• requestVideoFrameCallback or MediaStreamTrackProcessor
• SharedArrayBuffer support in cross-origin isolated environments
• WebCodecs for the best capture/runtime path

The app probes feature availability and GPU limits at startup and uses a capability tier to choose safer defaults.

Diagnostics And Debugging

Face Light includes a diagnostics log that captures structured events from:

• the app shell
• camera startup
• worker initialization
• pipeline lifecycle
• UI interactions
• runtime errors

This is useful when debugging:

• browser capability mismatches
• camera startup failures
• worker messaging issues
• context loss
• performance regressions

The diagnostics panel can export a session log for reproduction and issue reporting.

Performance Notes

This app is intentionally GPU-heavy.

Behavior depends on:

• browser support level
• webcam capture resolution
• GPU driver quality
• laptop thermals and power mode
• whether expensive effects like blur are enabled

The repo already contains:

• pass timing instrumentation
• adaptive quality plumbing
• capability-tier startup defaults
• reduced-resolution paths for more expensive blur work

Even with those safeguards, browser graphics stacks are inconsistent, so cross-device testing still matters.

Limitations

• camera access only works on secure origins or localhost
• build-time asset fetching makes production builds network-dependent
• the runtime path is centered on WebGL2; WebGPU code exists but is not the active backend
• effect quality and stability vary across browsers and drivers
• this is still closer to an advanced demo/prototype than a hardened consumer product

Troubleshooting

The app builds locally but not in CI or Vercel

Check whether the asset download step failed. The build needs outbound access to download MediaPipe assets.

The camera starts but the processed output looks subtle

The app starts with the Video Call preset, which is visible but still moderate. Try switching to Portrait or Cinematic and increasing blur, sharpening, or vignette.

The app opens but processing does not start

Check the diagnostics panel first. The most common causes are:

• unsupported browser capabilities
• worker initialization errors
• camera permission issues
• graphics driver or WebGL-related failures

The output resolution is lower than requested

The camera hardware may negotiate down from the requested ideal dimensions. That is normal and depends on the device/browser combination.

Why This Repo Exists

Face Light is a useful starting point for teams exploring:

• browser-native webcam enhancement
• real-time face-region correction
• WebGL2 post-processing pipelines
• MediaPipe integration in a worker-based architecture
• diagnostics-first prototyping for graphics-heavy web apps

Contributing

Issues and PRs are welcome if they are concrete and technically grounded.

Good contribution areas:

• browser compatibility hardening
• WebGPU backend completion
• shader quality improvements
• automated tests and CI
• UX polish around capture and diagnostics

Roadmap Ideas

• selectable WebGPU backend
• stronger fallback modes for lower-end devices
• reusable benchmark scenes
• better automated browser coverage
• model/version pinning for deterministic production builds
• shareable preset URLs and session profiles

Status

Local production builds currently pass with:

npm run build

The repo is also configured to deploy as a static app on Vercel.

Author

Built by @pradhankukiran.