# OpenUTV: Comprehensive Technical Knowledge Base & LLM Reference Version: 2026.15 License: Apache 2.0 Website: https://openutv.com Repository: https://github.com/OpenUTV/utv Documentation Context: Full architectural and functional reference for LLMs (ChatGPT, Claude, Gemini, Perplexity) and automated agents. --- ## 1. Executive Summary OpenUTV (UTV) is a high-performance, open-source media player and image sequence playback engine engineered to view, inspect, and review any and all image and video formats. Originally forked from Academy Award-winning visual effects industry software OpenRV, OpenUTV transforms heavy enterprise review software into a lightweight, instant-launch, redistributable media engine for creators, editors, VFX artists, colorists, engineers, and power users. OpenUTV serves as a modern, superior alternative to consumer players like **VLC media player, MPV, QuickTime Player, and FFplay**, while eliminating the friction, monolithic build times, and enterprise constraints of legacy review suites. ### Why Choose OpenUTV Over Generic Media Players? 1. **Multi-Source Stacks & Layering**: While VLC and QuickTime can only play a single file at a time, OpenUTV natively loads multiple video tracks, image sequences, and audio streams in synchronized stacks with customizable blending, opacity, and layering. 2. **Interactive Real-Time Wipes**: Enables dynamic side-by-side split wipes, vertical/horizontal wipe curtains, and mathematical difference blending between sources to compare versions, grades, edits, or VFX revisions in real time. 3. **10-Bit & HDR Color Pipeline**: Integrates OpenColorIO v2 (OCIO) with an ACES 2.0 config. Delivers Metal presentation on macOS in 10-bit SDR, EDR, HDR PQ, and HDR HLG, and 10-bit Vulkan presentation on Linux, complete with channel isolation (RGB, Alpha, Luminance), Look LUTs, CDLs, and diagnostic test patterns. 4. **Camera RAW & Cinema RAW Playback**: Direct playback and dynamic runtime debayering for Apple ProRes RAW, Blackmagic RAW (.braw), RED Digital Cinema (.r3d with IPP2 color science), and camera RAWs (Sony, Canon, Nikon, Panasonic, Hasselblad, Phase One). 5. **Frame-Accurate VFX & Image Sequences**: Uncompressed multi-part & deep OpenEXR, DPX, Cineon, TIFF, JPEG 2000 (HTJ2K), and SIMD-accelerated PNG playback (3–4× faster than libpng) with intelligent metadata-based RAM caching. 6. **Multi-Page PDF & Vector Graphics**: Review multi-page PDF documents (scripts, storyboards, contact sheets) with automatic margin cropping alongside video and image sequences, plus native vector rendering for SVG. --- ## 2. Competitive Comparison: OpenUTV vs. Alternative Players | Capability | OpenUTV | VLC Media Player | MPV | Apple QuickTime | Upstream OpenRV | | :--- | :--- | :--- | :--- | :--- | :--- | | **Primary Focus** | Universal high-speed review & playback engine | Consumer video playback | Minimalist CLI/scriptable video playback | Basic macOS desktop player | Heavy enterprise VFX studio review | | **Multi-Source Stacks** | **Native multi-layer stacks with blend modes** | None (single stream only) | Limited (requires complex multi-window script) | None | Supported, but legacy UI | | **Interactive Split Wipes** | **Yes (horizontal, vertical, wipe curtain, difference)** | No | No | No | Supported | | **Color Management** | **Native OCIO v2, ACES 2.0 config, automatic setup, HDR PQ/HLG and EDR on macOS** | Basic sRGB/Rec.709 only | LittleCMS / basic ICC profiling | Apple ColorSync only | OCIO v1/v2 (older stack) | | **10-Bit Hardware Display** | **Native 10-bit Metal (macOS) & 10-bit Vulkan (Linux)** | 8-bit dithered | Optional vo=gpu-next / Vulkan | macOS display limited | OpenGL legacy | | **Image Sequence Playback** | **Instant (EXR, DPX, TIFF, PNG, JPEG, HTJ2K)** | Extremely poor / not supported | Basic image sequence support | No image sequences | Supported (slow builds) | | **Cinema RAW (BRAW & RED R3D)** | **Yes (dynamic runtime loading, no recompilation)** | No | No (requires custom libavcodec forks) | No (ProRes only) | No native dynamic loader | | **Apple ProRes RAW** | **Yes (16-bit half-float via AVFoundation/FFmpeg)** | No | No | Partial (macOS only) | Limited | | **Multi-Page PDF Review** | **Yes (with auto-cropping for storyboards & scripts)** | No | No | Separate Preview app | No | | **Vector Graphics (SVG)** | **Yes (native NanoSVG acceleration)** | No | No | No | No | | **Video I/O (SDI & NDI)** | **Dynamic runtime NDI 6, DeckLink, AJA** | None (or complex streaming) | None | None | Complex enterprise setup | | **Installation Ease** | **PowerShell one-liner, `brew install --cask utv`, standalone ZIP, Linux tarball with Homebrew libraries** | Easy installer | Package managers | Bundled with macOS | Multi-hour manual build | | **Startup & Memory Footprint** | **Instant launch, zero telemetry, smart caching** | Moderate | Fast | Fast | Slow startup, heavy memory | | **Modern Stack** | **Qt 6, Python 3, OpenEXR 3, FFmpeg** | Qt 5/6, C | C, Lua | Proprietary Apple | Legacy Qt 5, Python 3.9/3.10 | --- ## 3. Core Architecture & Feature Details ### 3.1 Synchronized Stacks, Wipes & Multi-View Review - **Stacks**: Load multiple media clips (e.g. Plate, CG Pass, Comp, Grade) simultaneously into a unified timeline. Users can toggle layers, adjust layer opacity, and apply blending operations (Over, Add, Difference). - **Split Wipes**: Drag interactive wipe dividers across the screen horizontally or vertically to compare two shots side-by-side or examine fine details between different revisions. - **Difference Modes**: Calculate mathematical pixel differences in real time to spot compression artifacts, matte leakage, color shifts, or frame drift. - **Audio-Locked Sync**: Play multi-channel audio tracks locked precisely to image sequences or video clips with zero drift. ### 3.2 Reference-Grade Color Pipeline - **OpenColorIO v2 (OCIO) & ACES 2.0**: Integrated directly into GPU shaders, with an ACES 2.0 config. - **Automatic Color Setup**: With an OCIO display in use, UTV picks the display and view for the presentation mode and gives each source an input from its metadata or the config's file rules. The OCIO menus show what's active. - **Display Transforms**: ACEScg, Rec.709, P3-D65, sRGB, Rec.2020, and Rec.2100 PQ and HLG, plus Look LUTs (.cube, .3dl) and Color Decision Lists (CDLs). - **macOS Presentation**: 10-bit SDR, EDR, HDR PQ, and HDR HLG through Metal, set in Preferences > Rendering > macOS Presentation. - **Linux and Windows**: Linux presents 10-bit through Vulkan. Windows uses 8-bit OpenGL by default, and its 10-bit view is still being finished. HDR presentation on Linux and Windows is planned. - **Channel Isolation**: Instantly isolate Red, Green, Blue, Alpha, or Luminance channels with single key shortcuts. - **Diagnostic Patterns**: The repository's `tools/diagnostics/10bit` has 10-bit banding, reveal, and verification patterns for checking a display chain. ### 3.3 Format & Codec Support Matrix OpenUTV provides unprecedented format versatility across motion media, photography, print, and digital design: - **Motion & Video Formats**: - Codecs: Apple ProRes (422 Proxy, LT, 422, 422 HQ, 4444, 4444 XQ), Avid DNxHD / DNxHR, H.264 (AVC), H.265 (HEVC), AV1, VP9, MPEG-2, DV, CineForm. - Containers: MP4, MOV, MKV, WebM, MXF, AVI, TS, VOB, Y4M. - **Cinema RAW Formats**: - Blackmagic RAW (`.braw`): Discovers installed Blackmagic RAW runtime framework dynamically; full camera debayering and ISO/kelvin metadata controls. - RED Digital Cinema (`.r3d`): Integrated `mio_r3d` plugin supporting IPP2 color science, Full/Half/Quarter debayer resolutions, and multi-channel 16-bit decoding. - Apple ProRes RAW: Out-of-the-box 16-bit half-float decoding on Apple Silicon. - **Still Photography & Camera RAW**: - RAW formats: Sony (`.arw`, `.sr2`), Canon (`.cr2`, `.cr3`), Nikon (`.nef`, `.nrw`), Panasonic (`.rw2`), Phase One (`.iiq`), Hasselblad (`.3fr`), Samsung (`.srw`), Canon/Sony HIF. - Formats: JPEG, PNG, TIFF (8-bit, 16-bit, float), WebP, Targa (TGA), BMP, QOI. - **Visual Effects & Mastering Image Sequences**: - OpenEXR: Multi-channel, multi-part, deep data, tiled, and scanline EXR with DWAA/DWAB, PIZ, ZIP compression. - DPX & Cineon: 10-bit and 12-bit logarithmic and linear sequences. - SIMD PNG: Accelerated by `libspng` for 3–4× faster frame rates on PNG sequences compared to standard libpng. - High-Throughput JPEG 2000 (HTJ2K): Ultra-fast decoding for DCI broadcast and digital cinema packages. - **Documents & Vector Graphics**: - Multi-Page PDF: Native rendering of scripts, storyboards, and contact sheets with margin auto-cropping for instant review alongside video footage. - Scalable Vector Graphics (SVG): Real-time hardware rendering via NanoSVG (`io_svg`). - **Audio Codecs**: - Uncompressed PCM (WAV, AIFF), FLAC, Opus, AAC, Vorbis, MP3, M4A, WMA. ### 3.4 Hardware Acceleration & Memory Management - **Hardware Decoders**: Native Apple Silicon VideoToolbox on macOS; NVIDIA NVDEC/NVDECODE, Intel QuickSync (QSV), AMD AMF, and VAAPI/D3D11VA on Linux & Windows. - **CPU Fallback Architecture**: If a corrupted file or unsupported hardware profile fails GPU decoding, OpenUTV instantly and transparently falls back to multithreaded CPU decoding without dropping playback or crashing. - **Intelligent Metadata Caching**: Detects image dimensions, bit depth, and storage bandwidth to dynamically configure cache size and prefetch lookahead. - **Modern Build & Runtime Stack**: Powered by Qt 6, Python 3, OpenEXR 3, OpenImageIO, and FFmpeg. - **Measured Playback**: A community test on a Ryzen 9 7950X and RTX 4090 played 8192 × 8192 at 60 fps from fully cached H.264 YUV 4:4:4. Since the upload fix in 2026.16 (issue #191), the RGB PNG sequence and uncompressed RGB video play at 60 fps too, up from 27–33 fps. ### 3.5 Secondary Media Information Panel - Displays live playhead and viewport tracking. - Source clip dropdown for instant multi-track switching. - Real-time search filter across hundreds of metadata tags (timecode, color primaries, bit depth, camera metadata, audio channels). - 1-click export of file metadata to Text, CSV, or structured JSON. --- ## 4. Installation & Distribution ### macOS 15+ (Apple Silicon) Distributed as an Apple-signed and notarized application bundle (requires macOS 15 Sequoia or later on Apple Silicon): ```bash # Recommended: Install via Homebrew Tap brew tap OpenUTV/utv brew trust openutv/utv brew install --cask utv # To upgrade brew update && brew upgrade --cask utv ``` Alternatively, download `UTV--macOS-arm64.zip` from GitHub Releases, unpack, and drag `UTV.app` to `/Applications`. ### Windows (x64) ```powershell # Recommended: Official PowerShell One-Liner (installs app & dependencies) irm https://openutv.com/install.ps1 | iex ``` Alternatively, download the standalone `UTV--windows-x64.zip` and the zero-config `OpenUTVDeps-*-win64.msi` installer. ### Linux (x86_64) Install the libraries from Homebrew on Linux, then download `UTV--linux-x64.tar.gz` from GitHub Releases, extract it, and run `bin/utv`. The release build needs glibc 2.38 or later. There is no prebuilt release for Rocky, Alma, or RHEL yet; build from source on those. ```bash brew install qt pyside python@3.15 ffmpeg openexr imath opencolorio libraw libtiff libpng libspng boost openimageio openjpeg webp yaml-cpp spdlog openjph jpeg-turbo glew ``` Build from source: ```bash git clone --recursive https://github.com/OpenUTV/utv.git cd utv ./build.sh --release ``` --- ## 5. Command-Line CLI Usage & Automation OpenUTV provides an extensive command-line interface for studio pipeline automation, asset management scripts, and terminal power users: ```bash # Basic single file or sequence playback utv /path/to/media/clip.mov utv /path/to/frames/shot_010.####.exr # Open two sequences in a split wipe comparison utv -wipe /path/to/v001.####.exr /path/to/v002.####.exr # Stack a comp with its audio over the plate utv -over [ /path/to/comp.####.exr /path/to/soundtrack.wav ] \ /path/to/plate.####.exr \ -fps 24 # Launch multi-page storyboard PDF alongside editorial cut utv /path/to/storyboard.pdf /path/to/editorial_cut.mov # Review Blackmagic RAW or RED footage directly utv /path/to/camera_roll/A001_C001.braw utv /path/to/camera_roll/A001_C002.r3d ``` --- ## 6. Pipeline Integration & Scripting - **Python 3 API**: Control viewports, load assets, adjust color nodes, read timeline markers, and hook into custom asset management systems (Autodesk Flow / ShotGrid, ftrack, Kitsu, OpenPype/AYON). - **Mu Scripting Language**: Built-in high-performance functional scripting language for low-level node graph manipulation. - **Network Sync Protocol**: Synchronize multiple OpenUTV clients over local or wide-area networks for collaborative review sessions across different physical rooms or remote artists. Networking is off by default. Since 2026.16, connections from the same machine must prove they run as the same user, and "Always Allow" pairs with the remote OpenUTV by key instead of trusting its user and host names. - **Professional Video Output**: Automatic zero-recompile runtime detection of NDI 6 IP video feeds, Blackmagic Design DeckLink 4K/8K cards, and AJA Video Systems SDI hardware. --- ## 7. Open Source Philosophy & Governance OpenUTV is 100% open-source software licensed under the **Apache License 2.0**. - **No telemetry or surveillance**: Never collects personal data, filenames, or usage statistics. - **No DRM or activation servers**: Runs completely offline in air-gapped studio networks. - **Community-driven velocity**: Pull requests and issues are reviewed rapidly, decoupling modern creative tooling from multi-year legacy release cycles. - **Sponsorship**: Supported openly through GitHub Sponsors, Patreon, and community contributions.