← Back to Video

UX Specification

Video

UX Specification AzDO #4022

UX Specification: Video Management

0492026-05-29

Contents

UX Specification: Video Management

Feature: 049 — Video Management

Created: 2026-05-29

Status: Draft

Depends on: spec.md (feature specification)

1. Overview

Video Management introduces videos as first-class content Objects in the CCMS. This UX spec covers how users create, manage, preview, link, and deliver video Objects — including subtitle and language variant workflows — within the existing Authoring and Admin portals.

Key UX principle: Videos must feel like any other Object in the system. The interface reuses existing patterns (Object List, Properties panel, Preview panel, Create Object Dialog) and extends them only where video-specific controls are necessary (inline player, subtitle management, format validation feedback).

2. Authoring Portal — Video Management

2.1 Creating a Video Object

Entry point: Author View → "+ Create" button (or Folder Explorer context menu)

The existing CreateObjectDialog is extended to support the "Video" object type. No new dialog is introduced.


┌────────────────────────────────────────────────────────────────┐

│ Create Object [✕] │

├────────────────────────────────────────────────────────────────┤

│ │

│ Name: [________________________________] │

│ │

│ Type: [Video ▾] │

│ ← Populated from Object Type Definitions │

│ │

│ Template: [Standard Video ▾] │

│ ← Filtered by selected type │

│ │

│ Location: [/Manuals/Safety/Videos ▾] │

│ ← Folder picker (current folder pre-selected) │

│ │

│ ┌──────────────────────────────────────────────────────────┐ │

│ │ ⓘ After creation you can upload a video file and │ │

│ │ manage subtitles from the Properties panel. │ │

│ └──────────────────────────────────────────────────────────┘ │

│ │

│ [Cancel] [Create] │

└────────────────────────────────────────────────────────────────┘

Behaviour:

On "Create" → video Object created in Draft status → Object List refreshes → new object selected

System creates the full hierarchy: Version 1 → Subversion 1 → Source Language Variant → Source Format → Revision 0 (empty, no file yet)

User is NOT immediately prompted to upload — upload is a separate, explicit action from Properties

Selection flow after creation:


Object created → appears in Object List → auto-selected

 → Properties panel shows "Video" type badge + upload prompt

 → Preview panel shows empty state: "No video file uploaded yet"

2.2 Object List — Video Objects

Video Objects appear in the standard Object List alongside all other objects. They are visually distinguished by:


┌────────────────────────────────────────────────────────────────────────┐

│ Name │ Type │ Status │ Modified │ Author │

├────────────────────────────────────────────────────────────────────────┤

│ &#127916; safety-demo.mp4 │ Video │ Draft │ May 28 │ J. Smith │

│ &#127916; assembly-guide.webm │ Video │ Released │ May 20 │ A. Lee │

│ &#128196; install-steps.dita │ DITA │ Checked In │ May 27 │ J. Smith │

│ &#128444; wiring-diagram.svg │ Graphic │ Released │ May 15 │ B. Chen │

└────────────────────────────────────────────────────────────────────────┘

Type icon: 🎬 (film/video icon) distinguishes videos from DITA (📄) and Graphics (🖼)

Type column: Shows "Video"

All other columns: Identical behaviour to existing object types (sortable, filterable)

Double-click: Opens Object Authoring page (video-specific adapter — see §2.5)

2.3 Properties Panel — Video-Specific Sections

When a Video Object is selected, the Properties panel (Zone B) shows standard metadata sections plus video-specific sections.


┌──────────────────────────────────────────────────────────┐

│ PROPERTIES │

├──────────────────────────────────────────────────────────┤

│ │

│ ── General ── │

│ Title: [Safety Demonstration Video ] │

│ Object Type: Video │

│ Status: Draft │

│ Language: EN (Source) │

│ │

│ ── Metadata ── │

│ [Standard metadata fields per workspace config] │

│ │

│ ── Video File ── │

│ ┌──────────────────────────────────────────────────┐ │

│ │ &#128193; safety-demo.mp4 │ │

│ │ Format: MP4 (H.264) │ Size: 142 MB │ │

│ │ Duration: 04:32 │ Resolution: 1920×1080 │ │

│ │ │ │

│ │ [Replace Video] [Download] │ │

│ └──────────────────────────────────────────────────┘ │

│ │

│ ── OR (no file uploaded yet) ── │

│ ┌──────────────────────────────────────────────────┐ │

