390 lines
18 KiB
Markdown
390 lines
18 KiB
Markdown
# Wild Dragon MAM — Editor, Growing File Preview & Feature Expansion
|
||
**Date:** 2026-05-18
|
||
**Status:** Draft — awaiting user approval before implementation begins
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
Three interconnected areas, sequenced by priority:
|
||
|
||
1. **NLE Editor** (`editor.html`) — Premiere-style timeline editor with razor blade, in/out marking, and EDL export
|
||
2. **Growing File Workflow** — HLS live preview during SDI/SRT/RTMP capture, with rewind support
|
||
3. **Feature Additions** — Prioritized list of high-value additions (subclips, player improvements, bulk ops, waveform, etc.)
|
||
|
||
---
|
||
|
||
## 1. NLE Editor
|
||
|
||
### 1.1 Layout
|
||
|
||
A new page `editor.html` replaces the role of `player.html` for editorial work. `player.html` is kept as the lightweight browse/metadata view; the editor is the full-screen creative environment.
|
||
|
||
```
|
||
┌─ SOURCE MONITOR ──────┬─ PROGRAM MONITOR ──────┐ ← 40vh
|
||
│ [video preview] │ [video preview] │
|
||
│ TC: 00:00:00:00 │ TC: 00:00:00:00 │
|
||
│ [────scrub bar────] │ [────scrub bar────] │
|
||
│ [IN] [OUT] [Insert] │ [J] [K] [L] [⏩] │
|
||
├─ MEDIA PANEL ─────────┴─ TIMELINE ─────────────┤ ← 60vh
|
||
│ [bin tree] │ [V] [C] [H] [──zoom──] │
|
||
│ [asset list] │ ruler: 00:00 00:05 00:10 … │
|
||
│ │ V1 ░░░░[clip A]░░░░[clip B]░░ │
|
||
│ │ V2 │
|
||
│ │ A1 ░░░░[clip A]░░░░[clip B]░░ │
|
||
│ │ A2 │
|
||
└───────────────┴──────────────────────────────────┘
|
||
```
|
||
|
||
The editor is accessed from the library: each asset card gains an "Open in Editor" action (next to the existing delete button). Clicking opens `editor.html?project=<id>&asset=<id>` — loads the asset into the source monitor and creates or resumes the project's active sequence.
|
||
|
||
The sidebar nav gains an **Editor** link (between Library and Ingest).
|
||
|
||
### 1.2 Source Monitor
|
||
|
||
- Displays the currently "loaded" clip (double-click asset in the media panel, or opened via `?asset=` URL param)
|
||
- Native `<video>` element with a custom transport bar (scrub slider, current-time / duration label, play/pause button)
|
||
- **Mark In:** keyboard `I` or button — stores `sourceIn` in seconds
|
||
- **Mark Out:** keyboard `O` or button — stores `sourceOut` in seconds
|
||
- In/out range shown as a highlighted region on the scrub bar
|
||
- **Insert:** drops the marked range into the timeline at the playhead, shifting downstream clips right
|
||
- **Overwrite:** drops the marked range at the playhead, overwriting whatever is there
|
||
- If no in/out marks are set, the full clip duration is used
|
||
|
||
### 1.3 Program Monitor
|
||
|
||
- Plays back the timeline from the current playhead position
|
||
- **Virtual playback:** a single `<video>` element cycles through clips — at each clip's source in-point, the video src is set to that clip's signed proxy URL and `currentTime` is seeked to `sourceIn`. When `currentTime` reaches `sourceOut`, the next clip loads. This is frame-close (not frame-perfect) and is acceptable for v1.
|
||
- Timecode display: `HH:MM:SS:FF` derived from timeline position and the sequence frame rate
|
||
- Transport shortcuts: `Space` (play/pause), `J` (reverse), `K` (stop), `L` (forward), `←`/`→` (± 1 frame), `Home` (jump to start)
|
||
|
||
### 1.4 Timeline
|
||
|
||
**Ruler:** Horizontal ruler showing timecode marks. Default scale: 100px/s. Adjustable via `Ctrl + scroll wheel` or a zoom slider.
|
||
|
||
**Tracks:** Four track rows — V1, V2 (video), A1, A2 (audio). Each track row has a fixed height (48px).
|
||
|
||
**Clips:** Absolutely positioned `<div>` elements within track rows.
|
||
- `left` = `timelineIn * scale`
|
||
- `width` = `(timelineOut - timelineIn) * scale`
|
||
- Clip body shows: clip name (truncated), timecode range
|
||
- If clip is wide enough (> 120px), shows the asset thumbnail centered
|
||
|
||
**Playhead:** Red vertical line spanning all tracks. Draggable. Clicking the ruler jumps the playhead.
|
||
|
||
**Tools (keyboard shortcuts):**
|
||
|
||
| Tool | Key | Behavior |
|
||
|------|-----|----------|
|
||
| Select | `V` | Click to select (highlight), drag to move horizontally within track, drag left/right edge to trim source in/out |
|
||
| Razor | `C` | Click anywhere on a clip to split it into two clips at that exact frame |
|
||
| Hand | `H` | Click-drag to pan the timeline horizontally |
|
||
|
||
**Selection + editing:**
|
||
- Delete key removes selected clip(s)
|
||
- Ctrl+Z / Ctrl+Shift+Z: undo / redo (state stored as a local history stack, max 50 steps)
|
||
- Clips cannot overlap within the same track (razor and move operations enforce this)
|
||
|
||
### 1.5 Data Model
|
||
|
||
**New migration: `schema_patch_editor.sql`**
|
||
|
||
```sql
|
||
-- Sequences (named timelines within a project)
|
||
CREATE TABLE sequences (
|
||
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||
project_id UUID NOT NULL REFERENCES projects ON DELETE CASCADE,
|
||
name TEXT NOT NULL DEFAULT 'Sequence 1',
|
||
frame_rate NUMERIC(6,3) NOT NULL DEFAULT 29.97,
|
||
width INTEGER NOT NULL DEFAULT 1920,
|
||
height INTEGER NOT NULL DEFAULT 1080,
|
||
created_at TIMESTAMPTZ DEFAULT NOW(),
|
||
updated_at TIMESTAMPTZ DEFAULT NOW()
|
||
);
|
||
|
||
CREATE INDEX idx_sequences_project_id ON sequences(project_id);
|
||
|
||
-- Clips on a sequence timeline
|
||
CREATE TABLE sequence_clips (
|
||
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||
sequence_id UUID NOT NULL REFERENCES sequences ON DELETE CASCADE,
|
||
asset_id UUID NOT NULL REFERENCES assets ON DELETE CASCADE,
|
||
track INTEGER NOT NULL DEFAULT 0,
|
||
-- 0=V1, 1=V2, 100=A1, 101=A2
|
||
timeline_in_frames BIGINT NOT NULL,
|
||
timeline_out_frames BIGINT NOT NULL,
|
||
source_in_frames BIGINT NOT NULL DEFAULT 0,
|
||
source_out_frames BIGINT NOT NULL,
|
||
created_at TIMESTAMPTZ DEFAULT NOW(),
|
||
updated_at TIMESTAMPTZ DEFAULT NOW()
|
||
);
|
||
|
||
CREATE INDEX idx_sequence_clips_sequence_id ON sequence_clips(sequence_id);
|
||
```
|
||
|
||
### 1.6 API Routes
|
||
|
||
All new routes live in `services/mam-api/src/routes/sequences.js`.
|
||
|
||
| Method | Path | Description |
|
||
|--------|------|-------------|
|
||
| GET | `/api/v1/sequences?project_id=X` | List sequences for project |
|
||
| POST | `/api/v1/sequences` | Create sequence (`{ project_id, name, frame_rate, width, height }`) |
|
||
| GET | `/api/v1/sequences/:id` | Get sequence + all clips (joined with asset thumbnail/name/proxy/fps) |
|
||
| PUT | `/api/v1/sequences/:id` | Update sequence metadata |
|
||
| DELETE | `/api/v1/sequences/:id` | Delete sequence and its clips |
|
||
| PUT | `/api/v1/sequences/:id/clips` | Replace entire clip array (full sync) |
|
||
| POST | `/api/v1/sequences/:id/export/edl` | Generate CMX3600 EDL string, return as `text/plain` download |
|
||
|
||
**Save strategy:** The editor auto-saves (debounces 2s after any change). Ctrl+S triggers immediate save. The full clip array is sent on each save — simple and avoids fine-grained diff logic.
|
||
|
||
### 1.7 EDL Export
|
||
|
||
A new `generateEDL(sequence, clips)` function added to a shared utility (or inline in the export route) using the existing `secondsToTimecode` helper from `worker/src/edl/parser.js` (the logic is duplicated into the API since they're separate services — or promoted to a shared `edl-utils` module).
|
||
|
||
Output format: CMX3600 compatible with the existing `conform.js` worker.
|
||
|
||
```
|
||
TITLE: Sequence 1
|
||
|
||
001 clip_filename V C 00:00:00:00 00:00:05:00 00:00:00:00 00:00:05:00
|
||
002 other_clip V C 00:00:02:00 00:00:08:00 00:00:05:00 00:00:11:00
|
||
```
|
||
|
||
### 1.8 api.js Additions
|
||
|
||
```js
|
||
// Sequences
|
||
getSequences(projectId)
|
||
createSequence(projectId, data)
|
||
getSequence(sequenceId)
|
||
updateSequence(sequenceId, data)
|
||
deleteSequence(sequenceId)
|
||
syncSequenceClips(sequenceId, clips)
|
||
exportSequenceEDL(sequenceId) // triggers download
|
||
```
|
||
|
||
---
|
||
|
||
## 2. Growing File Workflow
|
||
|
||
### 2.1 Problem
|
||
|
||
During SDI capture, two fragmented MP4 streams are piped to S3 via multipart upload. Multipart uploads are invisible in S3 until `CompleteMultipartUpload` — so the proxy doesn't exist until recording stops. The UI has no way to preview an in-progress capture, and there's no way to rewind to review what was just captured.
|
||
|
||
For SRT/RTMP sources, there is no proxy at all until the BullMQ worker processes the file post-stop.
|
||
|
||
### 2.2 Solution: HLS Segmentation During Capture
|
||
|
||
Replace the pipe-to-S3 proxy step with **local HLS segment writing** during capture. After the recording stops, stitch the segments into a single MP4 and upload that to S3 as the proxy.
|
||
|
||
**Why HLS:**
|
||
- Growing playlists are the standard browser mechanism for live video
|
||
- Segments accumulate on disk — seeking back to the start of the capture (rewind) is natural
|
||
- `hls.js` provides a tiny CDN-loadable library for Chrome/Firefox
|
||
- FFmpeg's `hls` muxer is well-tested in production
|
||
|
||
**FFmpeg proxy args change (SDI — currently spawned as a second process):**
|
||
|
||
```bash
|
||
# Before (fragmented MP4 → pipe → S3):
|
||
ffmpeg [decklink input] \
|
||
-c:v libx264 -preset fast -b:v 10M -c:a aac -b:a 192k \
|
||
-movflags +frag_keyframe+empty_moov -f mp4 pipe:1
|
||
|
||
# After (HLS segments → local temp dir):
|
||
ffmpeg [decklink input] \
|
||
-c:v libx264 -preset fast -b:v 10M -c:a aac -b:a 192k \
|
||
-hls_time 2 \
|
||
-hls_list_size 0 \
|
||
-hls_flags append_list \
|
||
-hls_segment_filename '/tmp/wd-hls/<sessionId>/seg%05d.ts' \
|
||
/tmp/wd-hls/<sessionId>/index.m3u8
|
||
```
|
||
|
||
**Disk budget:** 2s segments at 10 Mbps ≈ 2.5 MB/segment. A 1-hour capture ≈ 9 GB temp disk. The capture host needs ≥ 10 GB free on the temp partition.
|
||
|
||
### 2.3 Capture Service Changes
|
||
|
||
**`capture-manager.js`:**
|
||
- New `HLS_SESSION_DIR` env var (default: `/tmp/wd-hls`)
|
||
- On `start()`: create `/tmp/wd-hls/<sessionId>/`, write HLS instead of piping to S3
|
||
- `proxyKey` is still generated for the final S3 path; the HLS dir is an intermediate
|
||
- `liveUrl` added to session state: `/capture/live/<sessionId>/index.m3u8`
|
||
- On `stop()`:
|
||
1. `SIGINT` the FFmpeg process (as now)
|
||
2. Wait for FFmpeg to flush the final segment and close the playlist
|
||
3. Run `ffmpeg -i /tmp/wd-hls/<sessionId>/index.m3u8 -c copy <tmp>.mp4` to stitch
|
||
4. Upload stitched MP4 to S3 as proxy (using existing `createUploadStream` or direct upload)
|
||
5. `rimraf(/tmp/wd-hls/<sessionId>/)` to clean up
|
||
- On startup: purge any `/tmp/wd-hls/` dirs older than 24h (crash recovery)
|
||
|
||
**New capture routes (`services/capture/src/routes/`):**
|
||
```
|
||
GET /capture/live/:sessionId/index.m3u8 → stream the HLS playlist file
|
||
GET /capture/live/:sessionId/:segment → stream a .ts segment file
|
||
```
|
||
Both routes check that the session is active (or was recently active) before serving.
|
||
|
||
**Updated `/capture/status` response:**
|
||
```json
|
||
{
|
||
"recording": true,
|
||
"sessionId": "...",
|
||
"liveUrl": "/capture/live/<sessionId>/index.m3u8",
|
||
...existing fields...
|
||
}
|
||
```
|
||
|
||
**nginx proxy:** Add location block to proxy `/capture/live/` through to the capture service (same pattern as existing `/capture/` pass-through).
|
||
|
||
### 2.4 SRT/RTMP Sources
|
||
|
||
Single FFmpeg process limitation: network streams can only be opened once. Use FFmpeg's multiple-output capability:
|
||
|
||
```bash
|
||
ffmpeg [srt/rtmp input] \
|
||
-c:v prores_ks -profile:v 3 -c:a pcm_s24le \
|
||
-movflags +frag_keyframe+empty_moov -f mov pipe:1 \ ← hires → S3 (unchanged)
|
||
-c:v libx264 -preset fast -b:v 10M -c:a aac \
|
||
-hls_time 2 -hls_list_size 0 -hls_flags append_list \
|
||
-hls_segment_filename '/tmp/wd-hls/<sessionId>/seg%05d.ts' \
|
||
/tmp/wd-hls/<sessionId>/index.m3u8 ← proxy → local HLS
|
||
```
|
||
|
||
The hires upload stream continues unchanged. The proxy no longer goes to S3 during capture — it goes to HLS segments, then stitched on stop.
|
||
|
||
### 2.5 Live Preview UI (`capture.html`)
|
||
|
||
When the status poll returns `recording: true` with a `liveUrl`:
|
||
|
||
1. Show a collapsible **Live Preview** panel below the capture controls
|
||
2. Load `hls.js` from CDN: `cdnjs.cloudflare.com/ajax/libs/hls.js/1.5.7/hls.min.js`
|
||
3. `new Hls()` → `hls.loadSource(status.liveUrl)` → `hls.attachMedia(videoEl)`
|
||
4. `video.play()` on `MANIFEST_PARSED` event — plays at the live edge by default
|
||
5. **"⏮ Rewind"** button: `video.currentTime = 0` — jumps to the start of the capture
|
||
6. Elapsed time counter ticking from `startedAt`
|
||
|
||
When recording stops: destroy the HLS instance, hide the preview panel. The asset appears in the library once the proxy upload and thumbnail job complete.
|
||
|
||
---
|
||
|
||
## 3. Feature Additions (Prioritized)
|
||
|
||
After Phase 1 (editor) and Phase 2 (growing file) are done, implement in this order:
|
||
|
||
### P1 — Improved Player (`player.html` rebuild)
|
||
Current `player.html` uses the old CSS variable naming convention (`--color-bg-tertiary`, etc.) and doesn't match the redesigned system. Rebuild it to match `index.html`'s design tokens and add:
|
||
- Custom transport bar with scrub slider (replace browser defaults)
|
||
- Timecode display `HH:MM:SS:FF` (using `fps` from asset metadata)
|
||
- Frame-step buttons (± 1 frame)
|
||
- J/K/L keyboard shortcuts
|
||
- Inline rename: click `display_name` to edit in place
|
||
- "Open in Editor" button linking to `editor.html?asset=<id>`
|
||
|
||
### P2 — Subclips
|
||
In `player.html`, after marking in/out points:
|
||
- "Create Subclip" button → `POST /api/v1/assets` with:
|
||
```json
|
||
{ "parent_asset_id": "...", "subclip_in_ms": 12000, "subclip_out_ms": 45000, ... }
|
||
```
|
||
- New columns on `assets`: `parent_asset_id UUID REFERENCES assets`, `subclip_in_ms BIGINT`, `subclip_out_ms BIGINT`
|
||
- Library shows subclip cards with a "✂" badge; clicking opens the player pre-seeked to `subclip_in_ms`
|
||
- Subclips use the same proxy S3 key as the parent; no extra transcoding needed
|
||
|
||
### P3 — Multi-select & Bulk Ops
|
||
In `index.html`:
|
||
- Shift-click or checkbox (appears on hover) to select multiple asset cards
|
||
- Floating action bar appears at bottom when ≥1 card selected: **Move to bin | Add tags | Delete**
|
||
- "Move to bin": slide panel with bin tree, moves selected assets via `PATCH /assets/:id { bin_id }`
|
||
- "Add tags": text input, appends tags to all selected assets
|
||
- Bulk delete: confirm modal, then soft-delete all
|
||
|
||
### P4 — Waveform Display in Editor
|
||
During proxy generation (`worker/src/workers/proxy.js`):
|
||
- After transcoding, run FFmpeg's `volumedetect` or `astats` filter to produce per-second peak arrays
|
||
- Alternatively: `ffmpeg -i proxy.mp4 -af astats=metadata=1:reset=1,ametadata=print:file=peaks.txt -f null -`
|
||
- Parse and store as `{ peaks: [0.2, 0.8, ...] }` JSON → upload to `waveforms/<assetId>.json` in S3
|
||
- New column on `assets`: `waveform_s3_key TEXT`
|
||
- Editor timeline: for audio track clips, fetch the waveform JSON and render an SVG polyline within the clip block
|
||
|
||
### P5 — Timecoded Comments
|
||
New table:
|
||
```sql
|
||
CREATE TABLE asset_comments (
|
||
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||
asset_id UUID NOT NULL REFERENCES assets ON DELETE CASCADE,
|
||
user_id UUID NOT NULL REFERENCES users,
|
||
timecode_seconds NUMERIC(10,3),
|
||
body TEXT NOT NULL,
|
||
created_at TIMESTAMPTZ DEFAULT NOW()
|
||
);
|
||
```
|
||
In `player.html` sidebar: "Comments" tab. Input field with "Post at [current TC]" button. Renders as a list of clickable entries that seek the video to that timecode.
|
||
|
||
### P6 — Smart Bins
|
||
Extend `bins` table:
|
||
```sql
|
||
ALTER TABLE bins ADD COLUMN is_smart BOOLEAN DEFAULT false;
|
||
ALTER TABLE bins ADD COLUMN smart_query JSONB;
|
||
```
|
||
Smart bin `smart_query` shape: `{ "tags": ["interview"], "media_type": "video", "created_after": "2026-01-01" }`.
|
||
When loading a smart bin's assets, run a dynamically built query against the `assets` table.
|
||
In the UI, smart bins show a ✦ icon in the bin tree and their contents cannot be manually modified.
|
||
|
||
### P7 — Metadata Templates
|
||
New table:
|
||
```sql
|
||
CREATE TABLE project_metadata_fields (
|
||
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
|
||
project_id UUID NOT NULL REFERENCES projects ON DELETE CASCADE,
|
||
field_key TEXT NOT NULL,
|
||
label TEXT NOT NULL,
|
||
field_type TEXT NOT NULL DEFAULT 'text', -- text, number, date, select
|
||
options JSONB, -- for select type
|
||
required BOOLEAN DEFAULT false,
|
||
sort_order INTEGER DEFAULT 0
|
||
);
|
||
```
|
||
New `metadata JSONB` column on `assets`. Player shows project-defined fields in the sidebar; values saved via `PATCH /assets/:id { metadata: {...} }`.
|
||
|
||
---
|
||
|
||
## Implementation Sequencing
|
||
|
||
### Phase 1 — Editor (estimated 3–4 dev sessions)
|
||
1. DB migration: `sequences` + `sequence_clips`
|
||
2. API: `sequences.js` route file (CRUD + clip sync + EDL export)
|
||
3. `api.js`: add sequence helper functions
|
||
4. `editor.html`: shell layout + CSS (4-panel, sidebar nav update)
|
||
5. Timeline engine: ruler, playhead, track rows, clip rendering
|
||
6. Select tool: click-select, drag-move, drag-edge trim
|
||
7. Razor tool: click-to-split
|
||
8. Source monitor: video + transport + in/out marking + Insert/Overwrite
|
||
9. Program monitor: virtual playback + timecode display
|
||
10. Library integration: "Open in Editor" card action + sidebar link
|
||
|
||
### Phase 2 — Growing File (estimated 2 dev sessions)
|
||
1. Capture service: HLS output instead of proxy pipe-to-S3
|
||
2. Capture service: new `/capture/live/:sessionId/` HTTP routes
|
||
3. Capture service: on-stop stitch + S3 upload, cleanup
|
||
4. nginx: add `/capture/live/` location block
|
||
5. `capture.html`: live preview panel with hls.js, rewind button
|
||
6. `api.js`: handle `liveUrl` in status response
|
||
|
||
### Phase 3 — Feature Additions (ongoing, in priority order)
|
||
P1 → P2 → P3 → P4 → P5 → P6 → P7
|
||
|
||
---
|
||
|
||
## Open Questions (for user review before implementation begins)
|
||
|
||
1. **Auto-save vs. explicit save:** The design calls for auto-save (debounced 2s). Do you want an explicit Ctrl+S only mode, or both (auto-save + Ctrl+S for immediate flush)?
|
||
|
||
2. **Multiple sequences per project:** The design allows multiple named sequences per project (like Premiere's Project panel). Or would you prefer one active sequence per project to keep things simpler?
|
||
|
||
3. **HLS temp disk:** Is there ≥ 10 GB spare disk available on the capture service host for HLS segments during recording?
|
||
|
||
4. **Frame rates in use:** What frame rates are you primarily working in? (23.976, 25, 29.97, 30, 59.94?) The EDL timecode generator needs to know.
|
||
|
||
5. **Program monitor fidelity:** For v1, is clip-by-clip virtual playback (brief gap at clip boundaries while the next video src loads) acceptable? Or do you need gapless/frame-accurate playback from day one?
|