================================================================================
 mh_PLAYer v2.12.2
 High-Performance CGI/VFX Image Sequence & Video Player
 Martin P. Heigan - anti-matter-3d.com/mhplayer
 Copyright (C) 2026 Martin P. Heigan. All Rights Reserved.
================================================================================

CONTENTS OF THIS ARCHIVE
-------------------------
  mh_PLAYer_Win_x64_v2_12_2.exe      Main application (signed executable)
  ffmpeg\                              Bundled FFmpeg for video decode and export
  _internal\                           Application runtime files
  plugins\                             Six bundled Studio Pro plugins,
                                         plus example_plugin.py
  mh_PLAYer_v2_12_User_Manual.pdf     User manual (open in any PDF viewer)
  mh_PLAYer_v2_12_Quick_Start.pdf     Quick start guide (Help -> Quick Start...)
  mh_PLAYer_v2_12_CLI_Cheatsheet.pdf  CLI cheat sheet (Help -> CLI Cheat Sheet...)
  Nuke_Integration\                    Nuke flipbook integration:
                                         mh_player_nuke.py, mh_player_nuke_Quickstart.pdf
  License_Agreement.pdf                End User License Agreement
  README.txt                           This file


QUICK START
-----------
1. Extract this ZIP to a folder of your choice.
2. Double-click mh_PLAYer_Win_x64_v2_12_2.exe to launch.
   No installer or admin rights required.
3. Drop an EXR frame, image file, or video onto the window to open it.
4. Press Space to play. Use J / K / L for shuttle control.
5. To unlock the licensed features, use Help -> Install License... and
   select your signed license.dat file.


INSTALL OPTIONS
---------------
This ZIP is the portable build -- no installer or admin rights required;
just extract and run. A signed Windows installer
(mh_PLAYer_Win_x64_v2_12_2_Setup.exe) is also available on the download
page: it installs per-user (no admin / UAC prompt), and on its "Select
Additional Tasks" page you can tick a Start Menu shortcut, a Desktop
shortcut, and adding mh_PLAYer to your PATH (all ticked by default).


DESKTOP & START MENU SHORTCUTS (portable ZIP)
----------------------------------------------
The portable ZIP does not use an installer. After extracting, use
Help -> Manage Shortcuts... to create Desktop and Start Menu shortcuts
that always point to the correct exe location. Works on all Windows
configurations including OneDrive-redirected user profiles (Windows 11).
If you move the folder later, use Manage Shortcuts... -> Update Shortcuts
to refresh the paths. (The Windows installer creates these for you.)


CLI PATH SETUP
--------------
Use Help -> CLI PATH Setup... to add the mh_PLAYer directory to your
user PATH environment variable (no admin rights or UAC prompt required).

  mh_player --check beauty.####.exr
  mh_player --convert beauty.####.exr out.mp4


CHECK FOR LATEST VERSION
------------------------
Use Help -> Check for Latest Version... to compare your installed version
against the latest mh_PLAYer release on GitHub. If a newer version is
available, a direct link to the download page is offered. This is a manual
check only -- mh_PLAYer never contacts the network on its own or at startup.


EDL / MULTI-CLIP TIMELINE  (Studio Pro)
----------------------------------------
Assemble multiple sequences and clips into a single ordered cut and review
it back-to-back.

  1. EDL -> New EDL, or build one from the Playlist with
     Playlist -> Send Playlist to Timeline (EDL)...
  2. EDL -> EDL Editor... opens a non-modal editor: drag clips to reorder,
     drag a clip edge to trim, and watch the live playhead during playback.
  3. EDL -> Activate EDL Playback runs the clips in order;
     Loop EDL Playback loops the cut.
  4. EDL -> Import/Export CMX3600 .edl... round-trips with Premiere, Avid,
     Resolve, and Final Cut (drop-frame-aware at 29.97 / 59.94).

Headless render of a timeline:
  mh_player --convert cut.mhedl review.mp4
  mh_player --convert cut.mhedl review.mov --display aces --burnin --codec prores


SYNCED REMOTE REVIEW  (Studio Pro)
-----------------------------------
Keep multiple mh_PLAYer instances on the same LAN locked to the same frame,
at full quality.

  - The host starts a Sync session; followers on the LAN see it appear
    automatically and join with one click (or enter the host address).
  - The host drives transport; playback stays frame-accurate across all
    participants, with automatic reconnect if a connection drops.

