# Video player

> A viewer: picture on a neutral black surround, safe-area guides, burnt-in timecode and slate, a scrub bar with the in–out range, and the compact transport.

Source: https://kwark.space/designSystem/components/video-player

## Usage

### What it is
Where picture is judged. A viewer frames the image in black, puts only the guides the person turned on over it, and says exactly which frame it is showing. Here it is the program viewer at 01:04:10:07, on 12B take 1, inside the in–out range the editor just marked around that shot.

### When to use
- As the source or program viewer in an editor (paired in [Source and program viewers](https://kwark.space/designSystem/components/viewer-pair.md)).
- In dailies, review and grading, where the frame needs an address.

### When not to
- For background or marketing video, or anything that autoplays.
- For a storyboard animatic with no media yet: use the [Playhead](https://kwark.space/designSystem/components/playhead.md) over [Storyboard frames](https://kwark.space/designSystem/components/storyboard-frame.md).

### Overlays
| Overlay | What it shows | Default |
|---|---|---|
| Action safe | 93% of the frame (SMPTE ST 2046-1) | Off; on for broadcast deliverables |
| Title safe | 90% of the frame | Off; on while placing titles |
| Burn-in, bottom centre | Timecode of the clock the viewer plays | On in review copies |
| Burn-in, top left | Slate and clip name, *12B-1 · A003C012* | On in review copies |
| In–out bar | The marked range under the picture | Always |

Guides are drawn at 1px in `--k-pro-picture-ink` at 45%. Nothing else touches the picture: no accent colours, no badges, no buttons floating over it.

### Writing
The header says the viewer and what is loaded: *Program · Scene 12 · cut v4*, *Source · 12B-1*.

**Do:** Picture on black, guides the editor turned on, timecode burnt in and under the frame.

**Don't:** A rounded, colourful frame with a play button floating over the actor's face.

## Style

### Anatomy

1. **Header**: 28px, `--k-pro-head`, viewer name 12px 500, what is loaded in `--k-text-2`, zoom menu (*Fit*, 50%, 100%) and the guides toggle.
2. **Picture**: 16:9 frame centred on `--k-pro-picture`, letterboxed with 8px of surround. The surround is neutral in both themes.
3. **Safe areas**: two 1px rectangles at 93% and 90%.
4. **Burn-ins**: 12px Poppins 500 on `--k-pro-picture` at 70%, 2px 6px, 3px corners.
5. **Scrub bar**: 14px; in–out range in `--k-pro-mark` at 22% with 2px edges; playhead a 2px `--k-pro-playhead` line with a 9px head.
6. **Foot**: 32px; timecode left, compact transport centre, in–out duration right.
7. **Active**: the viewer that J/K/L drive has a 2px `--k-pro-playhead` line under its header.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-pro-picture` | #0b0b0c |  |
| `--k-pro-picture-ink` | #e6e6e6 |  |
| `--k-pro-panel` | #f6f7f9 | #19191b |
| `--k-pro-head` | #eceff3 | #202023 |
| `--k-pro-line` | #d3d9e0 | rgba(255, 255, 255, .09) |
| `--k-pro-playhead` | #c4502f | #f28b71 |
| `--k-pro-mark` | #23767d | #83cfd3 |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |

### Numbers
| Part | Value |
|---|---|
| Header, foot | 28px, 32px |
| Surround padding | 8px (4px under 360px wide) |
| Burn-in text | 12px, weight 500, tabular |
| Safe areas | inset 3.5% and 5% of each side |
| Scrub bar | 14px tall, track 4px |
| Narrow (under 340px) | marks, go to in/out and duration hide; frame steps and play stay |

## Code

### React

Use the HTML below with `kwark.css`. The example shows the markup and styling. Supply any application behavior described on this page.

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<figure class="kw-pro kw-pro-viewer" data-active aria-label="Program viewer, Scene 12 · cut v4">
  <div class="kw-pro-bar"><strong>Program</strong><span class="kw-pro-dim kw-pro-ellip">Scene 12 · cut v4</span><span class="kw-pro-sp"></span><button class="kw-pro-btn kw-pro-btn--menu" type="button" aria-haspopup="menu" aria-label="Zoom: Fit">Fit<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></button><button class="kw-pro-btn" type="button" aria-pressed="true" aria-label="Safe area guides" title="Safe area guides"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="3" y="5" width="18" height="14" rx="1"/><rect x="6.5" y="8" width="11" height="8" stroke-dasharray="2 2"/></svg></button></div>
  <div class="kw-pro-viewer__pic"><div class="kw-pro-viewer__frame"><svg class="kw-pro-pic" viewBox="0 0 160 90" preserveAspectRatio="xMidYMid slice" aria-hidden="true"><rect class="w" width="160" height="90"/><circle class="l" cx="26" cy="22" r="11" opacity=".35"/><circle class="l" cx="46" cy="33" r="5" opacity=".25"/><path class="b" d="M40 90c0-19 19-29 44-29s44 10 44 29z"/><rect class="s" x="76" y="52" width="16" height="14"/><ellipse class="s" cx="84" cy="40" rx="17" ry="21"/><path class="h" d="M66 42c0-17 8-25 19-25s18 8 18 23c-4-9-10-13-18-13s-14 7-19 15z"/><path class="m" d="M99 29c4 5 5 13 3 21l-3 4c2-9 2-17 0-25z" opacity=".85"/></svg><span class="kw-pro-viewer__safe" data-k="action"></span><span class="kw-pro-viewer__safe" data-k="title"></span><span class="kw-pro-burn" data-pos="tl">12B-1 · A003C012</span><span class="kw-pro-burn kw-tc" data-pos="bc">01:04:10:07</span></div></div>
  <div class="kw-pro-vscrub"><span class="kw-pro-vscrub__io" style="left:27%;width:26%"></span><span class="kw-pro-vscrub__ph" role="slider" tabindex="0" style="left:43%" aria-label="Program position" aria-valuemin="0" aria-valuemax="576" aria-valuenow="248" aria-valuetext="01:04:10:07"></span></div>
  <div class="kw-pro-viewer__foot"><output class="kw-pro-tc">01<i>:</i>04<i>:</i>10<i>:</i>07</output><div class="kw-pro-transport" role="toolbar" aria-label="Program transport"><button class="kw-pro-btn kw-pro-x" type="button" aria-label="Mark in (I)" title="Mark in (I)"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M14 4H9v16h5"/></svg></button><button class="kw-pro-btn kw-pro-x" type="button" aria-label="Go to in (Shift I)" title="Go to in (Shift I)"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M9 5H6v14h3M20 12h-9m3-3.5L10.5 12l3.5 3.5"/></svg></button><button class="kw-pro-btn" type="button" aria-label="Back one frame (Left arrow)" title="Back one frame (Left arrow)"><svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M5 5h2v14H5zM19 5v14L8.5 12z"/></svg></button><button class="kw-pro-btn" type="button" aria-label="Play backwards (J)" title="Play backwards (J)"><svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M17 4.5v15L5 12z"/></svg></button><button class="kw-pro-btn kw-pro-btn--play" type="button" aria-label="Play (Space or L)" title="Play (Space or L)"><svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M7 4.5v15l12-7.5z"/></svg></button><button class="kw-pro-btn" type="button" aria-label="Forward one frame (Right arrow)" title="Forward one frame (Right arrow)"><svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M17 5h2v14h-2zM5 5v14l10.5-7z"/></svg></button><button class="kw-pro-btn kw-pro-x" type="button" aria-label="Go to out (Shift O)" title="Go to out (Shift O)"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M15 5h3v14h-3M4 12h9m-3-3.5 3.5 3.5-3.5 3.5"/></svg></button><button class="kw-pro-btn kw-pro-x" type="button" aria-label="Mark out (O)" title="Mark out (O)"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M10 4h5v16h-5"/></svg></button></div><span class="kw-pro-tc kw-pro-dim kw-pro-x" title="In to out">00<i>:</i>00<i>:</i>06<i>:</i>06</span></div>
</figure>
```

### Picture
Put the real `<video>` (or a canvas) inside `.kw-pro-viewer__frame`; it fills it with `object-fit: contain`. The specimen's frame is a flat stand-in for footage.

## Accessibility

### Keyboard
| Key | Does |
|---|---|
| Space, J, K, L | Play and shuttle (see [Transport bar](https://kwark.space/designSystem/components/transport-bar.md)) |
| ← / → | Step a frame (on the scrub bar too) |
| Home / End | First / last frame |
| ' (apostrophe) | Safe-area guides on / off |

### ARIA
- `<figure>` with an `aria-label` naming the viewer and what is loaded.
- The scrub handle is `role="slider"` with `aria-valuetext` in timecode.
- Captions for speech in review copies; native `<video>` caption tracks.
- No autoplay. Under reduced motion, previews show a still.

## For agents

### Rules

- **Must** keep the surround around picture neutral black in every theme and room.
- **Never** put accent colours, badges or floating buttons over the picture; only guides the person turns on.
- **Must** show the timecode of the clock the viewer plays, labelled, with frames.
- **Always** show the in–out range under the picture when one is marked.
- **Never** autoplay with sound.

### AI readiness test

**Task:** Let a director watch cut v4 of Scene 12 and leave a note at a frame on a laptop.

**Give the agent:** Video player, Transport bar, Marker list.

**Constraint:** Review copies need burnt-in timecode; the director never edits.

**A reliable answer:**
- Picture on neutral black
- Burn-in timecode and slate
- Scrub slider with timecode valuetext
- Add marker (M) stores the frame
- No autoplay
- No accent near picture
