Gecko Web Runtime Client

Python page and browser client for a versioned Firefox-derived WPR runtime. It exposes pages, contexts, navigation, DOM access, screenshots, diagnostics, Turnstile and WeChat workflow adapters.

The native runtime is installed separately:

python -m gecko_web_runtime install-runtime --version 155

The runtime is held in a private GitHub Release. Automatic download needs access to childclm/gecko-web-runtime. The Python client depends on wpr-runtime-core for Worker lifecycle and protocol compatibility. Historical HTTP imports are retained through wpr-http.

Optional HTTP WeChat integration

The same distribution includes gecko_web_runtime.integrations.wechat. It uses wpr-http and a local Node.js environment, with no browser Page. Install version 1.4.3 or newer with its optional dependencies, then prepare Node.js 20+ dependencies in the user's cache:

pip install --upgrade "gecko-web-runtime-client[wechat]>=1.4.3"
python -m gecko_web_runtime.integrations.wechat install-js

These commands require a client build containing this integration. An older published package does not acquire the integration by installing the extra. Local development: pip install -e "./python[wechat]".

from gecko_web_runtime.integrations.wechat import AsyncWechatClient

async with AsyncWechatClient(proxy="") as client:
    result = await client.get(article_url)
    print(result.summary())
    if result.ok:
        article_html = result.html

Only Node dependencies are installed by install-js; a compatible Firefox network runtime is installed separately through wpr-http. Native graphics queries additionally require an installed Firefox ANGLE directory containing libEGL.dll and libGLESv2.dll, passed as native_gl_dir or NATIVE_GL_DIR. Direct article responses need neither Node nor native graphics.

One client retains one HTTP session and serializes its article flows. Separate client instances have separate HTTP and JavaScript state. total_timeout bounds an active flow; cancellation terminates an active Node subprocess. The module uses Python logging and does not configure application handlers. Artifacts are off by default; output_dir opts into per-call directories that can contain session-sensitive diagnostic data. Keep those directories outside source control. Site rejection is returned as a structured failure, not a promise that any verification will succeed.

Media capture

For a browser-played Widevine page, use AsyncMediaDownloader. It starts the Worker, provisions the caller's Widevine profile, enables bounded native H.264 capture, waits for playback progress, writes a checkpoint, and verifies the final MP4 with FFmpeg.

import asyncio
from pathlib import Path

from gecko_web_runtime import AsyncMediaDownloader


async def main() -> None:
    result = await AsyncMediaDownloader(
        "https://example.test/video",
        output_dir=Path("./media-output"),
        ffmpeg=Path(r"C:\\ffmpeg\\bin\\ffmpeg.exe"),
        expected_duration=2575.32,
        max_retries=1,
    ).download()
    if not result["completed"]:
        raise RuntimeError(result["attempts"])
    print(result["package"]["output"])


asyncio.run(main())

Set WPR_RUNTIME_DIR, WPR_WORKER_EXE, WPR_PERSISTENT_PROFILE_DIR, and WPR_ENABLE_CDM=1 before creating the downloader. Widevine is installed by Firefox's official GMP installer into the persistent WPR profile; no existing Firefox profile or component is imported. This requires the Worker build with runtime.widevine_start/status support (Runtime 155.0.8 or later). For a bounded smoke test of a longer page, use sample_seconds=120 instead of expected_duration. The downloader keeps a checkpoint.json; rerunning with the same output directory returns a completed result without starting another Worker.