3. Python plugin reference - Revision history

Admin at 20:34, 3 July 2026

2026-07-03T20:34:28Z

← Older revision		Revision as of 22:34, 3 July 2026
Line 36:		Line 36:
	# The installation / resource directory: <code>plugins/media/python/</code>		# The installation / resource directory: <code>plugins/media/python/</code>

	Playlist plugins:		Playlist plugins, descending precedence:

			# The open <code>.mxw</code> project's <code>plugins/playlist/python/</code> tree (opt-in via settings, highest precedence)
			# Directories configured explicitly in the settings (Python tab)
	# The per-user data directory: <code>.../plugins/playlist/python/</code>		# The per-user data directory: <code>.../plugins/playlist/python/</code>
	# The installation / resource directory: <code>plugins/playlist/python/</code>		# The installation / resource directory: <code>plugins/playlist/python/</code>

Admin at 16:43, 3 July 2026

2026-07-03T16:43:35Z

@@ Line 439: / Line 439: @@
 | <code>plugin_video_writer</code> || playlist || Write video files from the playlist || [https://github.com/mxwendler/plugin_video_writer plugin_video_writer]
 |}
 == Persistence ==

Admin at 16:31, 3 July 2026

2026-07-03T16:31:54Z

← Older revision		Revision as of 18:31, 3 July 2026
Line 113:		Line 113:
	=== Installing own modules with mxw-pip ===		=== Installing own modules with mxw-pip ===

	Plugins may use third-party packages (<code>numpy</code>, <code>moderngl</code>, <code>opencv-python</code>, ...). ~~MXWendler bundles an ''embeddable'' Python 3.12 without its own <code>python.exe</code>, so packages~~ are not installed into the installation folder — ~~instead~~ the '''mxw-pip''' helper (shipped next to the StageDesigner executable) installs them into the current user's writable folder, '''no administrator rights required''':		Plugins may use third-party packages (<code>numpy</code>, <code>moderngl</code>, <code>opencv-python</code>, ...). Packages are not installed into the installation folder — the '''mxw-pip''' helper (shipped next to the StageDesigner executable) installs them into the current user's writable folder, '''no administrator rights required''':

	<pre>		<pre>
Line 120:		Line 120:

	This is exactly the directory StageDesigner prepends to <code>sys.path</code> when the option '''Prepend user site-path''' is enabled (Settings → Python tab).		This is exactly the directory StageDesigner prepends to <code>sys.path</code> when the option '''Prepend user site-path''' is enabled (Settings → Python tab).

			mxw-pip runs <code>pip</code> with the '''Python 3.12 shipped with StageDesigner''' (<code>python.exe</code> in the installation folder / in its <code>python312/</code> subfolder) — nothing else needs to be installed. Only when the shipped interpreter is missing does it fall back to a system Python (<code>py -3.12</code>, then <code>python</code> on <code>PATH</code>), which must be 3.12 so binary wheels match the runtime ABI.

	Step by step:		Step by step:

	# Make sure a system '''Python 3.12''' is installed — mxw-pip uses it to run <code>pip</code> (install it via the StageDesigner dependencies installer, or from [https://www.python.org/ python.org] with ''Add python.exe to PATH'' ticked). It must be 3.12 so binary wheels match the embedded interpreter's ABI.
	# Open '''Settings → Python''' and enable '''Prepend user site-path'''. The two installer buttons below are only active while this option is on, because mxw-pip installs into exactly that folder. Enabling applies immediately; disabling takes full effect after a restart.		# Open '''Settings → Python''' and enable '''Prepend user site-path'''. The two installer buttons below are only active while this option is on, because mxw-pip installs into exactly that folder. Enabling applies immediately; disabling takes full effect after a restart.
	# Click '''Launch CMD window with mxw-pip module installer..''' — this opens the installer shell (<code>mxw-pip-shell.bat</code>). In the shell, type:		# Click '''Launch CMD window with mxw-pip module installer..''' — this opens the installer shell (<code>mxw-pip-shell.bat</code>). In the shell, type:

Admin at 16:27, 3 July 2026

2026-07-03T16:27:01Z

← Older revision		Revision as of 18:27, 3 July 2026
Line 111:		Line 111:
	* <code>mxw_imgui</code> — Dear ImGui bindings for drawing settings panels inside MXWendler (used by <code>onRenderPanel()</code>).		* <code>mxw_imgui</code> — Dear ImGui bindings for drawing settings panels inside MXWendler (used by <code>onRenderPanel()</code>).

	=== Installing ~~Python packages~~ ===		=== Installing own modules with mxw-pip ===

	Plugins may use third-party packages (<code>numpy</code>, <code>moderngl</code>, <code>opencv</code>, ...). ~~Install~~ them into the embedded interpreter ~~with the~~ '''module installer ~~shell~~''' ~~available from~~ the ~~settings dialog~~ (~~Python tab~~), ~~which runs~~ <code>pip</code> ~~against MXWendler~~'~~s Python 3~~.12.		Plugins may use third-party packages (<code>numpy</code>, <code>moderngl</code>, <code>opencv-python</code>, ...). MXWendler bundles an ''embeddable'' Python 3.12 without its own <code>python.exe</code>, so packages are not installed into the installation folder — instead the '''mxw-pip''' helper (shipped next to the StageDesigner executable) installs them into the current user's writable folder, '''no administrator rights required''':

			<pre>
			%APPDATA%\Python\Python312\site-packages
			</pre>

			This is exactly the directory StageDesigner prepends to <code>sys.path</code> when the option '''Prepend user site-path''' is enabled (Settings → Python tab).

			Step by step:

			# Make sure a system '''Python 3.12''' is installed — mxw-pip uses it to run <code>pip</code> (install it via the StageDesigner dependencies installer, or from [https://www.python.org/ python.org] with ''Add python.exe to PATH'' ticked). It must be 3.12 so binary wheels match the embedded interpreter's ABI.
			# Open '''Settings → Python''' and enable '''Prepend user site-path'''. The two installer buttons below are only active while this option is on, because mxw-pip installs into exactly that folder. Enabling applies immediately; disabling takes full effect after a restart.
			# Click '''Launch CMD window with mxw-pip module installer..''' — this opens the installer shell (<code>mxw-pip-shell.bat</code>). In the shell, type:
			#: <pre>mxw-pip install <modulename></pre>
			#: for example:
			#: <pre>mxw-pip install moderngl</pre>
			# '''Restart MXWendler StageDesigner''' so the new module is loaded.

			Other <code>pip</code> subcommands are passed through unchanged, e.g. <code>mxw-pip list</code>, <code>mxw-pip show moderngl</code>, <code>mxw-pip uninstall moderngl</code>. The button '''Open per-user module install folder..''' next to the installer button shows the target directory in the Explorer. Both <code>mxw-pip.bat</code> and <code>mxw-pip-shell.bat</code> can also be run directly from the installation folder in any command prompt.

			Because the target folder lives in the user profile, every user keeps their own module set, and reinstalling / updating StageDesigner never touches the installed modules.

	=== Error handling ===		=== Error handling ===
Line 192:		Line 212:
	=== Approach 2: rendering into an FBO and streaming ===		=== Approach 2: rendering into an FBO and streaming ===

	Render with OpenGL (e.g. via '''ModernGL''') into an offscreen framebuffer, read the pixels back and return them like in approach 1. The scene renders on the GPU, but every frame makes a round trip GPU → CPU (<code>fbo.read()</code>) → GPU (PBO upload).		Render with OpenGL (e.g. via '''ModernGL''', installed once with <code>mxw-pip install moderngl numpy</code>) into an offscreen framebuffer, read the pixels back and return them like in approach 1. The scene renders on the GPU, but every frame makes a round trip GPU → CPU (<code>fbo.read()</code>) → GPU (PBO upload).

	Bundled reference: <code>plugins/media/python/plugin_opengl_cube</code> ([https://github.com/mxwendler/mxw-plugin-opengl-cube github]).		Bundled reference: <code>plugins/media/python/plugin_opengl_cube</code> ([https://github.com/mxwendler/mxw-plugin-opengl-cube github]).
Line 428:		Line 448:
	* '''Errors''' — open the interpreter console (IO dialog): hook exceptions are reported there (throttled). Remember that a throwing per-frame hook is blacklisted until reload.		* '''Errors''' — open the interpreter console (IO dialog): hook exceptions are reported there (throttled). Remember that a throwing per-frame hook is blacklisted until reload.
	* '''Media shows black''' — <code>onRenderFrame</code> returned a buffer of the wrong size (must be <code>widthheight4</code> bytes), or a GL plugin created its own context instead of attaching to MXWendler's (see the OpenGL rules).		* '''Media shows black''' — <code>onRenderFrame</code> returned a buffer of the wrong size (must be <code>widthheight4</code> bytes), or a GL plugin created its own context instead of attaching to MXWendler's (see the OpenGL rules).
	* '''Missing packages''' — install them with ~~the module installer shell from the settings dialog;~~ the embedded interpreter ~~has its own package directory,~~ a system-wide Python installation ~~is not used~~.		* '''Missing packages''' — install them with mxw-pip (see [[#Installing own modules with mxw-pip\|Installing own modules with mxw-pip]]) and make sure '''Prepend user site-path''' is enabled: the embedded interpreter does not see a system-wide Python installation's packages.

Admin: Created page with " MXWendler StageDesigner can be extended with '''Python plugins'''. A plugin is a plain folder containing a manifest file and a Python module; MXWendler discovers it at startup, shows it in the user interface and calls a def..."

2026-07-03T16:10:53Z

Created page with "   MXWendler StageDesigner can be extended with '''Python plugins'''. A plugin is a plain folder containing a manifest file and a Python module; MXWendler discovers it at startup, shows it in the user interface and calls a def..."

New page

MXWendler StageDesigner can be extended with '''Python plugins'''. A plugin is a plain folder containing a manifest file and a Python module; MXWendler discovers it at startup, shows it in the user interface and calls a defined set of Python functions (''hooks'') at the right moments.

Two plugin types exist:

* '''Media plugins''' produce pixels: they appear as a media source that can be placed in a clip like any video file. Examples: a web browser media, a generative OpenGL cube.
* '''Playlist plugins''' are items in the playlist grid: they run logic when their cue plays. Examples: advance the playlist at a given time of day, write video files, ping a host.

The embedded interpreter is '''Python 3.12'''. The general Python command interface (module <code>mxw</code>) is documented in the [[Python_Reference|Python Reference]].

== Plugin anatomy ==

A plugin is one folder with at least two files:

<pre>
plugins/media/python/plugin_my_effect/
mxw_plugin.ini the manifest: identity, menu entries, addressing
mxw_main.py the Python module with the hook functions
(more .py files) optional: importable as "from plugin_my_effect.xyz import ..."
</pre>

The folder name is the Python package name: additional modules in the folder are imported with absolute imports, e.g. <code>from plugin_my_effect.helpers import foo</code>.

=== Plugin locations ===

Plugins are searched in several directories. '''User-controlled locations always override the bundled system location''', so a user can replace a built-in plugin by placing a same-named folder in a higher-precedence directory — even without write access to the installation.

Media plugins, descending precedence:

# The open <code>.mxw</code> project's <code>plugins/media/python/</code> tree (opt-in via settings, highest precedence)
# Directories configured explicitly in the settings (Python tab)
# The per-user data directory, e.g. <code>%APPDATA%/MXWendler/plugins/media/python/</code>
# The installation / resource directory: <code>plugins/media/python/</code>

Playlist plugins:

# The per-user data directory: <code>.../plugins/playlist/python/</code>
# The installation / resource directory: <code>plugins/playlist/python/</code>

=== The manifest: mxw_plugin.ini ===

<syntaxhighlight lang="ini">
[mxw_plugin] ; must be here
plugin_version = 1 ; must be V1
plugin_script_language = Python ; must be Python
</syntaxhighlight>

Common keys:

{| class="wikitable"
! Key !! Used by !! Meaning
|-
| <code>plugin_menu_parent</code> || both || Menu the plugin is listed under (e.g. <code>Media</code>, <code>IO</code>)
|-
| <code>plugin_menu_name</code> || both || Display name in the menu
|-
| <code>plugin_grid_name</code> || both || Short name shown in the grid / media list
|-
| <code>plugin_tooltip</code> || both || Tooltip text
|-
| <code>plugin_menu_level</code> (media) / <code>plugin_action_level</code> (playlist) || both || <code>user</code> (default, visible), <code>development</code> (visible in debug builds only), <code>disabled</code> (invisible)
|}

Media-only keys:

{| class="wikitable"
! Key !! Meaning
|-
| <code>plugin_media_scheme</code> || The URI scheme this plugin handles, e.g. <code>generative</code> or <code>web</code>. Media is addressed as <code><scheme>://<payload></code>.
|-
| <code>plugin_media_payload</code> || Optional. If set, the plugin handles exactly <code>scheme://payload</code>; if omitted, it handles every URI of its scheme. Several plugins can share one scheme and dispatch on the payload.
|-
| <code>plugin_media_create_uri</code> || The URI used when the user creates this media from the menu / Create button.
|}

Playlist-only keys:

{| class="wikitable"
! Key !! Meaning
|-
| <code>plugin_grid_bg_color</code> || Item background color as <code>r g b a</code> floats, e.g. <code>0.05 0.05 0.45 1.0</code>
|}

== The plugin environment ==

=== Per-instance state ===

One Python module serves '''many simultaneous instances''' (several clips using the same media plugin, several copies of a playlist item). Before every hook call, the host sets module globals identifying the instance:

* Media plugins: <code>media_id</code> (integer)
* Playlist plugins: <code>item_id</code> (integer) and <code>item_position</code> (tuple <code>(x, y)</code>, the grid position)

The standard pattern is a module-level dictionary keyed by the id:

<syntaxhighlight lang="python">
storage = {}

def onCreate(): # playlist; media plugins use onOpen(uri)
storage[item_id] = my_instance_state()

def onDelete():
storage.pop(item_id, None)
</syntaxhighlight>

=== Host modules ===

* <code>mxw</code> — the MXWendler command interface (playlist control, layers, clips, ...), see the [[Python_Reference|Python Reference]].
* <code>mxw_imgui</code> — Dear ImGui bindings for drawing settings panels inside MXWendler (used by <code>onRenderPanel()</code>).

=== Installing Python packages ===

Plugins may use third-party packages (<code>numpy</code>, <code>moderngl</code>, <code>opencv</code>, ...). Install them into the embedded interpreter with the '''module installer shell''' available from the settings dialog (Python tab), which runs <code>pip</code> against MXWendler's Python 3.12.

=== Error handling ===

Exceptions raised by a hook are reported to the interpreter console (IO dialog) — throttled, so a per-frame error does not flood the log. A '''per-frame hook that throws is blacklisted''': it is not called again until the plugin is reloaded, so one broken callback cannot stall the render loop. Playlist plugins can be hot-reloaded from disk (state is snapshotted via <code>onSave()</code>, the module source re-executed, then <code>onCreate()</code> + <code>onLoad()</code> restore each instance), which also clears the blacklist.

== Media plugins ==

A media plugin is addressed by a URI: <code><scheme>://<payload></code>, for example <code>generative://cube_spin_opengl</code> or <code>web://https://mxwendler.net</code>. Every created media instance internally carries a unique instance token so two clips never share state; the plugin always sees the clean URI.

=== Hooks ===

All hooks are optional except <code>onOpen</code> and '''one of the two render hooks'''.

{| class="wikitable"
! Hook !! Direction !! Meaning
|-
| <code>onOpen(uri)</code> || returns <code>(width, height, length, fps, has_alpha)</code> || Called when the media is created / loaded. Create the per-instance state here. Do '''not''' touch OpenGL yet (see below).
|-
| <code>onRenderFrame(frame)</code> || returns a pixel buffer || Approach 1 and 2: return a <code>H*W*4</code> <code>uint8</code> buffer (bytes / bytearray / numpy), '''BGRA''' byte order, top-down. The host uploads it into the media texture.
|-
| <code>onRenderFrameGL(frame, texture, width, height)</code> || returns <code>bool</code> || Approach 3: render '''directly into the media texture''' — <code>texture</code> is its raw GL handle. Return <code>True</code> when the frame is in the texture; the pixel upload path is then skipped. Tried before <code>onRenderFrame</code>; a plugin implements one of the two.
|-
| <code>onClose()</code> || — || The media is destroyed: release per-instance resources.
|-
| <code>onRenderPanel()</code> || — || Draw ImGui controls (via <code>mxw_imgui</code>) in the clip panel, above the Video Info section.
|-
| <code>onSizeChange(w, h)</code> || — || The host changed the render size: recreate size-dependent resources.
|-
| <code>onSpeedRange()</code> || returns <code>(min, max)</code> || Allowed clip playback speed range. Without it the media is locked to speed 1.
|-
| <code>onSetSpeed(speed)</code> || — || The clip playback speed changed. Not clamped: 0 and negative values are allowed.
|-
| <code>onSave()</code> / <code>onLoad(state)</code> || string round-trip || Persist per-instance state in the project file.
|-
| <code>onDisplayName()</code> || returns string || Optional live display name (e.g. the web plugin reports the current page URL).
|}

=== OpenGL rules for media plugins ===

These rules apply to approaches 2 and 3:

* '''Never create a standalone GL context''' (no windowed/standalone <code>moderngl.create_context()</code> at import or in <code>onOpen</code>). MXWendler makes its own context current every frame; GL objects created in a foreign context will be dereferenced against the wrong context and crash the driver.
* Instead, '''lazily attach on the first render call''': <code>moderngl.create_context()</code> inside <code>onRenderFrame / onRenderFrameGL</code> attaches to MXWendler's context, which the host guarantees to be current there.
* The host '''snapshots and restores all relevant GL state''' around the render hooks (FBO bindings, program, VAO, buffers, viewport, enables, pixel store). The plugin does not need to unbind anything.

=== Approach 1: rendering into pixels (CPU) ===

The simplest approach: compute the frame on the CPU and return it. No OpenGL knowledge required. The host uploads the buffer into the media texture through a PBO (pixel buffer object) double-buffer, so the upload is asynchronous and cheap — the cost of this approach is the CPU rendering itself.

<syntaxhighlight lang="python">
import numpy as np

W, H = 640, 360
storage = {}

def onOpen(uri):
storage[media_id] = {"phase": 0.0}
return (W, H, 1, 60.0, True) # width, height, length, fps, has_alpha

def onRenderFrame(frame):
inst = storage[media_id]
inst["phase"] += 0.01
# a moving horizontal gradient, BGRA byte order, top-down
x = (np.linspace(0.0, 1.0, W) + inst["phase"]) % 1.0
row = np.zeros((W, 4), dtype=np.uint8)
row[:, 0] = (x * 255).astype(np.uint8) # B
row[:, 2] = ((1 - x) * 255).astype(np.uint8) # R
row[:, 3] = 255 # A
return np.ascontiguousarray(np.tile(row, (H, 1, 1)))

def onClose():
storage.pop(media_id, None)
</syntaxhighlight>

Use this for: generated images, PIL/Pillow output, OpenCV results, slow-changing content.

=== Approach 2: rendering into an FBO and streaming ===

Render with OpenGL (e.g. via '''ModernGL''') into an offscreen framebuffer, read the pixels back and return them like in approach 1. The scene renders on the GPU, but every frame makes a round trip GPU → CPU (<code>fbo.read()</code>) → GPU (PBO upload).

Bundled reference: <code>plugins/media/python/plugin_opengl_cube</code> ([https://github.com/mxwendler/mxw-plugin-opengl-cube github]).

<syntaxhighlight lang="python">
import numpy as np
import moderngl

storage = {}

class inst_t:
def __init__(self):
self.ctx = None
self.fbo = None

def onOpen(uri):
storage[media_id] = inst_t()
return (1024, 1024, 1, 60.0, True)

def onRenderFrame(frame):
inst = storage[media_id]
if inst.ctx is None:
# first frame: attach to MXWendler's context (never earlier!)
inst.ctx = moderngl.create_context()
color = inst.ctx.texture((1024, 1024), 4)
depth = inst.ctx.depth_renderbuffer((1024, 1024))
inst.fbo = inst.ctx.framebuffer([color], depth)
# ... build program / vao here ...

inst.fbo.use()
inst.ctx.clear(0.0, 0.0, 0.0, 0.0, depth=1.0)
# ... draw the scene ...

# read back: GL is bottom-up RGBA, the host wants top-down BGRA
raw = inst.fbo.read(components=4, alignment=1)
img = np.frombuffer(raw, dtype=np.uint8).reshape((1024, 1024, 4))
img = np.flipud(img)
return np.ascontiguousarray(img[:, :, [2, 1, 0, 3]])
</syntaxhighlight>

Use this for: GPU-rendered content when you also need the pixels on the CPU (analysis, recording), or as a stepping stone to approach 3.

=== Approach 3: rendering into a bound texture target (direct) ===

The fastest path: the host passes the '''raw GL handle of the media texture''' to <code>onRenderFrameGL</code>. The plugin attaches it to its own framebuffer and renders straight into it. '''No readback, no upload, no texture streaming''' — the frame never leaves the GPU.

Bundled reference: <code>plugins/media/python/plugin_opengl_cube_direct</code>.

<syntaxhighlight lang="python">
import moderngl

storage = {}

class inst_t:
def __init__(self):
self.ctx = None
self.fbo = None
self.depth = None
self.fbo_key = None # (texture, w, h) the fbo was built for

def onOpen(uri):
storage[media_id] = inst_t()
return (1024, 1024, 1, 60.0, True)

def onRenderFrameGL(frame, texture, width, height):
inst = storage[media_id]
if inst.ctx is None:
inst.ctx = moderngl.create_context() # attach to MXWendler's context
# ... build program / vao here ...

# (re)wrap the host texture when the handle or size changed: the host
# recreates the media texture on a render size change
if inst.fbo_key != (texture, width, height):
if inst.fbo:
inst.fbo.release()
if inst.depth:
inst.depth.release()
color = inst.ctx.external_texture(texture, (width, height), 4, 0, "f1")
inst.depth = inst.ctx.depth_renderbuffer((width, height))
inst.fbo = inst.ctx.framebuffer([color], inst.depth)
inst.fbo_key = (texture, width, height)

inst.fbo.use()
inst.ctx.clear(0.0, 0.0, 0.0, 0.0, depth=1.0)
# ... draw the scene; flip Y in the projection, see below ...

return True # the frame is in the texture: host skips the upload path
</syntaxhighlight>

Rules specific to the direct approach:

* '''Never <code>release()</code> the external texture wrapper''' — the GL texture belongs to MXWendler. Only release your own framebuffer and depth renderbuffer.
* '''Rebuild the framebuffer when <code>(texture, width, height)</code> changes.''' The handle is not stable: a render size change makes the host recreate the media texture.
* '''Flip Y.''' MXWendler media textures are top-down (row 0 = top of the image), a GL render is bottom-up. Negate the Y row of your projection matrix (approaches 1/2 flip on the CPU instead, e.g. with <code>numpy.flipud</code>).

=== Choosing an approach ===

{| class="wikitable"
! !! 1: Pixels (CPU) !! 2: FBO + streaming !! 3: Direct texture
|-
| Scene renders on || CPU || GPU || GPU
|-
| Per-frame copies || CPU → GPU upload || GPU → CPU readback + CPU → GPU upload || none
|-
| OpenGL required || no || yes || yes
|-
| CPU access to the pixels || yes (you made them) || yes (after readback) || no
|-
| Typical use || generated images, PIL, OpenCV || GPU render that also needs CPU pixels || pure GPU generative content, best performance
|}

== Playlist plugins ==

A playlist plugin is an item placed in the playlist grid. It participates in the cue lifecycle: it can run logic when its cue is played, every frame while its cue is active, or every frame globally. Playlist control functions (<code>mxw.playlist.play()</code>, <code>mxw.playlist.navigate_index()</code>, ...) are documented in the [[Python_Reference|Python Reference]].

=== Hooks ===

{| class="wikitable"
! Hook !! Required !! Meaning
|-
| <code>onCreate()</code> || yes || A new instance was placed in the grid (also called after hot-reload): create the per-instance state entry.
|-
| <code>onDelete()</code> || yes || The instance was deleted: release the state entry.
|-
| <code>onAction()</code> || yes || The item's cue was played (the item ''fires'').
|-
| <code>onPostAction()</code> || no || Called after the action completed.
|-
| <code>onSave()</code> / <code>onLoad(state)</code> || yes || Serialize / restore per-instance state (string). Called on project save/load and around hot-reload.
|-
| <code>onRenderPanel()</code> || yes || Draw the item's settings panel with <code>mxw_imgui</code>.
|-
| <code>getText()</code> || yes || Detail text appended to the item's grid label.
|-
| <code>onNewFrameAlways()</code> || no || Called every rendered frame, regardless of cue state.
|-
| <code>onNewFrameInPlayoutCue()</code> || no || Called every rendered frame while the item's cue is the active playout cue.
|-
| <code>onPause(is_paused)</code> || no || Pause was pressed / released.
|-
| <code>onPreparePlayback()</code> / <code>onCleanup()</code> || no || Prepare / release playout resources.
|-
| <code>onActivateInUI()</code> || no || The item was selected in the user interface.
|-
| <code>onActiveCueChange(direction)</code> || no || The active cue changed past this item (navigation).
|-
| <code>onSettingsChanged()</code> || no || Item settings were changed from outside.
|-
| <code>getDuration()</code> || no || Report the item's action duration in milliseconds.
|-
| <code>getTimeSinceOnActionIssued()</code> || no || Report elapsed action time in milliseconds (drives the progress display).
|-
| <code>getColorBG()</code> || no || Return a <code>mxw_imgui.Vec4</code> (rgb 0..255) to set the grid cell background color dynamically.
|-
| <code>renderBlinking()</code> || no || Return <code>True</code> to make the grid cell blink.
|}

=== Minimal example ===

<syntaxhighlight lang="python">
import pickle, codecs
import mxw
import mxw_imgui

class state_t:
fire_count = 0

storage = {}

def onCreate():
storage[item_id] = state_t()

def onDelete():
storage.pop(item_id, None)

def onAction():
# the item's cue was played
storage[item_id].fire_count += 1

def getText():
return " : fired %d times" % storage[item_id].fire_count

def onRenderPanel():
inst = storage[item_id]
mxw_imgui.text_unformatted("Fired %d times" % inst.fire_count)
if mxw_imgui.button("Reset"):
inst.fire_count = 0

def onSave():
return codecs.encode(pickle.dumps(storage[item_id]), "base64").decode()

def onLoad(serialized):
storage[item_id] = pickle.loads(codecs.decode(serialized.encode(), "base64"))
</syntaxhighlight>

With a manifest:

<syntaxhighlight lang="ini">
[mxw_plugin]
plugin_version = 1
plugin_script_language = Python
plugin_menu_parent = IO
plugin_menu_name = Fire Counter
plugin_grid_name = Counter
plugin_tooltip = Counts how often its cue was played
</syntaxhighlight>

Bundled references: <code>plugins/playlist/python/plugin_advance_datetime</code> (timed playlist navigation, rich settings panel — [https://github.com/mxwendler/plugin_advance_datetime github]), <code>plugin_video_writer</code> ([https://github.com/mxwendler/plugin_video_writer github]), <code>plugin_ping</code>.

== Example plugins on GitHub ==

The bundled example plugins are maintained as public repositories under [https://github.com/mxwendler github.com/mxwendler] — good starting points to fork for an own plugin:

{| class="wikitable"
! Plugin !! Type !! Approach / purpose !! Repository
|-
| <code>plugin_opengl_cube</code> || media || Approach 2: ModernGL cube into an offscreen FBO, streamed || [https://github.com/mxwendler/mxw-plugin-opengl-cube mxw-plugin-opengl-cube]
|-
| <code>plugin_opengl_cube_direct</code> || media || Approach 3: same cube rendered directly into the media texture || ships with the installation
|-
| <code>plugin_web_media</code> || media || A web browser as media source (whole-scheme <code>web://</code> plugin) || [https://github.com/mxwendler/mxw-plugin-web-media mxw-plugin-web-media]
|-
| <code>plugin_advance_datetime</code> || playlist || Timed playlist navigation with a rich settings panel || [https://github.com/mxwendler/plugin_advance_datetime plugin_advance_datetime]
|-
| <code>plugin_video_writer</code> || playlist || Write video files from the playlist || [https://github.com/mxwendler/plugin_video_writer plugin_video_writer]
|}

== Persistence ==

Both plugin types persist per-instance state through the <code>onSave() → string</code> / <code>onLoad(string)</code> pair. The string is stored inside the project file; anything goes, a common choice is base64-encoded pickle (see the playlist example above). Media plugins additionally have their render size stored and restored by the host automatically.

== Troubleshooting ==

* '''Nothing appears in the menu''' — check the manifest: <code>plugin_version = 1</code>, <code>plugin_script_language = Python</code>, a non-empty <code>plugin_menu_name</code>, and the level key (<code>development</code> plugins only show in debug builds).
* '''Errors''' — open the interpreter console (IO dialog): hook exceptions are reported there (throttled). Remember that a throwing per-frame hook is blacklisted until reload.
* '''Media shows black''' — <code>onRenderFrame</code> returned a buffer of the wrong size (must be <code>width*height*4</code> bytes), or a GL plugin created its own context instead of attaching to MXWendler's (see the OpenGL rules).
* '''Missing packages''' — install them with the module installer shell from the settings dialog; the embedded interpreter has its own package directory, a system-wide Python installation is not used.