Studio Aja · Gap Filling

Purpose#

Admin lane console for reconstructing missing-data gaps in a tracked joint. It wires the real @aja/motion-processing detectGaps + fillShortGaps pipeline via /v1/admin/aja/gap-filling: detect missing frames in a joint X-track (entered as empty / "null" / "-" segments) and reconstruct them by linear interpolation between the valid boundary keyframes, returning gaps detected, frames recovered, and the filled track.

Entry points#

• Direct URL / bookmark — /studio/aja/gap-filling; metadata sets alternates.canonical
• Linked from /studio Domain-bridge studios section (Aja sub-area)
• Quick action — "Open Aja Retiming workspace" (/studio/aja/retiming)

Layout regions#

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

• Workspace StudioAjaGapFillingWorkspace — <h1> "Aja Gap Filling Workspace" + summary (data-aja-gap-filling-summary), the model line (data-aja-gf-model, gap type + fill method), then the fill form
• Route Map panel (data-aja-gap-filling-route-map, <h2>) — 5 entries from STUDIO_AJA_GAP_FILLING_ROUTE_MAP
• Quick-action lane — quickAction links: retiming, /studio

States#

• Loading — data-aja-gf-loading "Loading gap-filling model…" while GET /v1/admin/aja/gap-filling is in flight
• Unauthorized (gated) — data-aja-gf-unauthorized on 401/403; admin scope message ("Aja workspace scope required to view gap filling.")
• Error — data-aja-gf-error on non-OK / malformed / network failure
• Ready (form) — data-aja-gf-fill-form once the catalog loads
• Result — data-aja-gf-result (-gaps-detected, -frames-recovered, -filled-track, per-gap rows) after a successful POST; validation error in data-aja-gf-fill-error
• Offline — SSR shell; lane error state when fetch unavailable
• Standalone PWA — desktop layout; quickAction anchors wrap
• Empty — N/A; catalog is constant

Interactions#

Fill form#

• Joint name (<input data-aja-gf-field-joint>) — required
• Joint X-track (<input data-aja-gf-field-track>) — comma-separated; "null" marks a dropped frame (≥2 entries)
• Frame rate (Hz) (<input data-aja-gf-field-rate>) — positive number
• "Detect & fill gaps" (<button data-aja-gf-fill-submit>) — POSTs { jointName, track, frameRate } to /v1/admin/aja/gap-filling/fill

Route Map panel#

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

Quick-action lane#

• "Open Aja Retiming workspace" → /studio/aja/retiming
• "Back to Studio workspace index" → /studio

E2E coverage#

• apps/oshun/web/e2e/studio-aja-cleanup-lane-consoles.spec.ts covers signed-in shell render, ready missing-data catalog (missing_data, linear), empty-joint client guard with no POST, real BFF fill output (gaps detected: 1, frames recovered: 2, filled track 0, 1, 2, 3, 4, 5), route-map count, exact quick-action hrefs, 44 px submit target, 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/gap-filling (catalog: gapType, interpolationMethods, consoleMethod) on mount, cache: 'no-store', buildBffAuthHeaders()
• Writes: POST /v1/admin/aja/gap-filling/fill
• 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-retiming.md
• Component sources:
  • apps/oshun/web/src/components/studio/StudioAjaGapFillingWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioAjaGapFillingRouteMap.ts

Known downstream boundaries#

• The lane fills a single joint X-track; multi-axis / multi-joint clip fill is not yet an input.
• Route-map sub-routes are descriptive contracts; implementation status of those child pages is tracked separately from this leaf console.