This is separate from the free browser Remote Review below, which needs no
second mh_PLAYer and works on a tablet or phone.


PLUGINS  (Studio Pro)
---------------------
Six plugins now ship inside the plugins\ folder -- no separate download.
They appear in the Plugins menu and require a Studio Pro license to run:

  Studio Watermark  Stamp a logo or title PNG onto a folder of rendered
                    frames. Opacity, scale, 9-point position or tiled, with
                    a live preview. Originals are untouched.
  Field Recorder    Capture a live HDMI / USB device to disk -- H.264
                    (MP4 / MOV) or ProRes 422, optional audio, preview
                    mirror. Uses the bundled FFmpeg.
  Contact Sheet     Labelled thumbnail grid from a folder of frames, or scan
                    a video for cuts to get one thumbnail per shot. Outputs
                    PNG plus an optional multi-page PDF.
  Colour Palette    Dominant colours from an image, folder, or every shot in
                    a video, as labelled swatches with hex, RGB and coverage.
                    Exports TXT / JSON / CSS.
  Colour Theme      Movie-barcode image of a whole shot, sequence or feature
                    -- one stripe per sampled frame, in AVERAGE (flat) or
                    SQUEEZE (keeps vertical structure) style. Outputs PNG.
  Test Patterns     SMPTE RP 219, SMPTE split-field, EBU 100% / 75% bars,
                    grey ramp and staircase. Any resolution, PNG / TIFF /
                    JPEG including 16-bit TIFF.

The plugins\ folder is user-writable: drop in your own .py file, or replace
a bundled plugin with a newer copy from anti-matter-3d.com/mhplayer/,
without touching the signed executable. Plugins load on startup and drive
the player through the mh_player_api module -- see example_plugin.py in the
same folder, and Appendix B of the user manual for the full API reference.


PLAYLIST  (license)
-------------------
Queue multiple sequences and clips for sequential review.
  - Drag-to-reorder and per-shot In/Out trim (trim badges shown in the list).
  - Import/Export standard M3U / M3U8 playlists (per-clip trim preserved).
  - Send Playlist to Timeline (EDL) to start a multi-clip cut (Studio Pro).


MULTI-VIEW COMPARE
------------------
Free feature -- no license required.

A dailies-style side-by-side window for comparing up to 9 images at once.
Open via View -> Multi-View Compare... or the 2x2 grid icon in the row-2
icon toolbar.

  1. Add Images... loads stills from disk (EXR, PNG, TIFF, JPG, DPX,
     Cineon, HDR, BMP, WebP).
  2. Grab Current Frame captures the player canvas exactly as displayed
     (EV, gamma, display mode and channel isolation baked in) -- ideal for
     comparing render versions.
  3. Select 1-9 thumbnails in the filmstrip to fill the grid; the layout
     is chosen automatically (1x1, 1x2, 1x3, 2x2, 2x3, 3x3).

Each pane has its own wheel-zoom and drag-pan. Sync Zoom & Pan mirrors
inspection across every pane. Fit All and 1:1 All reset all panes at once.

Window keys:  Left/Right walk the filmstrip, F fit all, 1 = 1:1 all,
Esc closes. The window keeps its images for the session.


ASPECT RATIO CORRECTION
-----------------------
Select an aspect ratio preset from the AR: combo in the transport bar
or in the DISPLAY section of the sidebar. 13 presets are available:
Pixel (default), 1:1, 4:3, 16:9, 1.37 Academy, 1.43 IMAX, 1.85 Flat,
2:1 Univisium, 2.39 Scope, 2K Flat, 2K Scope, 4K Flat, 4K Scope.

Aspect ratio is a per-source setting: it resets to Pixel when you open a
new file, and is saved with the workspace. In CLI convert mode:
  mh_player --convert --ar 2.39 beauty.####.exr review.mp4


STEREO / ANAGLYPH
-----------------
Free feature -- no license required.

Two-sequence workflow:
  1. Open the left eye sequence via File -> Open Sequence.
  2. In the sidebar STEREO / ANAGLYPH section, click Load R Eye...
  3. Select the right eye sequence. Check Enable Anaglyph.

Single stereo EXR workflow:
  1. Click Load Stereo EXR... in the STEREO / ANAGLYPH sidebar section.
  2. Select a single EXR file. mh_PLAYer auto-detects left/right layer
     pairs (left.R/G/B + right.R/G/B and 10 other naming conventions).

