Human-like input
With human=True (the default) the cursor travels to its target along a
planned path and keystrokes follow a variable rhythm, modelled on published
models of human pointing and typing. The goal is input that looks natural to a
person watching the screen and to pages that react to pointer movement. emunium
makes no claim that this input is indistinguishable from a person’s or that it
avoids bot detection.
Choose a preset
| Preset | Pointer movement | Typing rhythm |
|---|---|---|
natural | Default, balanced movement | 280 characters per minute |
careful | Slower, with more corrections | 200 characters per minute |
brisk | Faster movement | 420 characters per minute |
Browser(motion="careful", typing="natural") selects each preset independently.
Motion planners, formulas, and parameter ranges
Motion planners
from emunium import Browser, Emunium, SigmaDriftPlanner, WindMousePlanner
browser = Browser(motion="careful") # preset of the default planner
browser = Browser(motion=WindMousePlanner.preset("brisk"))
# Standalone mode takes the same argument.
emu = Emunium(motion=SigmaDriftPlanner(sample_hz=250.0))motion= (on Browser and Emunium) is None (the natural preset of
SigmaDriftPlanner), a preset name ("natural", "careful", "brisk", all
of SigmaDriftPlanner), or a planner object. Every planner except
LinearPlanner has Planner.preset("natural" | "careful" | "brisk"):
careful moves slower with more corrections, brisk faster.
| Planner | Path |
|---|---|
SigmaDriftPlanner (default) | Sigma-lognormal strokes (Plamondon) along a gently curved path; duration from Fitts’ law; tremor and slow drift; sometimes an overshoot or undershoot followed by a corrective sub-stroke. |
BezierTremorPlanner | Cubic Bezier curve (occasionally S-shaped) walked with a minimum-jerk speed profile; tremor and drift; occasional overshoot with a straight corrective approach. |
WindMousePlanner | Benjamin Land’s WindMouse (gravity pulls toward the target, wind wanders), reported at a mouse polling rate. |
LinearPlanner | One step straight onto the target, no delay. |
Move duration follows Fitts’ law, a + b * log2(D / W + 1), where D is the
distance and W the target size: for element actions, the smaller side of the
element’s visible box in screen pixels (24 px when no element size is known,
for example in standalone mode). The duration varies randomly from move to move and
stays within 0.12 to 1.6 seconds for every preset (natural at most 1.2 s,
brisk 0.9 s). On Windows, steps are timed with a 1 ms timer resolution while
the move plays; a step that falls behind schedule is skipped rather than
delayed. The built-in planners keep intermediate steps inside the virtual
screen and off its corners and the primary monitor’s corners (the fail-safe);
on Windows, emunium also moves them onto a real monitor of a mixed
multi-monitor layout. Every move ends exactly on the target.
Parameters are dataclass fields; every value is checked on construction and an
out-of-range value raises InvalidArgumentError naming the parameter and its
range. Pairs are (low, high) ranges a value is drawn from.
| Object | Parameter (range) |
|---|---|
FittsTiming (timing= of each planner except LinearPlanner) | a 0 to 0.3 s, b 0.05 to 0.3 s/bit, variability 0 to 0.35, min_duration 0.12 to 0.6 s, max_duration 0.3 to 1.6 s; min_duration < max_duration and a + b <= max_duration |
Tremor (tremor=) | frequency_hz 4 to 15 Hz, amplitude_px 0 to 2 px, drift_px 0 to 3 px; amplitude_px[1] + drift_px <= 4 px. Tremor is also capped at a quarter of the target size and fades out before the end of the move. |
Overshoot (overshoot=) | probability 0 to 1, share 0 to 0.15 of the distance, px 0 to 80 px, slack_px 0 to 10 px; only for moves of at least 3 target sizes |
SigmaDriftPlanner | sigma 0.08 to 0.16, primary_fraction 0.85 to 1.0, correction_probability 0 to 1, correction_onset 0.5 to 2.5 sigma, correction_ratio 0.3 to 1.0, curvature 0 to 0.3, sample_hz 60 to 1000 Hz |
BezierTremorPlanner | curvature 0 to 0.3, s_curve_probability 0 to 1, correction_share 0.05 to 0.4, sample_hz 60 to 1000 Hz |
WindMousePlanner | gravity 1 to 20, wind 0 to 10 (at most gravity), max_step 3 to 50 px, target_area 1 to 50 px, sample_hz 60 to 1000 Hz |
from emunium import FittsTiming, Overshoot, SigmaDriftPlanner, Tremor
planner = SigmaDriftPlanner(
timing=FittsTiming(a=0.12, b=0.14, max_duration=1.4),
overshoot=Overshoot(probability=0.1),
tremor=Tremor(amplitude_px=(0.2, 0.8), drift_px=0.5),
)Custom planners
Any object with a plan method matching the MotionPlanner protocol can be
passed as motion=:
import random
from emunium import Browser, MotionStep, ScreenBounds
class StraightPlanner:
"""Twenty evenly spaced steps over 0.3 seconds."""
def plan(
self,
start: tuple[int, int],
end: tuple[int, int],
*,
target_size: float,
rng: random.Random,
bounds: ScreenBounds | None = None,
) -> list[MotionStep]:
steps = []
for i in range(1, 21):
t = i / 20
x = round(start[0] + (end[0] - start[0]) * t)
y = round(start[1] + (end[1] - start[1]) * t)
steps.append(MotionStep(x, y, 0.015))
return steps
browser = Browser(motion=StraightPlanner())MotionStep(x, y, dt) means “dt seconds after the previous step, put the
cursor on (x, y)” in screen input coordinates. target_size is Fitts’ W
in the same unit; rng is the random generator to draw from; bounds, when
given, is the virtual screen the steps should stay inside. The last step
should be end: emunium places the cursor exactly on the target after the
last step in any case. Keeping the other steps on screen and off its corners
is the planner’s job; on Windows, emunium additionally moves them onto the
nearest monitor and off the corners.
Typing rhythm and tuning reference
Typing rhythm
from emunium import Browser, TypingRhythm
browser = Browser(typing="brisk")
browser = Browser(typing=TypingRhythm(characters_per_minute=320, word_pause=(1.8, 2.8)))typing= (on Browser and Emunium) is None (the natural preset), a
preset name, or a TypingRhythm. The wait between two keystrokes is:
- a lognormal base interval with median
60 / characters_per_minuteseconds and spreadsigma(cut at 3 sigma); - multiplied by
word_pauseafter a space or tab, or bysentence_pauseafter a line break or after.,!,?or…followed by whitespace or the end of the text; - multiplied by
shift_pausebefore an ASCII capital or shifted symbol; - multiplied by a US-QWERTY bigram factor:
alternate_handwhen the keys use different hands,rollfor neighbouring fingers of one hand,same_fingerwhen one finger types both; 1.0 for other pairs and for non-ASCII characters; - plus, with probability
micro_pause_probability, a pause drawn frommicro_pauseseconds; - plus a random jitter of up to
jitter_msmilliseconds either way (theoffsetargument oftype); - never shorter than 15 ms.
| Preset | characters_per_minute | jitter_ms | Character |
|---|---|---|---|
natural (default) | 280 | 20 | average typist |
careful | 200 | 15 | slower, longer word and sentence pauses |
brisk | 420 | 10 | faster, shorter pauses |
Ranges: characters_per_minute 60 to 900, sigma 0.1 to 0.6, word_pause
1 to 4, sentence_pause 1 to 6, shift_pause 1 to 2, alternate_hand 0.5 to
1, roll 0.5 to 1, same_finger 1 to 2, micro_pause_probability 0 to 0.1,
micro_pause 0 to 2 s, jitter_ms 0 to 1000 ms and below the median interval
60000 / characters_per_minute ms, dwell 0.03 to 0.25 s, dwell_sigma 0 to
0.5. dwell and dwell_sigma describe key hold time, but the built-in
backends send each keystroke’s down and up events together, so they currently
have no effect on typing.
human=False
human=False skips both models: the cursor is put on the target in one step
and keys are sent without delay between them. Everything else stays the same:
clicks are still verified, typing still checks focus, and a headless browser
still refuses native input.