│ │ [Drag & drop video file here] │ │

│ │ │ │

│ │ or [Browse...] │ │

│ │ │ │

│ │ Accepted: MP4, WebM (max 2 GB) │ │

│ └──────────────────────────────────────────────────┘ │

│ │

│ ── Subtitles ── │

│ ┌──────────────────────────────────────────────────┐ │

│ │ Language │ File │ Status │ Actions │ │

│ │ EN (source) │ en.vtt │ Current │ ↓ ✏ &#128465; │ │

│ │ DE │ de.srt │ ⚠ Stale │ ↓ ✏ &#128465; │ │

│ │ FR │ — │ Missing │ + Add │ │

│ │ │ │

│ │ [+ Add Subtitle] │ │

│ └──────────────────────────────────────────────────┘ │

│ │

└──────────────────────────────────────────────────────────┘

Video File section behaviours:

Upload zone (no file): Drag-and-drop area + browse button. Shows accepted formats and max size.

After upload: Shows file info card with format, size, duration, resolution (extracted on upload).

Replace Video: Opens file picker, uploads new file → creates new Revision.

Download: Downloads the current video file locally.

Validation errors: Inline error below the upload zone if format unsupported or file too large.

Subtitles section behaviours:

Lists all subtitle files across language variants.

Status indicators:

Current — subtitle matches the latest video revision

⚠ Stale — source video updated since subtitle was last edited (FR-009)

Missing — language variant exists but no subtitle file uploaded

Actions: Download (↓), Edit/Replace (✏), Delete (🗑), Add (+)

+ Add Subtitle: Opens subtitle upload dialog (see §2.4)

2.4 Subtitle Upload Dialog

Triggered by: "+ Add Subtitle" button in Properties panel


┌────────────────────────────────────────────────────────────┐

│ Add Subtitle [✕] │

├────────────────────────────────────────────────────────────┤

│ │

│ Language: [German (DE) ▾] │

│ ← Dropdown: configured language variants │

│ │

│ File: [________________________________] [Browse] │

│ ← Drag-and-drop zone also supported │

│ │

│ Accepted formats: SRT, VTT │

│ │

│ ┌──────────────────────────────────────────────────────┐ │

│ │ ⚠ Validation Results (shown after file selected): │ │

│ │ │ │

│ │ ✓ Format: Valid VTT │ │

│ │ ✓ Encoding: UTF-8 │ │

│ │ ⚠ Warning: 2 timing overlaps detected (lines 14, │ │

│ │ 28). These may cause display issues. │ │

│ └──────────────────────────────────────────────────────┘ │

│ │

│ [Cancel] [Upload] │

└────────────────────────────────────────────────────────────┘

Behaviour:

File is validated immediately on selection (FR-008)

Blocking errors (malformed syntax, wrong format): Upload button disabled, error shown

Non-blocking warnings (timing overlaps, long gaps): Upload button enabled, warning shown

On upload → new revision created for the language variant → Subtitles table refreshes

2.5 Object Authoring — Video Adapter

Route: /ws/:workspaceId/object-authoring?objectId=...

When a Video Object is opened in the Object Authoring page, a video-specific adapter renders instead of the XML editor.


┌────────────────────────────────────────────────────────────────┐

│ [Object Authoring Shell] │

│ ─ "Safety Demonstration Video" / breadcrumb │

│ ─ Action bar: [Save] [Check Out] [Check In] [Close] │

├────────────────────────────────────────────────────────────────┤

│ │

│ ┌──────────────────────────────────────────────────────────┐ │

│ │ │ │

│ │ ┌──────────────────────────┐ │ │

│ │ │ │ │ │

│ │ │ ▶ VIDEO PLAYER │ │ │

│ │ │ (inline) │ │ │

│ │ │ │ │ │

│ │ └──────────────────────────┘ │ │

│ │ │ │

│ │ ┌──────────────────────────────────────────────┐ │ │

│ │ │ ▶ ■ ─────────●──────────── 01:32 / 04:32 │ │ │

│ │ │ [CC] [Language: EN ▾] [⛶ Full] │ │ │

│ │ └──────────────────────────────────────────────┘ │ │

│ │ │ │

│ └──────────────────────────────────────────────────────────┘ │

│ │

│ ── Below Player ── │

│ ┌────────────────────┬─────────────────────────────────────┐ │