CLI headless anaglyph convert:
  mh_player --convert --anaglyph left.####.exr --right-eye right.####.exr out.mp4
  mh_player --convert --anaglyph --stereo-exr camera_stereo.####.exr out.mp4
  mh_player --convert --anaglyph --anaglyph-mode rc_grey left.####.exr ...


REMOTE REVIEW  (browser streaming)
-----------------------------------
Free feature -- no license required.

Start via Help -> Remote Review or the antenna icon in the toolbar.
A dialog shows the URL to open on any device on the same network:

  http://192.168.x.x:8765

The browser page updates continuously during playback (~15-20 fps on
a wired LAN). Works on iPad, phone, laptop, or second PC with any
modern browser. No software installation required on the remote device.
The server auto-detects the correct LAN IP -- use the URL shown in the
dialog, not localhost.


QUICK-ACCESS ICON TOOLBAR (ROW 2)
----------------------------------
The second row of the transport bar is a collapsible icon toolbar.
Icons are grouped by function:

  Display:  EV/gamma, colour mode dropdown
  HUD/Guides: HUD overlay menu, Guides menu
  Review:   Annotation, Load B source, A/B Compare,
            Scopes, Pixel Inspector
  Workflow: Playlist, EDL / Timeline, Onion-skin, Export, Sync
  Actions:  Info bar toggle, Fullscreen, Quick Save, Remote Review
  Help:     User Manual (opens PDF), Preferences

Sidebar-anchor icons automatically expand the sidebar if collapsed and
scroll to the relevant section -- one click is always enough.
Collapse the toolbar by clicking the narrow strip on its left edge.
State persists across sessions.


FRAME STRIDE -- QUICK SEQUENCE PREVIEW
---------------------------------------
Click the xN label next to the FPS control to cycle: x1 x2 x3 x4 x5.
  x1  every frame (default)
  x2  every 2nd frame -- half the frames decoded
  x4  75% fewer frames decoded
  x5  rapid overview of very long sequences

CLI:  mh_player -n 2 beauty.####.exr
      mh_player --convert --stride 2 ...


COMMAND LINE INTERFACE
----------------------
  Viewer:   mh_player beauty.####.exr
            mh_player -s 1001 -e 1250 --display aces -n 2 beauty.####.exr
            mh_player cut.mhedl --play        (open a saved timeline)
            mh_player review.m3u8 --play      (open a playlist)
  Convert:  mh_player --convert beauty.####.exr review\beauty.####.png
            mh_player --convert --display aces beauty.####.exr out.mp4
            mh_player --convert cut.mhedl review.mp4   (render a timeline)
  AR:       mh_player --convert --ar 2.39 beauty.####.exr review.mp4
  Anaglyph: mh_player --convert --anaglyph left.####.exr --right-eye right.####.exr out.mp4
  Check:    mh_player --check beauty.####.exr
            mh_player --help

Burn-in timecode in --convert is drop-frame-correct at 29.97 / 59.94 fps.


NUKE FLIPBOOK INTEGRATION
-------------------------
See Nuke_Integration\mh_player_nuke_Quickstart.pdf for full setup instructions.

Copy Nuke_Integration\mh_player_nuke.py to %USERPROFILE%\.nuke\
Add to %USERPROFILE%\.nuke\menu.py:
    import mh_player_nuke
    mh_player_nuke.register()
Set exe path:
    set MH_PLAYER_PATH=C:\App\mh_PLAYer\mh_PLAYer_Win_x64_v2_12_2.exe


COLOUR MANAGEMENT
-----------------
Display modes: sRGB, ACES Filmic, Power Gamma, Linear, LUT, OCIO,
False Colour.
CDL grade (slope / offset / power / saturation) via a fast precomputed
LUT, with ASC-CDL .cc import and export.
OpenColorIO is bundled -- no separate installation required. Set the
$OCIO environment variable before launching to auto-load your studio
config.

LUTs load into either of two independent slots:

  Display LUT   COLOUR MANAGEMENT sidebar section. Active when the display
                transform is set to LUT, and replaces it. Scene-linear in,
                display-linear out -- mh_PLAYer applies the sRGB encode
                afterwards, so a display LUT must not bake sRGB gamma in.
  Source LUT    SOURCE LUT sidebar section. Applied in scene-linear before
                the display transform, so sRGB / ACES / OCIO stay
                selectable underneath it.

