============================================================================
  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.

SHIPPED WITH mh_PLAYer v2.12.2 AND NEWER. This plugin is already in the
plugins folder next to the mh_PLAYer .exe - there is nothing to install.
The standalone download below is for adding it to v2.12.1, or for picking
up a newer or corrected copy between mh_PLAYer releases:
  https://anti-matter-3d.com/mhplayer/


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_Studio_Watermark.txt        This file

  THE TWO SAMPLE PNGs MATTER. This plugin stamps an IMAGE, not text - it has
  no text generator, so a watermark PNG is required before it can do anything.
  The two supplied samples ("WORK IN PROGRESS" and "(C) Copyright", white
  fill with a dark outline on transparency) are ready to use as-is, and are
  also a template for the size, contrast and alpha your own logo should have.
  They are included in the standalone plugin zip from
  https://anti-matter-3d.com/mhplayer/ - if you are running the bundled copy
  and do not have them, download that zip to get them.


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  (only if you are NOT on v2.12.2 or newer)
----------------------------------------------------------------------------
  On v2.12.2+ this plugin is already installed - skip to USING IT.

  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. They are not loaded automatically;
        you browse to one in step 3 of USING IT.)
  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 remembered automatically between sessions - use
  "Save Settings" in the dialog to store the current choices.

  "Reset to Defaults" restores every field to its factory value (Opacity
  60, Scale 30, Margin 10, Tile on, Angle 0). Nothing is written until you
  click Save Settings.


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/
============================================================================
