Proxy Editing¶

A proxy is a lower-resolution / lower-bitrate copy of a high-resolution source file. Using proxies while editing 4K/8K or high-bitrate footage can significantly improve timeline and node-editor playback performance. Oak automatically falls back to the original high-quality source when exporting.

Proxy States¶

Each footage item can be in one of the following proxy states:

State	Meaning
missing	The proxy file does not exist and is not being generated.
generating	A proxy task is running; a `.working.mp4` temporary file exists.
ready	The proxy file is ready for use.
failed	Generation failed.

Creating Proxies¶

Oak provides a dedicated Proxy dialog for managing proxies. It can be opened from several entry points:

Tools > Proxy Settings....
Project panel: select one or more footage items → right-click → Proxy → Proxy Settings....
Timeline: select clip(s) → right-click → Proxy → Proxy Settings....

The dialog shows the global proxy settings, lets you define custom settings for the selected footage, and provides Generate and Delete buttons.

The per-item context actions (Generate Proxy / Use Proxy / Reveal Proxy / Delete Proxy) are still available in the project panel and timeline context menus for quick operations.

Right-click selected footage in the project panel to see Generate Proxy, Use Proxy, etc. The same menu is available on timeline clips, and you can batch-process multiple selected items.¶

Proxy Settings¶

Proxy settings are global by default, located in the Proxy Settings group under Edit > Preferences > Disk. Each footage item can override them with custom settings, configured in the Proxy dialog and persisted in the project file.

Adjustable parameters:

Parameter	Description
Proxy Width	Default 1280.
Proxy Height	Default 720.
CRF	H.264 quality factor; default 23.
Preset	Encoding speed preset; default `veryfast`, range `ultrafast` to `veryslow`.
Include audio in proxies	Default on. When enabled, the source audio streams are included in the proxy (encoded as AAC).
ffmpeg Executable	Path to the `ffmpeg` binary. Leave empty for auto-detection.

When no path is configured, ffmpeg is auto-detected in the following order:

The configured path, if set and usable.
The system PATH.
Common install locations, e.g. /opt/homebrew/bin/ffmpeg and /usr/local/bin/ffmpeg on macOS, the application directory, and /usr/bin.

Proxy File Location¶

Proxy files are stored under the project’s disk-cache directory:

<project_cache_path>/proxy/<unique_id>-<stream>.<W>x<H>.v<version>.a<0|1>.<ext>

The a marker records whether audio is included: a1 when audio inclusion was enabled, a0 otherwise.

While generating, the temporary file is named:

<proxy_filename>.working.mp4

Proxy Generation Process¶

Oak runs ffmpeg (see auto-detection above) to transcode.
The requested video stream is mapped first, so it becomes stream 0 in the proxy.
When audio inclusion is enabled, all source audio streams are mapped after the video stream and encoded as AAC 128 kbps; otherwise audio is dropped (-an).
Video encoding uses libx264, -pix_fmt yuv420p, and -movflags +faststart.
Background tasks appear in the Task Manager; the state changes to ready when finished.

Enabling and Disabling Proxies¶

Use Proxy: enables the proxy for that footage item during preview and node editing.
Right-click again to disable it and revert to the original source.
Proxy state is saved in the .ove project file.

Behavior on Export¶

Preview / offline rendering (RenderMode::kOffline) uses the proxy if it is available, decoding audio from the proxy when present.
Export (RenderMode::kOnline) always uses the original high-quality source and never the proxy.
You do not need to disable proxies before exporting.

Limitations¶

Proxies are only used for preview / offline rendering; export always uses the original high-quality source.

Proxy Editing — Oak Video Editor Manual