Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 8 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@
</p>

> ⭐ **Enjoying CaptchaKraken?** [Star & watch the repo](https://github.com/JWriter20/CaptchaKraken)
> for new puzzle types, smaller models, and video support. One repo, two
> for new puzzle types and new models. One repo, two
> published ports — the TypeScript browser driver (**npm:** `captchakraken`) and
> the Python engine (**PyPI:** `captchakraken`).

Expand Down Expand Up @@ -178,7 +178,7 @@ CaptchaKraken detects the captcha, solves it, clicks, and verifies — end to en
| ✅ **NetEase Yidun** | Jigsaw, picture-click, icon-click |
| ✅ **Lemin, Prosopo, Tencent** | Cropped-image, grid, and slide flows |
| ✅ **Distorted text** | BotDetect, MTCaptcha, Yandex — read and typed, not clicked |
| 🟡 Video challenges | Driver support ships; the adapter `setup.sh` installs skips them ([roadmap](./docs/roadmap.md)) |
| ✅ **Animated / video challenges** | Recorded, cut into keyframes, solved as one multi-image prompt, then clicked once the widget returns to the chosen frame |

The non-Google/hCaptcha vendors are driven end-to-end in CI against generated
fixtures in **both** ports. Per-vendor accuracy varies more than the headline
Expand Down Expand Up @@ -341,26 +341,23 @@ cell indices:

### End-to-end, in a real browser

Both runs below drove **live reCAPTCHA challenges** at
The run below drove **live reCAPTCHA challenges** at
`google.com/recaptcha/api2/demo` on 2026-07-27, headless, against the hosted
API. A "solve" means reCAPTCHA accepted and the widget cleared — not that the
model's first answer was right.

| Browser | Solved | Rounds billed | Median wall clock |
|---|---:|---:|---:|
| [Camoufox](https://camoufox.com) 0.4.11 | **3 / 3** | 21 | 96 s |
| Holo 152.0.3 | **1 / 3** | 21 | 85 s |

A solve took 5–8 model rounds, because reCAPTCHA replaces tiles after each
click and every replacement is a fresh puzzle. That is the whole reason the
hosted API meters per round rather than per solve.

**Solve rate in a browser is not model accuracy, and the gap is mostly your
IP.** reCAPTCHA rejects correct answers from addresses it distrusts, and both
runs above came from the same datacenter address in the same hour — which is
the least favourable condition there is, and the likeliest explanation for the
difference between the two rows. Neither figure is a benchmark; they are proof
the path works. See
**Solve rate in a browser is not model accuracy, and much of it is your IP.**
reCAPTCHA rejects correct answers from addresses it distrusts, and the run above
came from a datacenter address — which is the least favourable condition there
is. The figure is not a benchmark; it is proof the path works. See
[Rate limiting & IP reputation](./docs/performance.md#rate-limiting--ip-reputation).

Reproduce it yourself — the demos in this repo drive a real browser end to end:
Expand Down Expand Up @@ -392,7 +389,7 @@ Most of the detail lives in the docs hub — start at **[docs/](./docs/README.md
| 🚀 [Usage](./docs/usage.md) | Install, the 4 browser frameworks, the Python CLI, migrating from v1 |
| ⚙️ [How it works](./docs/how-it-works.md) | The solve pipeline, `find_grid`, the freshness guard, dedup |
| 📊 [Performance](./docs/performance.md) | Accuracy, speed-by-device tables, IP-reputation & rate limits |
| 🗺️ [Roadmap](./docs/roadmap.md) | Video support, more captcha types, and what shipped |
| 🗺️ [Roadmap](./docs/roadmap.md) | What shipped, what's in progress, and what's planned |
| 📜 [Licensing](./docs/licensing.md) | Plain-English: what you can and can't build |

---
Expand Down
6 changes: 3 additions & 3 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ guides. Start here.
> One repo, two published ports — the TypeScript browser driver
> (npm: `captchakraken`) and the Python engine (PyPI: `captchakraken`). ⭐ **Star
> & watch** [the repo](https://github.com/JWriter20/CaptchaKraken) for smaller
> models, video support, and new puzzle types.
> models and new puzzle types.

## 📚 Guides

Expand All @@ -17,7 +17,7 @@ guides. Start here.
| [🧑‍💻 Usage](./usage.md) | Install both ports, the Python one-liner, all four browser frameworks (Playwright / Patchright / camoufox-js / Puppeteer), and migrating from v1. |
| [⚙️ How it works](./how-it-works.md) | The detect → grid → click → verify pipeline, the OpenCV grid tracer, the stale-frame freshness guard, and solution dedup. |
| [📊 Performance](./performance.md) | Model accuracy, the memory-bandwidth speed model + per-device throughput, and IP-reputation guidance. |
| [🗺️ Roadmap](./roadmap.md) | What shipped recently, what's in progress, and what's planned (video support, more captcha types). |
| [🗺️ Roadmap](./roadmap.md) | What shipped recently, what's in progress, and what's planned (more captcha types). |
| [⚖️ Licensing](./licensing.md) | Plain-English explainer of the source-available license — what you may and may not build. |

## ✅ What it solves today
Expand All @@ -32,7 +32,7 @@ CaptchaKraken detects the captcha, solves it, clicks, and verifies.
| ✅ **hCaptcha 3×3 image grid** | Works end-to-end |
| ✅ **hCaptcha click / drag puzzles** | Full-puzzle model → pixel click/drag actions |
| ✅ Cloudflare Turnstile | Works via the checkbox flow |
| 🟡 **Animated / video challenges** | Driver support ships: recorded, cut into keyframes, solved as a multi-image prompt, then clicked once the widget returns to the chosen frame. Accuracy depends on the adapter; the one `setup.sh` installs skips them ([roadmap](./roadmap.md)) |
| **Animated / video challenges** | Recorded (4 s @ 10 fps), cut into keyframes, solved as one multi-image prompt, then clicked once the widget returns to the chosen frame. The model half shipped with **v1.2**, which `setup.sh` installs and the hosted API serves |

Non-grid still-image puzzles — **click** ("click each …"), **drag** ("drag the
piece into place"), path/connect, "choose the card" — route to the full-puzzle
Expand Down
12 changes: 6 additions & 6 deletions docs/performance.md
Original file line number Diff line number Diff line change
Expand Up @@ -87,12 +87,12 @@ any harness that trusts the file naively:
2. **`rows`/`cols` disagree with `puzzle_type` on those same records.** Trust
`puzzle_type`; it is the only field that agrees with the answer.

**Browser solve rates are a different measurement.** In live runs against
`google.com/recaptcha/api2/demo` on 2026-07-27, Camoufox cleared 3/3 challenges
and Holo 1/3, each taking 5–8 model rounds — reCAPTCHA replaces tiles after
every click, and each replacement is a fresh puzzle. Both runs came from one
datacenter IP within one hour, which is the least favourable condition
available; see [below](#rate-limiting--ip-reputation).
**Browser solve rates are a different measurement.** In a live run against
`google.com/recaptcha/api2/demo` on 2026-07-27, Camoufox cleared 3/3 challenges,
taking 5–8 model rounds — reCAPTCHA replaces tiles after every click, and each
replacement is a fresh puzzle. The run came from a datacenter IP, which is the
least favourable condition available; see
[below](#rate-limiting--ip-reputation).

## A note on speed

Expand Down
2 changes: 1 addition & 1 deletion docs/roadmap.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ Where CaptchaKraken is headed. Legend: 🟢 shipped · 🟡 in progress · ⚪ p
| ⬛ **Abyss** | 🟡 in progress | The next hosted-only model, trained against the open weights' measured failures. **Not serving yet** — the endpoint answers with Twilight v1.2 until it lands. |
| 🪶 **Sunlight / Twilight merges** | 🟢 shipped | The adapter merged into the base at 4-bit (~9 GB) and 8-bit (~14 GB), so self-hosting is one download instead of two. Published for both v1.1 and v1.2, all public on [HuggingFace](https://huggingface.co/CaptchaKraken). |
| 📈 **More real labeled data** | 🟡 in progress | Broader coverage for under-represented prompts. |
| 🎥 **Video challenge support** | 🟢 shipped | **The driver half has shipped.** A challenge that never settles is now recorded (4 s @ 10 fps), cut into keyframes, and sent to the model as one multi-image prompt; the answer names which keyframe it acted on, and the driver waits for the widget to return to that frame before clicking. The model half shipped with **v1.2**, which is trained on the keyframe format. |
| 🎥 **Video challenge support** | 🟢 shipped | **Both halves are out.** A challenge that never settles is recorded (4 s @ 10 fps), cut into keyframes, and sent to the model as one multi-image prompt; the answer names which keyframe it acted on, and the driver waits for the widget to return to that frame before clicking. The model half shipped with **v1.2**trained on the keyframe format, installed by `setup.sh`, and what the hosted API answers with. |

## ⚪ Planned

Expand Down
Loading