---
path: /studio/aja/reference-video-library
surface: studio
domain: aja
auth: signed-in + studio entitlement
source: apps/oshun/web/src/app/studio/aja/reference-video-library/page.tsx
status: walked
last_walked:
  '2026-05-29 automated runtime walk (Playwright headless) — render, /v1 data
  (2xx), console/page-errors, expected content, screenshot verified; live
  screen-reader, touch, offline, and telemetry-delivery checks pending a manual
  AT pass. Evidence: WALKTHROUGH/results/runtime-sweep-2026-05-29.md; body
  re-derived 2026-06-03 from current source (lane-console architecture)'
---

# Studio Aja · Reference Video Library

## Purpose

Admin lane console for querying the reference-video library. Its catalog lane
wires the library query + duplicate-detection engine via
`/v1/admin/aja/reference-video-library`: filter a library item set by format /
tag / title search, stable-sort by a key + direction, and flag content
duplicates by checksum — returning matched/total counts, the sorted items, and
the duplicate groups.

## Entry points

- **Direct URL / bookmark** — `/studio/aja/reference-video-library`; metadata
  sets `alternates.canonical`
- **Linked from `/studio`** Domain-bridge studios section (Aja sub-area)
- **Quick action** — "Open Aja Gaming Pipeline workspace"
  (`/studio/aja/gaming-pipeline`)

## Layout regions

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

- **Workspace** `StudioAjaReferenceVideoLibraryWorkspace` — `<h1>` "Aja
  Reference Video Library Workspace" + summary
  (`data-aja-reference-video-library-summary`), then the **Library Catalog Lane**
  (`<h2 data-aja-rvl-lane-heading>`)
- **Route Map panel** (`data-aja-reference-video-library-route-map`, `<h2>`) — 5
  entries from `STUDIO_AJA_REFERENCE_VIDEO_LIBRARY_ROUTE_MAP`
- **Quick-action lane** — `quickAction` links: gaming-pipeline, `/studio`

## States

- [ ] **Loading** — `data-aja-rvl-loading` "Loading reference-video library…"
      while `GET /v1/admin/aja/reference-video-library` is in flight
- [ ] **Unauthorized (gated)** — `data-aja-rvl-unauthorized` on 401/403; admin
      scope message ("Aja workspace scope required to query the library.")
- [ ] **Error** — `data-aja-rvl-error` on non-OK / malformed / network failure
- [ ] **Ready (form)** — `data-aja-rvl-form` once the catalog loads (engine
      summary `data-aja-rvl-engine-summary`)
- [ ] **Result** — `data-aja-rvl-result` (`-headline` matched/total + duplicate
      groups, `-items-list`, `-duplicates-list`) after a successful POST; query
      error in `data-aja-rvl-query-error`
- [ ] **Offline** — SSR shell; lane error state when `fetch` unavailable
- [ ] **Standalone PWA** — desktop layout; `quickAction` anchors wrap
- [x] **Empty** — N/A; catalog (formats / sort keys / directions) is constant

## Interactions

### Library Catalog Lane

- [ ] **Library items JSON** (`<textarea data-aja-rvl-items>`, label "library
      items json")
- [ ] **Format** (`<select data-aja-rvl-format>`) — `— any —` + catalog formats
- [ ] **Tag** (`<input data-aja-rvl-tag>`, label "tag")
- [ ] **Search** (`<input data-aja-rvl-search>`, label "search")
- [ ] **Sort by** (`<select data-aja-rvl-sortby>`) — catalog sort keys
- [ ] **Dir** (`<select data-aja-rvl-sortdir>`) — catalog sort directions
- [ ] **"Query library"** (`<button data-aja-rvl-submit>`) — POSTs
      `{ items, query }` to `/v1/admin/aja/reference-video-library/query`

### Route Map panel

- [ ] **5 entries** (`<article>` per `path` + `purpose`) — non-interactive

### Quick-action lane

- [ ] **"Open Aja Gaming Pipeline workspace"** → `/studio/aja/gaming-pipeline`
- [ ] **"Back to Studio workspace index"** → `/studio`

## Data & contracts

- **Reads**: `GET /v1/admin/aja/reference-video-library` (catalog: `summary`,
  `formats`, `sortKeys`, `sortDirections`) on mount, `cache: 'no-store'`,
  `buildBffAuthHeaders()`
- **Writes**: `POST /v1/admin/aja/reference-video-library/query`
- **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`](../../studio-overview.md)
- Sibling routes:
  [`./studio-aja-gaming-pipeline.md`](./studio-aja-gaming-pipeline.md)
- Component sources:
  - `apps/oshun/web/src/components/studio/StudioAjaReferenceVideoLibraryWorkspace.tsx`
  - `apps/oshun/web/src/components/studio/StudioAjaReferenceVideoLibraryRouteMap.ts`

## Open questions / known gaps

- [ ] The lane queries a library item set supplied as JSON in the form; it does
      not browse a persisted library catalog from the backend