============================================================================
  mh_PLAYer  -  STUDIO WATERMARK  (plugin add-on)
  Plugin v1.0   |   targets mh_PLAYer v2.12.1+   |   2026-06-14
============================================================================

A drop-in plugin for mh_PLAYer that stamps a logo / title PNG onto a folder
of rendered frames and writes watermarked COPIES to an output sub-folder.
Handy for marking WIP, dailies and slap-comps before they leave the studio.

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
----------------------------------------------------------------------------
  studio_watermark.py                The plugin
  sample_logo_work_in_progress.png   Example watermark (transparent PNG)
  sample_logo_copyright.png          Example watermark (transparent PNG)
  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)

  No extra Python install is needed - the plugin runs inside mh_PLAYer and
  uses the Pillow / NumPy / OpenCV that already ship with it.


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.
  3. Copy  studio_watermark.py  into that  plugins  folder.
       (The sample PNGs can live anywhere - keep them with your project, or
        next to the plugin for convenience.)
  4. Start mh_PLAYer. The plugin loads automatically and adds
     "Studio Watermark..." to the Plugins menu.

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


USING IT
----------------------------------------------------------------------------
  1. Plugins menu  ->  Studio Watermark...
  2. Frames folder:  pick the folder of rendered frames to watermark.
     If a clip is loaded, this is pre-filled with its folder.
  3. Logo:  browse to a watermark PNG. A transparent PNG looks best; the
     two included samples are ready to use. A logo with no alpha is stamped
     as an opaque rectangle.
  4. Appearance:
       Opacity (%)         how strong the watermark is
       Scale (% of width)  logo width as a percentage of the frame width
       Edge margin (px)    inset from the edge (single-stamp mode)
       Position            9-point grid (ignored when Tile is on)
  5. Tile (repeat across the whole frame):  on by default. Turn it off for
     a single stamp at the chosen Position. Angle 0 = straight; Gap sets
     the spacing between tiles.
  6. Preview:  updates live as you adjust settings, over the first frame in
     your folder (or the loaded clip - it can even grab a frame from a
     loaded movie). "Refresh Frame" re-grabs the background. The preview is
     for POSITIONING; it is not colour-managed like the viewer.
  7. "Watermark Sequence..."  writes the watermarked copies into a
     sub-folder (default  watermarked )  inside the frames folder.
     Originals are never touched.

  Save Settings stores your choices so they are remembered next time.

  AUTO-WATERMARK AFTER EXPORT (optional)
  Tick "Also watermark frames automatically after a GUI export" to have the
  plugin watermark an export's output folder into its  watermarked
  sub-folder right after a frame/video export completes.


SUPPORTED INPUT
----------------------------------------------------------------------------
  .png  .tif  .tiff  .jpg  .jpeg  .bmp  .webp

  NOT supported in this version:
    - EXR sequences (linear float - needs a future mh_PLAYer pixel-hook API)
    - Movie files (.mp4 / .mov / ...). Export the movie to a frame sequence
      first (File > Export Frames), then watermark the frames.


SETTINGS
----------------------------------------------------------------------------
  Your settings are stored in:
    %APPDATA%\mh_tools\studio_watermark_prefs.json

  Delete that file to return to the defaults (Opacity 60, Scale 30,
  Margin 10, Tile on, Angle 0).


TIPS
----------------------------------------------------------------------------
  - Use a transparent PNG for a clean watermark; white text with a dark
    outline (like the samples) stays readable on light and dark frames.
  - Keep the source PNG at full opacity and dial it back with the Opacity
    control rather than pre-fading the file.
  - For a tiled deterrent, lower the Opacity (e.g. 25-40 %) and raise the
    Gap so the field is legible but not overwhelming.


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. The two sample PNGs are provided
  as examples and may be used or edited freely.

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