Initialization Parameters

When loading gazefilter.app, you can use several query parameters to customize the initialization behavior of the application.

startup

The startup parameter overrides the default behavior for camera connection on application launch.

By default, gazefilter.app does not attempt to connect to a camera automatically when launched for the first time. However, on subsequent launches, if there was a successful camera connection in a previous session, the application will attempt to connect to the most recently used camera.

Values:

  • true — attempts to connect to a camera even on first launch,
  • false — never attempts to connect to a camera automatically.

origin

The origin parameter provides an extra layer of security by restricting the Gazefilter communicate only with the specified origin.

vfp

The vfp parameter enables polyfilling for Video Frame API, even if the browser supports it.

Can be useful when the browser’s implementation of the Video Frames API has known bugs or issues.

controls

The controls parameter customizes which UI control elements are visible.

Values:

  • none — hides all controls
  • full or all — shows all controls (default)
  • Comma-separated list of controls to show:
    • devices — camera device selection
    • models — model selection
    • preview — preview settings
    • hints — toggle for UI hints
    • power — power toggle
    • settings — settings and calibration
    • help — question mark button

visuals

The visuals parameter allows tweaking UI elements visibility.

Values (comma-separated):

  • nocorner — hides the GitHub corner link
  • nofps — hides the frame rate counter

config

The config parameter allows customizing the Gazefilter configuration. It accepts either a JSON string or a preset identifier.

Use predefined configurations with simple preset identifiers. You can specify either a detector or shape model preset alone, or combine them:

  • Detector presets (use alone or as prefix):
    • DB — basic detector,
    • DL — lightweight detector.
  • Shape model presets (use alone or as suffix):
    • S05 — 5-points face shape model,
    • S20 — 20-points face shape model,
    • S68 — 68-points face shape model.

When combining detector and shape model presets:

  1. Face detector (DB/DL) must always come first,
  2. Use a hyphen (-) as separator,
  3. Add shape model (S05/S20/S68) second.

Examples:

  • DL — Light detector only,
  • S20 — 20-points shape model only,
  • DL-S20 — Light detector with 20-points shape model.

For advanced customization, provide a JSON string with configuration overrides:

{
  "backend": {
    "face_shaper": "models/face-05.shaper.bin",
    "face_pinmap": "models/face-05.shaper.json",
    "core": {
      "pose": {
        "keys": [
          "nose_bottom",
          "left_eye_outer_corner",
          "right_eye_outer_corner",
          "left_eye_inner_corner",
          "right_eye_inner_corner"
        ]
      }
    }
  }
}

When passing JSON configuration in URL parameters, use a minified string without newlines.

calib

The calib parameter allows customizing the calibration sequence. It accepts either a preset identifier or a custom sequence definition.

Preset descriptions:

  • quick — A balanced sequence that requires minimal head movement:

    1. Initial demo point with introduction
    2. Classic 9-point calibration on gray background
    3. Comfort break and closer position calibration
    4. Rectangle pattern calibration on gray background
    5. Comfort break and farther position calibration
    6. Classic 9-point calibration on gray background
    7. Perimeter pattern on white background
    8. Rectangle pattern on black background
    9. Final outro message

  • basic — Standard sequence with head movement variations:

    1. Initial demo point with introduction
    2. Classic 9-point calibration on gray background
    3. Left-facing triangle pattern calibration
    4. Comfort break and right-facing triangle pattern calibration
    5. Comfort break and closer position rectangle pattern
    6. Comfort break and farther position classic pattern
    7. Classic 9-point calibration on white background
    8. Classic 9-point calibration on black background
    9. Final outro message

  • long — Extended sequence with dense patterns:

    1. Initial demo point with introduction
    2. Dense pattern calibration on gray background
    3. Left-facing diamond pattern calibration
    4. Comfort break and right-facing diamond pattern calibration
    5. Comfort break and closer position perimeter pattern
    6. Comfort break and farther position classic pattern
    7. Dense pattern calibration on white background
    8. Dense pattern calibration on black background
    9. Final outro message

  • full — Comprehensive sequence covering all head positions:

    1. Initial demo point with introduction
    2. Dense pattern calibration on gray background
    3. Left-facing diamond pattern calibration
    4. Right-facing diamond pattern calibration
    5. Bottom-facing diamond pattern (head tilted forward)
    6. Top-facing diamond pattern (head tilted backward)
    7. Elevated position triangle pattern
    8. Lower position triangle pattern
    9. Left-tilted triangle pattern at top-left
    10. Right-tilted triangle pattern at top-right
    11. Body-left triangle pattern
    12. Body-right triangle pattern
    13. Close-range perimeter pattern
    14. Classic pattern from normal distance
    15. Dense pattern on white background
    16. Dense pattern on black background
    17. Final outro message

For custom sequences, each step is defined using this format:

[background][.calibset][~directive]

Where:

  • background: white, gray, black, or interface (default)
  • calibset: empty (default), demo, classic, perimeter, rectangle, dense, diamond
  • directive: Instruction like intro, straight, comfort, outro

Important: Point samples are only recorded to the calibration dataset when a non-default background is specified (white, gray, or black). Using the default interface background or no background will show the points but won’t record samples.

Position values for patterns and single points:

  • Cardinal: top, right, bottom, left
  • Diagonal: right-top, right-bottom, left-bottom, left-top

Available directives:

  • intro — initial instructions
  • straight — request to face straight ahead
  • tilt-left — request to tilt head left
  • tilt-right — request to tilt head right
  • tilt-forward — request to move chin down
  • tilt-backward — request to move chin up
  • turn-left — request to turn head left
  • turn-right — request to turn head right
  • elevate — request to move body up
  • descent — request to move body down
  • move-left — request to move body left
  • move-right — request to move body right
  • move-closer — request to move closer to screen
  • move-farther — request to move away from screen
  • comfort — request to return to comfortable position
  • outro — completion message

Some examples of custom sequences:

?calib=demo~intro>white.classic>~outro
?calib=demo~intro>gray.dense>~outro
?calib=demo~intro>gray.rectangle>white.classic>black.diamond>~outro

This creates a sequence with:

  1. Demo point with intro message
  2. Classic 9-point calibration on white background
  3. Final outro message

Initialization Example

You can combine multiple parameters using the & symbol:

https://gazefilter.app?origin=https://example.com&startup=true&controls=devices,models&vpf

This initialization URL will:

  • Attempt to connect to a camera on startup
  • Restrict communication to https://example.com
  • Show only the device selection and model selection controls
  • Enable Video Frame API polyfilling