mirror of https://github.com/heygen-com/hyperframes.git synced 2026-09-11 06:30:03 +00:00

Files

T

Miguel ÁngelandClaude Opus 4.8 16eb11367a feat(media-use): usage visibility — shared telemetry identity, miss log, resolve --stats (#2113 )

* feat(media-use): usage visibility — shared telemetry identity, miss log, resolve --stats

- U6: join the CLI/studio telemetry identity — read the shared install id from
  ~/.hyperframes/config.json (seed if absent) instead of a media-use-only
  ~/.media/anon-id, and $identify to the HeyGen account (email/username) once
  per run on sign-in. One PostHog person across surfaces; pseudonymous before
  sign-in, account-linked after. Event properties stay coarse (no intent/paths).
- U1: one-time first-run disclosure to stderr + Privacy section in SKILL.md;
  honors DO_NOT_TRACK / HYPERFRAMES_NO_TELEMETRY.
- U2: persist resolve misses to ~/.media/misses.jsonl (local → intent kept;
  the media_use_resolve_miss telemetry event stays intent-free).
- U3: `resolve --stats` (+ --days) — local usage report over .media/ + ~/.media
  (volume by type, source/provider/via split, hit-rate, top missed intents,
  global-cache size/reuse); human + --json.
- U4: reproducible PostHog dashboard definition (references/telemetry-dashboard.md).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv

* fix(media-use): address #2113 review — shared notice state, legacy id migration, stats robustness

- Notice-shown state now lives in the shared ~/.hyperframes/config.json
  (config.telemetryNoticeShown, the CLI's own field) instead of a media-use-only
  ~/.media marker — so shared-identity users see the first-run notice once per
  person, not once per tool.
- Migrate a pre-existing ~/.media/anon-id into the shared config on upgrade, so
  media-use-only users keep their PostHog persona instead of resetting.
- buildStats: --days only windows on a positive finite value (negative/NaN → all
  time, not an empty report); dropped the top-level catch that masked a real
  error as an all-zero "no usage" report (sub-reads are individually guarded).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01H5k87mPZ4d6yiFwcWSb8Vv

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-07-09 18:33:55 -04:00

4.2 KiB

Raw Blame History

media-use usage dashboard (PostHog)

Reproducible definition of the media-use usage dashboard. The dashboard answers "how much is media-use used, for what, is reuse working, and what can't it satisfy" from the telemetry scripts/lib/telemetry.mjs already emits. Build it in PostHog project Hyperframes (356858); this doc is the source of truth so it can be recreated. Local complement: resolve --stats (same questions, from .media/ + ~/.media, no PostHog access needed).

Identity (see `scripts/lib/telemetry.mjs`)

Events attribute to the same PostHog person as the hyperframes CLI and studio — the shared install id in ~/.hyperframes/config.json (anonymousId), stitched to the HeyGen account ($identify, distinct_id = email/username) on sign-in. Not fully anonymous by design; pseudonymous before sign-in, account-linked after. $ip:null. Opt-out: HYPERFRAMES_NO_TELEMETRY=1 / DO_NOT_TRACK=1 (also CI, dev).

Event catalog (verified present in-project)

Every event carries surface: "media-use". Event properties are coarse — never intent text, file names, or paths.

Event	Fires on	Key properties
`media_use_resolve`	a resolve that produced/returned an asset	`type`, `source`, `provider`, `via`, `local_only`, `provider_override`
`media_use_resolve_miss`	a resolve that found nothing	`type`, `local_only`, `provider_override` (no intent)
`media_use_candidates`	`--candidates` / `--dry-run` listing	`type`, counts
`media_use_doctor_run`	`--doctor`	`ok`, `checks_failed`, `failed[]`
`media_use_compare`	`grade-compare` / `compare`	`command`, `cells`, `truncated`, `total`, `render_ready_timed_out`
`media_use_transcribe` · `media_use_duck` · `media_use_transcript_cut`	audio-engine ops	op-specific

Dashboard tiles

Invocation volume — query-trends, count of media_use_resolve over time (daily). "How much."
By media type — media_use_resolve broken down by type (bgm/sfx/image/icon/logo/voice/grade/lut). "For what."
Resolve hit-rate — trends formula: A / (A + B) where A = media_use_resolve, B = media_use_resolve_miss. "Is the catalog covering needs."
Provider mix — media_use_resolve broken down by provider; a second tile by via (url / params-fallback / params) to catch CDN→params LUT downgrades.
Top misses — media_use_resolve_miss broken down by type (the tuning signal — pair with local resolve --stats, which also shows the missed intents that telemetry deliberately omits).
Doctor health — media_use_doctor_run broken down by failed[] (which dependency check fails most) + checks_failed distribution.
Compare cost — media_use_compare by command, plus truncated / render_ready_timed_out rates (observe before lifting the 16-cell cap).
Adoption (optional) — if the first_run property ships (plan U5), segment media_use_resolve first-run vs repeat.

Recreate via the PostHog MCP

For each tile: read-data-schema to confirm the event/property, then a query-* tool (query-trends for 1–7), then insight-create, then dashboard-create collecting the insights. Keep names prefixed media-use: so the dashboard is greppable. Cross-surface note: because identity is shared with CLI/studio, you can also break these down by the same person across cli_command* and studio:* events.

4.2 KiB Raw Blame History Unescape Escape