mirror of
https://github.com/PR0M3TH3AN/bitvid.git
synced 2026-10-27 07:52:24 +00:00
96 lines
4.2 KiB
Markdown
96 lines
4.2 KiB
Markdown
# Watch history system overview
|
||
|
||
This doc ties the playback telemetry in `js/services/watchHistoryTelemetry.js` to
|
||
our watch history logging pipeline documented in
|
||
[`docs/watch-history-logging.md`](watch-history-logging.md).
|
||
|
||
## System map
|
||
|
||
* **Playback telemetry** (`WatchHistoryTelemetry`) listens to the active `<video>`
|
||
element and decides when a watch should be logged.
|
||
* **Watch history service** (`WatchHistoryService`) batches views into a local
|
||
queue, publishes snapshots to relays, and emits in-app events when the queue or
|
||
snapshots change.
|
||
* **Watch history logging pipeline** (v2) describes how snapshots are encrypted
|
||
and published to relays. See `docs/watch-history-logging.md` for the wire
|
||
format and publish cadence.
|
||
|
||
## What gets captured
|
||
|
||
### Playback telemetry fields
|
||
|
||
`WatchHistoryTelemetry` watches playback and only logs a view once the viewer
|
||
passes the threshold duration (default 12 seconds). It also tracks a per-viewer
|
||
cooldown key so the same actor doesn’t log the same pointer repeatedly in a
|
||
single session. The telemetry payload stores a sanitized slice of video metadata
|
||
(id, title, thumbnail, pubkey, created_at) and intentionally omits playback
|
||
endpoints (URL/magnet/hash) so these never get persisted as watch history
|
||
metadata.
|
||
|
||
### Watch history snapshots
|
||
|
||
Once a view is accepted, the telemetry layer forwards the pointer to the watch
|
||
history service. The service packages pointer-only entries into watch-history
|
||
snapshots (chunked NIP-04 encrypted events) and emits a pointer index event. The
|
||
payload shape and relay publication sequence are documented in
|
||
`docs/watch-history-logging.md`.
|
||
|
||
## Where data is stored
|
||
|
||
* **Local queue:** `WatchHistoryService` uses `localStorage` to persist the
|
||
in-flight view queue (`bitvid:watch-history:queue:v1`) so the history survives
|
||
refreshes even before a snapshot succeeds.
|
||
* **Local cache:** A rolling watch-history cache (TTL controlled via
|
||
`WATCH_HISTORY_CACHE_TTL_MS`) keeps recently synced history available without
|
||
hitting relays on every page load.
|
||
* **Relay snapshots:** Chunked, encrypted watch-history events are sent to relays
|
||
using the kind and list identifier configured in `config/instance-config.js`.
|
||
|
||
> **Roadmap note:** Current watch history is **not** stored as an encrypted
|
||
> local list. We plan to add encrypted local history in the future.
|
||
|
||
## Privacy considerations
|
||
|
||
* Watch history metadata is intentionally sanitized to exclude playback URLs,
|
||
magnets, and hashes; only presentation-safe fields are kept for history
|
||
rendering.
|
||
* Relay payloads store pointer tags rather than full metadata, ensuring that
|
||
relays don’t learn titles or thumbnails unless an operator opts into local
|
||
metadata caching (see `docs/watch-history-logging.md`).
|
||
* Session actors are treated as local-only history when they cannot publish to
|
||
relays; the history service retains those pointers locally without attempting
|
||
network sync.
|
||
|
||
## Event emission and consumption
|
||
|
||
### Telemetry → watch history service
|
||
|
||
`WatchHistoryTelemetry.preparePlaybackLogging` attaches listeners to the video
|
||
player. When the threshold is hit, it calls `watchHistoryService.publishView`
|
||
(when available) or falls back to `nostrClient.recordVideoView`. Successful
|
||
publish results are also forwarded to `ingestLocalViewEvent` so the view counter
|
||
can update immediately.
|
||
|
||
### Watch history service events
|
||
|
||
`WatchHistoryService` emits events to subscribers and to the browser via the
|
||
`bitvid:watchHistory` custom event. Any UI component can subscribe to these
|
||
updates and refresh the watch-history view or related counters.
|
||
|
||
## Configuration and sampling
|
||
|
||
* **Telemetry sampling threshold:** `WatchHistoryTelemetry` defaults to 12
|
||
seconds before a view is logged. Integrations can override
|
||
`viewThresholdSeconds` when constructing the class.
|
||
* **Feature flag:** Watch-history v2 is guarded by `FEATURE_WATCH_HISTORY_V2` in
|
||
`js/constants.js`.
|
||
* **Instance configuration:** `config/instance-config.js` exposes watch-history
|
||
limits (max items, payload size), batching controls
|
||
(`WATCH_HISTORY_BATCH_RESOLVE`, `WATCH_HISTORY_BATCH_PAGE_SIZE`), and cache TTL
|
||
(`WATCH_HISTORY_CACHE_TTL_MS`) for operator tuning.
|
||
|
||
## Related docs
|
||
|
||
* [`docs/watch-history-logging.md`](watch-history-logging.md)
|
||
* [`docs/instance-config.md`](instance-config.md)
|