│ │ VIDEO DETAILS │ SUBTITLES MANAGEMENT │ │

│ │ ────────────── │ ───────────────────── │ │

│ │ File: safety.mp4 │ [Same as Properties subtitle │ │

│ │ Format: MP4 │ section — see §2.3] │ │

│ │ Duration: 04:32 │ │ │

│ │ Resolution: 1080p │ [+ Add Subtitle] │ │

│ │ Size: 142 MB │ [Upload New Version] │ │

│ │ │ │ │

│ │ [Replace Video] │ │ │

│ │ [Download] │ │ │

│ └────────────────────┴─────────────────────────────────────┘ │

│ │

└────────────────────────────────────────────────────────────────┘

Player controls:

Standard video controls: play/pause, seek bar, time display, fullscreen

[CC]: Toggle subtitle display on/off + select subtitle track

[Language ▾]: Switch between language variants (loads different video file or different subtitles depending on variant type)

Check-out / Check-in:

Follows existing Object locking semantics (pessimistic lock at Version level)

"Replace Video" and "Add Subtitle" are only enabled when the Object is checked out by the current user

2.6 Preview Panel — Video Preview

When a Video Object is selected in the Object List, the Preview panel (Zone C) renders an inline video player.


┌──────────────────────────────────────────────────────────┐

│ PREVIEW │

├──────────────────────────────────────────────────────────┤

│ │

│ ┌──────────────────────────────────────────────────┐ │

│ │ │ │

│ │ ▶ VIDEO PLAYER │ │

│ │ (aspect-ratio preserved) │ │

│ │ │ │

│ └──────────────────────────────────────────────────┘ │

│ │

│ ┌──────────────────────────────────────────────────┐ │

│ │ ▶ ■ ──────●────────────── 00:45 / 04:32 │ │

│ │ [CC ▾] [Lang: EN ▾] [⛶ Full] │ │

│ └──────────────────────────────────────────────────┘ │

│ │

│ ── Video Info (below player) ── │

│ Duration: 04:32 │ Format: MP4 │ 1920×1080 │

│ Subtitles: EN ✓, DE ✓, FR (missing) │

│ │

└──────────────────────────────────────────────────────────┘

States:

| State | Appearance |

|-------|------------|

| No file uploaded | Empty state: illustration + "No video uploaded. Open properties to upload." |

| File uploading | Progress bar + "Uploading… 67%" |

| Ready to play | Video player with poster frame (first frame or custom thumbnail) |

| Unsupported format (browser) | Fallback: file info card + download link |

| Error loading | Error state with retry |

Language variant switcher:

Dropdown in player controls shows available language variants

Switching variant reloads the video source (dubbed) or switches subtitle track (subtitled)

Current variant indicated with checkmark

2.7 Inserting Video References in DITA Topics

Context: User is editing a DITA topic in the XML Editor (Object Authoring page, DITA adapter)

Entry point: Editor toolbar → "Insert Reference" → "Video" (or from a content-assist / auto-complete)


┌────────────────────────────────────────────────────────────┐

│ Insert Video Reference [✕] │

├────────────────────────────────────────────────────────────┤

│ │

│ &#128269; Search video Objects: [________________________] │

│ │

│ ┌──────────────────────────────────────────────────────┐ │

│ │ Results: │ │

│ │ &#127916; Safety Demonstration Video │ Released │ EN │ │

│ │ &#127916; Assembly Guide │ Released │ EN, DE │ │

│ │ &#127916; Wiring Overview │ Draft │ EN │ │

│ └──────────────────────────────────────────────────────┘ │

│ │

│ Selected: Safety Demonstration Video │

│ │

│ Display: [○ Embedded player ● Link ○ Thumbnail+link] │

│ │

│ ── Post-MVP (disabled, greyed out) ── │

│ Start time: [__:__] End time: [__:__] │

│ ⓘ Timestamp references available in a future release │

│ │

│ [Cancel] [Insert] │

└────────────────────────────────────────────────────────────┘

Behaviour:

Search filters to Video-type Objects only

Results show status and available languages

Display mode determines how the reference renders in published output

Timestamp fields are visible but disabled for MVP (post-MVP: User Story 3)

On "Insert" → DITA <video> element with data attribute pointing to the Object ID is inserted at cursor position

Cross-reference resolution follows existing platform patterns

After insertion (in XML editor):


