Metadata-Version: 2.4
Name: wpr-runtime-core
Version: 0.2.1
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 locally installed Widevine

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.

`widevine_source_profile` (or `WPR_WIDEVINE_SOURCE_PROFILE`) additionally copies
only an already-installed local Firefox Widevine CDM and its required metadata
into that WPR profile. It does not copy cookies, passwords or other Firefox
site data, and the CDM is never part of a WPR package. This option is browser
Worker-only and requires a persistent profile. The native Worker must also
support opt-in `WPR_ENABLE_CDM=1`; otherwise CDM availability is not implied by
the Python configuration.

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
has not yet been included in a published WPR runtime package. 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.
