Metadata-Version: 2.4
Name: gecko-web-runtime-client
Version: 1.4.1
Summary: Thin Python client for the Firefox-derived WPR Gecko Worker protocol
Author: WPR project
License: MPL-2.0-compatible client; see the runtime bundle notices
Project-URL: Repository, https://github.com/childclm/gecko-web-runtime-client
Project-URL: Documentation, https://github.com/childclm/gecko-web-runtime-client/blob/main/README.md
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: wpr-runtime-core<0.3,>=0.2.0
Requires-Dist: wpr-http<0.3,>=0.2.0
Provides-Extra: diagnostics
Requires-Dist: loguru>=0.7.2; extra == "diagnostics"

# 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:

```powershell
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`.

## 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.

```python
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_WIDEVINE_SOURCE_PROFILE` before creating the downloader. 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.