<video>

 <media-source value="object://abc-123-def"/>

 <video-poster value="object://abc-123-def/poster"/>

 <desc>Safety Demonstration Video</desc>

</video>

The editor renders this as a visual placeholder block showing the video title and a thumbnail (not a live player — full playback is in Preview).

2.8 Video Reference in Topic Preview

When a topic containing a video reference is previewed, the video renders inline.


┌──────────────────────────────────────────────────────────────┐

│ TOPIC PREVIEW │

├──────────────────────────────────────────────────────────────┤

│ │

│ ## Step 3: Connect the Wiring Harness │

│ │

│ Route the harness through the left channel and │

│ secure with the provided clips. │

│ │

│ ┌────────────────────────────────────────────────────────┐ │

│ │ │ │

│ │ ▶ INLINE VIDEO PLAYER │ │

│ │ (Safety Demonstration Video) │ │

│ │ │ │

│ │ ──────────●───────────── 00:00 / 04:32 │ │

│ │ [CC ▾] [Lang: EN ▾] [⛶ Full] │ │

│ └────────────────────────────────────────────────────────┘ │

│ │

│ Ensure the connector clicks into place before │

│ proceeding to the next step. │

│ │

└──────────────────────────────────────────────────────────────┘

Broken reference state:


┌────────────────────────────────────────────────────────────┐

│ ⚠ Video reference broken │

│ "Safety Demonstration Video" has been deleted/obsoleted. │

│ [Open referencing topic to fix] │

└────────────────────────────────────────────────────────────┘

2.9 Upload Progress & Validation Feedback

Large video files require clear progress indication and early validation feedback.

Upload flow (in Properties panel or Object Authoring page):


Step 1: File selected

┌──────────────────────────────────────────────────────────┐

│ &#128193; safety-demo.mp4 (142 MB) │

│ Validating format... │

└──────────────────────────────────────────────────────────┘

 

Step 2: Validation passed, upload in progress

┌──────────────────────────────────────────────────────────┐

│ &#128193; safety-demo.mp4 (142 MB) │

│ ████████████░░░░░░░░░░░░░░ 45% 67 MB / 142 MB │

│ Estimated: ~2 min remaining │

│ [Cancel Upload] │

└──────────────────────────────────────────────────────────┘

 

Step 3: Upload complete, metadata extraction

┌──────────────────────────────────────────────────────────┐

│ ✓ safety-demo.mp4 uploaded successfully │

│ Extracting video metadata... │

│ Duration: 04:32 │ Resolution: 1920×1080 │ H.264 │

└──────────────────────────────────────────────────────────┘

Validation error examples:


┌──────────────────────────────────────────────────────────┐

│ ✗ Upload failed: Unsupported format │

│ "recording.avi" is not an accepted format. │

│ Accepted formats: MP4, WebM │

│ [Try Again] │

└──────────────────────────────────────────────────────────┘

 

┌──────────────────────────────────────────────────────────┐

│ ✗ Upload failed: File too large │

│ "full-training.mp4" (4.2 GB) exceeds the maximum │

│ upload size of 2 GB for this workspace. │

│ [Try Again] │

└──────────────────────────────────────────────────────────┘

2.10 Accessibility Warning on Status Progression

When a user progresses a Video Object to "Approved" or "Released" status and no subtitle/caption file exists for the source language, a non-blocking warning is shown (FR-019).


┌────────────────────────────────────────────────────────────┐

│ ⚠ Accessibility Notice [✕] │

├────────────────────────────────────────────────────────────┤

│ │

│ This video has no subtitle or caption file for the │

│ source language (EN). │

│ │

│ Videos without captions may not meet accessibility │

│ requirements for all audiences. │

│ │

│ [Add Subtitles Now] [Proceed Without Subtitles] │

│ │

└────────────────────────────────────────────────────────────┘

"Add Subtitles Now" → Navigates user to subtitle management (opens Subtitle Upload Dialog)

"Proceed Without Subtitles" → Continues the status transition, warning acknowledged

Warning is non-blocking — user is never prevented from progressing

2.11 Stale Subtitle Notification

When a source video is updated to a new revision, all existing subtitles are flagged as stale (FR-009). The notification appears:

In Properties panel (Subtitles section):


┌──────────────────────────────────────────────────────────┐

│ ⚠ Source video updated — 2 subtitle files may be │

│ out of date and need review. │

│ │

│ Language │ File │ Status │ Actions │

