Text on screen

Passes when text recognised on the screen, in the front window or in an area contains, equals or matches what you give it.

The screen shows text

Keyboard Maestro: OCR (Contains, Matches)

Details #

Captures the screen, reads the text in it with the Mac's text recognition, and tests the result against text. Use it when an app doesn't expose its text to Accessibility, such as a video, a game or a remote desktop.

The mode decides the test: contains (default) looks for the text anywhere, ignoring case; equals compares the whole recognised text, trimmed and ignoring case; regex searches with a regular expression.

source is screen (default) for the whole display, or window for the front window. area narrows either to a rectangle in screen points from the top left, with x, y, w and h; all four are needed, or the area is ignored. Recognised lines are joined top to bottom.

The trace shows what was read (the first 200 characters), the mode and what you were looking for.

Every condition accepts "negate": true, which flips the verdict. The trace records what was compared before the flip, so a negated condition that blocks a macro still shows the real values.

Conditions in an Only if list combine with all: every one must pass, and an empty list always passes. An if step or a repeat loop takes a match of all (default) or any.

Parameters #

Parameter	Type	Required	Values	What it does
`text`	text	Yes		The text or, in `regex` mode, the pattern to look for.
`area`	record		`h` `w` `x` `y`	A rectangle `{x, y, w, h}` in screen points. Optional; all four numbers are needed.
`mode`	one of		`contains` `equals` `regex`	`contains` (default), `equals` or `regex`.
`sample`	yes / no			Used only in a dry run: the pretend answer. Default `true`.
`source`	one of		`screen` `window`	`screen` (default) or `window`, the front window.

Examples #

Is a word on screen

If the screen shows “Cancel”
Show “Found Cancel”
Else
Show “No Cancel in the window”

Open in Switchboard to try it

Gotchas #

In a dry run nothing is captured: the condition passes with sample (default true) and the trace says simulated.
Recognition is not perfect, and language correction is off, so small or stylised text may be misread. Prefer contains over equals.
An invalid regular expression fails with '...' isn't a valid regular expression. Reading the screen works on the Mac only.