============================================================================
  mh_PLAYer  -  FIELD RECORDER  (plugin add-on)
  Plugin v1.0   |   targets mh_PLAYer v2.12.1+   |   2026-06-27
============================================================================

A drop-in plugin for mh_PLAYer that captures a live HDMI / USB video device,
shows a live preview, and records the clean feed to disk. Handy for grabbing
a capture-card or webcam feed without leaving the player.

This is a separate add-on download for now; it is planned to ship with a
future mh_PLAYer installer release.


CONTENTS OF THIS ARCHIVE
----------------------------------------------------------------------------
  field_recorder.py                  The plugin
  README.txt                         This file


REQUIREMENTS
----------------------------------------------------------------------------
  mh_PLAYer        v2.12.1 or newer
  Licence tier     Plugin Scripting (Studio Pro). The Plugins menu is
                   locked on lower tiers.
  Platform         Windows (as per mh_PLAYer)
  Capture device   An HDMI / USB capture card or webcam (DirectShow or
                   Media Foundation)

  No extra Python install is needed - the plugin runs inside mh_PLAYer and
  uses the FFmpeg, OpenCV, NumPy, sounddevice and soundfile that already
  ship with it. Recording is done through the bundled FFmpeg.


INSTALL
----------------------------------------------------------------------------
  1. Locate your mh_PLAYer folder - the one that contains
     mh_PLAYer_Win_x64_v2_12_*.exe
  2. Open (or create) the  plugins  sub-folder in that same folder.
       (This install-root  plugins  folder is the only location mh_PLAYer
        scans - do not use %USERPROFILE%\.mh_player\plugins\.)
  3. Copy  field_recorder.py  into that  plugins  folder.
  4. Start mh_PLAYer. The plugin loads automatically and adds
     "Field Recorder..." to the Plugins menu.

  To remove it, delete field_recorder.py from the plugins folder and
  restart mh_PLAYer.


USING IT
----------------------------------------------------------------------------
  1. Plugins menu  ->  Field Recorder...
  2. Source:
       Device       pick the capture device. "Refresh" re-scans.
       Resolution   "Device default", or a mode the device reports.
       Request MJPG  tick for high-resolution USB capture that needs it.
  3. Output:
       Format       MP4 (H.264), MOV (H.264), or ProRes 422
                    (Proxy / LT / 422 / HQ).
       Quality      High / Medium / Low (H.264 only; ProRes ignores it).
       Folder       where files are written. If a clip is loaded, this is
                    pre-filled with its folder.
       Filename stem  the recording is saved as  <stem>_<timestamp>.<ext>
  4. Audio (optional):
       Tick "Record audio" and pick an input device. The list is the same
       set of input devices mh_PLAYer's Audio Tab shows. The audio is
       captured alongside the video and muxed into the file when you stop.
  5. Framing aids (preview only - never baked into the recording):
       Flip         Horizontal / Vertical mirror the PREVIEW only. The
                    recorded file is never flipped - it stays the true
                    clean signal.
       Guides       overlay framing guides on the preview:
                      Thirds      rule-of-thirds grid
                      Cross       centre crosshair
                      Safe areas  action-safe (90%) + title-safe (80%)
                    Toggle any combination; they are drawn over the preview
                    only and do not affect the recorded file.
  6. Start Preview  ->  the live feed appears. The Record button enables
     once the device is open.
  7. Record / Stop  ->  captures while it runs; an elapsed timer and frame
     count are shown. On Stop the file is finalised (and audio muxed in if
     enabled), and the saved path is reported.


WHAT IT RECORDS
----------------------------------------------------------------------------
  The CLEAN feed only - what the device sends, with no overlays burned in.
  Monitoring aids such as the preview flip and the framing guides (thirds,
  cross, safe areas) are deliberately NOT baked into the file.

  Video formats:
    - H.264 in MP4 or MOV (libx264)
    - ProRes 422 Proxy / LT / 422 / HQ in MOV (prores_ks)

  Audio (optional) is muxed as AAC for H.264 / MP4-MOV, or PCM for ProRes.

  ProRes is intra-frame and high-bitrate - a fast SSD is recommended.


SETTINGS
----------------------------------------------------------------------------
  Your settings (device, resolution, format, quality, folder, filename
  stem, audio, flip and guide choices) are stored in:
    %APPDATA%\mh_tools\field_recorder_prefs.json

  Delete that file to return to the defaults.


TROUBLESHOOTING
----------------------------------------------------------------------------
  Device shows "Camera index N" instead of a name
    The device names come from FFmpeg's DirectShow probe. Some modern
    webcams expose only Media Foundation, which DirectShow cannot name -
    capture still works by index. The raw probe output is written to:
      %APPDATA%\mh_tools\field_recorder_dshow.txt
    so you can see exactly what FFmpeg reported.

  "Could not open the capture device"
    The device may be in use by another app (close it first), or the
    selected resolution may be unsupported - try "Device default", a
    different resolution, or toggle Request MJPG.

  "FFmpeg not found"
    Recording needs the bundled FFmpeg at  ffmpeg\bin\ffmpeg.exe  inside
    the mh_PLAYer install folder (it ships there). You can also point the
    plugin at an FFmpeg explicitly with the  MH_PLAYER_FFMPEG  environment
    variable (a full path to ffmpeg.exe, or the folder that contains
    bin\ffmpeg.exe).

  No audio devices listed
    Audio uses sounddevice; if mh_PLAYer's Audio Tab lists input devices,
    this plugin will too. If none appear, no input device is available.


TIPS
----------------------------------------------------------------------------
  - For high-resolution USB capture (e.g. 4K over USB-3), try ticking
    Request MJPG if the device delivers no frames at the chosen size.
  - Use ProRes for editing/grading masters; H.264 for review copies.
  - The preview flip is for framing only - record straight, flip later in
    your editor if you need a mirrored result.
  - The framing guides (thirds, cross, safe areas) are overlays on the
    preview only; combine them as needed to compose the shot.


LICENCE & SUPPORT
----------------------------------------------------------------------------
  (C) 2026 Martin P. Heigan - anti-matter-3d.com

  This plugin is provided for use with a licensed copy of mh_PLAYer and is
  covered by the mh_PLAYer licence terms.

  Questions / feedback / more tools:
    https://anti-matter-3d.com/contact/
    https://anti-matter-3d.com/
============================================================================