│ DE │ de.srt │ ⚠ Needs Review │ ↓ ✏ &#128465; [✓ OK] │

│ FR │ fr.vtt │ ⚠ Needs Review │ ↓ ✏ &#128465; [✓ OK] │

└──────────────────────────────────────────────────────────┘

[✓ OK] marks the subtitle as reviewed/still-valid without requiring a re-upload

[✏] opens the subtitle upload dialog to replace with an updated file

3. Admin Portal — Video Configuration

3.1 Object Types Page — Video Type Configuration

Route: /c/:customerId/ws/:workspaceId/object-types

The existing Object Types page is used to configure the "Video" object type. No new admin page is required.


┌──────────────────────────────────────────────────────────────────┐

│ HIERARCHY TREE │

│ ────────────── │

│ ▾ Document │

│ ├── DITA Topic │

│ ├── DITA Map │

│ └── Markdown │

│ ▾ Graphic │

│ ├── SVG │

│ └── Raster Image │

│ ▾ Video ← NEW ENTRY │

│ ├── Standard Video │

│ │ └── [Templates: Standard, Tutorial, Safety Demo] │

│ └── Animated Illustration │

│ └── [Templates: Short Loop, Explainer] │

│ ▸ Resource │

└──────────────────────────────────────────────────────────────────┘

Video type settings (when selected in tree):


┌──────────────────────────────────────────────────────────────┐

│ Video — Type Settings │

├──────────────────────────────────────────────────────────────┤

│ │

│ Accepted Formats: [✓ MP4] [✓ WebM] [☐ MOV] [☐ MKV] │

│ ← Workspace-configurable per FR-002 │

│ │

│ Maximum File Size: [2048 ] MB │

│ ← Workspace override (system default │

│ shown as placeholder) │

│ │

│ Subtitle Formats: [✓ SRT] [✓ VTT] │

│ │

│ Require Subtitles for Release: [☐] │

│ ← When checked, warning becomes blocking for Release only │

│ │

│ [Save Settings] │

│ │

└──────────────────────────────────────────────────────────────┘

3.2 Workspace Settings — Video Upload Limits

Route: /c/:customerId/ws/:workspaceId/settings

A "Video" section is added to the existing Workspace Settings page.


┌──────────────────────────────────────────────────────────────┐

│ ── VIDEO SETTINGS ── │

│ ┌────────────────────────────────────────────────────────┐ │

│ │ Max Upload Size: [2048 ] MB │ │

│ │ System default: 2048 MB │ │

│ │ │ │

│ │ Accepted Video Formats: [MP4, WebM ] (editable) │ │

│ │ │ │

│ │ Accepted Subtitle Formats: [SRT, VTT ] (editable) │ │

│ │ │ │

│ │ [Save] │ │

│ └────────────────────────────────────────────────────────┘ │

└──────────────────────────────────────────────────────────────┘

4. Content Delivery — Consumer Experience

4.1 Video in Delivered Topic

When a consumer views delivered content through the CDP that contains a video reference, they see:


┌──────────────────────────────────────────────────────────────┐

│ [Delivered Topic Content] │

├──────────────────────────────────────────────────────────────┤

│ │

│ Step 3: Connect the Wiring Harness │

│ │

│ Route the harness through the left channel... │

│ │

│ ┌────────────────────────────────────────────────────────┐ │

│ │ ┌──────────────────────────────────────────────────┐ │ │

│ │ │ │ │ │

│ │ │ ▶ VIDEO PLAYER │ │ │

│ │ │ │ │ │

│ │ └──────────────────────────────────────────────────┘ │ │

│ │ ──────────────────────────── 00:00 / 04:32 │ │

│ │ [▶] [CC: English ▾] [Quality ▾] [⛶ Full] │ │

│ │ │ │

│ │ Available subtitles: EN │ DE │ FR │ │

│ └────────────────────────────────────────────────────────┘ │

│ │

│ Ensure the connector clicks into place... │

│ │

└──────────────────────────────────────────────────────────────┘

Consumer interactions:

Play/pause, seek, fullscreen — standard HTML5 video controls

Subtitle selector: Lists available subtitle tracks. Auto-selects based on consumer's language preference (from CDP language context).

Post-MVP (User Story 3): If timestamp reference present, player auto-seeks to start time on load. A visual indicator shows the referenced segment range.

4.2 Video Language Resolution in Delivery

The CDP resolves which video to serve based on the consumer's language:


