170 lines
13 KiB
Markdown
170 lines
13 KiB
Markdown
# Monitor view options
|
||
|
||
The View menu and each monitor's wrench menu set how the Source and Program monitors show their
|
||
picture. It is all UI state (`MonitorView` in `crates/ui-egui/src/state.rs`, serde): agents read
|
||
it with `ui.inspect` (`ui.program`, `ui.source`) and set it with `ui.set {"program": {…}}`, or run
|
||
the `view.*` UI commands. Commands act on `params.monitor` (`"program"` / `"source"`), else on the
|
||
focused monitor (Program by default). Code: `crates/ui-egui/src/panels/monitor_view.rs`.
|
||
|
||
| Command | Menu | Effect |
|
||
|---|---|---|
|
||
| `view.playbackRes.<full\|half\|quarter\|eighth\|sixteenth>` | View ▸ Playback Resolution | render scale while playing |
|
||
| `view.pausedRes.<…>` | View ▸ Paused Resolution | render scale while stopped (default Full) |
|
||
| `view.highQualityPlayback` | View ▸ High Quality Playback | play at the paused resolution when it is higher |
|
||
| `view.display.<composite\|alpha\|red\|green\|blue>` | View ▸ Display Mode | composite, or one channel as greyscale (colour channels premultiplied) |
|
||
| `view.display.multicam` | Display Mode ▸ Multi-Camera | the Program's multi-camera view (`multicam.toggleView`) |
|
||
| `view.display.audioWaveform`, `view.display.videoAndWaveform` | Display Mode ▸ Audio Waveform / Video and Audio Waveform Split | Source Monitor: the clip's waveform (click to move the source playhead); audio-only clips always show it |
|
||
| `view.display.comparison` | Display Mode ▸ Comparison View | Program: the reference frame (left) beside the current frame; the reference starts at the playhead and is stepped or reset with the buttons under it, or `view.compare.setReference {time\|seconds}` |
|
||
| `view.magnification.<fit\|10\|25\|50\|75\|100\|150\|200\|400\|800\|1600>` | View ▸ Magnification and the zoom dropdown | 100% = one frame pixel per screen pixel. The mouse wheel (or a pinch) over a monitor zooms about the pointer, from Fit too, within 10%–1600%; drag with the middle mouse button, or with the Hand tool, to pan; Fit resets both. Each monitor keeps its own zoom and pan |
|
||
| `view.showRulers`, `view.showGuides`, `view.lockGuides`, `view.clearGuides` | View | toggles take `{"enabled": bool}` |
|
||
| `view.addGuide` | View ▸ Add Guide… | dialog, or `{"orientation": "vertical\|horizontal", "position": px}` |
|
||
| `view.snapInProgramMonitor` | View ▸ Snap in Program Monitor | graphic moves snap to the frame edges / centre and the guides (6 pt) |
|
||
| `view.safeMargins` | Guide Templates ▸ Safe Margins | action- and title-safe boxes |
|
||
| `view.guideTemplates.save`, `.manage`, `.apply`, `.delete` | Guide Templates ▸ Save Guides as Template… / Manage Guides… | templates are stored in the user preferences (`guides.templates`) |
|
||
|
||
Guides are in frame pixels. Drag out of the top ruler for a horizontal guide or the left ruler for
|
||
a vertical one; drag a guide to move it (unless locked) and drop it outside the picture to remove it.
|
||
|
||
Automation ids: `<monitor>.zoom`, `<monitor>.zoom.<level>`, `<monitor>.settings.<command suffix>`
|
||
(wrench menu items, e.g. `program.settings.display.alpha`), `<monitor>.ruler.top|left`,
|
||
`<monitor>.guide.<n>`, `program.compare.reference|prev|next|set`, `source.waveform`, and in the
|
||
dialogs `guides.add.vertical|horizontal|position|ok|cancel`, `guides.save.name|ok|cancel`,
|
||
`guides.manage.row.<n>|apply|delete|close`.
|
||
|
||
## Source playback
|
||
|
||
Video files, audio files, generated media and media subclips play in the Source monitor with its
|
||
Play/Pause button or Space while Source has focus. The Source clock and playhead are independent
|
||
of the active sequence; auditioning does not create timeline clips or change the project. Starting
|
||
Source stops Program playback, and starting Program stops Source, so only one monitor owns audio.
|
||
Scrubbing while playing seeks the Source clock and restarts its audio at that position. Replacing
|
||
the open source stops playback. Playback stops at the last frame, and Play there starts again.
|
||
Play auditions the full source span by default. Play In to Out and Play to Out
|
||
address the marked Source range when Source has focus. The Source wrench menu can loop the
|
||
marked range; Program keeps its separate loop setting.
|
||
|
||
Normal forward playback has sound. With Source focused, L plays forward and J backward; pressing
|
||
the same key again doubles the speed up to 8×, K stops, Shuttle Slow Right/Left play at ¼ speed,
|
||
and the left/right frame-step keys step the Source playhead. As in Program, shuttle speeds other
|
||
than normal forward play without sound, and backward playback stops on the first frame. Source
|
||
sequences are not yet supported and report an explanatory error. A failed audio device leaves
|
||
the picture advancing with a status message; a decoding error stops Source.
|
||
|
||
Commands: `source.playback.play`, `source.playback.stop`, `source.playback.toggle` (no parameters),
|
||
available through the UI command registry, CLI bridge and MCP. `playback.toggle`,
|
||
`playback.forward`, `playback.reverse`, `playback.slowForward` and `playback.slowReverse` also
|
||
accept `monitor: "source"|"program"` to override focus. `ui.inspect.sourcePlayback` reports playing,
|
||
audioClock and playhead. Test: `cargo test --release -p filmcraft-ui-egui --test source_playback_ui`.
|
||
|
||
## Drag a marked Source range to the timeline
|
||
|
||
An unmarked Source clip shows In at its beginning and Out on its last frame. These are implicit
|
||
limits: opening a clip does not write marks or dirty the project. Set In/Out with I/O or the
|
||
transport buttons; the saved marks are reused when reopening that clip. Out includes its frame.
|
||
|
||
Drag the **Video only**, **Audio only**, or **Video + audio** icons between Fit and playback
|
||
resolution to an open
|
||
sequence. Drop video on a video track and audio on an audio track. Both uses the dropped track
|
||
and its corresponding track of the other kind, creating linked clips in one undoable edit.
|
||
Unavailable stream choices are disabled. Dragging the video picture also brings its available
|
||
streams; a vertical drag from an audio waveform brings sound, while a horizontal drag scrubs.
|
||
The drag captures the selected range at its start. Source playback pauses when lifting a clip.
|
||
A locked or unavailable destination reports an error without partially placing the pair.
|
||
|
||
Automation ids: `source.drag.video`, `source.drag.audio`, `source.drag.both`, `source.picture`,
|
||
and `source.waveform`. Placement dispatches `timeline.place` with `sourceIn`, `duration`, `video`
|
||
and `audio`; the stream flags default to true for existing callers. Engine tests cover range
|
||
bounds, stream choices, linked placement, invalid parameters and undo/redo. UI tests exercise
|
||
actual drags: `cargo test --release -p filmcraft-ui-egui --test source_drag_ui`.
|
||
|
||
Ctrl+Shift+X (Cmd+Shift+X on macOS) clears In/Out on the focused Source clip, including split
|
||
points, and restores the implicit full span. It is undoable and leaves Program marks unchanged.
|
||
The command `markers.clearInOut` accepts `target: "source"|"program"`; omitting it addresses Program.
|
||
Source drag icons use the Windows hand cursor because its native Grab mapping is crossed arrows.
|
||
|
||
Source range braces use the playhead's theme color and the gray selection band is translucent,
|
||
so the ruler ticks remain visible. This shared egui implementation applies to Windows, macOS
|
||
and Linux. The clear shortcut uses the primary modifier: Ctrl on Windows/Linux, Cmd on macOS;
|
||
I/O, Space and the three drag gestures are common to all three platforms. Runtime verification
|
||
for this contribution was performed on Windows; macOS/Linux have not been run locally.
|
||
|
||
## Adjust Source marks on the ruler
|
||
|
||
Drag either In/Out handle to trim the selected span, or drag the interior gray band to move
|
||
both marks while keeping the duration. Handles show an original red bracket and arrows on
|
||
hover. Edits snap to source frames, stay within the clip and retain at least one frame.
|
||
A gesture previews without editing the project and commits one undoable `project.setMarks`
|
||
command on release. Escape cancels; opening another source or a concurrent project edit
|
||
also cancels the draft. Subclip handles are currently disabled.
|
||
|
||
Automation ids are `source.range.in`, `source.range.out`, `source.range.body` and
|
||
`source.settings.loop`. Clicking the band's interior still scrubs.
|
||
|
||
Source-focused Go to In/Out, clear individual/both marks, clip-marker commands and
|
||
previous/next marker address the open Source clip. Shift+Left/Right step multiple Source
|
||
frames using the preference. UI callers can override focus with `monitor: "source"|"program"`;
|
||
engine marker/navigation commands accept `target: "source"|"program"` and default to Program.
|
||
Source marker edits leave sequence markers and the Program playhead unchanged.
|
||
|
||
Coverage: engine `source_monitor::tests` validates frame bounds and hostile inputs; UI
|
||
`source_drag_ui` covers release, cancellation, range movement and command routing;
|
||
`source_playback_ui` covers marked-range stopping, looping and the last-frame boundary.
|
||
|
||
## Program range handles
|
||
|
||
Program uses the same In/Out hover cues, frame-snapped trimming, duration-preserving range
|
||
movement and one-edit undo behavior. It targets the active sequence through `project.setMarks`
|
||
and leaves an independently opened Source clip's marks and playhead unchanged. Program shows only explicitly set marks; clearing them hides the corresponding handles.
|
||
Range movement requires both Program marks. Empty sequences disable the handles.
|
||
Changing the active sequence cancels an unfinished draft. Automation ids: `program.range.in`,
|
||
`program.range.out` and `program.range.body`. Both monitors share the original brace artwork,
|
||
playhead-blue color and translucent gray band. Runtime review remains Windows-only.
|
||
|
||
The playhead has drag priority above the range band and trim handles, including a full-span
|
||
selection. Drag it to scrub; the unoccupied upper ruler can also scrub. Drag the gray band away
|
||
from the playhead to translate the marked range.
|
||
|
||
## Zoom the time ruler
|
||
|
||
Under each monitor's time ruler is a zoom scroll bar like the Timeline's. Its thumb is the part of
|
||
the clip or sequence the ruler shows: drag a handle at either end to zoom in or out, drag the
|
||
middle to scroll, or press beside the thumb to move it there. A thumb filling the bar shows the
|
||
whole duration; the ruler zooms in as far as five frames. The playhead, markers, In/Out and ticks
|
||
follow the part shown, and clicking or scrubbing the ruler sets a time within it; what lies
|
||
outside it is not drawn. While the monitor plays, a zoomed ruler follows the playhead as the
|
||
Timeline does (Settings ▸ Timeline ▸ Timeline Playback Auto-Scrolling): it pages when the playhead
|
||
runs off the right edge or jumps before the left one, or keeps the playhead in the middle with
|
||
smooth scrolling, and keeps its width; scrubbing and clicking never move it. Each monitor keeps its own range in its view state (`time_zoom`: start
|
||
and end as fractions of the duration, `null` for all of it). Automation ids: `<monitor>.zoomBar`
|
||
(the thumb) and `<monitor>.zoomBar.track`.
|
||
|
||
## Export Frame
|
||
|
||
The camera button in either monitor opens Export Frame. Drag its white header to move the dialog.
|
||
The suggested name is the source filename without its extension, or the sequence name, without an added `.Still` suffix. Choose a name, format and depth,
|
||
use Browse to choose the destination folder (or edit Path), and click OK. Existing files require
|
||
an explicit Replace confirmation. Cancel, the header close button, Escape, and clicking outside
|
||
the dialog (including the top menus or mode tabs) dismiss it without writing anything.
|
||
The dialog's own dropdowns and Browse button keep it open. The white
|
||
header and dark body use original generic controls. Source details and frame time appear below
|
||
the settings. Frame time uses the same hours/minutes/seconds/frames timecode as its monitor,
|
||
including the Program sequence's drop-frame setting, and stays captured while the dialog is open.
|
||
The last successful folder is reused during the current app session.
|
||
|
||
PNG and TIFF support 8 or 16 bits per channel. The 16-bit path quantizes directly from the
|
||
float image, preserving precision beyond 8 bits. JPEG (quality 95) and BMP support 8-bit output;
|
||
choosing either resets Depth to 8 Bit and disables 16 Bit. The command rejects unsupported
|
||
format/depth combinations. In the browser the still is offered as a download. Import into project
|
||
adds the saved still as one undoable edit. Failed writes retain the settings and report an error.
|
||
|
||
The monitor, item and frame time are captured when the settings open. Export uses the original
|
||
full-resolution media, even with proxies or reduced preview resolution enabled. Source exports
|
||
the source picture at its media playhead; Program exports the sequence composite, effects and
|
||
captions at its timeline playhead. Audio-only Source clips have no picture to export.
|
||
|
||
The shared `file.exportFrame` command accepts `target: "source" | "program"` (Program by default),
|
||
`format: "png" | "jpeg" | "tiff" | "bmp"`, `depth: 8 | 16` (default 8),
|
||
optional `item` for Source or `sequence` for Program, and an exact integer `time` in ticks.
|
||
Supplying `path` executes directly; invoking it through the UI without a path opens settings,
|
||
routed to the focused monitor unless an explicit monitor/target is provided.
|