Studio Aja · Basic Quality Metrics

Purpose#

Admin lane console for capture-take quality scoring. It wires the real @aja/motion-quality analyzeBasicQuality composite via /v1/admin/aja/basic-quality-metrics: the operator supplies a single-joint X-position track (one value per frame) plus a frame rate, and the engine scores the take across six deterministic analyzers (jitter, foot sliding, bone-length stability, joint-angle limits, smoothness, physical plausibility) into one weighted rating, with the exact peak acceleration / jerk detail surfaced.

Entry points#

• Direct URL / bookmark — /studio/aja/basic-quality-metrics; metadata sets alternates.canonical
• Linked from /studio Domain-bridge studios section (Aja sub-area)
• Quick action — "Open Aja Segmentation workspace" (/studio/aja/segmentation)

Layout regions#

page.tsx renders inside <ShellLayout active="studio">:

• Workspace StudioAjaBasicQualityMetricsWorkspace — <h1> "Aja Basic Quality Metrics Workspace" + summary (data-aja-basic-quality-metrics-summary), the dimensions list (data-aja-bqm-dimensions, weight per dimension), then the assess form
• Route Map panel (data-aja-basic-quality-metrics-route-map, <h2>) — 5 entries from STUDIO_AJA_BASIC_QUALITY_METRICS_ROUTE_MAP
• Quick-action lane — quickAction links: segmentation, /studio

States#

• Loading — data-aja-bqm-loading "Loading quality dimensions…" while GET /v1/admin/aja/basic-quality-metrics is in flight
• Unauthorized (gated) — data-aja-bqm-unauthorized on 401/403; admin scope message ("Aja workspace scope required to view quality metrics.")
• Error — data-aja-bqm-error on non-OK / malformed / network failure
• Ready (form) — data-aja-bqm-assess-form once the dimension catalog loads
• Result — data-aja-bqm-result (-overall, -rating, -peak-accel, -peak-jerk, per-dimension scores) after a successful POST; validation error in data-aja-bqm-assess-error
• Offline — SSR shell; lane error state when fetch unavailable
• Standalone PWA — desktop layout; quickAction anchors wrap
• Empty — N/A; dimensions catalog is constant

Interactions#

Assess form#

• Joint X-position track (<input data-aja-bqm-field-track>) — comma-separated, one value per frame (≥3)
• Frame rate (Hz) (<input data-aja-bqm-field-rate>) — positive number
• "Assess" (<button data-aja-bqm-assess-submit>) — POSTs { frames, frameRate } to /v1/admin/aja/basic-quality-metrics/assess

Route Map panel#

• 5 entries (<article> per path + purpose) — non-interactive

Quick-action lane#

• "Open Aja Segmentation workspace" → /studio/aja/segmentation
• "Back to Studio workspace index" → /studio

E2E coverage#

• apps/oshun/web/e2e/studio-aja-quality-metrics-lane-consoles.spec.ts covers signed-in shell render, route-map shape, exact quick-action hrefs, the ready six-dimension catalog, 44 px submit target, short-track client guard with no POST, real BFF zigzag assessment output (including exact 1800 m/s² peak acceleration), loading / unauthorized / malformed-catalog fail-closed states, mobile no-overflow, and direct BFF auth/schema/happy-path gates.

Data & contracts#

• Reads: GET /v1/admin/aja/basic-quality-metrics (dimension catalog) on mount, cache: 'no-store', buildBffAuthHeaders()
• Writes: POST /v1/admin/aja/basic-quality-metrics/assess
• Realtime: none
• Caching: client fetch on mount (no-store); SSR shell
• Auth/role check: BFF endpoints admin-scoped, fail-closed (401/403 → unauthorized render); route gated signed-in + studio via the proxy

Cross-references#

• Parent: ../../studio-overview.md
• Sibling routes: ./studio-aja-segmentation.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioAjaBasicQualityMetricsWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioAjaBasicQualityMetricsRouteMap.ts

Known downstream boundaries#

• The lane assesses a single synthetic joint track (TestJoint); the six analyzers run, but multi-joint capture clips are not yet an input.
• Route-map sub-routes are descriptive contracts; implementation status of those child pages is tracked separately from this leaf console.