Consumer language = DE

 

 1. Does a DE language variant with a dubbed video exist?

 → YES: Serve the DE video file

 → NO: Continue to step 2

 

 2. Does the source video have DE subtitles?

 → YES: Serve the source (EN) video + DE subtitle track (auto-selected)

 → NO: Serve the source (EN) video with no subtitles pre-selected

This resolution is transparent to the consumer — they always see a playable video with the best available localization.

5. User Flows

Flow V1: Upload a Video File to a New Object


User in /authoring

 → Clicks "+ Create"

 → CreateObjectDialog: selects "Video" type, names it, selects folder

 → Clicks "Create" → Object created in Draft

 → Object selected in list → Properties panel loads

 → User sees "Video File" section with upload zone

 → Drags video file onto upload zone

 → Client validates: format check (MP4? ✓), size check (142MB < 2GB? ✓)

 → Upload begins → progress bar shown (45%... 67%... 100%)

 → Server extracts metadata (duration, resolution, codec)

 → Properties panel refreshes: file info card shown

 → Preview panel refreshes: video player ready

Flow V2: Add Subtitles to a Video


User selects video Object in Object List

 → Properties panel → Subtitles section

 → Clicks "+ Add Subtitle"

 → Subtitle Upload Dialog opens

 → Selects language: "German (DE)"

 → Browses/drops subtitle file: "de.srt"

 → Client validates syntax → results shown (✓ valid, ⚠ 1 timing overlap)

 → User clicks "Upload"

 → File stored as asset of DE language variant

 → Subtitles table refreshes: DE row shows "de.srt" with "Current" status

 → Preview panel: [CC] dropdown now includes "DE" option

Flow V3: Insert Video Reference into DITA Topic


