Metadata-Version: 2.4
Name: wpr-runtime-core
Version: 0.2.2
Summary: Shared process, IPC and versioned runtime support for WPR clients
License: MPL-2.0-compatible client; see runtime bundle notices
Project-URL: Repository, https://github.com/childclm/gecko-web-runtime
Project-URL: Documentation, https://github.com/childclm/gecko-web-runtime/blob/main/docs/runtime-products.md
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# WPR runtime core

Shared Worker process lifecycle, named-pipe IPC, IOCP, shared-memory leases and
versioned runtime resolution. This internal dependency is used by the standalone
HTTP client and the unchanged WPR browser product. It contains no Page API,
browser workflow or DOM interaction implementation.

Current native runtime support: Windows x86-64, Firefox 155, wpr-http-v1.

## Persistent browser profile and official Widevine installation

Browser sessions use disposable profiles by default. For a persistent,
version-bound profile, pass `RuntimeConfig(persistent_profile_dir=...)` (or set
`WPR_PERSISTENT_PROFILE_DIR`). The directory is held by an exclusive lock for
one Worker at a time and is rejected if its WPR application ID, version or
build ID does not match. It is not deleted when the Worker exits. The profile
contains site data, so treat it as sensitive and give each account/Worker its
own directory. `profile_root` remains only a parent for disposable profiles.

`RuntimeConfig(enable_widevine=True, persistent_profile_dir=...)` enables
Widevine installation through the Worker's Firefox GMPInstallManager. The
browser client waits for download, verification and registration at startup.
Firefox selects the platform component from official update metadata, verifies
the downloaded archive, and stores the component and its preferences in the
WPR profile. No Firefox installation or source Profile is required. The old
`widevine_source_profile` / `WPR_WIDEVINE_SOURCE_PROFILE` import option now
raises a migration error instead of copying components. Network-only Workers
reject this browser capability. This requires the new `runtime.widevine_*`
RPCs, available in Runtime 155.0.8 and later.

This is a capability boundary, not a promise of playback. Verify separately:
`requestMediaKeySystemAccess("com.widevine.alpha", ...)`, GMP/RDD/Utility
subprocess launch, license response, media element `readyState`, video frames,
and advancing `currentTime`. The source fix in
`source/gecko-net-worker/fixes/cdm-profile-lifecycle` now links Firefox's
sandbox broker through an isolated archive; a local release build passed both
an open Widevine test and the target Shahid playback test. This source change
is included in Runtime 155.0.8. Do not ship a
diagnostic build that uses linker duplicate-symbol overrides or disables
GMP/RDD/Utility sandboxing.

## Opt-in media-output path probe

`RuntimeConfig(media_capture=True)` or `WPR_MEDIA_CAPTURE=1` enables the
Firefox 155 WPR metadata probe. The per-Worker log is read incrementally via
`WorkerSession.media_capture_snapshot()`,
`AsyncWorkerSession.media_capture_snapshot()`, or the browser client's
`AsyncGeckoRuntime.media_capture_snapshot()`. It reports successful
`decrypt_sample` and `decode_frame` output counts by track, timestamps and
sizes, without saving media data or license/key material. `buffer_bytes` for
decoded frames is allocated shared-memory capacity, not payload length.
The option is browser-Worker-only and off by default. It requires a runtime
built with `media-capture-output.patch`; existing published packages have
not been updated with this feature.

For a short, bounded file capture, set `RuntimeConfig(media_output_dir=Path(...))`
or `WPR_MEDIA_OUTPUT_DIR`. The Worker writes per-session/per-CDM `video.i420`,
`audio.aac` and JSONL timing sidecars. The default limit remains five seconds
and 256 MiB of raw video; no output path is used by default. For an explicitly
longer capture, configure `media_output_max_seconds` and
`media_output_max_bytes` (or `WPR_MEDIA_OUTPUT_MAX_SECONDS` and
`WPR_MEDIA_OUTPUT_MAX_BYTES`). The output is still raw I420, so callers must
preflight free disk space and verify the final timeline before declaring a
recording complete. The browser client's `package_media_capture` helper accepts
`max_seconds=None`, `expected_duration_seconds=...`, and `low_copy=True` to
encode the complete continuous capture directly from the source files without
duplicating the raw video. Playback and site permissions remain the caller's
responsibility.
