Studio Aja · Gaming Pipeline

Purpose#

Admin lane console for the real @aja/motion-quality analyzePerceptualQuality ship-readiness gate. The operator supplies joint ids and a frames array (≥4 frames of per-joint positions) for a game-animation clip; the lane runs the combined perceptual-quality suite — naturalness, style consistency, temporal coherence, and visual quality folded into a weighted overall score and a quality rating.

Entry points#

• Direct URL / bookmark — /studio/aja/gaming-pipeline; metadata canonical to this path
• Studio nav — Domain-bridge studios section of /studio
• Sibling quick-actions on this page: Film/VFX Pipeline, Back to Studio (no breadcrumb panel on this route)
• Operator surfacing — see ../../studio-overview.md

Layout regions#

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

• Workspace (<StudioAjaGamingPipelineWorkspace />, archetype: LEAF with a capability summary):
  • <h1> (WorkspaceHeading) "Aja Gaming Pipeline Workspace"
  • Summary <p data-aja-gaming-pipeline-summary> — operations lane runs the real combined perceptual-quality suite
  • Capability Summary panel (data-aja-gaming-pipeline-capability-summary, <h2>Capability Summary</h2>) — a single descriptive <div> (typed operations, diagnostics, security, parity), not a card grid
  • Operations lane (data-aja-gaming-pipeline-operations-lane, <h2>Perceptual Quality Operations Lane</h2>) — the live analyze form
• Route Map panel (data-aja-gaming-pipeline-route-map): <h2>Route Map</h2> listing 5 entries from STUDIO_AJA_GAMING_PIPELINE_ROUTE_MAP exposed with data-aja-gaming-pipeline-route-map-entry / data-route-path (primary, scenes, exports, revisions, governance)
• Quick-action panel (data-aja-gaming-pipeline-quick-actions): two Link.quickAction anchors — Film/VFX Pipeline, Back to Studio workspace index

States#

• Loading — operations lane GETs the suite catalog on mount; renders <p data-aja-gp-loading> "Loading perceptual-quality suite..."
• Unauthorized — 401/403 renders data-aja-gp-unauthorized ("Access restricted." + admin-scope message, default "Aja workspace scope required to run the perceptual-quality suite.")
• Error — non-OK / malformed / unreachable renders data-aja-gp-error ("Could not load the perceptual-quality suite." + reason)
• Ready (form) — success renders data-aja-gp-catalog with suite, sub-score count, rating count, data-aja-gp-sub-score spans, data-aja-gp-rating spans, data-aja-gp-suite-summary, and the idle data-aja-gp-form
• Result — a successful POST renders data-aja-gp-result with stable score / rating / naturalness / style-consistency / temporal-coherence / visual-quality attributes, data-aja-gp-headline, and data-aja-gp-subscores
• Validation / analyze error — client guards (≥1 joint id; frames valid JSON array ≥4) and POST failures render data-aja-gp-analyze-error
• Pending — controls and submit disable while data-aja-gp-form-state="analyzing" / data-aja-gp-submit-state="analyzing"
• Mobile/touch containment — form controls and route actions remain at least 44 px tall with no horizontal overflow
• Empty / Standalone PWA / offline — N/A beyond the above; shell SSR, lane is a client fetch on mount

Interactions#

Operations lane (data-aja-gp-form)#

• Joint ids (data-aja-gp-joints, input, aria-label "joint ids", comma-separated)
• Frames (data-aja-gp-frames, textarea, aria-label "frames json", JSON array of { positions: { jointId: { x, y, z } } }, ≥4)
• "Run perceptual-quality suite" (data-aja-gp-submit, submit) — fires POST /v1/admin/aja/gaming-pipeline/analyze with { joints, frames }; locked with data-aja-gp-submit-state="analyzing" while the real request is pending

Route Map panel#

• Route entries (5 × <article>) — non-interactive path+purpose with exact path ordering

Quick-action panel#

• "Open Aja Film/VFX Pipeline workspace" → /studio/aja/film-vfx-pipeline
• "Back to Studio workspace index" → /studio

Data & contracts#

• Reads: GET /v1/admin/aja/gaming-pipeline on mount — catalog { suite, summary, subScores: string[], ratings: string[] }; client fails closed unless the expected perceptual-quality suite, all four sub-score keys, and all five quality ratings are present
• Writes: POST /v1/admin/aja/gaming-pipeline/analyze — { joints, frames } → { result } (overallScore, rating, naturalnessScore, styleConsistencyScore, temporalCoherenceScore, visualQualityScore); client fails closed unless every score is finite and the rating is one of the expected suite ratings
• Realtime: none
• Caching: client fetch on mount with cache: 'no-store' and buildBffAuthHeaders(); SSR shell only
• Auth/role check: BFF endpoints admin-scoped + fail-closed (401/403 → unauthorized render); route behind the signed-in + studio proxy gate

Cross-references#

• Parent: ../../studio-overview.md
• Shell: ../../../shell/04-auth-session.md
• Sibling routes: ./studio-aja-film-vfx-pipeline.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioAjaGamingPipelineWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioAjaGamingPipelineRouteMap.ts

Verification evidence#

• apps/oshun/web/e2e/studio-aja-gaming-pipeline.spec.ts runs against the real Next Studio shell and local BFF, forwarding browser bearer auth rather than mocking the perceptual-quality contract.
• The spec covers anonymous redirect, Aja-admin catalog load, exact shipped balanced output, edited degraded output, local validation with no POST, BFF validation details, malformed result, transport failure, loading / 503 / malformed / non-admin states, pending form locking, mobile no-overflow + 44px controls, scoped axe, and direct BFF 401/403/400/200 gates.

Open questions / known gaps#

• Route-map sub-routes are advertised but have no page.tsx in V1