User editing a DITA topic in Object Authoring (XML Editor)

 → Toolbar → "Insert Reference" → "Video"

 → Insert Video Reference dialog opens

 → Types search: "safety"

 → Results show: "Safety Demonstration Video" (Released, EN)

 → Selects it → Display mode: "Embedded player"

 → Clicks "Insert"

 → DITA <video> element inserted at cursor

 → Editor shows visual placeholder: [&#127916; Safety Demonstration Video]

 → User switches to Preview tab

 → Preview renders inline video player at the reference position

Flow V4: Review Video with Subtitles (Reviewer)


Reviewer navigates to video Object in /authoring

 → Selects the video Object → Preview panel loads

 → Video player renders with poster frame

 → Reviewer clicks play → video plays

 → Clicks [CC ▾] → selects "DE" subtitles

 → German subtitles overlay on video

 → Reviewer switches [Language ▾] → selects "FR"

 → Player reloads with French dubbed video (if available)

 → OR: stays on source video, switches subtitle track to FR

 → Reviewer satisfied → navigates to Properties → progresses to "Approved"

 → No accessibility warning (subtitles exist) → status updated

Flow V5: Source Video Updated — Stale Subtitle Flow


Author checks out video Object

 → Uploads a new video revision (re-recorded safety demo)

 → System creates new revision

 → System flags all existing subtitles as "⚠ Needs Review"

 → Properties panel shows warning banner: "2 subtitle files may be out of date"

 → Author notifies translator (or handles via workflow)

 → Translator uploads updated DE subtitle file

 → DE row changes from "⚠ Needs Review" to "Current"

 → Author reviews FR subtitle, confirms still valid

 → Clicks [✓ OK] on FR row → status changes to "Current"

Flow V6: Broken Video Reference Detection


Content manager obsoletes a video Object

 → System scans for cross-references to this Object

 → Finds 3 topics referencing it

 → System flags broken references (FR-015)

 → In each referencing topic's Properties or Change History:

 → "⚠ 1 broken reference: video Object obsoleted"

 → Author opens topic → sees broken reference indicator in XML editor

 → Removes or replaces the video reference

 → Saves → broken reference warning clears

Flow V7: Video Object in Search Results


User opens search (Dashboard or any search-enabled panel)

 → Types: "safety"

 → Results include:

 &#128196; Safety Procedures Manual (DITA Map)

 &#127916; Safety Demonstration Video (Video) ← Video object in results

 &#128196; Safety Checklist (DITA Topic)

 → User applies filter: Type = "Video"

 → Results narrow to only video Objects:

 &#127916; Safety Demonstration Video

 &#127916; Safety Equipment Overview

6. States & Edge Cases

6.1 Empty States

| Location | Condition | Display |

|----------|-----------|---------|

| Preview panel | No video file uploaded | Illustration + "No video uploaded yet. Use Properties to upload a file." |

| Subtitles section | No subtitles exist | "No subtitles added. Click + Add Subtitle to get started." + CTA button |

| Insert Video dialog | Search returns no results | "No video Objects found. Create a video Object first." |

| Object List (filtered to Video) | No video Objects in workspace | "No video Objects in this workspace. Create one with + Create." |

6.2 Error States

| Scenario | Display |

|----------|---------|

| Video upload network failure | "Upload failed. Check your connection and try again." + [Retry] |

| Video file corrupt / unreadable | "Unable to process this video file. Ensure it is a valid MP4 or WebM." |

| Subtitle parse failure | Inline validation errors in Subtitle Upload Dialog (specific line numbers) |

| Preview load failure | Standard error state in Preview panel + [Retry] |

| CDP video delivery failure | Fallback: download link shown instead of player |

6.3 Loading States

| Location | Skeleton |

|----------|----------|

| Preview panel (video loading) | Grey rectangle at 16:9 aspect ratio + pulsing animation |

| Properties panel (metadata loading) | Standard properties skeleton |

| Upload in progress | Progress bar with percentage + estimated time |

| Subtitle validation | Spinner + "Validating subtitle file..." |

7. Responsive & Platform Considerations

7.1 Responsive Behaviour

| Breakpoint | Video Player | Properties |

|------------|-------------|------------|

| Desktop (≥ 768px) | Full player in Preview panel or Object Authoring | Side panel with all sections |

| Mobile (< 768px) | Full-width player, stacked below content | Collapsed accordion sections |

7.2 Electron vs. Web

| Behaviour | Web | Electron |

|-----------|-----|----------|

| Video upload | Browser file picker | Native file picker (larger file support) |

| Large file handling | Browser memory limits may apply | IPC-based chunked upload |

| Video playback | HTML5 `<video>` element | Same (Chromium-based) |

| Popout video player | Browser popup window | Separate BrowserWindow |

8. Capability Gating

Video management does not introduce new capabilities (per spec clarification). It reuses existing object-editing capabilities:

| Action | Required Capability |

|--------|-------------------|

| Create video Object | Same as creating any Object |

| Upload video file | Same as editing binary Objects |

| Manage subtitles | Same as editing binary Objects |

| Insert video reference | Same as editing DITA topics |

| Preview video | Same as previewing any Object |

| Configure video types (Admin) | Object type admin capability |

| Configure workspace video settings (Admin) | Workspace settings capability |

9. URL State Conventions

| State | Mechanism | Example |

|-------|-----------|---------|

| Selected video Object | URL search param | `?object=video-abc-123` |

| Video language variant (preview) | Component state (not URL) | Player dropdown |

| Subtitle track selection | Component state (not URL) | CC dropdown |

| Object Authoring (video) | URL search param | `/object-authoring?objectId=video-abc-123` |

10. Integration Points

| System | Integration |

|--------|-------------|

| Object List | Video type icon, double-click opens video adapter |

| Properties Panel | Video File section + Subtitles section (new) |

| Preview Panel | Video player adapter (new renderer) |

| Object Authoring | Video adapter (new, alongside DITA/Markdown/Graphics) |

| XML Editor (DITA) | Insert Video Reference action + visual placeholder |

| Topic Preview | Inline video player for `<video>` elements |

| Search | Video Objects indexed and filterable by type |

| CDP | Video + subtitle delivery with language resolution |

| Audit | All video operations emit audit events |

| Workflow | Standard status progression + accessibility warning |

11. Conventions Checklist

[x] Reuses existing page structures (Author View, Object Authoring, Admin Object Types)

[x] No new sidebar navigation items required

[x] Empty states defined for all new sections

[x] Error states use shared ErrorState component pattern

[x] Loading skeletons defined (video player placeholder, upload progress)

[x] No new capability gates (reuses existing)

[x] URL state follows workspace-scoped conventions

[x] Data fetching via useFetch / useMutate (no raw fetch)

[x] Destructive actions (delete subtitle, replace video) use confirmation dialogs

[x] Dialogs follow Radix UI Dialog pattern

[x] All new user-facing strings require i18n namespace entries

[x] Responsive behaviour documented

[x] Electron/Web differences addressed