Formats: .cube (1D curve, 3D cube, or a 1D shaper plus a 3D cube in one
file -- the shaper runs first) and .3dl. The status line under each slot
reports what loaded. Note that most downloadable film-look LUTs are
display-referred: they suit video and 8-bit stills, not scene-linear EXR.


COLOUR SANITY KITS  (free downloads)
-------------------------------------
Four free QC kits are available on the mh_PLAYer download page --
known-good configs, LUTs and test charts for confirming a colour pipeline
loads correctly, and for telling whether a problem is the player or your
own config:

  OCIO / LUT Sanity Kit   Valid OCIO v2 config, identity + contrast LUTs,
                          sRGB test chart.
  ACES Sanity Kit         Scene-linear EXR chart, standalone ACES 2.0 OCIO
                          config, sRGB reference PNG.
  Display Transform & EV  Scene-linear chart with an exact-stop EV ladder,
                          shadow wedge and clipping wedge, plus the
                          expected 8-bit values for every display mode.
  LatLong / CGI LUT Kit   Working LUTs for both LUT slots -- ACES viewport
                          preview, HDRI ambience neutraliser, plate-to-
                          slate match.

  anti-matter-3d.com/mhplayer


SYSTEM REQUIREMENTS
-------------------
  OS:       Windows 10 or 11 (64-bit)
  RAM:      16 GB minimum; 32 GB+ recommended
  Storage:  SSD recommended for L3 disk cache
  Display:  1920x1080 minimum; 4K supported


SUPPORTED FORMATS
-----------------
  Image sequences:  EXR (multi-layer), PNG, TIFF, JPEG, DPX, HDR
  Video:            MP4, MOV, MKV, AVI, WebM, WMV
  Audio:            WAV, MP3, FLAC, AIFF (imported tracks)


LICENSE
-------
mh_PLAYer is fully functional without a license. The core viewer,
display and colour management, aspect ratio correction, stereo anaglyph
compositing, browser remote review, the QC toolkit, Multi-View Compare,
and the pipeline CLI are available to everyone with no time limit.

A license unlocks the production workflow features:
  Annotations      Per-frame drawing tools + voice notes
  A/B Compare      Wipe and diff (|A-B| x amplify) compare modes
  Playlist         Multi-clip queue, reorder, trim, M3U/M3U8 import/export
  Audio            Import WAV/MP3/FLAC/AIFF for image sequence sync
  Export Frames    PNG / TIFF / EXR export with burn-in
  Export Video     H.264 / H.265 / ProRes via bundled FFmpeg
  Slate & Burn-in  Title card + frame number, timecode, watermark

Studio Pro adds the advanced collaboration and automation features:
  EDL / Multi-Clip Timeline   Assemble cuts, CMX 3600, headless render
  Synced Remote Review        Frame-accurate LAN sync + auto-discovery
  Plugin Scripting            Python plugins via mh_player_api
                              (six plugins bundled in plugins\)

License tiers:
  Individual:  MAC-address bound, single machine, no expiry
  Studio:      Any machine in licensed organisation, no expiry
  Studio Pro:  Any machine in organisation + EDL, Sync & Plugins, no expiry
  Trial:       All features (incl. Studio Pro), 10 days -- on request, no payment

Video file audio plays without a license -- only imported audio for
image sequences requires one.

Install license: Help -> Install License... (select your signed license.dat)
To register:     Help -> Register / Activate
Web:             anti-matter-3d.com/mhplayer
Contact:         anti-matter-3d.com/contact


VERIFYING YOUR DOWNLOAD
-----------------------
PowerShell:
  Get-FileHash mh_PLAYer_Win_x64_v2_12_2.exe -Algorithm SHA256

Command Prompt:
  certutil -hashfile mh_PLAYer_Win_x64_v2_12_2.exe SHA256

Compare the output against SHA256SUMS.txt.
Verify the signed catalogue: signtool verify /pa /v release_manifest.cat


SECURITY
--------
The exe is digitally signed. The distribution is covered by a signed
release catalogue (release_manifest.cat) and a signed SFX archive.
Submitted to Microsoft WDSI and VirusTotal prior to every release.


================================================================================
 mh_PLAYer v2.12.2 -- Copyright (C) 2026 Martin P. Heigan. All Rights Reserved.
================================================================================
