OSC Reference

2026-08-08T19:08:59Z

Admin: Update link after renaming Troubleshooting -> OSC Troubleshooting (bot)

This reference applies to all different OS. The presented OSC commands are for most part supported in version 6.0 but will be fully functional in version 6.0.08 and above.
<div class="noprint">

== Introduction==
</div>
This document describes the MXWendler (MXW) OSC Command Interface through an overview of the command structure and practical examples of integration with external controlling software.

== What is OSC? ==
</div>
OSC or „Open Sound Control“ is a Network-based protocol that commonly utilizes the UDP transport mechanism. Originally developed as a successor of the MIDI control protocol, it used nowadays as a practical communication method between platforms.

OSC Features:
* Connectionless communication architecture
* Broadcast-type messages
* High resolution time tag
* Allowed data formats including numeric, symbolic, and “blob” arguments
* Open-ended, dynamic, URL-style naming scheme for the receivers' address

[https://en.wikipedia.org/wiki/Open_Sound_Control [1<nowiki>]</nowiki> Wikipedia Link]

== Contents ==
{|
|-
| style="padding: 0px 10px" | [[Controlling MXW through OSC]]
|-
| style="padding: 0px 30px" | ''Receiving OSC commands in MXW''
|-
| style="padding: 0px 30px 10px" | ''Output OSC from MXW: Send vs. Reply''
|-
| style="padding: 0px 10px 0px" | [[MXW OSC command structure]]
|-
| style="padding: 0px 30px" | ''Sending OSC Values''
|-
| style="padding: 0px 30px" | ''Examples''
|-
| style="padding: 10px" | [[OSC command reference]]
|-
| style="padding: 10px" | [[OSC Troubleshooting|Troubleshooting]]
|}
[[Category:OSC]]
[[Category:Reference]]

OSC Troubleshooting

2026-08-08T19:08:57Z

Admin: Admin moved page Troubleshooting to OSC Troubleshooting: Clarify: OSC-specific troubleshooting

Common issues that can arise while using OSC and MXW are generally linked to network malfunctions.

===Network diagnostics===

Make sure that the system you want to control is correctly connected to the same network as the ‘master’ machine.

==== To proof if the two machines are able to communicate in the network try to ping reciprocally the two systems: ====
:* For Windows users:
::1. Open the “Command Prompt” in the ‘master’ system as Administrator
::2. Type <code> ipconfig </code> take note of the IPv4 Address
::3. Repeat for the ‘slave’ system
::4.In the ‘master’ test if the other machine is reachable by typing <code> ping </code> followed by the IP of the ‘slave’ (e.g. <code> ping 192.168.178.7 </code>)
::5. If the machine is reachable a similar message will appear:
</div>
Pinging 192.168.178.7 with 32 bytes of data:
Reply from 192.168.178.7: bytes=32 time<1ms TTL=64
Reply from 192.168.178.7: bytes=32 time<1ms TTL=64
Reply from 192.168.178.7: bytes=32 time<1ms TTL=64
Reply from 192.168.178.7: bytes=32 time<1ms TTL=64

Ping statistics for 192.168.178.7:
Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
Minimum = 0ms, Maximum = 0ms, Average = 0ms
</div>
::* In case it is not reachable the message will show in the statistics
Received = 0 , Lost = 4 (100% Loss)
::* Repeat the steps sending the ping from the ‘slave’ to the ‘master’ IP to proof the connections
:* For Mac OS X users:
::1. Press “Apple” + "SPACE BAR" and search for “Terminal” in the ‘master’ system
::2. Type <code> ping </code> followed by the IP Address of the ‘slave’
::3. Proof if the ping get through
::4. Repeat for the ‘slave’ system pinging the IP of the ‘master’

==== In case of failure to connect: ====
:*Verify that the firewall is not blocking the communication:
::* For Windows users:
:::1. Search for “Firewall & Network Protection” in the “Start” menu
:::2. Deactivate all three (Domain, Private and Public) firewalls by entering the respective window and switching the protection to “Off” in all of them
::* For Mac OS X users:
:::1. In the Apple menu, select “System Preferences”
:::2. In the System Preferences window, select “Security and Privacy”
:::3. In the tab “Firewall” turn off the Firewall by pressing the “Turn Off” Button (10.6 or higher) or by deselecting the checkbox “Block all incoming connections” (10.5 or lower)
</div>
::* In your Router settings page (see the manufacturers manual for instructions) disable AP (access point) isolation, also known as 'Client Isolation' or 'Guest Mode' when active

==== In case of occasional loss of OSC packages: ====
::* The maximum size of every OSC package is defined by the MTU (minimum transport unit) of the network in use. Big packages tend to get lost more easily depending on the characteristics of the network so reducing the amount of big blobs (e.g. preview requests) can lower the loss rate. See
::* In case of loss of small packages, verify if the packages are getting sent and their size with a package sniffer (e.g. "Wireshark") and try different settings on your receiving console/device.
</br>
</br>
If none of the above solutions solves the issue try by restarting the software and reconnecting all the network chain from start.

For further diagnostics activate the Log of received data in MXW and the dispatch of livesigns (See Points 2.2 and 2.2 d. of the Open Sound Control References) to test the receiving and sending functionality on the wished OSC console, Pd patch or the Protokol App for a mobile option (see point 4.).

OSC Reference

2026-08-08T19:04:34Z

Admin: Remove index numbering from OSC contents (links + sub-items) (bot)

This reference applies to all different OS. The presented OSC commands are for most part supported in version 6.0 but will be fully functional in version 6.0.08 and above.
<div class="noprint">

== Introduction==
</div>
This document describes the MXWendler (MXW) OSC Command Interface through an overview of the command structure and practical examples of integration with external controlling software.

== What is OSC? ==
</div>
OSC or „Open Sound Control“ is a Network-based protocol that commonly utilizes the UDP transport mechanism. Originally developed as a successor of the MIDI control protocol, it used nowadays as a practical communication method between platforms.

OSC Features:
* Connectionless communication architecture
* Broadcast-type messages
* High resolution time tag
* Allowed data formats including numeric, symbolic, and “blob” arguments
* Open-ended, dynamic, URL-style naming scheme for the receivers' address

[https://en.wikipedia.org/wiki/Open_Sound_Control [1<nowiki>]</nowiki> Wikipedia Link]

== Contents ==
{|
|-
| style="padding: 0px 10px" | [[Controlling MXW through OSC]]
|-
| style="padding: 0px 30px" | ''Receiving OSC commands in MXW''
|-
| style="padding: 0px 30px 10px" | ''Output OSC from MXW: Send vs. Reply''
|-
| style="padding: 0px 10px 0px" | [[MXW OSC command structure]]
|-
| style="padding: 0px 30px" | ''Sending OSC Values''
|-
| style="padding: 0px 30px" | ''Examples''
|-
| style="padding: 10px" | [[OSC command reference]]
|-
| style="padding: 10px" | [[Troubleshooting]]
|}
[[Category:OSC]]
[[Category:Reference]]

OSC Troubleshooting

2026-08-08T19:04:14Z

Admin: Admin moved page 5. Troubleshooting to Troubleshooting: Remove leading index prefix from title

MXW OSC command structure

2026-08-08T19:04:13Z

Admin: Admin moved page 2. MXW OSC command structure to MXW OSC command structure: Remove leading index prefix from title

View source for 2. MXW OSC command structure
← 2. MXW OSC command structure
Jump to navigationJump to search
You do not have permission to edit this page, for the following reason:

The action you have requested is limited to users in the group: Users.

You can view and copy the source of this page.

Commands to the MXW OSC interface always follow the same syntax:

<code>/mxw/<address of widget> [MSGID] <float|integer|string></code>

for example:

<code>/mxw/track/1 0.5</code><br>
or:<br>
<code>/mxw/set play patch1</code><br>
or:<br>
<code>/mxw/playlist MSGID0001 info</code> <br>

Commands always begin with /mxw/ and it is followed by the address of the receiver and an argument that can be a numeric value, a string, or a combination of both.
The only optional element is the “Message-ID”.

== 2.1 Sending OSC Values ==
</div>
The command receivers listen to a value that is either a float or an integer (if they are widgets), or to strings (e.g. to choose patches or clips).
==== Faders ====
Receivers in MXW connected to faders in the user interface are responding to Float values. Floats are always in the range of 0.0 to 1.0 and will be scaled to the actual range of the recalled widget. <br>
For instance, the speed fader has a range in MXW that goes between -5 and 5 and its active range is dependent on the type of played media. <br> If a float value like 0.6 is sent to the OSC address of the clip speed, the fader moves to the value 1.0 (original speed of the clip).

==== Buttons and Checkboxes ====
Widgets in MXW that have an '''ON/OFF''' state accept integers as values. Buttons have the functions Press and Release assigned respectively to <code>1</code> and <code>0</code> and checkboxes have assigned ON and OFF respectively to <code>1</code> and <code>0</code>. </br> This means that if one wants to send a button press, e.g. a "play" button press, a value "0" has to be sent (to send a command, like with a mouse-click, a button must be pressed <u>and released</u> after)

==== Drop-down Boxes and Combo Boxes ====
Drop-down lists and Combo Boxes are indexed with integers ranging between <code>1</code> and the maximum number of elements. For example to select the third element of a list the integer <code>3</code> will be sent to the address of the Combo Box.

=== String Tokens ===
</div>
Specific string tokens can also be sent to the command receivers and they can respectively activate specific functions paired with a numeric value or another string. The usable strings are <code>play</code><code>info</code> <code>select</code> <code>preview</code> <code>clear</code>.
==== play ====
The string play can be sent together with another string containing the name of a saved patch in the address <code>/mxw/set </code> to start the playback of the recalled patch.

<code>/mxw/set play patch1</code>.
==== info ====
The string variable info can be sent to a specific address to acquire information about one field or clip through a reply sent by MXW.
The reply bundle coming from MXW will also be sent through OSC and will have this format:

* A reply header composed by:

1. Message <code>mxw/reply</code> <br>
2. <code>MSGID</code> (if specified in the info request)<br>
3. Address pattern of the request<br>
4. Time as a long variable<br>

* The actual '''reply content''' following this table:<br>

{| class="wikitable"
|-
! ADDRESS !! REPLY CONTENT
|-
| <code>/mxw/playlist info </code>|| 1. State of the playback (<code>play</code>, <code>paused</code>, <code>stopped</code>)
|-
| <code>/mxw/playlist/container/active info </code>|| 1. Active container index <br> 2. Number of columns <br> 3. Number of rows
|-
| <code>mxw/playlist/container/active/column/1/row/1 info </code>|| 1. Label of media in the container in column 1, row 1
|-
| <code>/mxw/track/active/layer/active/clip info </code>|| 1. Length of media <br> 2. Width <br>3. Height<br>4. ms per frame<br> 5. Completition of cache (<code>cachecomplete</code>/<code>cachenotcomplete</code>)<br> 6. Path directory of the active clip
|-
| <code>/mxw/preload/1 info </code>|| 1. Length of media <br> 2. Width <br>3. Height<br>4. ms per frame<br> 5. Completition of cache (<code>cachecomplete</code>/<code>cachenotcomplete</code>)<br> 6. Path directory of the media of the first preload
|-
| <code>mxw/keystone info </code>|| 1. Active keystone element index <br> 2. Name of active keystone element<br> 3. Amount of total keystone elements <br> 4. Names of keystone elements separated by commas <br> 5. Active softedge index <br> 6. Name of active softedge <br> 7. Amount of total softedges <br> 8. Names of softedges separated by commas <br> 9. Active grabber element index <br> 10. Name of active grabber element<br> 11. Amount of total grabber elements <br> 12. Names of grabber elements separated by commas <br> 13. Active blacklevel element index <br> 14. Name of active blacklevel element<br> 15. Amount of total blacklevel elements <br> 16. Names of blacklevel elements separated by commas
|-
| <code>mxw/keystone/element/1 info </code>|| 1. Element name <br> 2. Element type <br> 3. Video track number <br> 4. Video layer number <br> 5. Precision <br> 6. Number of pivots x <br> 7. Number of pivots y <br> 8. Scale <br> 9. Opacity <br> 10. Rotation of element number 1
|-
| <code>/mxw/keystone/element/1/pivot/col/1/row/1 info </code>|| 1. Pivot translation x <br> 2. Translation y <br> 3. Translation z <br> 4. UV value x <br> 5. UV values y <br> 6. UV normalized x <br> 7. UV normalized y <br> 8. RGB COLOUR
|-
| <code>mxw/layermanager info</code>|| 1. Active layer index <br> 2. Name of active layer <br> 3. Amount of total layers <br> 4. Names of layers separated by commas
|-
| <code>mxw/set info</code> || 1. Active patch index <br> 2. Name of active patch <br> 3. Amount of total patches <br> 4. Names of patches separated by commas
|-
| <code>mxw/trackmanager info</code>|| 1. Active track index <br> 2. Name of active track<br> 3. Amount of total tracks <br> 4. Names of tracks separated by commas
|-
| Addresses of Drop-down Boxes and Combo Boxes in MXW <br>(e.g. <code>mxw/render/effect info</code>)|| 1. Index and Name of currently selected item <br> 2. Amount of total items <br> 3. Names of items separated by commas
|-
| Addresses of Faders in MXW <br>(e.g. <code>mxw/render/opacity info</code> )|| 1. Value of position of fader (<code>0 .. 1</code>)
|-
| Addresses of Buttons/Checkboxes in MXW <br>(e.g. <code>mxw/track/1/crossfade info</code>)|| 1. State of the widget (<code>0 = released/OFF , 1 = pressed/ON</code>)
|-
|colspan="2" | NOTE: The token <code>active</code> can be substituted with an integer corresponding to the index of the wished element
|}

As an example, if we send:

<code>/mxw/playlist/container/active info</code>

MXWendler will reply:

<code>mxw/reply /mxw/playlist/container/active &emsp;&emsp;&emsp;&emsp;&emsp; 980451 &emsp;&emsp;&emsp;0 &emsp;&emsp;&emsp;&ensp;3 &emsp;&emsp; &emsp; 20</code> <br>
Reply Message Address of Request Time Index Col. Row

====select====
The token select can be added to different addresses to select the single elements on a list of many using a string. This command is can be used in combination with the token <code>info</code> as the names of the elements can be recalled with <code>info</code> first and then selected with the <code>select</code> token.
The receivers that respond with the token select are:
* trackmanager
* layermanager
* combo-boxes

<code>/mxw/trackmanager select track2</code>

====active====
The token active is used in the receiver address and can be used in multiple situations to act on the selected element of a list. For example the command:

<code>/mxw/track/active/fader 0.5</code>

will move the fader of the selected (active) track to his middle position, setting its opacity to 50%.

====preview====
The string preview can be used to get in return an OSC blob, containing a 128x128px '''jpg''' file that is a preview of the currently played media or a thumbnail of the selected clip. Here are the available addresses for a preview:
{| class="wikitable"
|-
! NAME !! ADDRESS
|-
| Render || <code>/mxw/render preview</code>
|-
| Track || <code>/mxw/track/active preview</code>
|-
| Layer || <code>/mxw/track/active/layer/active preview</code>
|-
| Clip || <code>/mxw/track/active/layer/active/clip preview</code>
|-
| Preload || <code>/mxw/preload/"preload index" preview</code> <br><code>/mxw/preload/7 preview</code>
|-
| Patch/Set || <code>/mxw/patch/"patch index" preview</code> <br> E.G.<code>/mxw/patch/3 preview</code>
|-
|colspan="2" | NOTE: The token <code>active</code> can be substituted with an integer corresponding to the index of the wished element
|}

====clear====

The function clear can be sent to the preloads to empty one of the preload spaces.

E.G. <code>mxw/preload/1 clear</code> will clear the first preload slot.

=== Message-ID ===
</div>
The “Message-ID” allows for clear communication and categorization of replies. When a command that generates a reply is sent, it is possible to prepend the command with a “Message-ID” which will be then in the reply as well. This message must have the format <code> MSGIDXXXX </code> and it must follow the OSC address like in the following example:

<code>/mxw/preload/3 MSGID0123 info</code>

will return a reply similar to:

<code>/mxw/reply MSGID0123 /mxw/preload/3 112 320 240 40 cachecomplete c:\footage\clip.avi</code>

== 2.2 Examples ==
To address the main fader and fade the opacity of the render from zero to full in ten steps, you would send a command sequence:
<br>
<code>/mxw/render 0.0</code><br>
<code>/mxw/render 0.1</code><br>
<code>/mxw/render 0.2</code><br>
<code>/mxw/render 0.3</code><br>
<code>/mxw/render 0.4</code><br>
<code>/mxw/render 0.5</code><br>
<code>/mxw/render 0.6</code><br>
<code>/mxw/render 0.7</code><br>
<code>/mxw/render 0.8</code><br>
<code>/mxw/render 0.9</code><br>
<code>/mxw/render 1.0</code>

Finer-grained values can be sent if needed. The commands will be evaluated as soon as they arrive in MXW and the last command before a new frame is drawn will set the widget's value.

<code>/mxw/track/active 0.5</code><br>Sets the active track opacity to 0.5

<code>/mxw/track/1 0.5</code><br>Sets track 1 opacity to 0.5

<code>/mxw/preload/1/trigger 1.0</code><br>Adds a layer with the contents of preload slot 1

<code>/mxw/track/1/layer/1/opacity 0.5</code><br>Sets the opacity of the first layer of the first track to 0.5 (if there is a layer playing content)

<code>/mxw/set 5</code><br>The active track will load patch 5

<code>/mxw/track/active/layer/active/clip/speed 0.6</code><br>Sets the speed of the clip of the active layer of the active track to 1.0 (0.6 translates to 1.0 in a -5 .. +5 range)

<code>/mxw/track/active/layer/active/clip/speed 0.5</code><br>Sets the speed of the clip of the active layer of the active track to 0.5 (clip stops)

<code>/mxw/trackmanager 1</code><br>Activate the first track

<code>/mxw/trackmanager 3</code><br>Activate the third track

<code>/mxw/trackmanager select track3</code><br>Activate the third track

<code>/mxw/track/2/layer/1/clip/effect/2 select ag_AnimWarp</code><br>Instructs the clip of the first layer of the second track to load the effect with the name "ag_AnimWarp" in the effect slot number 2

<code>/mxw/track/2/layer/1/clip/effect/1/param/1 0.8</code><br>Set to the value of 0.8, the parameter 1 of the first effect of the clip of the first layer of the second track

<code>/mxw/preload/2 c:/footage/clip.avi</code><br>Preload slot 2 will load c:/footage/clip.avi (and answer with info). Note the direction of the slashes.

<code>/mxw/preload/2 clear</code><br>Preload slot 2 will unload

<code>/mxw/preload/2 info</code><br>Preload 2 will answer with clip info like <br>
<code>/mxw/reply /mxw/preload/3 112 320 240 40 cachecomplete
c:\footage\clip.avi</code>

<code>/mxw/preload/2 MSGID0123 info</code><br>Preload 2 will answer with clip info like <br>
<code>/mxw/reply MSGID0123 /mxw/preload/3 112 320 240 40 cachecomplete c:\footage\clip.avi</code>

<code>/mxw/master/load_showfile c:/footage/showfile.mxw</code><br>Load the stated showfile

<code>/mxw/master/load_keystonefile c:/footage/keystonefile.mxw_keystone2</code><br>Load the stated keystonefile

Controlling MXW through OSC

2026-08-08T19:04:11Z

Admin: Admin moved page 1. Controlling MXW through OSC to Controlling MXW through OSC: Remove leading index prefix from title

MXW is designed to be a high-performance real-time video software for media servers. It interactively composites high-resolution footage and interactive media.
OSC commands can be generated, sent, and received by MXWendler and a wide range of applications: signaling frameworks like Pure Data, Max/MSP, TouchOSC, and TouchDesigner, audio workstations like Ableton Live, Logic, or Protools, programming environments like Processing, Perl, Java, Unity, and TidalCycles, other Multimedia, Sensoring, Signal Processing software, Microcontrollers and many more, offering a compatible and fast intercommunication method.

Separating the media server from the controlling infrastructure offers various creative and usability options:

*Control multiple machines from one single point
*Control a single machine from multiple points
*Replicate a state into a remote system
*Custom user interfaces
*Intercommunication with external software and platforms
*Control via WAN
*Control via a microcontroller
*Connect scene-analysis with scene-composition systems
*Extract control features e.g mapping or triggering

<div class="noprint">
== 1.1 Receiving OSC commands in MXW ==
</div>

To enable OSC receiving open the software MXWendler: <br>
1. In '''Menu: Settings → Input and Output ''(CTRL+1)'' →''' in the tab '''OSC''', activate the box '''Receive OSC''' ( '''(A)''' In the following picture) <br>
2. Set the port ( 7000 is recommended as an OSC Standard) <br>
3. The box '''Log received data''' will log commands in the Error and Log Window visible through '''Menu: Settings → Error and Log Window ''(CTRL+SHFT+L)'' ''' <br>

This is particularly useful for testing and troubleshooting as it will make visible what OSC commands are received by MXW. The logging of data has a performance impact on the system so it is important to turn it off when not in use.
As this option is marked (r) in the menu, to activate the changes, please restart the software.
<div class="noprint">

== 1.2 Output OSC from MXW: Send vs. Reply ==
</div>
MXW can send OSC commands as well. Multiple distinct options are available in '''Menu: Settings → Input and Output ''(CTRL+1)'' →''' tab '''OSC''' : <br>

[[File:mxwIO.png|728px]]

{{#mpdftags: pagebreak}}

=== Broadcast and Receive Time over OSC '''(B)''' ===
This option will broadcast the MXW time into the selected subnet to synchronize the time among a pool of machines.
To achieve this a selection mechanism is applied: every machine sends its time until it receives the time from a machine with a lower IP address. In the end, the machine with the lowest IP is selected as the 'master' and controls the pool clock.
IO Events can be forwarded by selecting the relative checkbox. You can for example connect a MIDI device and it will send the MIDI events to the pool.

=== Receive OSC over RS232 '''(C)''' ===
Check this box if the OSC commands are received through a Serial Port instead of a network port. Options for port selection and integer indexing are available.

=== Send OSC '''(D)''' ===
This option will send any action on the running host to another host/network defined in the command options. Moving a track slider will generate the commands that make the track slider in the remote machine move to the same position. The goal is to make another machine (pretended it carries the same media data) produce exactly the same result as the master machine by sending osc commands to replicate the same behaviour.
Sometimes it is desireable to send only a selction of the generated actions. You can filter the sent commands using the following rules:
<br>
- Adding a + before a *token*, [comment(optional)]<br>
- Adding a - before a token*, [comment(optional)]<br>
<br>
The *token* is a part of the string like "playlist" or "opacity", a comment can be added after a comma in case we want to specify the reason of the filter. So adding the line <code>+,*playlist*</code> will result into that only commands containing the keyword "playlist" will be sent. In the same way using the filter <code>-,*opacity*, opacity_does_not_change</code> any command referring to "opacity" will not be sent through and everything else will.

=== OSC reply channel '''(E)''' ===
Many OSC commands are capable of asking for specific information e.g. the name of a clip in the preload or the playback status of the playlist. This option must be active in MXW to allow the software to reply to the received OSC commands. Options for a specific IP address of the host/subnet and Port are given in the settings. The last checkbox “Send periodical livesigns” allows to receive a constant periodical flow of data from MXW regarding performance and render information, useful as well for diagnostic reasons.

OSC Reference

2026-08-08T19:02:08Z

Admin: Remove useless '6. External links' entry from contents (bot)

This reference applies to all different OS. The presented OSC commands are for most part supported in version 6.0 but will be fully functional in version 6.0.08 and above.
<div class="noprint">

== Introduction==
</div>
This document describes the MXWendler (MXW) OSC Command Interface through an overview of the command structure and practical examples of integration with external controlling software.

== What is OSC? ==
</div>
OSC or „Open Sound Control“ is a Network-based protocol that commonly utilizes the UDP transport mechanism. Originally developed as a successor of the MIDI control protocol, it used nowadays as a practical communication method between platforms.

OSC Features:
* Connectionless communication architecture
* Broadcast-type messages
* High resolution time tag
* Allowed data formats including numeric, symbolic, and “blob” arguments
* Open-ended, dynamic, URL-style naming scheme for the receivers' address

[https://en.wikipedia.org/wiki/Open_Sound_Control [1<nowiki>]</nowiki> Wikipedia Link]

== Contents ==
{|
|-
| style="padding: 0px 10px" | [[1. Controlling MXW through OSC]]
|-
| style="padding: 0px 30px" | ''1.1 Receiving OSC commands in MXW''
|-
| style="padding: 0px 30px 10px" | ''1.2 Output OSC from MXW: Send vs. Reply''
|-
| style="padding: 0px 10px 0px" | [[2. MXW OSC command structure]]
|-
| style="padding: 0px 30px" | ''2.1 Sending OSC Values''
|-
| style="padding: 0px 30px" | ''2.2 Examples''
|-
| style="padding: 10px" | [[OSC command reference]]
|-
| style="padding: 10px" | [[5. Troubleshooting]]
|}
[[Category:OSC]]
[[Category:Reference]]

OSC Reference

2026-08-08T19:00:26Z

Admin: Remove outdated 'Practical examples: Pure Data and TouchOSC' entry from contents (bot)

This reference applies to all different OS. The presented OSC commands are for most part supported in version 6.0 but will be fully functional in version 6.0.08 and above.
<div class="noprint">

== Introduction==
</div>
This document describes the MXWendler (MXW) OSC Command Interface through an overview of the command structure and practical examples of integration with external controlling software.

== What is OSC? ==
</div>
OSC or „Open Sound Control“ is a Network-based protocol that commonly utilizes the UDP transport mechanism. Originally developed as a successor of the MIDI control protocol, it used nowadays as a practical communication method between platforms.

OSC Features:
* Connectionless communication architecture
* Broadcast-type messages
* High resolution time tag
* Allowed data formats including numeric, symbolic, and “blob” arguments
* Open-ended, dynamic, URL-style naming scheme for the receivers' address

[https://en.wikipedia.org/wiki/Open_Sound_Control [1<nowiki>]</nowiki> Wikipedia Link]

== Contents ==
{|
|-
| style="padding: 0px 10px" | [[1. Controlling MXW through OSC]]
|-
| style="padding: 0px 30px" | ''1.1 Receiving OSC commands in MXW''
|-
| style="padding: 0px 30px 10px" | ''1.2 Output OSC from MXW: Send vs. Reply''
|-
| style="padding: 0px 10px 0px" | [[2. MXW OSC command structure]]
|-
| style="padding: 0px 30px" | ''2.1 Sending OSC Values''
|-
| style="padding: 0px 30px" | ''2.2 Examples''
|-
| style="padding: 10px" | [[OSC command reference]]
|-
| style="padding: 10px" | [[5. Troubleshooting]]
|-
| style="padding: 10px" | [[6. External links]]
|}
[[Category:OSC]]
[[Category:Reference]]

Python Reference

2026-08-08T18:58:04Z

Admin: Point TOC to de-numbered 'Controlling MXW through Python'; drop index prefixes (bot)

== Introduction ==
This document describes the MXWendler (MXW) Python command interface through an overview of the programming structure, with practical examples of automation and internal scripting. The presented Python commands are for most part supported in version 7.2.

== What is Python? ==
Python is a standardized interpreted, high level programming language. It is used in many applications, mainly in AI and generative tasks. The amount of available libraries is outstanding.

== Contents ==
{|
|-
| style="padding: 10px" | [[Controlling MXW through Python]]
|-
| style="padding: 10px" | [[Python command reference]]
|-
| style="padding: 10px" | [[Python imgui reference]]
|-
| style="padding: 10px" | [[Python plugin reference]]
|-
|}
[[Category:Python]]
[[Category:Reference]]

Controlling MXW through Python

2026-08-08T18:58:03Z

Admin: Admin moved page 1. Controlling MXW through Python to Controlling MXW through Python: Remove leading index prefix from title

MXWendler StageDesigner embeds '''Python 3.12'''. Python is used in two ways:

* '''Command interface / scripting''' – the module <code>mxw</code> controls the running software (playlist, layers, clips, media, I/O, widgets by their address, ...) from the script console or from within a plugin.
* '''Plugins''' – self-contained folders that add a media source or a playlist item and are called back by the host through a defined set of functions (''hooks'').

'''The presented Python interface is supported in version 7.2. and up'''

== Where to go ==

The detailed documentation lives on three dedicated pages; this page only points to them so nothing is documented twice.

{| class="wikitable"
|-
! Topic !! Page
|-
| The <code>mxw</code> command interface – software info, <code>playlist</code>, <code>io</code>, <code>widget(address)</code>, <code>media(name)</code>, <code>preload(n)</code>, <code>grabber(name)</code> || [[Python command reference|Python command reference]]
|-
| Drawing plugin settings panels with <code>mxw_imgui</code> (MXWendler's Dear ImGui binding) || [[Python imgui reference|Python ImGui reference]]
|-
| Writing '''plugins''' – media and playlist – the manifest (<code>mxw_plugin.ini</code>), the hooks, per-instance state, examples || [[Python plugin reference|Python plugin reference]]
|}

== Quick start ==

A minimal look at each entry point; follow the links above for the full reference.

'''Scripting.''' From the script console (or any hook), the <code>mxw</code> module reaches the software:

<syntaxhighlight lang="Python" line>
import mxw
mxw.print_console("frame " + str(mxw.framecounter))
mxw.playlist.play()
mxw.widget("/mxw/track/active/layer/active/opacity").setValue(0.5)
</syntaxhighlight>

'''Plugins.''' A plugin is a folder holding a manifest and a Python module:

<pre>
plugins/playlist/python/plugin_my_item/
mxw_plugin.ini the manifest: identity, menu entries
mxw_main.py the Python module with the hook functions
</pre>

The host discovers it at startup, shows it in the user interface and calls its hooks at the right moments. See the [[Python plugin reference|Python plugin reference]] for the manifest fields, the full hook list for media and playlist plugins, plugin locations, installing extra packages with <code>mxw-pip</code>, and complete examples.

== See also ==

* [[Python command reference|Python command reference]] – the <code>mxw</code> module
* [[Python imgui reference|Python ImGui reference]] – drawing plugin panels with <code>mxw_imgui</code>
* [[Python plugin reference|Python plugin reference]] – writing media and playlist plugins

JavaScript Reference

2026-08-08T18:51:36Z

Admin: Point TOC to de-numbered page titles; drop index prefixes (bot)

External Resources

2026-08-08T18:51:22Z

Admin: Admin moved page 6. External Resources to External Resources: Remove leading index prefix from title

</br>
1 https://en.wikipedia.org/wiki/JavaScript</br>
2 https://developer.mozilla.org/en-US/docs/Web/JavaScript </br>
3 https://curlie.org/Computers/Programming/Languages/JavaScript/ </br>
4 https://duktape.org/index.html </br>

Troubleshooting scripts

2026-08-08T18:51:21Z

Admin: Admin moved page 5. Troubleshooting scripts to Troubleshooting scripts: Remove leading index prefix from title

'''Problem'''

JavaScript is not functioning as intended. No corresponding action happens when the trigger button for the event is pressed.

'''Hints'''

# Open the JavaScript console by pressing Ctrl+Shift+J (Mac:Command+Shift+J) and look for error messages.
# Check for syntax errors in your code and ensure that interface functions are written correctly.
# Check that predefined hooks and functions like e.g. on_trigger() are written correctly. Syntax highlighting and coloring may help you identify these issues.
# When resolving widgets, verify the used widgets address (e.g. "/mxw/render/opacity") and make sure that it is valid. To find the correct address, maybe refer to the list of address suggestions available in the 'Receiver' menu.

Practical examples

2026-08-08T18:51:19Z

Admin: Admin moved page 4. Practical examples to Practical examples: Remove leading index prefix from title

Download the Javascript Reference folder from https://www.mxwendler.net/de/downloads.html

1) Double click on the "js-demo.mxw" to load the demo.<div>

2) Open the I/O Settings Window (CTRL+1) or click on "Settings" → "Inputs and Outputs - Keyboard, Midi, DMX" <div>
&emsp; and click on SHOW JAVASCRIPT CONSOLE, almost at the bottom of the I/O window.

3) Follow the instructions on the Javascript Console. <div>

===Commands:===

Remember to click on the interface header before giving commands,
the operating System needs to know where the keyboard signals are directed.

<code>backspace</code> starts the patch and selects the LiveEditor Tab.
<div>
<code>spacebar</code> (6 times at least) to set up a tap tempo
<div>
<code>1</code> Sets the render opacity to 0
<div>
<code>2</code> Sets the render opacity to 0.5
<div>
<code>3</code> Sets the render opacity to 1
<div>
<code>4</code> Writes Output informations on the Javascript console.
Takes a screenshot of the output and saves it in "C:\screen"
(if the directory already exists)

Controlling MXW through JavaScript

2026-08-08T18:51:18Z

Admin: Admin moved page 1. Controlling MXW through JavaScript to Controlling MXW through JavaScript: Remove leading index prefix from title

Although there are many ways to control MXWendler with a lot of I/O devices, e.g. mouse buttons, keyboard, DMX and MIDI devices, and automation commands in MXWendler using events in the playlist, some desired behaviours are too complex to be offered through a GUI element.
JavaScript allows instead to script any animation and behaviour sequence. Additionally, JavaScript allows you to emit values to I/O devices like DMX, OSC or MIDI and set various internal variables in media and in the software.

The JavaScript engine used by the MXWendler scripting is Duktape, standardized under ECMAScript E5/E5.1. (more info at the Duktape [https://duktape.org/index.html website])

To write JavaScripts open MXWendler "StageDesigner" or "FxServer" and access the editor by clicking "Settings" → "Inputs and Outputs - Keyboard, Midi, DMX" (or with the hotkey <code>CTRL + 1</code>)
<div>

[[File:Open settings.jpeg|728px]]
{{#mpdftags: pagebreak}}
<div>
On the window, in the first tab ("DMX/Midi/Keyboard Events") the editor is available in the lower right corner.
<div>

[[File:Editor.jpeg|728px]]
{{#mpdftags: pagebreak}}
<div>

To facilitate debugging, a script-wide function "print_console" is available and the Javascript console is available to be opened from either the checkbox under the editor, or from the menu: "Settings" → "Open Javascript Console" (<code>CTRL + J</code>)

Python imgui reference

2026-08-08T18:00:10Z

Admin: Fix example (mxw.print_console) and repoint broken Python Plugin Howto link (bot)

Here are listed the commands available in module <code>mxw_imgui</code>, MXWendler's Python binding of '''Dear ImGui'''. This is how plugins draw their settings panel, in the <code>onRenderPanel()</code> hook (see the [[Python plugin reference|Python plugin reference]]).

<code>mxw_imgui</code> mirrors the Dear ImGui C++ API almost function-for-function: the C++ <code>ImGui::PascalCase</code> names become Python <code>snake_case</code>, one argument at a time. If you already know Dear ImGui (or its C++/other-language bindings), the name of a call is usually a mechanical translation away.

=== Legend ===
<div>

Everything from the [[Python_Reference|Python Reference]] Legend applies (floats, integers, strings, <u>OR</u> for alternative formats). In addition:

Dear ImGui widgets that take a pointer to their value in C++ (so the value can be written back) instead return a '''tuple''' <code>(changed, value)</code> in Python: <code>changed</code> is <code>true</code> when the user edited the widget this frame, <code>value</code> is the (possibly new) value to keep and pass back in next frame. E.g.:

<code>changed, value = mxw_imgui.slider_float("Speed", value, 0.0, 1.0)</code>

Widgets with several packed floats/ints (<code>drag_float2</code>, <code>slider_int4</code>, ...) take and return a plain Python list/tuple of that length instead of a C array.

'''Flags''' (<code>ImGuiTreeNodeFlags</code>, <code>ImGuiWindowFlags</code>, <code>ImGuiCol</code>, ...) are '''not''' exposed as named Python constants — pass the plain integer value of the Dear ImGui enum (default <code>0</code> means "no flags" for nearly every call). Consult the Dear ImGui headers/docs for the numeric values if you need non-default flags.

Parameters shown as <code>= value</code> in the tables below are '''optional''' with that default; omit them to use the default.

Plugins draw '''into an existing panel''' — there is no <code>begin</code>/<code>end</code> for top-level windows; start directly with widget calls.

</div>

=== Data types ===

{| class="wikitable"
|-
! PYTHON TYPE !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.Vec2()</code> OR <code>mxw_imgui.Vec2(x, y)</code> || 2D float vector (<code>.x</code>, <code>.y</code>), used for sizes and positions || <code>size = mxw_imgui.Vec2(200, 0)</code>
|-
|<code>mxw_imgui.Vec4()</code> OR <code>mxw_imgui.Vec4(x, y, z, w)</code> || 4D float vector (<code>.x</code>, <code>.y</code>, <code>.z</code>, <code>.w</code>), used for colors (RGBA) and rectangles || <code>col = mxw_imgui.Vec4(1.0, 0.0, 0.0, 1.0)</code>
|-
|<code>mxw_imgui.Vector_char</code>, <code>Vector_float</code>, <code>Vector_unsignedchar</code>, <code>Vector_unsignedshort</code>, <code>Vector_DrawCmd</code>, <code>Vector_DrawVert</code>, <code>Vector_FontGlyph</code> || Read-only iterable wrappers around Dear ImGui's internal <code>ImVector<T></code> buffers, returned by some getters (e.g. draw list data). Support <code>len()</code>, iteration and indexing || <code>for glyph in font.Glyphs: pass</code>
|}

=== Style & Fonts ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.push_font(font)</code> || push a font onto the font stack for subsequent widgets || <code>mxw_imgui.push_font(mxw_imgui.get_font())</code>
|-
|<code>mxw_imgui.pop_font()</code> || pop the last pushed font || <code>mxw_imgui.pop_font()</code>
|-
|<code>mxw_imgui.push_style_color(idx, col)</code> || push a style color override (<code>col</code> as packed <code>u32</code> OR <code>Vec4</code>) || <code>mxw_imgui.push_style_color(0, mxw_imgui.Vec4(1,0,0,1))</code>
|-
|<code>mxw_imgui.pop_style_color(count = 1)</code> || pop <code>count</code> previously pushed style colors || <code>mxw_imgui.pop_style_color()</code>
|-
|<code>mxw_imgui.push_style_var(idx, val)</code> || push a style var override (<code>val</code> as float OR <code>Vec2</code>) || <code>mxw_imgui.push_style_var(0, 4.0)</code>
|-
|<code>mxw_imgui.pop_style_var(count = 1)</code> || pop <code>count</code> previously pushed style vars || <code>mxw_imgui.pop_style_var()</code>
|-
|<code>mxw_imgui.push_allow_keyboard_focus(allow_keyboard_focus)</code> || allow/disallow tab-focusing the next widgets || <code>mxw_imgui.push_allow_keyboard_focus(false)</code>
|-
|<code>mxw_imgui.pop_allow_keyboard_focus()</code> || pop the keyboard-focus override || <code>mxw_imgui.pop_allow_keyboard_focus()</code>
|-
|<code>mxw_imgui.push_button_repeat(repeat)</code> || make subsequent buttons behave as repeating (held = repeated clicks) || <code>mxw_imgui.push_button_repeat(true)</code>
|-
|<code>mxw_imgui.pop_button_repeat()</code> || pop the button-repeat override || <code>mxw_imgui.pop_button_repeat()</code>
|-
|<code>mxw_imgui.get_font()</code> || returns the current font object || <code>f = mxw_imgui.get_font()</code>
|-
|<code>mxw_imgui.get_font_size()</code> || returns the current font size in px || <code>sz = mxw_imgui.get_font_size()</code>
|-
|<code>mxw_imgui.get_font_tex_uv_white_pixel()</code> || returns UV coordinate of a white pixel in the font texture, for custom draw-list use || <code>uv = mxw_imgui.get_font_tex_uv_white_pixel()</code>
|-
|<code>mxw_imgui.get_color_u32(idx, alpha_mul = 1.0)</code> OR <code>mxw_imgui.get_color_u32(col)</code> || resolve a style color index, a <code>Vec4</code>, or a packed <code>u32</code> to a final packed <code>u32</code> color || <code>c = mxw_imgui.get_color_u32(0)</code>
|-
|<code>mxw_imgui.get_style_color_vec4(idx)</code> || returns the raw <code>Vec4</code> for a style color index || <code>c = mxw_imgui.get_style_color_vec4(0)</code>
|-
|<code>mxw_imgui.get_style_color_name(idx)</code> || returns the readable name of a style color index || <code>mxw.print_console(mxw_imgui.get_style_color_name(0))</code>
|-
|<code>mxw_imgui.set_color_edit_options(flags)</code> || set default flags for every subsequent color_edit/color_picker call || <code>mxw_imgui.set_color_edit_options(0)</code>
|}

=== Cursor & Layout ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.push_item_width(item_width)</code> || push a fixed width (px, or negative = right-aligned) for subsequent widgets || <code>mxw_imgui.push_item_width(150)</code>
|-
|<code>mxw_imgui.pop_item_width()</code> || pop the pushed item width || <code>mxw_imgui.pop_item_width()</code>
|-
|<code>mxw_imgui.set_next_item_width(item_width)</code> || set the width of just the next widget || <code>mxw_imgui.set_next_item_width(300)</code>
|-
|<code>mxw_imgui.calc_item_width()</code> || returns the width the next widget would use || <code>w = mxw_imgui.calc_item_width()</code>
|-
|<code>mxw_imgui.push_text_wrap_pos(wrap_local_pos_x = 0.0)</code> || push a word-wrap position (0 = wrap at window edge) for subsequent text || <code>mxw_imgui.push_text_wrap_pos()</code>
|-
|<code>mxw_imgui.pop_text_wrap_pos()</code> || pop the pushed wrap position || <code>mxw_imgui.pop_text_wrap_pos()</code>
|-
|<code>mxw_imgui.separator()</code> || draw a thin horizontal separator line || <code>mxw_imgui.separator()</code>
|-
|<code>mxw_imgui.same_line(offset_from_start_x = 0.0, spacing = -1.0)</code> || keep the next widget on the same line as the previous one || <code>mxw_imgui.same_line()</code>
|-
|<code>mxw_imgui.new_line()</code> || force a following widget to start on a new line || <code>mxw_imgui.new_line()</code>
|-
|<code>mxw_imgui.spacing()</code> || add vertical spacing || <code>mxw_imgui.spacing()</code>
|-
|<code>mxw_imgui.dummy(size)</code> || reserve an empty invisible <code>size</code> (<code>Vec2</code>) area, e.g. as a spacer || <code>mxw_imgui.dummy(mxw_imgui.Vec2(0, 10))</code>
|-
|<code>mxw_imgui.indent(indent_w = 0.0)</code> || move the cursor right (indent) || <code>mxw_imgui.indent()</code>
|-
|<code>mxw_imgui.unindent(indent_w = 0.0)</code> || move the cursor back left (unindent), matching a prior indent() || <code>mxw_imgui.unindent()</code>
|-
|<code>mxw_imgui.begin_group()</code> || start a layout group (following widgets are treated as one unit for layout purposes) || <code>mxw_imgui.begin_group()</code>
|-
|<code>mxw_imgui.end_group()</code> || close the current layout group || <code>mxw_imgui.end_group()</code>
|-
|<code>mxw_imgui.get_cursor_pos()</code> || returns the cursor position (<code>Vec2</code>) relative to the current window || <code>p = mxw_imgui.get_cursor_pos()</code>
|-
|<code>mxw_imgui.get_cursor_pos_x()</code> OR <code>mxw_imgui.get_cursor_pos_y()</code> || returns just the X or Y cursor coordinate || <code>x = mxw_imgui.get_cursor_pos_x()</code>
|-
|<code>mxw_imgui.set_cursor_pos(local_pos)</code> || set the cursor position (<code>Vec2</code>), window-relative || <code>mxw_imgui.set_cursor_pos(mxw_imgui.Vec2(0, 0))</code>
|-
|<code>mxw_imgui.set_cursor_pos_x(local_x)</code> OR <code>mxw_imgui.set_cursor_pos_y(local_y)</code> || set just the X or Y cursor coordinate || <code>mxw_imgui.set_cursor_pos_x(20)</code>
|-
|<code>mxw_imgui.get_cursor_start_pos()</code> || returns the initial cursor position of the current window/child || <code>p = mxw_imgui.get_cursor_start_pos()</code>
|-
|<code>mxw_imgui.get_cursor_screen_pos()</code> || returns the cursor position in absolute screen coordinates || <code>p = mxw_imgui.get_cursor_screen_pos()</code>
|-
|<code>mxw_imgui.set_cursor_screen_pos(pos)</code> || set the cursor in absolute screen coordinates || <code>mxw_imgui.set_cursor_screen_pos(p)</code>
|-
|<code>mxw_imgui.align_text_to_frame_padding()</code> || vertically align following text with standard framed widgets on the same line || <code>mxw_imgui.align_text_to_frame_padding()</code>
|-
|<code>mxw_imgui.get_text_line_height()</code> OR <code>mxw_imgui.get_text_line_height_with_spacing()</code> || returns one text line's height, with or without inter-line spacing || <code>h = mxw_imgui.get_text_line_height()</code>
|-
|<code>mxw_imgui.get_frame_height()</code> OR <code>mxw_imgui.get_frame_height_with_spacing()</code> || returns a standard framed widget's height, with or without spacing || <code>h = mxw_imgui.get_frame_height()</code>
|}

=== ID stack ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.push_id(str_id)</code> OR <code>mxw_imgui.push_id(str_id_begin, str_id_end)</code> OR <code>mxw_imgui.push_id(ptr_id)</code> OR <code>mxw_imgui.push_id(int_id)</code> || push a scope onto the ID stack, so same-labelled widgets in a loop don't collide || <code>mxw_imgui.push_id(i)</code>
|-
|<code>mxw_imgui.pop_id()</code> || pop the last pushed ID scope || <code>mxw_imgui.pop_id()</code>
|-
|<code>mxw_imgui.get_id(str_id)</code> OR <code>mxw_imgui.get_id(str_id_begin, str_id_end)</code> OR <code>mxw_imgui.get_id(ptr_id)</code> || compute a widget ID without pushing it || <code>uid = mxw_imgui.get_id("my_widget")</code>
|}

=== Text ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.text_unformatted(text, text_end = None)</code> || draw raw text, faster than <code>text()</code> for long/dynamic strings (no format parsing) || <code>mxw_imgui.text_unformatted("Ready.")</code>
|-
|<code>mxw_imgui.text(fmt)</code> || draw a line of text || <code>mxw_imgui.text("Frame: " + str(mxw.framecounter))</code>
|-
|<code>mxw_imgui.text_colored(col, fmt)</code> || draw text in the given <code>Vec4</code> color || <code>mxw_imgui.text_colored(mxw_imgui.Vec4(1,0,0,1), "Error")</code>
|-
|<code>mxw_imgui.text_disabled(fmt)</code> || draw text in the disabled/grey style color || <code>mxw_imgui.text_disabled("(no signal)")</code>
|-
|<code>mxw_imgui.text_wrapped(fmt)</code> || draw text that wraps at the window edge, regardless of the wrap-pos stack || <code>mxw_imgui.text_wrapped(status_message)</code>
|-
|<code>mxw_imgui.label_text(label, fmt)</code> || draw a "label: value"-style line (label aligned like other widgets) || <code>mxw_imgui.label_text("Status", "OK")</code>
|-
|<code>mxw_imgui.bullet_text(fmt)</code> || draw a bulleted line of text || <code>mxw_imgui.bullet_text("first item")</code>
|}

=== Main widgets ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.button(label, size = Vec2(0,0))</code> || a clickable button; returns <code>true</code> the frame it's clicked || <code>if mxw_imgui.button("Reload"): reload()</code>
|-
|<code>mxw_imgui.small_button(label)</code> || a button with no extra vertical padding, fits inline with text || <code>if mxw_imgui.small_button("x"): close()</code>
|-
|<code>mxw_imgui.invisible_button(str_id, size, flags = 0)</code> || an invisible clickable/draggable area || <code>mxw_imgui.invisible_button("drag_area", mxw_imgui.Vec2(50,50))</code>
|-
|<code>mxw_imgui.arrow_button(str_id, dir)</code> || a small square button with an arrow glyph (<code>dir</code>: 0=left,1=right,2=up,3=down) || <code>mxw_imgui.arrow_button("up", 2)</code>
|-
|<code>mxw_imgui.image(user_texture_id, size, uv0 = Vec2(0,0), uv1 = Vec2(1,1), tint_col = Vec4(1,1,1,1), border_col = Vec4(0,0,0,0))</code> || draw a texture (GL texture id) as an image || <code>mxw_imgui.image(tex_id, mxw_imgui.Vec2(128,128))</code>
|-
|<code>mxw_imgui.image_button(user_texture_id, size, uv0 = Vec2(0,0), uv1 = Vec2(1,1), frame_padding = -1, bg_col = Vec4(0,0,0,0), tint_col = Vec4(1,1,1,1))</code> || a clickable image button || <code>if mxw_imgui.image_button(tex_id, mxw_imgui.Vec2(32,32)): pass</code>
|-
|<code>mxw_imgui.checkbox(label, v)</code> || a checkbox; <code>v</code>/return is <code>bool</code> || <code>changed, enabled = mxw_imgui.checkbox("Enabled", enabled)</code>
|-
|<code>mxw_imgui.checkbox_flags(label, flags, flags_value)</code> || a checkbox that toggles one bit(mask) of an int flags value || <code>changed, flags = mxw_imgui.checkbox_flags("Bit 1", flags, 1)</code>
|-
|<code>mxw_imgui.radio_button(label, active)</code> OR <code>mxw_imgui.radio_button(label, v, v_button)</code> || a radio button; single-bool form for manual state, or bind directly to an int selection variable || <code>changed, mode = mxw_imgui.radio_button("Mode A", mode, 0)</code>
|-
|<code>mxw_imgui.progress_bar(fraction, size_arg = Vec2(-FLT_MIN, 0), overlay = None)</code> || a progress bar, <code>fraction</code> 0.0..1.0 || <code>mxw_imgui.progress_bar(0.5)</code>
|-
|<code>mxw_imgui.bullet()</code> || draw just a bullet glyph, e.g. before inline text/widgets || <code>mxw_imgui.bullet()</code>
|}

=== Combo box ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.combo(label, current_item, items, popup_max_height_in_items = -1)</code> || a combo box built from a Python list of strings; simplest way to pick one of several options || <code>changed, sel = mxw_imgui.combo("Mode", sel, ["A", "B", "C"])</code>
|-
|<code>mxw_imgui.begin_combo(label, preview_value, flags = 0)</code> / <code>mxw_imgui.end_combo()</code> || low-level combo box: build the popup content yourself (e.g. with <code>selectable()</code>) between these two calls || <code>if mxw_imgui.begin_combo("Mode", preview): mxw_imgui.end_combo()</code>
|}

=== Drag sliders ===
Click-and-drag widgets; typing is also possible (Ctrl+click / double-click).

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.drag_float(label, v, v_speed = 1.0, v_min = 0.0, v_max = 0.0, format = None, flags = 0)</code> || drag a single float; <code>v_min == v_max == 0</code> means unbounded || <code>changed, value = mxw_imgui.drag_float("Speed", value, 0.01, 0.0, 2.0)</code>
|-
|<code>mxw_imgui.drag_float2(label, v, ...)</code> / <code>drag_float3</code> / <code>drag_float4</code> || same, for a list of 2/3/4 floats (e.g. a color or position) || <code>changed, xyz = mxw_imgui.drag_float3("Position", xyz)</code>
|-
|<code>mxw_imgui.drag_float_range2(label, v_current_min, v_current_max, v_speed = 1.0, v_min = 0.0, v_max = 0.0, format = None, format_max = None, flags = 0)</code> || drag a min/max float range with two handles || <code>changed, lo, hi = mxw_imgui.drag_float_range2("Range", lo, hi)</code>
|-
|<code>mxw_imgui.drag_int(label, v, v_speed = 1.0, v_min = 0, v_max = 0, format = None, flags = 0)</code> || drag a single int || <code>changed, value = mxw_imgui.drag_int("Count", value, 1, 0, 10)</code>
|-
|<code>mxw_imgui.drag_int2(label, v, ...)</code> / <code>drag_int3</code> / <code>drag_int4</code> || same, for a list of 2/3/4 ints || <code>changed, rgb = mxw_imgui.drag_int3("RGB", rgb, 1, 0, 255)</code>
|-
|<code>mxw_imgui.drag_int_range2(label, v_current_min, v_current_max, ...)</code> || drag a min/max int range with two handles || <code>changed, lo, hi = mxw_imgui.drag_int_range2("Range", lo, hi)</code>
|-
|<code>mxw_imgui.drag_scalar(label, data_type, p_data, v_speed, p_min = None, p_max = None, format = None, flags = 0)</code> / <code>drag_scalar_n(..., components, ...)</code> || generic drag widget for any <code>ImGuiDataType</code>, rarely needed from Python || <code>mxw_imgui.drag_scalar("Value", 0, ptr, 1.0)</code>
|}

=== Sliders ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.slider_float(label, v, v_min, v_max, format = None, flags = 0)</code> || slide a single float between <code>v_min</code> and <code>v_max</code> || <code>changed, value = mxw_imgui.slider_float("Mouse X", value, 0.0, 1.0)</code>
|-
|<code>mxw_imgui.slider_float2(label, v, v_min, v_max, ...)</code> / <code>slider_float3</code> / <code>slider_float4</code> || same, for a list of 2/3/4 floats || <code>changed, rgba = mxw_imgui.slider_float4("Color", rgba, 0.0, 1.0)</code>
|-
|<code>mxw_imgui.slider_angle(label, v_rad, v_degrees_min = -360.0, v_degrees_max = 360.0, format = None, flags = 0)</code> || slide an angle, stored in radians but displayed/typed in degrees || <code>changed, rot = mxw_imgui.slider_angle("Rotation", rot)</code>
|-
|<code>mxw_imgui.slider_int(label, v, v_min, v_max, format = None, flags = 0)</code> || slide a single int || <code>changed, idx = mxw_imgui.slider_int("Preset", idx, 0, 99)</code>
|-
|<code>mxw_imgui.slider_int2(label, v, v_min, v_max, ...)</code> / <code>slider_int3</code> / <code>slider_int4</code> || same, for a list of 2/3/4 ints || <code>changed, xy = mxw_imgui.slider_int2("Grid pos", xy, 0, 10)</code>
|-
|<code>mxw_imgui.slider_scalar(label, data_type, p_data, p_min, p_max, format = None, flags = 0)</code> / <code>slider_scalar_n(..., components, ...)</code> || generic slider for any <code>ImGuiDataType</code>, rarely needed from Python || <code>mxw_imgui.slider_scalar("Value", 0, ptr, p_min, p_max)</code>
|-
|<code>mxw_imgui.v_slider_float(label, size, v, v_min, v_max, format = None, flags = 0)</code> || vertical slider variant of <code>slider_float</code> || <code>changed, value = mxw_imgui.v_slider_float("##vol", mxw_imgui.Vec2(20,100), value, 0.0, 1.0)</code>
|-
|<code>mxw_imgui.v_slider_int(label, size, v, v_min, v_max, format = None, flags = 0)</code> || vertical slider variant of <code>slider_int</code> || <code>changed, value = mxw_imgui.v_slider_int("##lvl", mxw_imgui.Vec2(20,100), value, 0, 10)</code>
|-
|<code>mxw_imgui.v_slider_scalar(label, size, data_type, p_data, p_min, p_max, format = None, flags = 0)</code> || generic vertical slider for any <code>ImGuiDataType</code> || <code>mxw_imgui.v_slider_scalar("##v", size, 0, ptr, p_min, p_max)</code>
|}

=== Input widgets ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.input_text(label, data, max_size, flags = 0)</code> || a single-line text field; <code>data</code> is the current string, <code>max_size</code> the max length in bytes || <code>changed, value = mxw_imgui.input_text("URL", url_text, 512)</code>
|-
|<code>mxw_imgui.input_text_multiline(label, data, max_size, size = Vec2(0,0), flags = 0)</code> || a multi-line text field || <code>changed, value = mxw_imgui.input_text_multiline("Notes", notes, 2048, mxw_imgui.Vec2(300,100))</code>
|-
|<code>mxw_imgui.input_float(label, v, step = 0.0, step_fast = 0.0, format = None, flags = 0)</code> || a typed float field with optional +/- step buttons || <code>changed, value = mxw_imgui.input_float("Gain", value, 0.1)</code>
|-
|<code>mxw_imgui.input_float2(label, v, ...)</code> / <code>input_float3</code> / <code>input_float4</code> || same, for a list of 2/3/4 floats || <code>changed, xyz = mxw_imgui.input_float3("Pos", xyz)</code>
|-
|<code>mxw_imgui.input_int(label, v, step = 1, step_fast = 100, flags = 0)</code> || a typed int field with +/- step buttons || <code>changed, value = mxw_imgui.input_int("Count", value)</code>
|-
|<code>mxw_imgui.input_int2(label, v, flags = 0)</code> / <code>input_int3</code> / <code>input_int4</code> || same, for a list of 2/3/4 ints || <code>changed, rgb = mxw_imgui.input_int3("RGB", rgb)</code>
|-
|<code>mxw_imgui.input_double(label, v, step = 0.0, step_fast = 0.0, format = None, flags = 0)</code> || a typed double field || <code>changed, value = mxw_imgui.input_double("Precise", value)</code>
|-
|<code>mxw_imgui.input_scalar(label, data_type, p_data, p_step = None, p_step_fast = None, format = None, flags = 0)</code> / <code>input_scalar_n(..., components, ...)</code> || generic typed field for any <code>ImGuiDataType</code>, rarely needed from Python || <code>mxw_imgui.input_scalar("Value", 0, ptr)</code>
|}

=== Color editor & picker ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.color_edit3(label, col, flags = 0)</code> || a compact RGB color editor (swatch + popup picker); <code>col</code> is a 3-float list || <code>changed, rgb = mxw_imgui.color_edit3("Tint", rgb)</code>
|-
|<code>mxw_imgui.color_edit4(label, col, flags = 0)</code> || same, RGBA (4-float list) || <code>changed, rgba = mxw_imgui.color_edit4("Tint", rgba)</code>
|-
|<code>mxw_imgui.color_picker3(label, col, flags = 0)</code> || a full RGB color picker widget, always expanded || <code>changed, rgb = mxw_imgui.color_picker3("Tint", rgb)</code>
|-
|<code>mxw_imgui.color_picker4(label, col, flags = 0, ref_col = None)</code> || same, RGBA, optionally showing a reference color for comparison || <code>changed, rgba = mxw_imgui.color_picker4("Tint", rgba)</code>
|-
|<code>mxw_imgui.color_button(desc_id, col, flags = 0, size = Vec2(0,0))</code> || a non-editable color swatch button (e.g. as a preview/trigger) || <code>if mxw_imgui.color_button("preview", col): open_picker()</code>
|}

=== Trees ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.tree_node(label)</code> OR <code>mxw_imgui.tree_node(str_id, fmt)</code> OR <code>mxw_imgui.tree_node(ptr_id, fmt)</code> || an expandable/collapsible tree node; returns <code>true</code> while open. Call <code>tree_pop()</code> if it returned <code>true</code> || <code>if mxw_imgui.tree_node("Advanced"): mxw_imgui.tree_pop()</code>
|-
|<code>mxw_imgui.tree_node_ex(label, flags = 0)</code> OR <code>mxw_imgui.tree_node_ex(str_id, flags, fmt)</code> OR <code>mxw_imgui.tree_node_ex(ptr_id, flags, fmt)</code> || <code>tree_node()</code> with explicit flags (e.g. default-open, leaf, selected) || <code>if mxw_imgui.tree_node_ex("Node", 0): mxw_imgui.tree_pop()</code>
|-
|<code>mxw_imgui.tree_push(str_id)</code> OR <code>mxw_imgui.tree_push(ptr_id = None)</code> || push an indent level without drawing a node (paired with <code>tree_pop()</code>) || <code>mxw_imgui.tree_push("scope"); mxw_imgui.tree_pop()</code>
|-
|<code>mxw_imgui.tree_pop()</code> || pop one indent level pushed by <code>tree_node()</code>/<code>tree_push()</code> || <code>mxw_imgui.tree_pop()</code>
|-
|<code>mxw_imgui.get_tree_node_to_label_spacing()</code> || returns the horizontal spacing between a tree node arrow and its label || <code>s = mxw_imgui.get_tree_node_to_label_spacing()</code>
|-
|<code>mxw_imgui.collapsing_header(label, flags = 0)</code> OR <code>mxw_imgui.collapsing_header(label, p_visible, flags = 0)</code> || a top-level collapsible section header; optionally with a close ("x") button when <code>p_visible</code> is passed || <code>if mxw_imgui.collapsing_header("Settings"): mxw_imgui.text("...")</code>
|-
|<code>mxw_imgui.set_next_item_open(is_open, cond = 0)</code> || force the next <code>tree_node()</code>/<code>collapsing_header()</code> open/closed state || <code>mxw_imgui.set_next_item_open(true)</code>
|}

=== Selectables & list boxes ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.selectable(label, selected = false, flags = 0, size = Vec2(0,0))</code> OR <code>mxw_imgui.selectable(label, p_selected, flags = 0, size = Vec2(0,0))</code> || a clickable, highlightable row (typically inside a list box) || <code>if mxw_imgui.selectable("Item 1", is_sel): pick(1)</code>
|-
|<code>mxw_imgui.begin_list_box(label, size = Vec2(0,0))</code> / <code>mxw_imgui.end_list_box()</code> || low-level list box: build the rows yourself (e.g. with <code>selectable()</code>) between these two calls || <code>if mxw_imgui.begin_list_box("Items"): mxw_imgui.end_list_box()</code>
|-
|<code>mxw_imgui.list_box(label, current_item, items, height_in_items = -1)</code> || a list box built from a Python list of strings, single-select || <code>changed, sel = mxw_imgui.list_box("Presets", sel, ["A", "B", "C"])</code>
|-
|<code>mxw_imgui.list_box_stretch(label, current_item, items)</code> || MXWendler custom variant of <code>list_box()</code> that stretches to fill the remaining panel height || <code>changed, sel = mxw_imgui.list_box_stretch("Presets", sel, names)</code>
|}

=== Data plotting ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.plot_lines(label, values, values_offset = 0, overlay_text = None, scale_min = FLT_MAX, scale_max = FLT_MAX, graph_size = Vec2(0,0))</code> || draw a line graph from a Python list of floats || <code>mxw_imgui.plot_lines("Levels", history)</code>
|-
|<code>mxw_imgui.plot_histogram(label, values, values_offset = 0, overlay_text = None, scale_min = FLT_MAX, scale_max = FLT_MAX, graph_size = Vec2(0,0))</code> || draw a bar histogram from a Python list of floats || <code>mxw_imgui.plot_histogram("Levels", history)</code>
|}

=== Value() helpers ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.value(prefix, b)</code> OR <code>mxw_imgui.value(prefix, v)</code> (int/uint) OR <code>mxw_imgui.value(prefix, v, float_format = None)</code> || draw a "prefix: value" line for a bool/int/float, without building the string yourself || <code>mxw_imgui.value("FPS", mxw.fps)</code>
|}

=== Menus ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.begin_menu_bar()</code> / <code>mxw_imgui.end_menu_bar()</code> || start/end a menu bar inside the current window || <code>if mxw_imgui.begin_menu_bar(): mxw_imgui.end_menu_bar()</code>
|-
|<code>mxw_imgui.begin_main_menu_bar()</code> / <code>mxw_imgui.end_main_menu_bar()</code> || start/end the application's main (top-level) menu bar || <code>if mxw_imgui.begin_main_menu_bar(): mxw_imgui.end_main_menu_bar()</code>
|-
|<code>mxw_imgui.begin_menu(label, enabled = true)</code> / <code>mxw_imgui.end_menu()</code> || start/end a (sub)menu; call <code>end_menu()</code> only if <code>begin_menu()</code> returned <code>true</code> || <code>if mxw_imgui.begin_menu("File"): mxw_imgui.end_menu()</code>
|-
|<code>mxw_imgui.menu_item(label, shortcut = None, selected = false, enabled = true)</code> OR <code>mxw_imgui.menu_item(label, shortcut, p_selected, enabled = true)</code> || a clickable (optionally checkable) menu entry || <code>if mxw_imgui.menu_item("Save", "Ctrl+S"): save()</code>
|}

=== Tooltips ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.begin_tooltip()</code> / <code>mxw_imgui.end_tooltip()</code> || build a custom tooltip (any widgets) between these two calls || <code>mxw_imgui.begin_tooltip(); mxw_imgui.text("info"); mxw_imgui.end_tooltip()</code>
|-
|<code>mxw_imgui.set_tooltip(fmt)</code> || a quick one-line tooltip for the last hovered item || <code>if mxw_imgui.is_item_hovered(): mxw_imgui.set_tooltip("Explain this")</code>
|}

=== Popups & modals ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.open_popup(str_id, flags = 0)</code> || flag a popup to open (by ID) on the next matching <code>begin_popup()</code> || <code>mxw_imgui.open_popup("confirm_delete")</code>
|-
|<code>mxw_imgui.begin_popup(str_id, flags = 0)</code> / <code>mxw_imgui.end_popup()</code> || build a plain popup's content; call <code>end_popup()</code> only if <code>begin_popup()</code> returned <code>true</code> || <code>if mxw_imgui.begin_popup("menu"): mxw_imgui.end_popup()</code>
|-
|<code>mxw_imgui.begin_popup_modal(name, p_open = None, flags = 0)</code> || build a modal popup's content (blocks interaction with the rest of the UI) || <code>opened, _ = mxw_imgui.begin_popup_modal("Confirm")</code>
|-
|<code>mxw_imgui.open_popup_on_item_click(str_id = None, popup_flags = 1)</code> || open a popup when the last item is clicked (e.g. right-click context menu) || <code>mxw_imgui.open_popup_on_item_click("ctx")</code>
|-
|<code>mxw_imgui.close_current_popup()</code> || close the popup currently being drawn (e.g. after a button inside it) || <code>if mxw_imgui.button("OK"): mxw_imgui.close_current_popup()</code>
|-
|<code>mxw_imgui.begin_popup_context_item(str_id = None, popup_flags = 1)</code> || combined open+begin for a right-click context popup on the last item || <code>if mxw_imgui.begin_popup_context_item(): mxw_imgui.end_popup()</code>
|-
|<code>mxw_imgui.begin_popup_context_window(str_id = None, popup_flags = 1)</code> || same, anchored to the current window instead of the last item || <code>if mxw_imgui.begin_popup_context_window(): mxw_imgui.end_popup()</code>
|-
|<code>mxw_imgui.begin_popup_context_void(str_id = None, popup_flags = 1)</code> || same, opens on right-click on empty space (no window/item under cursor) || <code>if mxw_imgui.begin_popup_context_void(): mxw_imgui.end_popup()</code>
|-
|<code>mxw_imgui.is_popup_open(str_id, flags = 0)</code> || returns whether the given popup is currently open || <code>open = mxw_imgui.is_popup_open("menu")</code>
|}

=== Tables ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.begin_table(str_id, column, flags = 0, outer_size = Vec2(0,0), inner_width = 0.0)</code> / <code>mxw_imgui.end_table()</code> || start/end a table; call <code>end_table()</code> only if <code>begin_table()</code> returned <code>true</code> || <code>if mxw_imgui.begin_table("grid", 3): mxw_imgui.end_table()</code>
|-
|<code>mxw_imgui.table_next_row(row_flags = 0, min_row_height = 0.0)</code> || start the next table row || <code>mxw_imgui.table_next_row()</code>
|-
|<code>mxw_imgui.table_next_column()</code> || advance to the next cell (wraps to the next row automatically) || <code>mxw_imgui.table_next_column()</code>
|-
|<code>mxw_imgui.table_set_column_index(column_n)</code> || jump directly to a given column in the current row || <code>mxw_imgui.table_set_column_index(1)</code>
|-
|<code>mxw_imgui.table_setup_column(label, flags = 0, init_width_or_weight = 0.0, user_id = 0)</code> || declare a column's header label / sizing before the first row || <code>mxw_imgui.table_setup_column("Name")</code>
|-
|<code>mxw_imgui.table_setup_scroll_freeze(cols, rows)</code> || freeze N leading columns/rows while the rest scrolls || <code>mxw_imgui.table_setup_scroll_freeze(0, 1)</code>
|-
|<code>mxw_imgui.table_headers_row()</code> || draw the header row from the declared <code>table_setup_column()</code> labels || <code>mxw_imgui.table_headers_row()</code>
|-
|<code>mxw_imgui.table_header(label)</code> || draw a single header cell manually (instead of <code>table_headers_row()</code>) || <code>mxw_imgui.table_header("Name")</code>
|-
|<code>mxw_imgui.table_get_sort_specs()</code> || returns the current column sort specification, if the table is sortable || <code>specs = mxw_imgui.table_get_sort_specs()</code>
|-
|<code>mxw_imgui.table_get_column_count()</code> || returns the number of columns of the current table || <code>n = mxw_imgui.table_get_column_count()</code>
|-
|<code>mxw_imgui.table_get_column_index()</code> || returns the current column index || <code>i = mxw_imgui.table_get_column_index()</code>
|-
|<code>mxw_imgui.table_get_row_index()</code> || returns the current row index || <code>i = mxw_imgui.table_get_row_index()</code>
|-
|<code>mxw_imgui.table_get_column_name(column_n = -1)</code> || returns a column's declared label (-1 = current column) || <code>name = mxw_imgui.table_get_column_name(0)</code>
|-
|<code>mxw_imgui.table_get_column_flags(column_n = -1)</code> || returns a column's current flags (e.g. is it hidden/sorted) || <code>flags = mxw_imgui.table_get_column_flags()</code>
|-
|<code>mxw_imgui.table_set_bg_color(target, color, column_n = -1)</code> || set the background color of a cell/row/column || <code>mxw_imgui.table_set_bg_color(0, mxw_imgui.color_convert_float4_to_u32(mxw_imgui.Vec4(1,0,0,1)))</code>
|}

=== Legacy columns ===
Superseded by [[#Tables|Tables]] above, kept for compatibility.

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.columns(count = 1, id = None, border = true)</code> || switch the rest of the window into a simple N-column layout (<code>count = 1</code> ends it) || <code>mxw_imgui.columns(2)</code>
|-
|<code>mxw_imgui.next_column()</code> || move to the next column (wraps to the next row) || <code>mxw_imgui.next_column()</code>
|-
|<code>mxw_imgui.get_column_index()</code> || returns the current column index || <code>i = mxw_imgui.get_column_index()</code>
|-
|<code>mxw_imgui.get_column_width(column_index = -1)</code> / <code>mxw_imgui.set_column_width(column_index, width)</code> || get/set a column's width || <code>w = mxw_imgui.get_column_width()</code>
|-
|<code>mxw_imgui.get_column_offset(column_index = -1)</code> / <code>mxw_imgui.set_column_offset(column_index, offset_x)</code> || get/set a column's X offset || <code>x = mxw_imgui.get_column_offset()</code>
|-
|<code>mxw_imgui.get_columns_count()</code> || returns the current column count || <code>n = mxw_imgui.get_columns_count()</code>
|}

=== Tabs ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.begin_tab_bar(str_id, flags = 0)</code> / <code>mxw_imgui.end_tab_bar()</code> || start/end a tab bar; call <code>end_tab_bar()</code> only if <code>begin_tab_bar()</code> returned <code>true</code> || <code>if mxw_imgui.begin_tab_bar("tabs"): mxw_imgui.end_tab_bar()</code>
|-
|<code>mxw_imgui.begin_tab_item(label, p_open = None, flags = 0)</code> / <code>mxw_imgui.end_tab_item()</code> || start/end one tab's content; call <code>end_tab_item()</code> only if <code>begin_tab_item()</code> returned <code>true</code> || <code>opened, _ = mxw_imgui.begin_tab_item("Settings")</code>
|-
|<code>mxw_imgui.tab_item_button(label, flags = 0)</code> || a button drawn as a tab (e.g. a "+" to add a tab) || <code>if mxw_imgui.tab_item_button("+"): add_tab()</code>
|-
|<code>mxw_imgui.set_tab_item_closed(tab_or_docked_window_label)</code> || programmatically close a tab by label || <code>mxw_imgui.set_tab_item_closed("Old Tab")</code>
|}

=== Logging / capture ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.log_to_tty(auto_open_depth = -1)</code> || start capturing following widgets' text output to the app's TTY/console || <code>mxw_imgui.log_to_tty()</code>
|-
|<code>mxw_imgui.log_to_file(auto_open_depth = -1, filename = None)</code> || start capturing to a file || <code>mxw_imgui.log_to_file(-1, "log.txt")</code>
|-
|<code>mxw_imgui.log_to_clipboard(auto_open_depth = -1)</code> || start capturing to the OS clipboard || <code>mxw_imgui.log_to_clipboard()</code>
|-
|<code>mxw_imgui.log_finish()</code> || stop the current capture || <code>mxw_imgui.log_finish()</code>
|-
|<code>mxw_imgui.log_buttons()</code> || draw the standard "Log/Copy to clipboard" buttons || <code>mxw_imgui.log_buttons()</code>
|-
|<code>mxw_imgui.log_text(fmt)</code> || add text directly to the active log capture, without drawing a widget || <code>mxw_imgui.log_text("captured line")</code>
|}

=== Drag and drop ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.begin_drag_drop_source(flags = 0)</code> / <code>mxw_imgui.end_drag_drop_source()</code> || make the last item a drag source; build the payload/preview between these two calls || <code>if mxw_imgui.begin_drag_drop_source(): mxw_imgui.end_drag_drop_source()</code>
|-
|<code>mxw_imgui.set_drag_drop_payload(type, data, sz, cond = 0)</code> || attach a payload to the drag currently being sourced || <code>mxw_imgui.set_drag_drop_payload("CLIP", data, len(data))</code>
|-
|<code>mxw_imgui.begin_drag_drop_target()</code> / <code>mxw_imgui.end_drag_drop_target()</code> || make the last item/window a drop target; check <code>accept_drag_drop_payload()</code> between these two calls || <code>if mxw_imgui.begin_drag_drop_target(): mxw_imgui.end_drag_drop_target()</code>
|-
|<code>mxw_imgui.accept_drag_drop_payload(type, flags = 0)</code> || accept a payload of the given type while inside a drop target || <code>p = mxw_imgui.accept_drag_drop_payload("CLIP")</code>
|-
|<code>mxw_imgui.get_drag_drop_payload()</code> || peek the payload of the drag currently in progress, even outside a target || <code>p = mxw_imgui.get_drag_drop_payload()</code>
|}

=== Clipping ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.push_clip_rect(clip_rect_min, clip_rect_max, intersect_with_current_clip_rect)</code> || push a manual clipping rectangle (<code>Vec2</code> corners) for subsequent drawing || <code>mxw_imgui.push_clip_rect(p_min, p_max, true)</code>
|-
|<code>mxw_imgui.pop_clip_rect()</code> || pop the pushed clip rect || <code>mxw_imgui.pop_clip_rect()</code>
|}

=== Focus & activation ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.set_item_default_focus()</code> || make the last item the one focused by default when the panel first appears || <code>mxw_imgui.set_item_default_focus()</code>
|-
|<code>mxw_imgui.set_keyboard_focus_here(offset = 0)</code> || focus the next widget for keyboard input (e.g. auto-focus a text field) || <code>mxw_imgui.set_keyboard_focus_here()</code>
|}

=== Item / widgets utilities ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.is_item_hovered(flags = 0)</code> || returns whether the last item is hovered by the mouse || <code>if mxw_imgui.is_item_hovered(): mxw_imgui.set_tooltip("info")</code>
|-
|<code>mxw_imgui.is_item_active()</code> || returns whether the last item is currently active (e.g. being held/edited) || <code>active = mxw_imgui.is_item_active()</code>
|-
|<code>mxw_imgui.is_item_focused()</code> || returns whether the last item has keyboard focus || <code>focused = mxw_imgui.is_item_focused()</code>
|-
|<code>mxw_imgui.is_item_clicked(mouse_button = 0)</code> || returns whether the last item was clicked this frame || <code>if mxw_imgui.is_item_clicked(): pass</code>
|-
|<code>mxw_imgui.is_item_visible()</code> || returns whether the last item is visible (not clipped) || <code>visible = mxw_imgui.is_item_visible()</code>
|-
|<code>mxw_imgui.is_item_edited()</code> || returns whether the last item's value changed this frame || <code>edited = mxw_imgui.is_item_edited()</code>
|-
|<code>mxw_imgui.is_item_activated()</code> || returns whether the last item just became active this frame || <code>started = mxw_imgui.is_item_activated()</code>
|-
|<code>mxw_imgui.is_item_deactivated()</code> || returns whether the last item just stopped being active this frame || <code>stopped = mxw_imgui.is_item_deactivated()</code>
|-
|<code>mxw_imgui.is_item_deactivated_after_edit()</code> || returns whether the last item stopped being active after its value changed (e.g. commit-on-release) || <code>if mxw_imgui.is_item_deactivated_after_edit(): save()</code>
|-
|<code>mxw_imgui.is_item_toggled_open()</code> || returns whether the last tree node/collapsing header was just opened or closed || <code>toggled = mxw_imgui.is_item_toggled_open()</code>
|-
|<code>mxw_imgui.is_any_item_hovered()</code> / <code>mxw_imgui.is_any_item_active()</code> / <code>mxw_imgui.is_any_item_focused()</code> || returns whether any item at all is hovered/active/focused || <code>busy = mxw_imgui.is_any_item_active()</code>
|-
|<code>mxw_imgui.get_item_rect_min()</code> / <code>mxw_imgui.get_item_rect_max()</code> / <code>mxw_imgui.get_item_rect_size()</code> || returns the last item's bounding rectangle (screen-space corners, or size) || <code>size = mxw_imgui.get_item_rect_size()</code>
|-
|<code>mxw_imgui.set_item_allow_overlap()</code> || allow the next widget to visually overlap the last item without stealing its hover/click || <code>mxw_imgui.set_item_allow_overlap()</code>
|}

=== Viewport & miscellaneous ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.get_main_viewport()</code> || returns the main viewport object (position/size of the whole application) || <code>vp = mxw_imgui.get_main_viewport()</code>
|-
|<code>mxw_imgui.is_rect_visible(size)</code> OR <code>mxw_imgui.is_rect_visible(rect_min, rect_max)</code> || returns whether a rectangle at the cursor (or explicit corners) is visible/unclipped || <code>visible = mxw_imgui.is_rect_visible(mxw_imgui.Vec2(50,50))</code>
|-
|<code>mxw_imgui.get_time()</code> || returns Dear ImGui's internal time in seconds (accumulates while the app runs) || <code>t = mxw_imgui.get_time()</code>
|-
|<code>mxw_imgui.get_frame_count()</code> || returns the number of ImGui frames rendered so far || <code>n = mxw_imgui.get_frame_count()</code>
|-
|<code>mxw_imgui.get_background_draw_list()</code> / <code>mxw_imgui.get_foreground_draw_list()</code> || returns the draw list rendered behind/in front of all windows, for custom drawing || <code>dl = mxw_imgui.get_foreground_draw_list()</code>
|-
|<code>mxw_imgui.get_draw_list_shared_data()</code> || returns data shared across draw lists (font atlas, clip rect stack, ...), rarely needed from Python || <code>d = mxw_imgui.get_draw_list_shared_data()</code>
|-
|<code>mxw_imgui.set_state_storage(storage)</code> / <code>mxw_imgui.get_state_storage()</code> || set/get the key-value storage backing tree/collapsing-header open states || <code>s = mxw_imgui.get_state_storage()</code>
|-
|<code>mxw_imgui.begin_child_frame(id, size, flags = 0)</code> / <code>mxw_imgui.end_child_frame()</code> || a framed, scrollable child region (styled like a text/list box) || <code>if mxw_imgui.begin_child_frame(1, mxw_imgui.Vec2(0,100)): mxw_imgui.end_child_frame()</code>
|-
|<code>mxw_imgui.calc_text_size(text, text_end = None, hide_text_after_double_hash = false, wrap_width = -1.0)</code> || returns the pixel size a string would occupy with the current font || <code>w = mxw_imgui.calc_text_size("0").x</code>
|}

=== Color utilities ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.color_convert_u32_to_float4(in)</code> || convert a packed <code>u32</code> color to a <code>Vec4</code> || <code>col = mxw_imgui.color_convert_u32_to_float4(0xFFFFFFFF)</code>
|-
|<code>mxw_imgui.color_convert_float4_to_u32(in)</code> || convert a <code>Vec4</code> color to a packed <code>u32</code> || <code>u = mxw_imgui.color_convert_float4_to_u32(mxw_imgui.Vec4(1,1,1,1))</code>
|-
|<code>mxw_imgui.color_convert_rg_bto_hsv(r, g, b)</code> || returns <code>(h, s, v)</code> for the given RGB floats (0.0..1.0) || <code>h, s, v = mxw_imgui.color_convert_rg_bto_hsv(1.0, 0.0, 0.0)</code>
|-
|<code>mxw_imgui.color_convert_hs_vto_rgb(h, s, v)</code> || returns <code>(r, g, b)</code> for the given HSV floats (0.0..1.0) || <code>r, g, b = mxw_imgui.color_convert_hs_vto_rgb(0.0, 1.0, 1.0)</code>
|}

=== Keyboard input ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.get_key_index(imgui_key)</code> || map a Dear ImGui <code>ImGuiKey_*</code> value to the user's backend key index || <code>idx = mxw_imgui.get_key_index(0)</code>
|-
|<code>mxw_imgui.is_key_down(user_key_index)</code> || returns whether a key is currently held down || <code>held = mxw_imgui.is_key_down(idx)</code>
|-
|<code>mxw_imgui.is_key_pressed(user_key_index, repeat = true)</code> || returns whether a key was just pressed (optionally auto-repeating while held) || <code>if mxw_imgui.is_key_pressed(idx): pass</code>
|-
|<code>mxw_imgui.is_key_released(user_key_index)</code> || returns whether a key was just released || <code>if mxw_imgui.is_key_released(idx): pass</code>
|-
|<code>mxw_imgui.get_key_pressed_amount(key_index, repeat_delay, rate)</code> || returns how many times a key auto-repeated this frame, given a delay/rate || <code>n = mxw_imgui.get_key_pressed_amount(idx, 0.3, 0.1)</code>
|}

=== Mouse input ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.is_mouse_down(button)</code> || returns whether a mouse button is currently held (0=left,1=right,2=middle) || <code>held = mxw_imgui.is_mouse_down(0)</code>
|-
|<code>mxw_imgui.is_mouse_clicked(button, repeat = false)</code> || returns whether a mouse button was just clicked || <code>if mxw_imgui.is_mouse_clicked(0): pass</code>
|-
|<code>mxw_imgui.is_mouse_released(button)</code> || returns whether a mouse button was just released || <code>if mxw_imgui.is_mouse_released(0): pass</code>
|-
|<code>mxw_imgui.is_mouse_double_clicked(button)</code> || returns whether a mouse button was just double-clicked || <code>if mxw_imgui.is_mouse_double_clicked(0): pass</code>
|-
|<code>mxw_imgui.is_mouse_hovering_rect(r_min, r_max, clip = true)</code> || returns whether the mouse is over the given screen-space rectangle || <code>over = mxw_imgui.is_mouse_hovering_rect(p_min, p_max)</code>
|-
|<code>mxw_imgui.is_mouse_pos_valid(mouse_pos = None)</code> || returns whether the (current or given) mouse position is valid (app has focus etc.) || <code>valid = mxw_imgui.is_mouse_pos_valid()</code>
|-
|<code>mxw_imgui.is_any_mouse_down()</code> || returns whether any mouse button is currently held || <code>held = mxw_imgui.is_any_mouse_down()</code>
|-
|<code>mxw_imgui.get_mouse_pos()</code> || returns the current mouse position (<code>Vec2</code>, screen-space) || <code>p = mxw_imgui.get_mouse_pos()</code>
|-
|<code>mxw_imgui.get_mouse_pos_on_opening_current_popup()</code> || returns the mouse position captured when the current popup was opened || <code>p = mxw_imgui.get_mouse_pos_on_opening_current_popup()</code>
|-
|<code>mxw_imgui.is_mouse_dragging(button, lock_threshold = -1.0)</code> || returns whether the mouse is dragging with the given button held || <code>dragging = mxw_imgui.is_mouse_dragging(0)</code>
|-
|<code>mxw_imgui.get_mouse_drag_delta(button = 0, lock_threshold = -1.0)</code> || returns the drag distance (<code>Vec2</code>) since the drag started || <code>d = mxw_imgui.get_mouse_drag_delta()</code>
|-
|<code>mxw_imgui.reset_mouse_drag_delta(button = 0)</code> || reset the tracked drag distance for a button || <code>mxw_imgui.reset_mouse_drag_delta()</code>
|-
|<code>mxw_imgui.get_mouse_cursor()</code> / <code>mxw_imgui.set_mouse_cursor(cursor_type)</code> || get/set the desired OS mouse cursor shape || <code>mxw_imgui.set_mouse_cursor(1)</code>
|}

=== Clipboard ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.get_clipboard_text()</code> || returns the current OS clipboard text || <code>txt = mxw_imgui.get_clipboard_text()</code>
|-
|<code>mxw_imgui.set_clipboard_text(text)</code> || set the OS clipboard text || <code>mxw_imgui.set_clipboard_text("copied value")</code>
|}

=== Disabled blocks & MXWendler extras ===
The last two functions are MXWendler additions, not part of stock Dear ImGui bindings.

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.begin_disabled(disabled = false)</code> / <code>mxw_imgui.end_disabled()</code> || grey out and block interaction with all widgets in between || <code>mxw_imgui.begin_disabled(not enabled); mxw_imgui.button("Go"); mxw_imgui.end_disabled()</code>
|-
|<code>mxw_imgui.render_frame(p_min, p_max, colf, border = true, rounding = 0.0)</code> || draw a filled/bordered rectangle (screen-space corners as <code>Vec2</code>, color as <code>Vec4</code>) directly, e.g. for custom backgrounds || <code>mxw_imgui.render_frame(mxw_imgui.Vec2(0,0), mxw_imgui.Vec2(100,20), mxw_imgui.Vec4(0.2,0.2,0.2,1))</code>
|}
[[Category:Python]]
[[Category:Reference]]

Tutorial Eventmaster Toolset Controlling MXWendler by e.g. e2 S3 Image Processor

2026-08-08T15:41:17Z

Admin: Update link after renaming to 'OSC command reference' (bot)

This tutorial applies to all different OS and MXWendler versions > 6.0.04

== Introduction==
This tutorial explains how to set up a Barco Eventmaster to trigger and control media playback on StageDesigner or FXServer.

==Control Setup==

1. Open SD (StageDesigner) and load a clip into preload 1:

[[File:e2_01.png|600px]]

2. Open Settings->IO->Barco e2 and activate TCP listening. Also note down the port number.

[[File:e2_02.png|600px]]

3. In the Barco Eventmaster Toolset, create an 'External Device', name it e.g. 'StageDesigner'.

[[File:e2_03.png|600px]]

4. In the 'Adjust: StageDesigner' tab, set IP address and port number.

[[File:e2_04.png|600px]]

5. In the 'Adjust: StageDesigner' tab, add a new command. Store the command content, e.g.
* /mxw/preload/1 play to start a clip
* /mxw/preload/1 play to stop a clip

More possible commands are in the OSC control section: [[OSC command reference]]

[[File:e2_05.png|600px]]

6. In the 'Cue' section, add a cue.

[[File:e2_06.png|600px]]

7. In this 'Cue', add actions.

[[File:e2_07.png|600px]]

8. From 'External Devices' drop an available command onto the 'Commands' field of the action.

[[File:e2_08c.png|600px]]

9. Play this cue, a clip should be started in the StageDesigner

OSC Reference

2026-08-08T15:40:47Z

Admin: Update link after renaming to 'OSC command reference' (bot)

This reference applies to all different OS. The presented OSC commands are for most part supported in version 6.0 but will be fully functional in version 6.0.08 and above.
<div class="noprint">

== Introduction==
</div>
This document describes the MXWendler (MXW) OSC Command Interface through an overview of the command structure and practical examples of integration with external controlling software.

== What is OSC? ==
</div>
OSC or „Open Sound Control“ is a Network-based protocol that commonly utilizes the UDP transport mechanism. Originally developed as a successor of the MIDI control protocol, it used nowadays as a practical communication method between platforms.

OSC Features:
* Connectionless communication architecture
* Broadcast-type messages
* High resolution time tag
* Allowed data formats including numeric, symbolic, and “blob” arguments
* Open-ended, dynamic, URL-style naming scheme for the receivers' address

[https://en.wikipedia.org/wiki/Open_Sound_Control [1<nowiki>]</nowiki> Wikipedia Link]

== Contents ==
{|
|-
| style="padding: 0px 10px" | [[1. Controlling MXW through OSC]]
|-
| style="padding: 0px 30px" | ''1.1 Receiving OSC commands in MXW''
|-
| style="padding: 0px 30px 10px" | ''1.2 Output OSC from MXW: Send vs. Reply''
|-
| style="padding: 0px 10px 0px" | [[2. MXW OSC command structure]]
|-
| style="padding: 0px 30px" | ''2.1 Sending OSC Values''
|-
| style="padding: 0px 30px" | ''2.2 Examples''
|-
| style="padding: 10px" | [[OSC command reference]]
|-
| style="padding: 0px 10px 0px" | [[4. Practical examples: Pure Data and TouchOSC]]
|-
| style="padding: 0px 30px" | ''4.1 Install Pure Data''
|-
| style="padding: 0px 30px" | ''4.2 MXW Pd Patch''
|-
| style="padding: 0px 30px 0px" | ''4.3 OSC for portable Devices: TouchOSC and Protokol''
|-
| style="padding: 10px" | [[5. Troubleshooting]]
|-
| style="padding: 10px" | [[6. External links]]
|}
[[Category:OSC]]
[[Category:Reference]]

OSC command reference

2026-08-08T15:40:46Z

Admin: Admin moved page MXW OSC command reference to OSC command reference: Rename: omit 'MXW' prefix

Here are listed all the commands that MXW recognizes.

=== Legend ===
<div>
==== Variables ====
When variables are found in the address of a command ( and not only as the value to be sent), the <code>$+index</code> notation has been employed :

<code>/mxw/track/$1 [value] </code> indicates that a variable <code>$1</code> has to be chosen and will specify the correct address where the value will be sent.<br>If the goal is, for example, to reduce of 50% the opacity of the 2nd track, the correct command would be:

<code>/mxw/track/2 0.5 </code>

==== Values ====
The standard used to represent the available values for each command (column “RANGE or TOKEN”) is:

''FLOATS'' are represented with one decimal:

<code>0.0 .. 1.0</code> → all float values between 0 and 1 included

''INTEGERS'' are represented with numbers or descriptions:

<code>1 .. 5</code> → all integers between 1 and 5 included ( 1 , 2 , 3 , 4 , 5 ) <br>
<code>1 .. (MAX n layers)</code> → all the integers between 1 and the maximum index of layers in MXW (e.g. if 6 layers are being used the values are integers between 1 and 6 included)

When only one number is indicated it means that only one option is given. This is found in addresses of buttons, checkboxes and in the options where "0" or "1" are the only significant values

''STRINGS'' are represented between quotation marks:

<code>“info”</code> means that the string info has to be used at the end of the command

E.G. to ask for information about the patches the command

<code>/mxw/set info </code>

would be sent.

When <code>“name”</code> is contained in the available string variable, then the content is to be substituted with the actual name.

E.G. : to select and play a patch called “patch_one” from its name, the address <code>/mxw/set</code> with tokens <code>"play" "name_of_patch"</code> has to be used, resulting in this OSC command:

<code>/mxw/set play patch_one</code>

When <u>OR</u> is found it means that two options can deliver a similar result. One of the two formats has to be used at one time.

===Set Reference===

{| class="wikitable"
|-
! OSC ADDRESS !! DESCRIPTION !! RANGE or TOKEN
|-
|<code> /mxw/set</code>||get information on the patches|| <code>“info”</code>
|-
| <code>/mxw/set</code>||play a specific patch|| <code>“play” “name_of_patch”</code>
|-
| <code>/mxw/set</code>||choose a patch|| <code>1 .. (MAX n patches)</code>
|-
| <code>/mxw/editor</code>||choose UI tab|| <code>0 .. 5</code>
|-
| <code>/mxw/trackmanager</code>||choose active track || <code>0.0 .. 1.0</code> <u>OR</u> <code>1 .. 4</code>
|-
| <code>/mxw/trackmanager</code>||clear all tracks || <code>"clear"</code>
|-
| <code>/mxw/layermanager</code> ||choose active layer || <code>1 .. (MAX n layers)</code>
|-
| <code>/mxw/layermanager</code>||clear layers in active track|| <code>"clear"</code>
|-
| <code>/mxw/beatbutton</code> || Send pulse to beat-button (BPM)|| <code>1</code>
|-
| <code>/mxw/playlist info</code> || return information on the state of the playback of playlist|| <code>"info"</code>
|-
| <code>/mxw/playlist select</code> || jump to cue by name || <code>"select" "cuename"</code>
|-
| <code>/mxw/playlist/gotostart</code> || stop and go to first track on list<ref>The functionality of ''gotostart'' is the same as the ''gotostart'' button in the MXW playlist GUI ( ❙❙◀ ), so the command has to be sent two times to reset the playlist at the original state.</ref>|| <code>0</code>
|-
| <code>/mxw/playlist/gotoprev</code> || go to previous cue|| <code>0</code>
|-
| <code>/mxw/playlist/play</code> || play active item|| <code>0</code>
|-
| <code>/mxw/playlist/pause</code> || pause active playing clip|| <code>0</code>
|-
| <code>/mxw/playlist/gotonext</code> || go to next cue|| <code>0</code>
|-
| <code>/mxw/playlist/gotocueandplay</code> || go to a specific cue and immediately play|| <code>0..n (MAX n rows)</code>
|-
| <code>/mxw/playlist/gotocue</code> || go to a specific cue|| <code>0..n (MAX n rows)</code>
|-
| <code>/mxw/playlist/container/active</code> || info about the total playlist container|| <code>"info"</code>
|-
| <code>/mxw/playlist/container/active/column/$1/row/$2</code> || info about the selected field in the playlist grid|| $1 → <code>0 .. (MAX n columns)</code><br>$2 → <code>1 .. (MAX n rows)</code><br><code>"info"</code>
|-
| <code>/mxw/set/first</code> || go to first patch on the list|| <code>0</code>
|-
| <code>/mxw/set/prev</code> || select the previous patch || <code>0</code>
|-
| <code>/mxw/set/play</code> || play selected patch <ref>The button play in the patch tab works like the play button in the MXW playlist GUI, every click will play the following patch.</ref>|| <code>0</code>
|-
| <code>/mxw/set/next</code>|| select to next patch|| <code>0</code>
|-
| <code>/mxw/set</code>|| clear all patches || <code>"clear"</code>
|-
| <code>/mxw/render</code>|| change of render opacity|| <code>0.0 .. 1.0</code>
|-
| <code>/mxw/render/opacity</code>|| change of render opacity|| <code>0.0 .. 1.0</code>
|-
| <code>/mxw/render/scale</code>|| change of render scale|| <code>0.0 .. 1.0</code>
|-
| <code>/mxw/render/scalexy</code>|| change of render scale ratio|| <code>0.0 .. 1.0</code>
|-
| <code>/mxw/render/translationx</code>|| change of render position x|| <code>0.0 .. 1.0</code>
|-
| <code>/mxw/render/translationy</code>|| change of render position y|| <code>0.0 .. 1.0</code>
|-
| <code>/mxw/render/rotation</code>|| change of render rotation|| <code>0.0 .. 1.0</code>
|-
| <code>/mxw/render/reset</code>|| reset render changes|| <code>0</code>
|-
| <code>/mxw/render/effect</code>|| selects wished render fx|| <code>1 .. (MAX n fx)
</code>
|-
| <code>/mxw/render/effect/1/param/$1 </code>|| modifies value of one parameter($1) of the render fx|| $1→ <code>1 .. (MAX n parameters)</code><br>
VALUE → <code>0.0 .. 1.0</code>
|-
| <code>/mxw/track/$1</code>|| set opacity value of a specific track ($1)|| $1 → <code>1 .. 4</code>
VALUE → <code>0.0 .. 1.0</code>
|-
| <code>/mxw/track/active</code>|| change opacity of active track moving the fader|| <code>0.0 .. 1.0
</code>
|-
| <code>/mxw/track/active/fader</code>|| change opacity of active track moving the fader|| <code>0.0 .. 1.0
</code>
|-
| <code>/mxw/track/active/crossfader</code>|| activates the crossfading between tracks|| <code>0.0 (OFF) <u>OR</u> 1.0 (ON)</code>
|-
| <code>/mxw/track/active/mode</code>|| changes the mode of fading|| <code>1 .. 8</code>
|-
| <code>/mxw/preload/$1/trigger</code>|| trigger preload $1 content to current track|| $1 → <code>1 .. (MAX n preloads)</code>
VALUE → <code>0</code>
|-
| <code>/mxw/preload/$1/flipflop</code>|| flipflop preload $1 content to current track|| $1 → <code>1 .. (MAX n preloads)</code>
VALUE → <code>0</code>
|-
| <code>/mxw/track/active/layer/active/clip/play</code> || toggles play-pause button of live editor || <code>0</code>
|-
| <code>/mxw/track/active/layer/active/scale</code> || change of layer scale || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/scalexy</code> || change of layer scale ratio || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/translationx</code> || change of layer position x || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/translationy</code> || change of layer position y || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/rotation</code> || change of layer rotation || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/mode</code> || change of layer blend mode || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/aspectmode</code> || change of layer aspect mode || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/reset</code> || reset layer changes || <code>0</code>
|-
| <code>/mxw/track/active/layer/active/clip/keyin</code> || set keyin of clip of active layer || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/clip/keyout</code> || set keyout of clip of active layer || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/clip/speed</code> || set speed of clip of active layer <ref> The values are sent to the "speed fader", which values go between 5 and -5, they do not act directly on the "speed value". This means that depending on the active media the available values in the fader will differ. </ref> || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/clip/position</code> || set position of clip of active layer || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/clip/mode</code> || set mode of clip of active layer || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/clip/effect</code> || choose active effect || <code>0 .. (MAX n of fx)</code>
|-
| <code>/mxw/track/active/layer/active/clip/effectbank</code> || selects active effect || <code>0 .. (MAX n of fx)</code>
|-
| <code>/mxw/track/active/layer/active/clip/effect/active/param/$1</code> || set param $1 of effect || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/clip/effect/1/color/1/red</code> || set red component of color param. || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/clip/effect/1/color/1/green</code> || set green component param. || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/clip/effect/1/color/1/blue</code> || set blue component param. || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/clip/effect/1/color/1/hue</code> || set huecomponent param. || <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/clip/effect/1/color/1/saturation</code> || set saturation | <code>0 .. 1</code>
|-
| <code>/mxw/track/active/layer/active/clip/effect/1/color/1/value</code> || set value component param. || <code>0 .. 1</code>
|-
| <code>/mxw/keystone/element/$1/pivot/col/$2/row/$3/xposition</code> || move keystone pivot in x || $1 → <code>1 .. (MAX n elements)</code>
$2 (COLUMN) → <code>1 <u>OR</u> 2</code>
$3 (ROW) → <code>1 <u>OR</u> 2</code>
VALUE → <code>0 .. 1</code>
|-
| <code>/mxw/keystone/element/$1/pivot/col/$2/row/$3/yposition</code> || move keystone pivot in y|| $1 → <code>1 .. (MAX n elements)</code>
$2 (COLUMN) → <code>1 <u>OR</u> 2</code>
$3 (ROW) → <code>1 <u>OR</u> 2</code>
VALUE → <code>0 .. 1</code>
|-
| <code>/mxw/keystone_io_animator</code> || keystone io animator fader|| <code>0 .. 1</code>
|-
|}
[[Category:OSC]]
[[Category:Reference]]

Category:OSC

2026-08-08T15:36:03Z

Admin: Create category page (bot)

Pages documenting how to control MXWendler through the Open Sound Control (OSC) protocol.

The list below is generated automatically from pages tagged <code><nowiki>[[Category:OSC]]</nowiki></code>.

[[Category:Reference]]

OSC command reference

2026-08-08T15:36:00Z

Admin: Add Category:OSC at page end (bot)

OSC Reference

2026-08-08T15:35:58Z

Admin: Add Category:OSC at page end (bot)

This reference applies to all different OS. The presented OSC commands are for most part supported in version 6.0 but will be fully functional in version 6.0.08 and above.
<div class="noprint">

== Introduction==
</div>
This document describes the MXWendler (MXW) OSC Command Interface through an overview of the command structure and practical examples of integration with external controlling software.

== What is OSC? ==
</div>
OSC or „Open Sound Control“ is a Network-based protocol that commonly utilizes the UDP transport mechanism. Originally developed as a successor of the MIDI control protocol, it used nowadays as a practical communication method between platforms.

OSC Features:
* Connectionless communication architecture
* Broadcast-type messages
* High resolution time tag
* Allowed data formats including numeric, symbolic, and “blob” arguments
* Open-ended, dynamic, URL-style naming scheme for the receivers' address

[https://en.wikipedia.org/wiki/Open_Sound_Control [1<nowiki>]</nowiki> Wikipedia Link]

== Contents ==
{|
|-
| style="padding: 0px 10px" | [[1. Controlling MXW through OSC]]
|-
| style="padding: 0px 30px" | ''1.1 Receiving OSC commands in MXW''
|-
| style="padding: 0px 30px 10px" | ''1.2 Output OSC from MXW: Send vs. Reply''
|-
| style="padding: 0px 10px 0px" | [[2. MXW OSC command structure]]
|-
| style="padding: 0px 30px" | ''2.1 Sending OSC Values''
|-
| style="padding: 0px 30px" | ''2.2 Examples''
|-
| style="padding: 10px" | [[MXW OSC command reference]]
|-
| style="padding: 0px 10px 0px" | [[4. Practical examples: Pure Data and TouchOSC]]
|-
| style="padding: 0px 30px" | ''4.1 Install Pure Data''
|-
| style="padding: 0px 30px" | ''4.2 MXW Pd Patch''
|-
| style="padding: 0px 30px 0px" | ''4.3 OSC for portable Devices: TouchOSC and Protokol''
|-
| style="padding: 10px" | [[5. Troubleshooting]]
|-
| style="padding: 10px" | [[6. External links]]
|}
[[Category:OSC]]
[[Category:Reference]]

Category:Python

2026-08-08T15:33:47Z

Admin: Create category page (bot)

Pages documenting how to control and extend MXWendler through its embedded Python 3.12 interface (the <code>mxw</code> module, imgui panels, and plugins).

The list below is generated automatically from pages tagged <code><nowiki>[[Category:Python]]</nowiki></code>.

[[Category:Reference]]

Category:JavaScript

2026-08-08T15:33:46Z

Admin: Create category page (bot)

Pages documenting how to control MXWendler through its embedded JavaScript (Duktape) interface.

The list below is generated automatically from pages tagged <code><nowiki>[[Category:JavaScript]]</nowiki></code>.

[[Category:Reference]]

Python plugin reference

2026-08-08T15:33:32Z

Admin: Add Category:Python at page end (bot)

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 command reference|Python command 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> (also <code>plugins/media/python_dev/</code>, same precedence, for internal/unpublished 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 installation / resource directory: <code>plugins/playlist/python/</code> (also <code>plugins/playlist/python_dev/</code>, same precedence, for internal/unpublished plugins)

=== 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.
|-
| <code>plugin_playlist_playbackmode_default</code> || Optional. The clip playback mode a freshly added clip of this media starts in: <code>stop</code>, <code>loop</code>, <code>oneshot</code>, <code>bounce</code>, <code>jitter</code> or <code>random</code>. Omitted or unknown defaults to <code>loop</code>. Only seeds the initial mode - a project reload restores the clip's own saved mode.
|}

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>
|-
| <code>plugin_accepts_trigger</code> || <code>true</code>/<code>false</code> (default <code>false</code>). When <code>true</code>, dragging a TRIGGER item onto this item's grid cell connects it (the drag shows a green "connect" outline) instead of moving/swapping cells, and the plugin can read the connection with <code>mxw.pending_trigger_drop(item_id)</code>. Set it for a timeline; see [[#Connecting to a TRIGGER item]].
|-
| <code>plugin_cell_scrub</code> || <code>true</code>/<code>false</code> (default <code>false</code>). When <code>true</code>, ALT + left-drag across this item's grid cell scrubs instead of moving the item: the host draws a playhead line and stashes the 0..1 fraction of the cell width each frame, readable with <code>mxw.pending_cell_scrub(item_id)</code>. Set it for a timeline; see [[#Connecting to a TRIGGER item]].
|}

== 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 command reference|Python command reference]].
* <code>mxw_imgui</code> — Dear ImGui bindings for drawing settings panels inside MXWendler (used by <code>onRenderPanel()</code>), documented in the [[Python imgui reference|Python ImGui Reference]].

=== Installing own modules with mxw-pip ===

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>
%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).

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:

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

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).
|-
| <code>onGetParams()</code> || returns a list of dicts || Declare addressable parameters, called once per instance and cached: <code>{"name": str, "type": "float"|"string", "min": float, "max": float, "default": float|str}</code> (<code>min</code>/<code>max</code> ignored for <code>"string"</code>; <code>type</code> defaults to <code>"float"</code>).
|-
| <code>onParamChanged(index, value)</code> || — || A parameter was set via OSC, Python or JS at <code>.../clip/media/1/param/<index+1></code> (0-based <code>index</code>). Store or apply it — the host never caches the value itself.
|}

Parameters are addressed exactly like shader effect parameters, e.g. <code>/mxw/track/2/layer/1/clip/media/1/param/1 0.8</code> or, for a <code>"string"</code>-typed param, <code>/mxw/track/2/layer/1/clip/media/1/param/2 "https://www.mxwendler.net"</code>. The <code>media/1</code> segment reflects the clip's single active media slot (any other index is out of range). Because the host does not persist a param's value, a plugin that wants one to survive a project reload must fold it into its own <code>onSave()</code>/<code>onLoad()</code> and hand the restored value back as <code>onGetParams()</code>'s <code>"default"</code> — which runs after <code>onLoad()</code> already restored the instance state.

=== 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''', 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]).

<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 command reference|Python command 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.
|-
| <code>getProgress()</code> || no || Return <code>0.0 .. 1.0</code> to fill the cell's bottom progress bar (the same bar the built-in advance/fade items draw); <code><= 0</code> draws nothing.
|}

=== Connecting to a TRIGGER item ===

A playlist plugin (e.g. a keyframe timeline) can bind to a TRIGGER item and animate its layer/clip controls. The user drops a trigger either onto the plugin's settings panel or onto its grid cell; the plugin resolves the connection to the trigger's grid <code>(col, row)</code> and enumerates its controls from there. No need to play the trigger first — the controls are read from the connected preload's fixture layer, and the very same <code>(col,row)</code> address resolves the ''live'' layer during playout.

{| class="wikitable"
! Function !! Meaning
|-
| <code>mxw_imgui.accept_trigger_drop()</code> || Makes the current panel window a drop target for a trigger; returns the dropped trigger's 1-based <code>(col, row)</code>, or <code>(-1, -1)</code>. Handles the "drop onto the panel" route.
|-
| <code>mxw.pending_trigger_drop(item_id)</code> || Returns a <code>(col, row)</code> stashed by the host when a trigger was dropped onto ''this'' plugin item's grid cell (pass your own <code>item_id</code>), or <code>(-1, -1)</code>. Handles the "drop onto the grid cell" route.
|-
| <code>mxw.trigger_controls(col, row)</code> || Returns the trigger's animatable (slider) controls as <code>(label, address)</code> pairs — layer, clip, effect and media params. Re-read it every frame: controls the user swaps on the clip appear/vanish live. Each <code>address</code> is usable with <code>mxw.widget(address).setValue()</code>.
|-
| <code>mxw.pending_cell_scrub(item_id)</code> || Returns the 0..1 fraction of an ALT + left-drag across ''this'' plugin item's grid cell (stashed by the host each frame while dragging, consumed on read), or <code>-1.0</code>. Needs the <code>plugin_cell_scrub</code> manifest opt-in. Poll it in <code>onNewFrameAlways()</code> so scrubbing also works while the panel is closed.
|}

Poll both drop routes at the top of <code>onRenderPanel()</code> and store the resulting <code>(col,row)</code>; then call <code>mxw.trigger_controls()</code> to (re)build your control list each frame.

A time connection between the connected clip and the plugin follows from these pieces: the clip's <code>.../clip/Position</code> control (normalized 0..1) is the clip's own time axis. Write it when your playhead moves (scrub → seek) and read it every frame to follow the clip when it is scrubbed — or simply playing. See the timeline plugin's <code>sync_time_link()</code> for a worked example including the echo filtering (a written Position reads back frame-quantized).

=== 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, all in the [https://github.com/mxwendler/mxw-plugins-playlist mxw-plugins-playlist] repository: <code>plugins/playlist/python/plugin_advance_datetime</code> (timed playlist navigation, rich settings panel), <code>plugin_video_writer</code>, <code>plugin_comment</code> (a minimal example: a no-op annotation item).

== Example plugins on GitHub ==

The bundled example plugins are maintained as public repositories under [https://github.com/mxwendler github.com/mxwendler], grouped by type — 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-plugins-media mxw-plugins-media]
|-
| <code>plugin_opengl_cube_direct</code> || media || Approach 3: same cube rendered directly into the media texture || [https://github.com/mxwendler/mxw-plugins-media mxw-plugins-media]
|-
| <code>plugin_web_media</code> || media || A web browser as media source (whole-scheme <code>web://</code> plugin) || [https://github.com/mxwendler/mxw-plugins-media mxw-plugins-media]
|-
| <code>plugin_fragcoord</code>, <code>plugin_shadertoy</code> || media || Shader-as-generative-media (FragCoord.xyz / Shadertoy) || [https://github.com/mxwendler/mxw-plugins-media mxw-plugins-media]
|-
| <code>plugin_advance_datetime</code> || playlist || Timed playlist navigation with a rich settings panel || [https://github.com/mxwendler/mxw-plugins-playlist mxw-plugins-playlist]
|-
| <code>plugin_video_writer</code> || playlist || Write video files from the playlist || [https://github.com/mxwendler/mxw-plugins-playlist mxw-plugins-playlist]
|-
| <code>plugin_comment</code> || playlist || Minimal example: a no-op text annotation item || [https://github.com/mxwendler/mxw-plugins-playlist mxw-plugins-playlist]
|}

=== Developing a new plugin inside a project ===

The most convenient place to develop a plugin is '''inside a project folder''': the plugin travels with the show, needs no write access to the installation, and overrides a same-named bundled plugin. Conceptually:

# '''Create a project folder''' — a plain directory that will hold everything belonging to the show, e.g. <code>D:/shows/particles/</code>.
# '''Save the project file there''' — ''File → Save As..'' into that folder, e.g. <code>D:/shows/particles/particles.mxw</code>. The folder containing the <code>.mxw</code> file ''is'' the project folder; loading the project later makes MXWendler pick up its plugins again.
# '''Create the plugin directory there''' — the project mirrors the installation layout: <code>D:/shows/particles/plugins/media/python/<plugin_folder>/</code> for media plugins (<code>plugins/playlist/python/...</code> for playlist plugins). Enable ''Settings → Python → Check for plugins inside the project folder'' — project plugins have the highest precedence of all plugin locations.

=== Letting Claude Code write the plugin ===

An AI coding agent like [https://claude.com/claude-code Claude Code] can write a complete plugin from the contract described on this page. Start it '''in the project folder''', so it creates the plugin directly where MXWendler looks for it:

<pre>
cd D:/shows/particles
claude
</pre>

Give it the reference material and a precise task — for a generative OpenGL particle system for example:

<pre>
Create an MXWendler media plugin under plugins/media/python/plugin_particle_system/
(folder + mxw_plugin.ini + mxw_main.py).

Reference: the bundled example in <MXWendler install dir>/plugins/media/python/
plugin_opengl_cube_direct/ - follow its structure and hook usage exactly, and the
plugin howto at https://wiki.mxwendler.net/index.php?title=Python_plugin_reference.

The plugin is a generative OpenGL particle system, addressed as
generative://particle_system, rendered with ModernGL directly into the media
texture via onRenderFrameGL (no readback, no onRenderFrame). Keep per-instance
state keyed by media_id. Emit particles from the center, integrate velocity and
gravity per frame scaled by the clip playback speed (onSetSpeed, onSpeedRange
-5..5). Expose particle count, gravity and start size as sliders in
onRenderPanel (mxw_imgui) and persist them via onSave/onLoad. Respect the GL
rules: attach with moderngl.create_context() lazily on the first render call,
never release the external texture, rebuild the fbo when (texture, w, h)
changes, flip Y in the projection.
</pre>

Then iterate: create the media in a clip (it appears under its <code>plugin_menu_name</code>, or address <code>generative://particle_system</code> directly) and refine with follow-up prompts ("make the particles fade out", "add a color gradient slider", ...). Errors show up in the interpreter console. For playlist plugins, ''Settings → Python → Reload Python Plugins'' hot-reloads the edited source; for media plugins, recreate the media (or restart) to re-import the module.

== 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 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.
[[Category:Python]]
[[Category:Reference]]

Python imgui reference

2026-08-08T15:33:30Z

Admin: Add Category:Python at page end (bot)

Here are listed the commands available in module <code>mxw_imgui</code>, MXWendler's Python binding of '''Dear ImGui'''. This is how plugins draw their settings panel, in the <code>onRenderPanel()</code> hook (see the [[Python_Plugin_Howto|Python Plugin Howto]]).

<code>mxw_imgui</code> mirrors the Dear ImGui C++ API almost function-for-function: the C++ <code>ImGui::PascalCase</code> names become Python <code>snake_case</code>, one argument at a time. If you already know Dear ImGui (or its C++/other-language bindings), the name of a call is usually a mechanical translation away.

=== Legend ===
<div>

Everything from the [[Python_Reference|Python Reference]] Legend applies (floats, integers, strings, <u>OR</u> for alternative formats). In addition:

Dear ImGui widgets that take a pointer to their value in C++ (so the value can be written back) instead return a '''tuple''' <code>(changed, value)</code> in Python: <code>changed</code> is <code>true</code> when the user edited the widget this frame, <code>value</code> is the (possibly new) value to keep and pass back in next frame. E.g.:

<code>changed, value = mxw_imgui.slider_float("Speed", value, 0.0, 1.0)</code>

Widgets with several packed floats/ints (<code>drag_float2</code>, <code>slider_int4</code>, ...) take and return a plain Python list/tuple of that length instead of a C array.

'''Flags''' (<code>ImGuiTreeNodeFlags</code>, <code>ImGuiWindowFlags</code>, <code>ImGuiCol</code>, ...) are '''not''' exposed as named Python constants — pass the plain integer value of the Dear ImGui enum (default <code>0</code> means "no flags" for nearly every call). Consult the Dear ImGui headers/docs for the numeric values if you need non-default flags.

Parameters shown as <code>= value</code> in the tables below are '''optional''' with that default; omit them to use the default.

Plugins draw '''into an existing panel''' — there is no <code>begin</code>/<code>end</code> for top-level windows; start directly with widget calls.

</div>

=== Data types ===

{| class="wikitable"
|-
! PYTHON TYPE !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.Vec2()</code> OR <code>mxw_imgui.Vec2(x, y)</code> || 2D float vector (<code>.x</code>, <code>.y</code>), used for sizes and positions || <code>size = mxw_imgui.Vec2(200, 0)</code>
|-
|<code>mxw_imgui.Vec4()</code> OR <code>mxw_imgui.Vec4(x, y, z, w)</code> || 4D float vector (<code>.x</code>, <code>.y</code>, <code>.z</code>, <code>.w</code>), used for colors (RGBA) and rectangles || <code>col = mxw_imgui.Vec4(1.0, 0.0, 0.0, 1.0)</code>
|-
|<code>mxw_imgui.Vector_char</code>, <code>Vector_float</code>, <code>Vector_unsignedchar</code>, <code>Vector_unsignedshort</code>, <code>Vector_DrawCmd</code>, <code>Vector_DrawVert</code>, <code>Vector_FontGlyph</code> || Read-only iterable wrappers around Dear ImGui's internal <code>ImVector<T></code> buffers, returned by some getters (e.g. draw list data). Support <code>len()</code>, iteration and indexing || <code>for glyph in font.Glyphs: pass</code>
|}

=== Style & Fonts ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.push_font(font)</code> || push a font onto the font stack for subsequent widgets || <code>mxw_imgui.push_font(mxw_imgui.get_font())</code>
|-
|<code>mxw_imgui.pop_font()</code> || pop the last pushed font || <code>mxw_imgui.pop_font()</code>
|-
|<code>mxw_imgui.push_style_color(idx, col)</code> || push a style color override (<code>col</code> as packed <code>u32</code> OR <code>Vec4</code>) || <code>mxw_imgui.push_style_color(0, mxw_imgui.Vec4(1,0,0,1))</code>
|-
|<code>mxw_imgui.pop_style_color(count = 1)</code> || pop <code>count</code> previously pushed style colors || <code>mxw_imgui.pop_style_color()</code>
|-
|<code>mxw_imgui.push_style_var(idx, val)</code> || push a style var override (<code>val</code> as float OR <code>Vec2</code>) || <code>mxw_imgui.push_style_var(0, 4.0)</code>
|-
|<code>mxw_imgui.pop_style_var(count = 1)</code> || pop <code>count</code> previously pushed style vars || <code>mxw_imgui.pop_style_var()</code>
|-
|<code>mxw_imgui.push_allow_keyboard_focus(allow_keyboard_focus)</code> || allow/disallow tab-focusing the next widgets || <code>mxw_imgui.push_allow_keyboard_focus(false)</code>
|-
|<code>mxw_imgui.pop_allow_keyboard_focus()</code> || pop the keyboard-focus override || <code>mxw_imgui.pop_allow_keyboard_focus()</code>
|-
|<code>mxw_imgui.push_button_repeat(repeat)</code> || make subsequent buttons behave as repeating (held = repeated clicks) || <code>mxw_imgui.push_button_repeat(true)</code>
|-
|<code>mxw_imgui.pop_button_repeat()</code> || pop the button-repeat override || <code>mxw_imgui.pop_button_repeat()</code>
|-
|<code>mxw_imgui.get_font()</code> || returns the current font object || <code>f = mxw_imgui.get_font()</code>
|-
|<code>mxw_imgui.get_font_size()</code> || returns the current font size in px || <code>sz = mxw_imgui.get_font_size()</code>
|-
|<code>mxw_imgui.get_font_tex_uv_white_pixel()</code> || returns UV coordinate of a white pixel in the font texture, for custom draw-list use || <code>uv = mxw_imgui.get_font_tex_uv_white_pixel()</code>
|-
|<code>mxw_imgui.get_color_u32(idx, alpha_mul = 1.0)</code> OR <code>mxw_imgui.get_color_u32(col)</code> || resolve a style color index, a <code>Vec4</code>, or a packed <code>u32</code> to a final packed <code>u32</code> color || <code>c = mxw_imgui.get_color_u32(0)</code>
|-
|<code>mxw_imgui.get_style_color_vec4(idx)</code> || returns the raw <code>Vec4</code> for a style color index || <code>c = mxw_imgui.get_style_color_vec4(0)</code>
|-
|<code>mxw_imgui.get_style_color_name(idx)</code> || returns the readable name of a style color index || <code>mxw_imgui.print_console(mxw_imgui.get_style_color_name(0))</code>
|-
|<code>mxw_imgui.set_color_edit_options(flags)</code> || set default flags for every subsequent color_edit/color_picker call || <code>mxw_imgui.set_color_edit_options(0)</code>
|}

=== Cursor & Layout ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.push_item_width(item_width)</code> || push a fixed width (px, or negative = right-aligned) for subsequent widgets || <code>mxw_imgui.push_item_width(150)</code>
|-
|<code>mxw_imgui.pop_item_width()</code> || pop the pushed item width || <code>mxw_imgui.pop_item_width()</code>
|-
|<code>mxw_imgui.set_next_item_width(item_width)</code> || set the width of just the next widget || <code>mxw_imgui.set_next_item_width(300)</code>
|-
|<code>mxw_imgui.calc_item_width()</code> || returns the width the next widget would use || <code>w = mxw_imgui.calc_item_width()</code>
|-
|<code>mxw_imgui.push_text_wrap_pos(wrap_local_pos_x = 0.0)</code> || push a word-wrap position (0 = wrap at window edge) for subsequent text || <code>mxw_imgui.push_text_wrap_pos()</code>
|-
|<code>mxw_imgui.pop_text_wrap_pos()</code> || pop the pushed wrap position || <code>mxw_imgui.pop_text_wrap_pos()</code>
|-
|<code>mxw_imgui.separator()</code> || draw a thin horizontal separator line || <code>mxw_imgui.separator()</code>
|-
|<code>mxw_imgui.same_line(offset_from_start_x = 0.0, spacing = -1.0)</code> || keep the next widget on the same line as the previous one || <code>mxw_imgui.same_line()</code>
|-
|<code>mxw_imgui.new_line()</code> || force a following widget to start on a new line || <code>mxw_imgui.new_line()</code>
|-
|<code>mxw_imgui.spacing()</code> || add vertical spacing || <code>mxw_imgui.spacing()</code>
|-
|<code>mxw_imgui.dummy(size)</code> || reserve an empty invisible <code>size</code> (<code>Vec2</code>) area, e.g. as a spacer || <code>mxw_imgui.dummy(mxw_imgui.Vec2(0, 10))</code>
|-
|<code>mxw_imgui.indent(indent_w = 0.0)</code> || move the cursor right (indent) || <code>mxw_imgui.indent()</code>
|-
|<code>mxw_imgui.unindent(indent_w = 0.0)</code> || move the cursor back left (unindent), matching a prior indent() || <code>mxw_imgui.unindent()</code>
|-
|<code>mxw_imgui.begin_group()</code> || start a layout group (following widgets are treated as one unit for layout purposes) || <code>mxw_imgui.begin_group()</code>
|-
|<code>mxw_imgui.end_group()</code> || close the current layout group || <code>mxw_imgui.end_group()</code>
|-
|<code>mxw_imgui.get_cursor_pos()</code> || returns the cursor position (<code>Vec2</code>) relative to the current window || <code>p = mxw_imgui.get_cursor_pos()</code>
|-
|<code>mxw_imgui.get_cursor_pos_x()</code> OR <code>mxw_imgui.get_cursor_pos_y()</code> || returns just the X or Y cursor coordinate || <code>x = mxw_imgui.get_cursor_pos_x()</code>
|-
|<code>mxw_imgui.set_cursor_pos(local_pos)</code> || set the cursor position (<code>Vec2</code>), window-relative || <code>mxw_imgui.set_cursor_pos(mxw_imgui.Vec2(0, 0))</code>
|-
|<code>mxw_imgui.set_cursor_pos_x(local_x)</code> OR <code>mxw_imgui.set_cursor_pos_y(local_y)</code> || set just the X or Y cursor coordinate || <code>mxw_imgui.set_cursor_pos_x(20)</code>
|-
|<code>mxw_imgui.get_cursor_start_pos()</code> || returns the initial cursor position of the current window/child || <code>p = mxw_imgui.get_cursor_start_pos()</code>
|-
|<code>mxw_imgui.get_cursor_screen_pos()</code> || returns the cursor position in absolute screen coordinates || <code>p = mxw_imgui.get_cursor_screen_pos()</code>
|-
|<code>mxw_imgui.set_cursor_screen_pos(pos)</code> || set the cursor in absolute screen coordinates || <code>mxw_imgui.set_cursor_screen_pos(p)</code>
|-
|<code>mxw_imgui.align_text_to_frame_padding()</code> || vertically align following text with standard framed widgets on the same line || <code>mxw_imgui.align_text_to_frame_padding()</code>
|-
|<code>mxw_imgui.get_text_line_height()</code> OR <code>mxw_imgui.get_text_line_height_with_spacing()</code> || returns one text line's height, with or without inter-line spacing || <code>h = mxw_imgui.get_text_line_height()</code>
|-
|<code>mxw_imgui.get_frame_height()</code> OR <code>mxw_imgui.get_frame_height_with_spacing()</code> || returns a standard framed widget's height, with or without spacing || <code>h = mxw_imgui.get_frame_height()</code>
|}

=== ID stack ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.push_id(str_id)</code> OR <code>mxw_imgui.push_id(str_id_begin, str_id_end)</code> OR <code>mxw_imgui.push_id(ptr_id)</code> OR <code>mxw_imgui.push_id(int_id)</code> || push a scope onto the ID stack, so same-labelled widgets in a loop don't collide || <code>mxw_imgui.push_id(i)</code>
|-
|<code>mxw_imgui.pop_id()</code> || pop the last pushed ID scope || <code>mxw_imgui.pop_id()</code>
|-
|<code>mxw_imgui.get_id(str_id)</code> OR <code>mxw_imgui.get_id(str_id_begin, str_id_end)</code> OR <code>mxw_imgui.get_id(ptr_id)</code> || compute a widget ID without pushing it || <code>uid = mxw_imgui.get_id("my_widget")</code>
|}

=== Text ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.text_unformatted(text, text_end = None)</code> || draw raw text, faster than <code>text()</code> for long/dynamic strings (no format parsing) || <code>mxw_imgui.text_unformatted("Ready.")</code>
|-
|<code>mxw_imgui.text(fmt)</code> || draw a line of text || <code>mxw_imgui.text("Frame: " + str(mxw.framecounter))</code>
|-
|<code>mxw_imgui.text_colored(col, fmt)</code> || draw text in the given <code>Vec4</code> color || <code>mxw_imgui.text_colored(mxw_imgui.Vec4(1,0,0,1), "Error")</code>
|-
|<code>mxw_imgui.text_disabled(fmt)</code> || draw text in the disabled/grey style color || <code>mxw_imgui.text_disabled("(no signal)")</code>
|-
|<code>mxw_imgui.text_wrapped(fmt)</code> || draw text that wraps at the window edge, regardless of the wrap-pos stack || <code>mxw_imgui.text_wrapped(status_message)</code>
|-
|<code>mxw_imgui.label_text(label, fmt)</code> || draw a "label: value"-style line (label aligned like other widgets) || <code>mxw_imgui.label_text("Status", "OK")</code>
|-
|<code>mxw_imgui.bullet_text(fmt)</code> || draw a bulleted line of text || <code>mxw_imgui.bullet_text("first item")</code>
|}

=== Main widgets ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.button(label, size = Vec2(0,0))</code> || a clickable button; returns <code>true</code> the frame it's clicked || <code>if mxw_imgui.button("Reload"): reload()</code>
|-
|<code>mxw_imgui.small_button(label)</code> || a button with no extra vertical padding, fits inline with text || <code>if mxw_imgui.small_button("x"): close()</code>
|-
|<code>mxw_imgui.invisible_button(str_id, size, flags = 0)</code> || an invisible clickable/draggable area || <code>mxw_imgui.invisible_button("drag_area", mxw_imgui.Vec2(50,50))</code>
|-
|<code>mxw_imgui.arrow_button(str_id, dir)</code> || a small square button with an arrow glyph (<code>dir</code>: 0=left,1=right,2=up,3=down) || <code>mxw_imgui.arrow_button("up", 2)</code>
|-
|<code>mxw_imgui.image(user_texture_id, size, uv0 = Vec2(0,0), uv1 = Vec2(1,1), tint_col = Vec4(1,1,1,1), border_col = Vec4(0,0,0,0))</code> || draw a texture (GL texture id) as an image || <code>mxw_imgui.image(tex_id, mxw_imgui.Vec2(128,128))</code>
|-
|<code>mxw_imgui.image_button(user_texture_id, size, uv0 = Vec2(0,0), uv1 = Vec2(1,1), frame_padding = -1, bg_col = Vec4(0,0,0,0), tint_col = Vec4(1,1,1,1))</code> || a clickable image button || <code>if mxw_imgui.image_button(tex_id, mxw_imgui.Vec2(32,32)): pass</code>
|-
|<code>mxw_imgui.checkbox(label, v)</code> || a checkbox; <code>v</code>/return is <code>bool</code> || <code>changed, enabled = mxw_imgui.checkbox("Enabled", enabled)</code>
|-
|<code>mxw_imgui.checkbox_flags(label, flags, flags_value)</code> || a checkbox that toggles one bit(mask) of an int flags value || <code>changed, flags = mxw_imgui.checkbox_flags("Bit 1", flags, 1)</code>
|-
|<code>mxw_imgui.radio_button(label, active)</code> OR <code>mxw_imgui.radio_button(label, v, v_button)</code> || a radio button; single-bool form for manual state, or bind directly to an int selection variable || <code>changed, mode = mxw_imgui.radio_button("Mode A", mode, 0)</code>
|-
|<code>mxw_imgui.progress_bar(fraction, size_arg = Vec2(-FLT_MIN, 0), overlay = None)</code> || a progress bar, <code>fraction</code> 0.0..1.0 || <code>mxw_imgui.progress_bar(0.5)</code>
|-
|<code>mxw_imgui.bullet()</code> || draw just a bullet glyph, e.g. before inline text/widgets || <code>mxw_imgui.bullet()</code>
|}

=== Combo box ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.combo(label, current_item, items, popup_max_height_in_items = -1)</code> || a combo box built from a Python list of strings; simplest way to pick one of several options || <code>changed, sel = mxw_imgui.combo("Mode", sel, ["A", "B", "C"])</code>
|-
|<code>mxw_imgui.begin_combo(label, preview_value, flags = 0)</code> / <code>mxw_imgui.end_combo()</code> || low-level combo box: build the popup content yourself (e.g. with <code>selectable()</code>) between these two calls || <code>if mxw_imgui.begin_combo("Mode", preview): mxw_imgui.end_combo()</code>
|}

=== Drag sliders ===
Click-and-drag widgets; typing is also possible (Ctrl+click / double-click).

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.drag_float(label, v, v_speed = 1.0, v_min = 0.0, v_max = 0.0, format = None, flags = 0)</code> || drag a single float; <code>v_min == v_max == 0</code> means unbounded || <code>changed, value = mxw_imgui.drag_float("Speed", value, 0.01, 0.0, 2.0)</code>
|-
|<code>mxw_imgui.drag_float2(label, v, ...)</code> / <code>drag_float3</code> / <code>drag_float4</code> || same, for a list of 2/3/4 floats (e.g. a color or position) || <code>changed, xyz = mxw_imgui.drag_float3("Position", xyz)</code>
|-
|<code>mxw_imgui.drag_float_range2(label, v_current_min, v_current_max, v_speed = 1.0, v_min = 0.0, v_max = 0.0, format = None, format_max = None, flags = 0)</code> || drag a min/max float range with two handles || <code>changed, lo, hi = mxw_imgui.drag_float_range2("Range", lo, hi)</code>
|-
|<code>mxw_imgui.drag_int(label, v, v_speed = 1.0, v_min = 0, v_max = 0, format = None, flags = 0)</code> || drag a single int || <code>changed, value = mxw_imgui.drag_int("Count", value, 1, 0, 10)</code>
|-
|<code>mxw_imgui.drag_int2(label, v, ...)</code> / <code>drag_int3</code> / <code>drag_int4</code> || same, for a list of 2/3/4 ints || <code>changed, rgb = mxw_imgui.drag_int3("RGB", rgb, 1, 0, 255)</code>
|-
|<code>mxw_imgui.drag_int_range2(label, v_current_min, v_current_max, ...)</code> || drag a min/max int range with two handles || <code>changed, lo, hi = mxw_imgui.drag_int_range2("Range", lo, hi)</code>
|-
|<code>mxw_imgui.drag_scalar(label, data_type, p_data, v_speed, p_min = None, p_max = None, format = None, flags = 0)</code> / <code>drag_scalar_n(..., components, ...)</code> || generic drag widget for any <code>ImGuiDataType</code>, rarely needed from Python || <code>mxw_imgui.drag_scalar("Value", 0, ptr, 1.0)</code>
|}

=== Sliders ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.slider_float(label, v, v_min, v_max, format = None, flags = 0)</code> || slide a single float between <code>v_min</code> and <code>v_max</code> || <code>changed, value = mxw_imgui.slider_float("Mouse X", value, 0.0, 1.0)</code>
|-
|<code>mxw_imgui.slider_float2(label, v, v_min, v_max, ...)</code> / <code>slider_float3</code> / <code>slider_float4</code> || same, for a list of 2/3/4 floats || <code>changed, rgba = mxw_imgui.slider_float4("Color", rgba, 0.0, 1.0)</code>
|-
|<code>mxw_imgui.slider_angle(label, v_rad, v_degrees_min = -360.0, v_degrees_max = 360.0, format = None, flags = 0)</code> || slide an angle, stored in radians but displayed/typed in degrees || <code>changed, rot = mxw_imgui.slider_angle("Rotation", rot)</code>
|-
|<code>mxw_imgui.slider_int(label, v, v_min, v_max, format = None, flags = 0)</code> || slide a single int || <code>changed, idx = mxw_imgui.slider_int("Preset", idx, 0, 99)</code>
|-
|<code>mxw_imgui.slider_int2(label, v, v_min, v_max, ...)</code> / <code>slider_int3</code> / <code>slider_int4</code> || same, for a list of 2/3/4 ints || <code>changed, xy = mxw_imgui.slider_int2("Grid pos", xy, 0, 10)</code>
|-
|<code>mxw_imgui.slider_scalar(label, data_type, p_data, p_min, p_max, format = None, flags = 0)</code> / <code>slider_scalar_n(..., components, ...)</code> || generic slider for any <code>ImGuiDataType</code>, rarely needed from Python || <code>mxw_imgui.slider_scalar("Value", 0, ptr, p_min, p_max)</code>
|-
|<code>mxw_imgui.v_slider_float(label, size, v, v_min, v_max, format = None, flags = 0)</code> || vertical slider variant of <code>slider_float</code> || <code>changed, value = mxw_imgui.v_slider_float("##vol", mxw_imgui.Vec2(20,100), value, 0.0, 1.0)</code>
|-
|<code>mxw_imgui.v_slider_int(label, size, v, v_min, v_max, format = None, flags = 0)</code> || vertical slider variant of <code>slider_int</code> || <code>changed, value = mxw_imgui.v_slider_int("##lvl", mxw_imgui.Vec2(20,100), value, 0, 10)</code>
|-
|<code>mxw_imgui.v_slider_scalar(label, size, data_type, p_data, p_min, p_max, format = None, flags = 0)</code> || generic vertical slider for any <code>ImGuiDataType</code> || <code>mxw_imgui.v_slider_scalar("##v", size, 0, ptr, p_min, p_max)</code>
|}

=== Input widgets ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.input_text(label, data, max_size, flags = 0)</code> || a single-line text field; <code>data</code> is the current string, <code>max_size</code> the max length in bytes || <code>changed, value = mxw_imgui.input_text("URL", url_text, 512)</code>
|-
|<code>mxw_imgui.input_text_multiline(label, data, max_size, size = Vec2(0,0), flags = 0)</code> || a multi-line text field || <code>changed, value = mxw_imgui.input_text_multiline("Notes", notes, 2048, mxw_imgui.Vec2(300,100))</code>
|-
|<code>mxw_imgui.input_float(label, v, step = 0.0, step_fast = 0.0, format = None, flags = 0)</code> || a typed float field with optional +/- step buttons || <code>changed, value = mxw_imgui.input_float("Gain", value, 0.1)</code>
|-
|<code>mxw_imgui.input_float2(label, v, ...)</code> / <code>input_float3</code> / <code>input_float4</code> || same, for a list of 2/3/4 floats || <code>changed, xyz = mxw_imgui.input_float3("Pos", xyz)</code>
|-
|<code>mxw_imgui.input_int(label, v, step = 1, step_fast = 100, flags = 0)</code> || a typed int field with +/- step buttons || <code>changed, value = mxw_imgui.input_int("Count", value)</code>
|-
|<code>mxw_imgui.input_int2(label, v, flags = 0)</code> / <code>input_int3</code> / <code>input_int4</code> || same, for a list of 2/3/4 ints || <code>changed, rgb = mxw_imgui.input_int3("RGB", rgb)</code>
|-
|<code>mxw_imgui.input_double(label, v, step = 0.0, step_fast = 0.0, format = None, flags = 0)</code> || a typed double field || <code>changed, value = mxw_imgui.input_double("Precise", value)</code>
|-
|<code>mxw_imgui.input_scalar(label, data_type, p_data, p_step = None, p_step_fast = None, format = None, flags = 0)</code> / <code>input_scalar_n(..., components, ...)</code> || generic typed field for any <code>ImGuiDataType</code>, rarely needed from Python || <code>mxw_imgui.input_scalar("Value", 0, ptr)</code>
|}

=== Color editor & picker ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.color_edit3(label, col, flags = 0)</code> || a compact RGB color editor (swatch + popup picker); <code>col</code> is a 3-float list || <code>changed, rgb = mxw_imgui.color_edit3("Tint", rgb)</code>
|-
|<code>mxw_imgui.color_edit4(label, col, flags = 0)</code> || same, RGBA (4-float list) || <code>changed, rgba = mxw_imgui.color_edit4("Tint", rgba)</code>
|-
|<code>mxw_imgui.color_picker3(label, col, flags = 0)</code> || a full RGB color picker widget, always expanded || <code>changed, rgb = mxw_imgui.color_picker3("Tint", rgb)</code>
|-
|<code>mxw_imgui.color_picker4(label, col, flags = 0, ref_col = None)</code> || same, RGBA, optionally showing a reference color for comparison || <code>changed, rgba = mxw_imgui.color_picker4("Tint", rgba)</code>
|-
|<code>mxw_imgui.color_button(desc_id, col, flags = 0, size = Vec2(0,0))</code> || a non-editable color swatch button (e.g. as a preview/trigger) || <code>if mxw_imgui.color_button("preview", col): open_picker()</code>
|}

=== Trees ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.tree_node(label)</code> OR <code>mxw_imgui.tree_node(str_id, fmt)</code> OR <code>mxw_imgui.tree_node(ptr_id, fmt)</code> || an expandable/collapsible tree node; returns <code>true</code> while open. Call <code>tree_pop()</code> if it returned <code>true</code> || <code>if mxw_imgui.tree_node("Advanced"): mxw_imgui.tree_pop()</code>
|-
|<code>mxw_imgui.tree_node_ex(label, flags = 0)</code> OR <code>mxw_imgui.tree_node_ex(str_id, flags, fmt)</code> OR <code>mxw_imgui.tree_node_ex(ptr_id, flags, fmt)</code> || <code>tree_node()</code> with explicit flags (e.g. default-open, leaf, selected) || <code>if mxw_imgui.tree_node_ex("Node", 0): mxw_imgui.tree_pop()</code>
|-
|<code>mxw_imgui.tree_push(str_id)</code> OR <code>mxw_imgui.tree_push(ptr_id = None)</code> || push an indent level without drawing a node (paired with <code>tree_pop()</code>) || <code>mxw_imgui.tree_push("scope"); mxw_imgui.tree_pop()</code>
|-
|<code>mxw_imgui.tree_pop()</code> || pop one indent level pushed by <code>tree_node()</code>/<code>tree_push()</code> || <code>mxw_imgui.tree_pop()</code>
|-
|<code>mxw_imgui.get_tree_node_to_label_spacing()</code> || returns the horizontal spacing between a tree node arrow and its label || <code>s = mxw_imgui.get_tree_node_to_label_spacing()</code>
|-
|<code>mxw_imgui.collapsing_header(label, flags = 0)</code> OR <code>mxw_imgui.collapsing_header(label, p_visible, flags = 0)</code> || a top-level collapsible section header; optionally with a close ("x") button when <code>p_visible</code> is passed || <code>if mxw_imgui.collapsing_header("Settings"): mxw_imgui.text("...")</code>
|-
|<code>mxw_imgui.set_next_item_open(is_open, cond = 0)</code> || force the next <code>tree_node()</code>/<code>collapsing_header()</code> open/closed state || <code>mxw_imgui.set_next_item_open(true)</code>
|}

=== Selectables & list boxes ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.selectable(label, selected = false, flags = 0, size = Vec2(0,0))</code> OR <code>mxw_imgui.selectable(label, p_selected, flags = 0, size = Vec2(0,0))</code> || a clickable, highlightable row (typically inside a list box) || <code>if mxw_imgui.selectable("Item 1", is_sel): pick(1)</code>
|-
|<code>mxw_imgui.begin_list_box(label, size = Vec2(0,0))</code> / <code>mxw_imgui.end_list_box()</code> || low-level list box: build the rows yourself (e.g. with <code>selectable()</code>) between these two calls || <code>if mxw_imgui.begin_list_box("Items"): mxw_imgui.end_list_box()</code>
|-
|<code>mxw_imgui.list_box(label, current_item, items, height_in_items = -1)</code> || a list box built from a Python list of strings, single-select || <code>changed, sel = mxw_imgui.list_box("Presets", sel, ["A", "B", "C"])</code>
|-
|<code>mxw_imgui.list_box_stretch(label, current_item, items)</code> || MXWendler custom variant of <code>list_box()</code> that stretches to fill the remaining panel height || <code>changed, sel = mxw_imgui.list_box_stretch("Presets", sel, names)</code>
|}

=== Data plotting ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.plot_lines(label, values, values_offset = 0, overlay_text = None, scale_min = FLT_MAX, scale_max = FLT_MAX, graph_size = Vec2(0,0))</code> || draw a line graph from a Python list of floats || <code>mxw_imgui.plot_lines("Levels", history)</code>
|-
|<code>mxw_imgui.plot_histogram(label, values, values_offset = 0, overlay_text = None, scale_min = FLT_MAX, scale_max = FLT_MAX, graph_size = Vec2(0,0))</code> || draw a bar histogram from a Python list of floats || <code>mxw_imgui.plot_histogram("Levels", history)</code>
|}

=== Value() helpers ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.value(prefix, b)</code> OR <code>mxw_imgui.value(prefix, v)</code> (int/uint) OR <code>mxw_imgui.value(prefix, v, float_format = None)</code> || draw a "prefix: value" line for a bool/int/float, without building the string yourself || <code>mxw_imgui.value("FPS", mxw.fps)</code>
|}

=== Menus ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.begin_menu_bar()</code> / <code>mxw_imgui.end_menu_bar()</code> || start/end a menu bar inside the current window || <code>if mxw_imgui.begin_menu_bar(): mxw_imgui.end_menu_bar()</code>
|-
|<code>mxw_imgui.begin_main_menu_bar()</code> / <code>mxw_imgui.end_main_menu_bar()</code> || start/end the application's main (top-level) menu bar || <code>if mxw_imgui.begin_main_menu_bar(): mxw_imgui.end_main_menu_bar()</code>
|-
|<code>mxw_imgui.begin_menu(label, enabled = true)</code> / <code>mxw_imgui.end_menu()</code> || start/end a (sub)menu; call <code>end_menu()</code> only if <code>begin_menu()</code> returned <code>true</code> || <code>if mxw_imgui.begin_menu("File"): mxw_imgui.end_menu()</code>
|-
|<code>mxw_imgui.menu_item(label, shortcut = None, selected = false, enabled = true)</code> OR <code>mxw_imgui.menu_item(label, shortcut, p_selected, enabled = true)</code> || a clickable (optionally checkable) menu entry || <code>if mxw_imgui.menu_item("Save", "Ctrl+S"): save()</code>
|}

=== Tooltips ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.begin_tooltip()</code> / <code>mxw_imgui.end_tooltip()</code> || build a custom tooltip (any widgets) between these two calls || <code>mxw_imgui.begin_tooltip(); mxw_imgui.text("info"); mxw_imgui.end_tooltip()</code>
|-
|<code>mxw_imgui.set_tooltip(fmt)</code> || a quick one-line tooltip for the last hovered item || <code>if mxw_imgui.is_item_hovered(): mxw_imgui.set_tooltip("Explain this")</code>
|}

=== Popups & modals ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.open_popup(str_id, flags = 0)</code> || flag a popup to open (by ID) on the next matching <code>begin_popup()</code> || <code>mxw_imgui.open_popup("confirm_delete")</code>
|-
|<code>mxw_imgui.begin_popup(str_id, flags = 0)</code> / <code>mxw_imgui.end_popup()</code> || build a plain popup's content; call <code>end_popup()</code> only if <code>begin_popup()</code> returned <code>true</code> || <code>if mxw_imgui.begin_popup("menu"): mxw_imgui.end_popup()</code>
|-
|<code>mxw_imgui.begin_popup_modal(name, p_open = None, flags = 0)</code> || build a modal popup's content (blocks interaction with the rest of the UI) || <code>opened, _ = mxw_imgui.begin_popup_modal("Confirm")</code>
|-
|<code>mxw_imgui.open_popup_on_item_click(str_id = None, popup_flags = 1)</code> || open a popup when the last item is clicked (e.g. right-click context menu) || <code>mxw_imgui.open_popup_on_item_click("ctx")</code>
|-
|<code>mxw_imgui.close_current_popup()</code> || close the popup currently being drawn (e.g. after a button inside it) || <code>if mxw_imgui.button("OK"): mxw_imgui.close_current_popup()</code>
|-
|<code>mxw_imgui.begin_popup_context_item(str_id = None, popup_flags = 1)</code> || combined open+begin for a right-click context popup on the last item || <code>if mxw_imgui.begin_popup_context_item(): mxw_imgui.end_popup()</code>
|-
|<code>mxw_imgui.begin_popup_context_window(str_id = None, popup_flags = 1)</code> || same, anchored to the current window instead of the last item || <code>if mxw_imgui.begin_popup_context_window(): mxw_imgui.end_popup()</code>
|-
|<code>mxw_imgui.begin_popup_context_void(str_id = None, popup_flags = 1)</code> || same, opens on right-click on empty space (no window/item under cursor) || <code>if mxw_imgui.begin_popup_context_void(): mxw_imgui.end_popup()</code>
|-
|<code>mxw_imgui.is_popup_open(str_id, flags = 0)</code> || returns whether the given popup is currently open || <code>open = mxw_imgui.is_popup_open("menu")</code>
|}

=== Tables ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.begin_table(str_id, column, flags = 0, outer_size = Vec2(0,0), inner_width = 0.0)</code> / <code>mxw_imgui.end_table()</code> || start/end a table; call <code>end_table()</code> only if <code>begin_table()</code> returned <code>true</code> || <code>if mxw_imgui.begin_table("grid", 3): mxw_imgui.end_table()</code>
|-
|<code>mxw_imgui.table_next_row(row_flags = 0, min_row_height = 0.0)</code> || start the next table row || <code>mxw_imgui.table_next_row()</code>
|-
|<code>mxw_imgui.table_next_column()</code> || advance to the next cell (wraps to the next row automatically) || <code>mxw_imgui.table_next_column()</code>
|-
|<code>mxw_imgui.table_set_column_index(column_n)</code> || jump directly to a given column in the current row || <code>mxw_imgui.table_set_column_index(1)</code>
|-
|<code>mxw_imgui.table_setup_column(label, flags = 0, init_width_or_weight = 0.0, user_id = 0)</code> || declare a column's header label / sizing before the first row || <code>mxw_imgui.table_setup_column("Name")</code>
|-
|<code>mxw_imgui.table_setup_scroll_freeze(cols, rows)</code> || freeze N leading columns/rows while the rest scrolls || <code>mxw_imgui.table_setup_scroll_freeze(0, 1)</code>
|-
|<code>mxw_imgui.table_headers_row()</code> || draw the header row from the declared <code>table_setup_column()</code> labels || <code>mxw_imgui.table_headers_row()</code>
|-
|<code>mxw_imgui.table_header(label)</code> || draw a single header cell manually (instead of <code>table_headers_row()</code>) || <code>mxw_imgui.table_header("Name")</code>
|-
|<code>mxw_imgui.table_get_sort_specs()</code> || returns the current column sort specification, if the table is sortable || <code>specs = mxw_imgui.table_get_sort_specs()</code>
|-
|<code>mxw_imgui.table_get_column_count()</code> || returns the number of columns of the current table || <code>n = mxw_imgui.table_get_column_count()</code>
|-
|<code>mxw_imgui.table_get_column_index()</code> || returns the current column index || <code>i = mxw_imgui.table_get_column_index()</code>
|-
|<code>mxw_imgui.table_get_row_index()</code> || returns the current row index || <code>i = mxw_imgui.table_get_row_index()</code>
|-
|<code>mxw_imgui.table_get_column_name(column_n = -1)</code> || returns a column's declared label (-1 = current column) || <code>name = mxw_imgui.table_get_column_name(0)</code>
|-
|<code>mxw_imgui.table_get_column_flags(column_n = -1)</code> || returns a column's current flags (e.g. is it hidden/sorted) || <code>flags = mxw_imgui.table_get_column_flags()</code>
|-
|<code>mxw_imgui.table_set_bg_color(target, color, column_n = -1)</code> || set the background color of a cell/row/column || <code>mxw_imgui.table_set_bg_color(0, mxw_imgui.color_convert_float4_to_u32(mxw_imgui.Vec4(1,0,0,1)))</code>
|}

=== Legacy columns ===
Superseded by [[#Tables|Tables]] above, kept for compatibility.

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.columns(count = 1, id = None, border = true)</code> || switch the rest of the window into a simple N-column layout (<code>count = 1</code> ends it) || <code>mxw_imgui.columns(2)</code>
|-
|<code>mxw_imgui.next_column()</code> || move to the next column (wraps to the next row) || <code>mxw_imgui.next_column()</code>
|-
|<code>mxw_imgui.get_column_index()</code> || returns the current column index || <code>i = mxw_imgui.get_column_index()</code>
|-
|<code>mxw_imgui.get_column_width(column_index = -1)</code> / <code>mxw_imgui.set_column_width(column_index, width)</code> || get/set a column's width || <code>w = mxw_imgui.get_column_width()</code>
|-
|<code>mxw_imgui.get_column_offset(column_index = -1)</code> / <code>mxw_imgui.set_column_offset(column_index, offset_x)</code> || get/set a column's X offset || <code>x = mxw_imgui.get_column_offset()</code>
|-
|<code>mxw_imgui.get_columns_count()</code> || returns the current column count || <code>n = mxw_imgui.get_columns_count()</code>
|}

=== Tabs ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.begin_tab_bar(str_id, flags = 0)</code> / <code>mxw_imgui.end_tab_bar()</code> || start/end a tab bar; call <code>end_tab_bar()</code> only if <code>begin_tab_bar()</code> returned <code>true</code> || <code>if mxw_imgui.begin_tab_bar("tabs"): mxw_imgui.end_tab_bar()</code>
|-
|<code>mxw_imgui.begin_tab_item(label, p_open = None, flags = 0)</code> / <code>mxw_imgui.end_tab_item()</code> || start/end one tab's content; call <code>end_tab_item()</code> only if <code>begin_tab_item()</code> returned <code>true</code> || <code>opened, _ = mxw_imgui.begin_tab_item("Settings")</code>
|-
|<code>mxw_imgui.tab_item_button(label, flags = 0)</code> || a button drawn as a tab (e.g. a "+" to add a tab) || <code>if mxw_imgui.tab_item_button("+"): add_tab()</code>
|-
|<code>mxw_imgui.set_tab_item_closed(tab_or_docked_window_label)</code> || programmatically close a tab by label || <code>mxw_imgui.set_tab_item_closed("Old Tab")</code>
|}

=== Logging / capture ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.log_to_tty(auto_open_depth = -1)</code> || start capturing following widgets' text output to the app's TTY/console || <code>mxw_imgui.log_to_tty()</code>
|-
|<code>mxw_imgui.log_to_file(auto_open_depth = -1, filename = None)</code> || start capturing to a file || <code>mxw_imgui.log_to_file(-1, "log.txt")</code>
|-
|<code>mxw_imgui.log_to_clipboard(auto_open_depth = -1)</code> || start capturing to the OS clipboard || <code>mxw_imgui.log_to_clipboard()</code>
|-
|<code>mxw_imgui.log_finish()</code> || stop the current capture || <code>mxw_imgui.log_finish()</code>
|-
|<code>mxw_imgui.log_buttons()</code> || draw the standard "Log/Copy to clipboard" buttons || <code>mxw_imgui.log_buttons()</code>
|-
|<code>mxw_imgui.log_text(fmt)</code> || add text directly to the active log capture, without drawing a widget || <code>mxw_imgui.log_text("captured line")</code>
|}

=== Drag and drop ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.begin_drag_drop_source(flags = 0)</code> / <code>mxw_imgui.end_drag_drop_source()</code> || make the last item a drag source; build the payload/preview between these two calls || <code>if mxw_imgui.begin_drag_drop_source(): mxw_imgui.end_drag_drop_source()</code>
|-
|<code>mxw_imgui.set_drag_drop_payload(type, data, sz, cond = 0)</code> || attach a payload to the drag currently being sourced || <code>mxw_imgui.set_drag_drop_payload("CLIP", data, len(data))</code>
|-
|<code>mxw_imgui.begin_drag_drop_target()</code> / <code>mxw_imgui.end_drag_drop_target()</code> || make the last item/window a drop target; check <code>accept_drag_drop_payload()</code> between these two calls || <code>if mxw_imgui.begin_drag_drop_target(): mxw_imgui.end_drag_drop_target()</code>
|-
|<code>mxw_imgui.accept_drag_drop_payload(type, flags = 0)</code> || accept a payload of the given type while inside a drop target || <code>p = mxw_imgui.accept_drag_drop_payload("CLIP")</code>
|-
|<code>mxw_imgui.get_drag_drop_payload()</code> || peek the payload of the drag currently in progress, even outside a target || <code>p = mxw_imgui.get_drag_drop_payload()</code>
|}

=== Clipping ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.push_clip_rect(clip_rect_min, clip_rect_max, intersect_with_current_clip_rect)</code> || push a manual clipping rectangle (<code>Vec2</code> corners) for subsequent drawing || <code>mxw_imgui.push_clip_rect(p_min, p_max, true)</code>
|-
|<code>mxw_imgui.pop_clip_rect()</code> || pop the pushed clip rect || <code>mxw_imgui.pop_clip_rect()</code>
|}

=== Focus & activation ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.set_item_default_focus()</code> || make the last item the one focused by default when the panel first appears || <code>mxw_imgui.set_item_default_focus()</code>
|-
|<code>mxw_imgui.set_keyboard_focus_here(offset = 0)</code> || focus the next widget for keyboard input (e.g. auto-focus a text field) || <code>mxw_imgui.set_keyboard_focus_here()</code>
|}

=== Item / widgets utilities ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.is_item_hovered(flags = 0)</code> || returns whether the last item is hovered by the mouse || <code>if mxw_imgui.is_item_hovered(): mxw_imgui.set_tooltip("info")</code>
|-
|<code>mxw_imgui.is_item_active()</code> || returns whether the last item is currently active (e.g. being held/edited) || <code>active = mxw_imgui.is_item_active()</code>
|-
|<code>mxw_imgui.is_item_focused()</code> || returns whether the last item has keyboard focus || <code>focused = mxw_imgui.is_item_focused()</code>
|-
|<code>mxw_imgui.is_item_clicked(mouse_button = 0)</code> || returns whether the last item was clicked this frame || <code>if mxw_imgui.is_item_clicked(): pass</code>
|-
|<code>mxw_imgui.is_item_visible()</code> || returns whether the last item is visible (not clipped) || <code>visible = mxw_imgui.is_item_visible()</code>
|-
|<code>mxw_imgui.is_item_edited()</code> || returns whether the last item's value changed this frame || <code>edited = mxw_imgui.is_item_edited()</code>
|-
|<code>mxw_imgui.is_item_activated()</code> || returns whether the last item just became active this frame || <code>started = mxw_imgui.is_item_activated()</code>
|-
|<code>mxw_imgui.is_item_deactivated()</code> || returns whether the last item just stopped being active this frame || <code>stopped = mxw_imgui.is_item_deactivated()</code>
|-
|<code>mxw_imgui.is_item_deactivated_after_edit()</code> || returns whether the last item stopped being active after its value changed (e.g. commit-on-release) || <code>if mxw_imgui.is_item_deactivated_after_edit(): save()</code>
|-
|<code>mxw_imgui.is_item_toggled_open()</code> || returns whether the last tree node/collapsing header was just opened or closed || <code>toggled = mxw_imgui.is_item_toggled_open()</code>
|-
|<code>mxw_imgui.is_any_item_hovered()</code> / <code>mxw_imgui.is_any_item_active()</code> / <code>mxw_imgui.is_any_item_focused()</code> || returns whether any item at all is hovered/active/focused || <code>busy = mxw_imgui.is_any_item_active()</code>
|-
|<code>mxw_imgui.get_item_rect_min()</code> / <code>mxw_imgui.get_item_rect_max()</code> / <code>mxw_imgui.get_item_rect_size()</code> || returns the last item's bounding rectangle (screen-space corners, or size) || <code>size = mxw_imgui.get_item_rect_size()</code>
|-
|<code>mxw_imgui.set_item_allow_overlap()</code> || allow the next widget to visually overlap the last item without stealing its hover/click || <code>mxw_imgui.set_item_allow_overlap()</code>
|}

=== Viewport & miscellaneous ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.get_main_viewport()</code> || returns the main viewport object (position/size of the whole application) || <code>vp = mxw_imgui.get_main_viewport()</code>
|-
|<code>mxw_imgui.is_rect_visible(size)</code> OR <code>mxw_imgui.is_rect_visible(rect_min, rect_max)</code> || returns whether a rectangle at the cursor (or explicit corners) is visible/unclipped || <code>visible = mxw_imgui.is_rect_visible(mxw_imgui.Vec2(50,50))</code>
|-
|<code>mxw_imgui.get_time()</code> || returns Dear ImGui's internal time in seconds (accumulates while the app runs) || <code>t = mxw_imgui.get_time()</code>
|-
|<code>mxw_imgui.get_frame_count()</code> || returns the number of ImGui frames rendered so far || <code>n = mxw_imgui.get_frame_count()</code>
|-
|<code>mxw_imgui.get_background_draw_list()</code> / <code>mxw_imgui.get_foreground_draw_list()</code> || returns the draw list rendered behind/in front of all windows, for custom drawing || <code>dl = mxw_imgui.get_foreground_draw_list()</code>
|-
|<code>mxw_imgui.get_draw_list_shared_data()</code> || returns data shared across draw lists (font atlas, clip rect stack, ...), rarely needed from Python || <code>d = mxw_imgui.get_draw_list_shared_data()</code>
|-
|<code>mxw_imgui.set_state_storage(storage)</code> / <code>mxw_imgui.get_state_storage()</code> || set/get the key-value storage backing tree/collapsing-header open states || <code>s = mxw_imgui.get_state_storage()</code>
|-
|<code>mxw_imgui.begin_child_frame(id, size, flags = 0)</code> / <code>mxw_imgui.end_child_frame()</code> || a framed, scrollable child region (styled like a text/list box) || <code>if mxw_imgui.begin_child_frame(1, mxw_imgui.Vec2(0,100)): mxw_imgui.end_child_frame()</code>
|-
|<code>mxw_imgui.calc_text_size(text, text_end = None, hide_text_after_double_hash = false, wrap_width = -1.0)</code> || returns the pixel size a string would occupy with the current font || <code>w = mxw_imgui.calc_text_size("0").x</code>
|}

=== Color utilities ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.color_convert_u32_to_float4(in)</code> || convert a packed <code>u32</code> color to a <code>Vec4</code> || <code>col = mxw_imgui.color_convert_u32_to_float4(0xFFFFFFFF)</code>
|-
|<code>mxw_imgui.color_convert_float4_to_u32(in)</code> || convert a <code>Vec4</code> color to a packed <code>u32</code> || <code>u = mxw_imgui.color_convert_float4_to_u32(mxw_imgui.Vec4(1,1,1,1))</code>
|-
|<code>mxw_imgui.color_convert_rg_bto_hsv(r, g, b)</code> || returns <code>(h, s, v)</code> for the given RGB floats (0.0..1.0) || <code>h, s, v = mxw_imgui.color_convert_rg_bto_hsv(1.0, 0.0, 0.0)</code>
|-
|<code>mxw_imgui.color_convert_hs_vto_rgb(h, s, v)</code> || returns <code>(r, g, b)</code> for the given HSV floats (0.0..1.0) || <code>r, g, b = mxw_imgui.color_convert_hs_vto_rgb(0.0, 1.0, 1.0)</code>
|}

=== Keyboard input ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.get_key_index(imgui_key)</code> || map a Dear ImGui <code>ImGuiKey_*</code> value to the user's backend key index || <code>idx = mxw_imgui.get_key_index(0)</code>
|-
|<code>mxw_imgui.is_key_down(user_key_index)</code> || returns whether a key is currently held down || <code>held = mxw_imgui.is_key_down(idx)</code>
|-
|<code>mxw_imgui.is_key_pressed(user_key_index, repeat = true)</code> || returns whether a key was just pressed (optionally auto-repeating while held) || <code>if mxw_imgui.is_key_pressed(idx): pass</code>
|-
|<code>mxw_imgui.is_key_released(user_key_index)</code> || returns whether a key was just released || <code>if mxw_imgui.is_key_released(idx): pass</code>
|-
|<code>mxw_imgui.get_key_pressed_amount(key_index, repeat_delay, rate)</code> || returns how many times a key auto-repeated this frame, given a delay/rate || <code>n = mxw_imgui.get_key_pressed_amount(idx, 0.3, 0.1)</code>
|}

=== Mouse input ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.is_mouse_down(button)</code> || returns whether a mouse button is currently held (0=left,1=right,2=middle) || <code>held = mxw_imgui.is_mouse_down(0)</code>
|-
|<code>mxw_imgui.is_mouse_clicked(button, repeat = false)</code> || returns whether a mouse button was just clicked || <code>if mxw_imgui.is_mouse_clicked(0): pass</code>
|-
|<code>mxw_imgui.is_mouse_released(button)</code> || returns whether a mouse button was just released || <code>if mxw_imgui.is_mouse_released(0): pass</code>
|-
|<code>mxw_imgui.is_mouse_double_clicked(button)</code> || returns whether a mouse button was just double-clicked || <code>if mxw_imgui.is_mouse_double_clicked(0): pass</code>
|-
|<code>mxw_imgui.is_mouse_hovering_rect(r_min, r_max, clip = true)</code> || returns whether the mouse is over the given screen-space rectangle || <code>over = mxw_imgui.is_mouse_hovering_rect(p_min, p_max)</code>
|-
|<code>mxw_imgui.is_mouse_pos_valid(mouse_pos = None)</code> || returns whether the (current or given) mouse position is valid (app has focus etc.) || <code>valid = mxw_imgui.is_mouse_pos_valid()</code>
|-
|<code>mxw_imgui.is_any_mouse_down()</code> || returns whether any mouse button is currently held || <code>held = mxw_imgui.is_any_mouse_down()</code>
|-
|<code>mxw_imgui.get_mouse_pos()</code> || returns the current mouse position (<code>Vec2</code>, screen-space) || <code>p = mxw_imgui.get_mouse_pos()</code>
|-
|<code>mxw_imgui.get_mouse_pos_on_opening_current_popup()</code> || returns the mouse position captured when the current popup was opened || <code>p = mxw_imgui.get_mouse_pos_on_opening_current_popup()</code>
|-
|<code>mxw_imgui.is_mouse_dragging(button, lock_threshold = -1.0)</code> || returns whether the mouse is dragging with the given button held || <code>dragging = mxw_imgui.is_mouse_dragging(0)</code>
|-
|<code>mxw_imgui.get_mouse_drag_delta(button = 0, lock_threshold = -1.0)</code> || returns the drag distance (<code>Vec2</code>) since the drag started || <code>d = mxw_imgui.get_mouse_drag_delta()</code>
|-
|<code>mxw_imgui.reset_mouse_drag_delta(button = 0)</code> || reset the tracked drag distance for a button || <code>mxw_imgui.reset_mouse_drag_delta()</code>
|-
|<code>mxw_imgui.get_mouse_cursor()</code> / <code>mxw_imgui.set_mouse_cursor(cursor_type)</code> || get/set the desired OS mouse cursor shape || <code>mxw_imgui.set_mouse_cursor(1)</code>
|}

=== Clipboard ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.get_clipboard_text()</code> || returns the current OS clipboard text || <code>txt = mxw_imgui.get_clipboard_text()</code>
|-
|<code>mxw_imgui.set_clipboard_text(text)</code> || set the OS clipboard text || <code>mxw_imgui.set_clipboard_text("copied value")</code>
|}

=== Disabled blocks & MXWendler extras ===
The last two functions are MXWendler additions, not part of stock Dear ImGui bindings.

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
|<code>mxw_imgui.begin_disabled(disabled = false)</code> / <code>mxw_imgui.end_disabled()</code> || grey out and block interaction with all widgets in between || <code>mxw_imgui.begin_disabled(not enabled); mxw_imgui.button("Go"); mxw_imgui.end_disabled()</code>
|-
|<code>mxw_imgui.render_frame(p_min, p_max, colf, border = true, rounding = 0.0)</code> || draw a filled/bordered rectangle (screen-space corners as <code>Vec2</code>, color as <code>Vec4</code>) directly, e.g. for custom backgrounds || <code>mxw_imgui.render_frame(mxw_imgui.Vec2(0,0), mxw_imgui.Vec2(100,20), mxw_imgui.Vec4(0.2,0.2,0.2,1))</code>
|}
[[Category:Python]]
[[Category:Reference]]

Python command reference

2026-08-08T15:33:29Z

Admin: Add Category:Python at page end (bot)

This page lists the commands of the Python module <code>mxw</code>, MXWendler's general Python command interface. It is available from the script console and from Python plugins (see the [[Python plugin reference|Python Plugin Howto]]). For drawing plugin panels see the [[Python imgui reference|Python ImGui Reference]].

The embedded interpreter is '''Python 3.12'''. Import is implicit in the script console; in a plugin module use <code>import mxw</code>.

'''The presented Python commands supported in version 7.2. and up'''

=== Legend ===
<div>

''FLOATS'' are written with one decimal: <code>0.0 .. 1.0</code> → every float between 0 and 1 inclusive.

''INTEGERS'' are written as plain numbers or ranges: <code>1 .. 5</code> → the integers 1,2,3,4,5.

''STRINGS'' are written between double quotes.

When <u>OR</u> appears, two alternative call formats produce a similar result; use one at a time.

'''Addressing:''' widgets are targeted by their OSC-style address string, e.g. <code>/mxw/track/active/layer/active/clip</code>. The same addresses used over OSC work here.

'''Access model (7.2):''' widget values are read/written through <code>mxw.widget(address)</code>; global functions live in the submodules/factories <code>mxw.playlist</code>, <code>mxw.io</code>, <code>mxw.preload(n)</code>, <code>mxw.media(name)</code>, <code>mxw.grabber(name)</code>.

</div>

=== Reference ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
!colspan="3" |Software Info
|-
|<code>mxw.millis</code> || milliseconds passed since the software was opened || <code>mxw.print_console("passed time is " + str(mxw.millis))</code>
|-
|<code>mxw.width</code> || current frame width in px || <code>mxw.print_console("frame width is " + str(mxw.width))</code>
|-
|<code>mxw.height</code> || current frame height in px || <code>mxw.print_console("frame height is " + str(mxw.height))</code>
|-
|<code>mxw.outwidth</code> || current output width in px || <code>mxw.print_console("output width is " + str(mxw.outwidth))</code>
|-
|<code>mxw.outheight</code> || current output height in px || <code>mxw.print_console("output height is " + str(mxw.outheight))</code>
|-
|<code>mxw.framecounter</code> || number of frames rendered since the software was opened || <code>mxw.print_console("frames rendered: " + str(mxw.framecounter))</code>
|-
|<code>mxw.print_console("text")</code> || print a line to the script console || <code>mxw.print_console("hello")</code>
|-
|<code>mxw.print_statusline("text")</code> || print text on the application status line || <code>mxw.print_statusline("running")</code>
|-
|<code>mxw.makescreenshot("path")</code> || save a full-frame screenshot as PNG (empty path → Desktop) || <code>mxw.makescreenshot("c:/Users/me/Desktop/shot.png")</code>
|-
|<code>mxw.makesectionscreenshot("path", x, y, w, h)</code> || save a cropped screenshot of the region (x, y, w, h) || <code>mxw.makesectionscreenshot("c:/Users/me/Desktop/crop.png", 0, 0, 400, 200)</code>
|-
|<code>mxw.describe()</code> || return a text listing of every operation known to the unified interface registry (auto-docs / discovery) || <code>mxw.print_console(mxw.describe())</code>
|-
!colspan="3" | I/O ( <code>mxw.io</code> )
|-
|<code>mxw.io.dmx(channel)</code> || return the DMX value received on the given channel || <code>v = mxw.io.dmx(4)</code>
|-
|<code>mxw.io.midi(device, channel)</code> || return the MIDI value received from device/channel || <code>v = mxw.io.midi(1, 6)</code>
|-
|<code>mxw.io.keyboard(state, key)</code> || return whether the given key (ASCII) is in the given state || <code>if mxw.io.keyboard(0, 65): pass</code>
|-
|<code>mxw.io.send_dmx(channel, value)</code> || send a DMX value on a channel || <code>mxw.io.send_dmx(4, 255)</code>
|-
|<code>mxw.io.send_midi(device, channel, value)</code> || send a MIDI value to device/channel || <code>mxw.io.send_midi(1, 6, 100)</code>
|-
|<code>mxw.io.pjlink("command", "ip", "pw")</code> || PJLink projector control. Commands: <code>on</code>, <code>off</code>, <code>avmute_on</code>, <code>avmute_off</code>, <code>vmute_on</code>, <code>vmute_off</code> || <code>mxw.io.pjlink("on", "192.168.1.2", "panasonic")</code>
|-
|<code>mxw.io.send_osc("host", port, "address", "tags", *args)</code> || send an OSC message. <code>tags</code> is one char per argument: <code>d</code> float, <code>i</code> int, <code>c</code> string, <code>b</code> blob (list of 0..255) || <code>mxw.io.send_osc("127.0.0.1", 7000, "/cue", "ci", "go", 5)</code>
|-
!colspan="3" |Playlist ( <code>mxw.playlist</code> )
|-
|<code>mxw.playlist.preload_media()</code> || preload the media used by the playlist || <code>mxw.playlist.preload_media()</code>
|-
|<code>mxw.playlist.play()</code> || play the playlist || <code>mxw.playlist.play()</code>
|-
|<code>mxw.playlist.pause()</code> || pause, or restart if already paused || <code>mxw.playlist.pause()</code>
|-
|<code>mxw.playlist.go_pause(True/False)</code> || halt (True) or resume (False) playback || <code>mxw.playlist.go_pause(True)</code>
|-
|<code>mxw.playlist.skiptonext()</code> || skip to the next cue || <code>mxw.playlist.skiptonext()</code>
|-
|<code>mxw.playlist.go_next()</code> || go to the next cue without playing || <code>mxw.playlist.go_next()</code>
|-
|<code>mxw.playlist.go_prev()</code> || go to the previous cue || <code>mxw.playlist.go_prev()</code>
|-
|<code>mxw.playlist.go_first()</code> || go to the first cue || <code>mxw.playlist.go_first()</code>
|-
|<code>mxw.playlist.navigate_index(index)</code> || go to the cue with the given index || <code>mxw.playlist.navigate_index(2)</code>
|-
|<code>mxw.playlist.navigate_string("name")</code> || go to the cue matching the given name || <code>mxw.playlist.navigate_string("BG_video2")</code>
|-
|<code>mxw.playlist.get_active_cue()</code> || return the active cue index (int) || <code>i = mxw.playlist.get_active_cue()</code>
|-
|<code>mxw.playlist.get_cue_count()</code> || return the number of cues (int) || <code>n = mxw.playlist.get_cue_count()</code>
|-
|<code>mxw.playlist.get_cue_names()</code> || return the list of cue names (index matches <code>navigate_index</code>) || <code>for name in mxw.playlist.get_cue_names(): pass</code>
|-
|<code>mxw.playlist.is_rehearsal()</code> || return True if the playlist is in rehearsal mode || <code>if mxw.playlist.is_rehearsal(): pass</code>
|-
!colspan="3" |Preload ( <code>mxw.preload(n)</code> )
|-
|<code>mxw.preload(n).isvalid()</code> || True if preload <code>n</code> exists || <code>if mxw.preload(2).isvalid(): pass</code>
|-
|<code>mxw.preload(n).clear()</code> || clear the selected preload || <code>mxw.preload(2).clear()</code>
|-
|<code>mxw.preload(n).set_media("filename")</code> || set the preload media by filename || <code>mxw.preload(2).set_media("try.mp4")</code>
|-
|<code>mxw.preload(n).set_name("name")</code> || rename the preload || <code>mxw.preload(2).set_name("new_background")</code>
|-
|<code>mxw.preload(n).add_preload()</code> || load the preload into the layers || <code>mxw.preload(2).add_preload()</code>
|-
|<code>mxw.preload(n).trigger_preload()</code> || trigger a layer from the preload || <code>mxw.preload(2).trigger_preload()</code>
|-
|<code>mxw.preload(n).get_activated()</code> || True if the preload is open for edit || <code>mxw.preload(2).get_activated()</code>
|-
|<code>mxw.preload(n).set_activated(True/False)</code> || open/close the preload for edit || <code>mxw.preload(2).set_activated(False)</code>
|-
|<code>mxw.preload(n).get_layer_position()</code> || return the preload's layer index || <code>mxw.preload(2).get_layer_position()</code>
|-
|<code>mxw.preload(n).get_track_position()</code> || return the preload's track index || <code>mxw.preload(2).get_track_position()</code>
|-
|<code>mxw.preload(n).set_layer_position(pos)</code> || set the preload's layer index || <code>mxw.preload(2).set_layer_position(2)</code>
|-
|<code>mxw.preload(n).set_track_position(pos)</code> || set the preload's track index || <code>mxw.preload(2).set_track_position(2)</code>
|-
|<code>mxw.preload(n).get_preload_names()</code> || return the list of preload comment/name strings || <code>names = mxw.preload(2).get_preload_names()</code>
|-
|<code>mxw.preload(n).get_image_sample_cvmat(w, h)</code> || return a <code>w</code>×<code>h</code> RGBA image sample of the preload as a buffer (OpenCV Mat) || <code>img = mxw.preload(2).get_image_sample_cvmat(64, 64)</code>
|-
!colspan="3" |Widgets ( <code>mxw.widget(address)</code> )
|-
|<code>mxw.widget("/mxw/path").getValue()</code> || return the widget's normalized value (float) || <code>o = mxw.widget("/mxw/track/active/layer/active/opacity").getValue()</code>
|-
|<code>mxw.widget("/mxw/path").setValue(v)</code> || set the widget's normalized value || <code>mxw.widget("/mxw/track/active/layer/active/opacity").setValue(0.5)</code>
|-
|<code>mxw.widget("/mxw/path").getStringValue()</code> || return the widget's string value (e.g. a cue/clip name) || <code>mxw.print_console(mxw.widget("/mxw/playlist/container/1/column/0/row/1").getStringValue())</code>
|-
|<code>mxw.widget("/mxw/path").setStringValue("text")</code> || set the widget's string value (e.g. name a cue) || <code>mxw.widget("/mxw/playlist/container/1/column/0/row/1").setStringValue("background videoclip")</code>
|-
|<code>mxw.widget("/mxw/path").setWidgetRealValue(d)</code> || set the widget's real (un-normalized) value || <code>mxw.widget("/mxw/path").setWidgetRealValue(120.0)</code>
|-
|<code>mxw.widget("/mxw/path").animate(initvalue, incomingvalue, duration, delta, type)</code> || animate the widget value over <code>duration</code> ms || <code>mxw.widget("/mxw/path").animate(0.0, 1.0, 1000, 0.0, 0)</code>
|-
|<code>mxw.widget("/mxw/path").info()</code> || return a list describing the widget. For a '''clip''': <code>[length, width, height, millis_per_frame, cache_state, media_path]</code>. Returns <code>[]</code> if the address does not resolve || <code>length, w, h, mspf, cache, path = mxw.widget("/mxw/track/active/layer/active/clip").info()</code>
|-
!colspan="3" |Media ( <code>mxw.media(name)</code> )
|-
|<code>mxw.media("name").isvalid()</code> || True if the named media exists || <code>if mxw.media("USB Cam").isvalid(): pass</code>
|-
|<code>mxw.media("name").reference(True/False)</code> || add (True) or remove (False) a reference that keeps the media loaded || <code>mxw.media("clip.mov").reference(True)</code>
|-
|<code>mxw.media("name").unload_media_full_if_not_used_by_clips()</code> || unload the media if no clip uses it (returns bool) || <code>mxw.media("clip.mov").unload_media_full_if_not_used_by_clips()</code>
|-
|<code>mxw.media("name").get_image_sample_cvmat(w, h)</code> || return a <code>w</code>×<code>h</code> RGBA image sample of the media (OpenCV Mat) || <code>img = mxw.media("clip.mov").get_image_sample_cvmat(64, 64)</code>
|-
|<code>mxw.media("name").get_image_sample_cvmat_async(w, h)</code> || non-blocking variant of the image sample || <code>img = mxw.media("clip.mov").get_image_sample_cvmat_async(64, 64)</code>
|-
|<code>mxw.media("name").get_capture_device_names()</code> || return the list of available capture-device names || <code>devs = mxw.media("").get_capture_device_names()</code>
|-
|<code>mxw.media("name").ptz("ptz_is_supported")</code> || return whether the (NDI) camera supports PTZ || <code>mxw.media("USB Cam").ptz("ptz_is_supported")</code>
|-
|<code>mxw.media("name").ptz("ptz_zoom", value)</code> || zoom, 0 (in) .. 1 (out) || <code>mxw.media("USB Cam").ptz("ptz_zoom", 0.5)</code>
|-
|<code>mxw.media("name").ptz("ptz_zoom_speed", value)</code> || zoom speed, -1 (out) .. 1 (in) || <code>mxw.media("USB Cam").ptz("ptz_zoom_speed", 0.5)</code>
|-
|<code>mxw.media("name").ptz("ptz_pan_tilt", pan, tilt)</code> || absolute pan/tilt, -1 .. 1 || <code>mxw.media("USB Cam").ptz("ptz_pan_tilt", -0.5, 0.2)</code>
|-
|<code>mxw.media("name").ptz("ptz_pan_tilt_speed", pan_speed, tilt_speed)</code> || pan/tilt speed, -1 (right/down) .. 1 (left/up) || <code>mxw.media("USB Cam").ptz("ptz_pan_tilt_speed", -0.3, 0.8)</code>
|-
|<code>mxw.media("name").ptz("ptz_store_preset", n)</code> || store position/focus/zoom into preset 0 .. 99 || <code>mxw.media("USB Cam").ptz("ptz_store_preset", 75)</code>
|-
|<code>mxw.media("name").ptz("ptz_recall_preset", n, speed)</code> || recall preset 0 .. 99 at speed 0 .. 1 || <code>mxw.media("USB Cam").ptz("ptz_recall_preset", 4, 0.5)</code>
|-
|<code>mxw.media("name").ptz("ptz_auto_focus")</code> || toggle auto-focus || <code>mxw.media("USB Cam").ptz("ptz_auto_focus")</code>
|-
|<code>mxw.media("name").ptz("ptz_focus", value)</code> || absolute focus, 0 (infinity) .. 1 (closest) || <code>mxw.media("USB Cam").ptz("ptz_focus", 0.5)</code>
|-
|<code>mxw.media("name").ptz("ptz_focus_speed", value)</code> || focus speed, -1 (out) .. 1 (in) || <code>mxw.media("USB Cam").ptz("ptz_focus_speed", -0.2)</code>
|-
|<code>mxw.media("name").ptz("ptz_white_balance_auto")</code> || auto white balance || <code>mxw.media("USB Cam").ptz("ptz_white_balance_auto")</code>
|-
|<code>mxw.media("name").ptz("ptz_white_balance_indoor")</code> || indoor white balance || <code>mxw.media("USB Cam").ptz("ptz_white_balance_indoor")</code>
|-
|<code>mxw.media("name").ptz("ptz_white_balance_outdoor")</code> || outdoor white balance || <code>mxw.media("USB Cam").ptz("ptz_white_balance_outdoor")</code>
|-
|<code>mxw.media("name").ptz("ptz_white_balance_oneshot")</code> || set white balance once from current brightness || <code>mxw.media("USB Cam").ptz("ptz_white_balance_oneshot")</code>
|-
|<code>mxw.media("name").ptz("ptz_white_balance_manual", red, blue)</code> || manual white balance, 0.0 .. 1.0 each || <code>mxw.media("USB Cam").ptz("ptz_white_balance_manual", 0.1, 0.7)</code>
|-
|<code>mxw.media("name").ptz("ptz_exposure_auto")</code> || auto exposure || <code>mxw.media("USB Cam").ptz("ptz_exposure_auto")</code>
|-
|<code>mxw.media("name").ptz("ptz_exposure_manual", level)</code> || manual exposure iris, 0.0 (dark) .. 1.0 (light) || <code>mxw.media("USB Cam").ptz("ptz_exposure_manual", 0.4)</code>
|-
|<code>mxw.media("name").ptz("ptz_exposure_manual_v2", iris, gain, shutter)</code> || manual exposure iris/gain/shutter, 0.0 .. 1.0 each || <code>mxw.media("USB Cam").ptz("ptz_exposure_manual_v2", 0.4, 0.2, 0.5)</code>
|-
!colspan="3" |Grabber ( <code>mxw.grabber(name)</code> )
|-
|<code>mxw.grabber("name").isvalid()</code> || True if the named keystone grabber exists || <code>if mxw.grabber("cam").isvalid(): pass</code>
|-
|<code>mxw.grabber("name").getGrabSizeX()</code> || grabber width in px || <code>mxw.grabber("cam").getGrabSizeX()</code>
|-
|<code>mxw.grabber("name").getGrabSizeY()</code> || grabber height in px || <code>mxw.grabber("cam").getGrabSizeY()</code>
|-
|<code>mxw.grabber("name").getData()</code> || return the grabber's pixels as a byte list (RGBA, width×height×4) || <code>px = mxw.grabber("cam").getData()</code>
|}

=== See also ===

* [[Python imgui reference|Python ImGui Reference]] – drawing plugin panels with <code>mxw_imgui</code>
* [[Python plugin reference|Python Plugin Howto]] – writing media and playlist plugins
[[Category:Python]]
[[Category:Reference]]

Python Reference

2026-08-08T15:33:27Z

Admin: Add Category:Python at page end (bot)

== Introduction ==
This document describes the MXWendler (MXW) Python command interface through an overview of the programming structure, with practical examples of automation and internal scripting. The presented Python commands are for most part supported in version 7.2.

== What is Python? ==
Python is a standardized interpreted, high level programming language. It is used in many applications, mainly in AI and generative tasks. The amount of available libraries is outstanding.

== Contents ==
{|
|-
| style="padding: 10px" | [[1. Controlling MXW through Python]]
|-
| style="padding: 10px" | [[Python command reference | 2. Python command reference]]
|-
| style="padding: 10px" | [[Python imgui reference | 2. Python imgui reference]]
|-
| style="padding: 10px" | [[Python plugin reference | Python plugin reference]]
|-
|}
[[Category:Python]]
[[Category:Reference]]

JavaScript command reference

2026-08-08T15:33:26Z

Admin: Add Category:JavaScript at page end (bot)

This page lists the commands of the MXWendler JavaScript command interface. Scripts run on an embedded ECMAScript engine (Duktape) and reach the software through the global <code>mxw</code> object plus a few free functions.

'''The presented JavaScript commands supported in version 7.2. and up'''

=== Legend ===
<div>

''FLOATS'' are written with one decimal: <code>0.0 .. 1.0</code> → every float between 0 and 1 inclusive.

''INTEGERS'' are written as plain numbers or ranges: <code>1 .. 5</code> → the integers 1,2,3,4,5.

''STRINGS'' are written between double quotes.

When <u>OR</u> appears, two alternative call formats produce a similar result; use one at a time.

'''Addressing:''' widgets are targeted by their OSC-style address string, e.g. <code>/mxw/track/active/layer/active/clip</code>.

'''Access model:''' <code>mxw.playlist</code> and <code>mxw.io</code> are ready-made objects – call their methods directly, e.g. <code>mxw.playlist.play()</code>, <code>mxw.io.dmx(4)</code>. <code>mxw.widget(address)</code>, <code>mxw.media(name)</code>, <code>mxw.preload(n)</code> and <code>mxw.grabber(name)</code> are factories that take an address/name/index and return the object to call, e.g. <code>mxw.widget("/mxw/path").getValue()</code>.

</div>

=== Reference ===

{| class="wikitable"
|-
! JS COMMAND !! DESCRIPTION !! EXAMPLE
|-
!colspan="3" |Software Info
|-
|<code>mxw.millis</code> || milliseconds passed since the software was opened || <code>print_console("passed time is " + mxw.millis)</code>
|-
|<code>mxw.width</code> || current frame width in px || <code>print_console("frame width is " + mxw.width)</code>
|-
|<code>mxw.height</code> || current frame height in px || <code>print_console("frame height is " + mxw.height)</code>
|-
|<code>mxw.outwidth</code> || current output width in px || <code>print_console("output width is " + mxw.outwidth)</code>
|-
|<code>mxw.outheight</code> || current output height in px || <code>print_console("output height is " + mxw.outheight)</code>
|-
|<code>mxw.framecounter</code> || number of frames rendered since the software was opened || <code>print_console("frames rendered: " + mxw.framecounter)</code>
|-
|<code>print_console("text")</code> || print a line to the script console (global function) || <code>print_console("hello")</code>
|-
|<code>print_statusline("text")</code> || print text on the application status line (global function) || <code>print_statusline("running")</code>
|-
|<code>mxw.makescreenshot("path")</code> || save a full-frame screenshot as PNG || <code>mxw.makescreenshot("c:/Users/me/Desktop/shot.png")</code>
|-
|<code>mxw.makesectionscreenshot("path", x, y, w, h)</code> || save a cropped screenshot of the region (x, y, w, h) || <code>mxw.makesectionscreenshot("c:/Users/me/Desktop/crop.png", 0, 0, 400, 200)</code>
|-
|<code>mxw.describe()</code> || return a text listing of every operation known to the unified interface registry || <code>print_console(mxw.describe())</code>
|-
!colspan="3" | I/O ( <code>mxw.io</code> )
|-
|<code>mxw.io.dmx(channel)</code> || return the DMX value received on the given channel || <code>print_console("DMX ch4 = " + mxw.io.dmx(4))</code>
|-
|<code>mxw.io.midi(device, channel)</code> || return the MIDI value received from device/channel || <code>print_console("MIDI = " + mxw.io.midi(1, 6))</code>
|-
|<code>mxw.io.keyboard(state, key)</code> || return whether the given key (ASCII) is in the given state || <code>mxw.io.keyboard(0, 65)</code>
|-
|<code>mxw.io.send_dmx(channel, value)</code> || send a DMX value on a channel || <code>mxw.io.send_dmx(4, 255)</code>
|-
|<code>mxw.io.send_midi(device, channel, value)</code> || send a MIDI value to device/channel || <code>mxw.io.send_midi(1, 6, 100)</code>
|-
|<code>mxw.io.pjlink("command", "ip", "pw")</code> || PJLink projector control. Commands: <code>on</code>, <code>off</code>, <code>avmute_on</code>, <code>avmute_off</code>, <code>vmute_on</code>, <code>vmute_off</code> || <code>mxw.io.pjlink("on", "192.168.1.2", "panasonic")</code>
|-
|<code>mxw.io.send_osc("host", port, "address", "tags", ...args)</code> || send an OSC message. <code>tags</code> is one char per argument: <code>d</code> float, <code>i</code> int, <code>c</code> string, <code>b</code> blob (array of 0..255) || <code>mxw.io.send_osc("127.0.0.1", 7000, "/cue", "ci", "go", 5)</code>
|-
!colspan="3" |Playlist ( <code>mxw.playlist</code> )
|-
|<code>mxw.playlist.preload_media()</code> || preload the media used by the playlist || <code>mxw.playlist.preload_media()</code>
|-
|<code>mxw.playlist.play()</code> || play the playlist || <code>mxw.playlist.play()</code>
|-
|<code>mxw.playlist.pause()</code> || pause, or restart if already paused || <code>mxw.playlist.pause()</code>
|-
|<code>mxw.playlist.go_pause(true/false)</code> || halt (true) or resume (false) playback || <code>mxw.playlist.go_pause(true)</code>
|-
|<code>mxw.playlist.skiptonext()</code> || skip to the next cue || <code>mxw.playlist.skiptonext()</code>
|-
|<code>mxw.playlist.go_next()</code> || go to the next cue without playing || <code>mxw.playlist.go_next()</code>
|-
|<code>mxw.playlist.go_prev()</code> || go to the previous cue || <code>mxw.playlist.go_prev()</code>
|-
|<code>mxw.playlist.go_first()</code> || go to the first cue || <code>mxw.playlist.go_first()</code>
|-
|<code>mxw.playlist.navigate_index(index)</code> || go to the cue with the given index || <code>mxw.playlist.navigate_index(2)</code>
|-
|<code>mxw.playlist.navigate_string("name")</code> || go to the cue matching the given name || <code>mxw.playlist.navigate_string("BG_video2")</code>
|-
|<code>mxw.playlist.get_active_cue()</code> || return the active cue index || <code>var i = mxw.playlist.get_active_cue()</code>
|-
!colspan="3" |Preload ( <code>mxw.preload(n)</code> )
|-
|<code>mxw.preload(n).clear()</code> || clear the selected preload || <code>mxw.preload(2).clear()</code>
|-
|<code>mxw.preload(n).set_media("filename")</code> || set the preload media by filename || <code>mxw.preload(2).set_media("try.mp4")</code>
|-
|<code>mxw.preload(n).set_name("name")</code> || rename the preload || <code>mxw.preload(2).set_name("new_background")</code>
|-
|<code>mxw.preload(n).get_name()</code> || return the preload name || <code>var s = mxw.preload(2).get_name()</code>
|-
|<code>mxw.preload(n).add_preload()</code> || load the preload into the layers || <code>mxw.preload(2).add_preload()</code>
|-
|<code>mxw.preload(n).trigger_preload()</code> || trigger a layer from the preload || <code>mxw.preload(2).trigger_preload()</code>
|-
|<code>mxw.preload(n).get_activated()</code> || true if the preload is open for edit || <code>mxw.preload(2).get_activated()</code>
|-
|<code>mxw.preload(n).set_activated(true/false)</code> || open/close the preload for edit || <code>mxw.preload(2).set_activated(false)</code>
|-
|<code>mxw.preload(n).get_layer_position()</code> || return the preload's layer index || <code>mxw.preload(2).get_layer_position()</code>
|-
|<code>mxw.preload(n).get_track_position()</code> || return the preload's track index || <code>mxw.preload(2).get_track_position()</code>
|-
|<code>mxw.preload(n).set_layer_position(pos)</code> || set the preload's layer index || <code>mxw.preload(2).set_layer_position(2)</code>
|-
|<code>mxw.preload(n).set_track_position(pos)</code> || set the preload's track index || <code>mxw.preload(2).set_track_position(2)</code>
|-
!colspan="3" |Widgets ( <code>mxw.widget(address)</code> )
|-
|<code>mxw.widget("/mxw/path").isvalid()</code> || true if the address resolves to a widget || <code>if (mxw.widget("/mxw/path").isvalid()) {}</code>
|-
|<code>mxw.widget("/mxw/path").getValue()</code> || return the widget's normalized value || <code>var o = mxw.widget("/mxw/track/active/layer/active/opacity").getValue()</code>
|-
|<code>mxw.widget("/mxw/path").setValue(v)</code> || set the widget's normalized value || <code>mxw.widget("/mxw/track/active/layer/active/opacity").setValue(0.5)</code>
|-
|<code>mxw.widget("/mxw/path").getStringValue()</code> || return the widget's string value (e.g. a cue/clip name) || <code>print_console(mxw.widget("/mxw/playlist/container/1/column/0/row/1").getStringValue())</code>
|-
|<code>mxw.widget("/mxw/path").setStringValue("text")</code> || set the widget's string value (e.g. name a cue) || <code>mxw.widget("/mxw/playlist/container/1/column/0/row/1").setStringValue("background videoclip")</code>
|-
|<code>mxw.widget("/mxw/path").animate(initvalue, incomingvalue, duration, delta, type)</code> || animate the widget value over <code>duration</code> ms || <code>mxw.widget("/mxw/path").animate(0.0, 1.0, 1000, 0.0, 0)</code>
|-
|<code>mxw.widget("/mxw/path").info()</code> || return an array describing the widget. For a '''clip''': <code>[length, width, height, millis_per_frame, cache_state, media_path]</code>. Empty array if the address does not resolve || <code>var info = mxw.widget("/mxw/track/active/layer/active/clip").info(); print_console(info[5]);</code>
|-
!colspan="3" |Media ( <code>mxw.media(name)</code> )
|-
|<code>mxw.media("name").isvalid()</code> || true if the named media exists || <code>if (mxw.media("USB Cam").isvalid()) {}</code>
|-
|<code>mxw.media("name").ptz("ptz_is_supported")</code> || return whether the (NDI) camera supports PTZ || <code>mxw.media("USB Cam").ptz("ptz_is_supported")</code>
|-
|<code>mxw.media("name").ptz("ptz_zoom", value)</code> || zoom, 0 (in) .. 1 (out) || <code>mxw.media("USB Cam").ptz("ptz_zoom", 0.5)</code>
|-
|<code>mxw.media("name").ptz("ptz_zoom_speed", value)</code> || zoom speed, -1 (out) .. 1 (in) || <code>mxw.media("USB Cam").ptz("ptz_zoom_speed", 0.5)</code>
|-
|<code>mxw.media("name").ptz("ptz_pan_tilt", pan, tilt)</code> || absolute pan/tilt, -1 .. 1 || <code>mxw.media("USB Cam").ptz("ptz_pan_tilt", -0.5, 0.2)</code>
|-
|<code>mxw.media("name").ptz("ptz_pan_tilt_speed", pan_speed, tilt_speed)</code> || pan/tilt speed, -1 (right/down) .. 1 (left/up) || <code>mxw.media("USB Cam").ptz("ptz_pan_tilt_speed", -0.3, 0.8)</code>
|-
|<code>mxw.media("name").ptz("ptz_store_preset", n)</code> || store position/focus/zoom into preset 0 .. 99 || <code>mxw.media("USB Cam").ptz("ptz_store_preset", 75)</code>
|-
|<code>mxw.media("name").ptz("ptz_recall_preset", n, speed)</code> || recall preset 0 .. 99 at speed 0 .. 1 || <code>mxw.media("USB Cam").ptz("ptz_recall_preset", 4, 0.5)</code>
|-
|<code>mxw.media("name").ptz("ptz_auto_focus")</code> || toggle auto-focus || <code>mxw.media("USB Cam").ptz("ptz_auto_focus")</code>
|-
|<code>mxw.media("name").ptz("ptz_focus", value)</code> || absolute focus, 0 (infinity) .. 1 (closest) || <code>mxw.media("USB Cam").ptz("ptz_focus", 0.5)</code>
|-
|<code>mxw.media("name").ptz("ptz_focus_speed", value)</code> || focus speed, -1 (out) .. 1 (in) || <code>mxw.media("USB Cam").ptz("ptz_focus_speed", -0.2)</code>
|-
|<code>mxw.media("name").ptz("ptz_white_balance_auto")</code> || auto white balance || <code>mxw.media("USB Cam").ptz("ptz_white_balance_auto")</code>
|-
|<code>mxw.media("name").ptz("ptz_white_balance_indoor")</code> || indoor white balance || <code>mxw.media("USB Cam").ptz("ptz_white_balance_indoor")</code>
|-
|<code>mxw.media("name").ptz("ptz_white_balance_outdoor")</code> || outdoor white balance || <code>mxw.media("USB Cam").ptz("ptz_white_balance_outdoor")</code>
|-
|<code>mxw.media("name").ptz("ptz_white_balance_oneshot")</code> || set white balance once from current brightness || <code>mxw.media("USB Cam").ptz("ptz_white_balance_oneshot")</code>
|-
|<code>mxw.media("name").ptz("ptz_white_balance_manual", red, blue)</code> || manual white balance, 0.0 .. 1.0 each || <code>mxw.media("USB Cam").ptz("ptz_white_balance_manual", 0.1, 0.7)</code>
|-
|<code>mxw.media("name").ptz("ptz_exposure_auto")</code> || auto exposure || <code>mxw.media("USB Cam").ptz("ptz_exposure_auto")</code>
|-
|<code>mxw.media("name").ptz("ptz_exposure_manual", level)</code> || manual exposure iris, 0.0 (dark) .. 1.0 (light) || <code>mxw.media("USB Cam").ptz("ptz_exposure_manual", 0.4)</code>
|-
|<code>mxw.media("name").ptz("ptz_exposure_manual_v2", iris, gain, shutter)</code> || manual exposure iris/gain/shutter, 0.0 .. 1.0 each || <code>mxw.media("USB Cam").ptz("ptz_exposure_manual_v2", 0.4, 0.2, 0.5)</code>
|-
!colspan="3" |Grabber ( <code>mxw.grabber(name)</code> )
|-
|<code>mxw.grabber("name").isvalid()</code> || true if the named keystone grabber exists || <code>if (mxw.grabber("cam").isvalid()) {}</code>
|-
|<code>mxw.grabber("name").getGrabSizeX()</code> || grabber width in px || <code>mxw.grabber("cam").getGrabSizeX()</code>
|-
|<code>mxw.grabber("name").getGrabSizeY()</code> || grabber height in px || <code>mxw.grabber("cam").getGrabSizeY()</code>
|-
|<code>mxw.grabber("name").getData()</code> || return the grabber's pixels (RGBA, width×height×4) || <code>var px = mxw.grabber("cam").getData()</code>
|}

=== See also ===

* [[JavaScript_Reference|JavaScript Reference]] – overview and getting started
[[Category:JavaScript]]
[[Category:Reference]]

JavaScript Reference

2026-08-08T15:33:24Z

Admin: Add Category:JavaScript at page end (bot)

JavaScript command reference

2026-08-08T15:28:33Z

Admin: Update links after removing '3.' prefix from reference titles (bot)

Python plugin reference

2026-08-08T15:28:30Z

Admin: Update links after removing '3.' prefix from reference titles (bot)

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 command reference|Python command 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> (also <code>plugins/media/python_dev/</code>, same precedence, for internal/unpublished 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 installation / resource directory: <code>plugins/playlist/python/</code> (also <code>plugins/playlist/python_dev/</code>, same precedence, for internal/unpublished plugins)

=== 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.
|-
| <code>plugin_playlist_playbackmode_default</code> || Optional. The clip playback mode a freshly added clip of this media starts in: <code>stop</code>, <code>loop</code>, <code>oneshot</code>, <code>bounce</code>, <code>jitter</code> or <code>random</code>. Omitted or unknown defaults to <code>loop</code>. Only seeds the initial mode - a project reload restores the clip's own saved mode.
|}

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>
|-
| <code>plugin_accepts_trigger</code> || <code>true</code>/<code>false</code> (default <code>false</code>). When <code>true</code>, dragging a TRIGGER item onto this item's grid cell connects it (the drag shows a green "connect" outline) instead of moving/swapping cells, and the plugin can read the connection with <code>mxw.pending_trigger_drop(item_id)</code>. Set it for a timeline; see [[#Connecting to a TRIGGER item]].
|-
| <code>plugin_cell_scrub</code> || <code>true</code>/<code>false</code> (default <code>false</code>). When <code>true</code>, ALT + left-drag across this item's grid cell scrubs instead of moving the item: the host draws a playhead line and stashes the 0..1 fraction of the cell width each frame, readable with <code>mxw.pending_cell_scrub(item_id)</code>. Set it for a timeline; see [[#Connecting to a TRIGGER item]].
|}

== 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 command reference|Python command reference]].
* <code>mxw_imgui</code> — Dear ImGui bindings for drawing settings panels inside MXWendler (used by <code>onRenderPanel()</code>), documented in the [[Python imgui reference|Python ImGui Reference]].

=== Installing own modules with mxw-pip ===

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>
%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).

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:

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

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).
|-
| <code>onGetParams()</code> || returns a list of dicts || Declare addressable parameters, called once per instance and cached: <code>{"name": str, "type": "float"|"string", "min": float, "max": float, "default": float|str}</code> (<code>min</code>/<code>max</code> ignored for <code>"string"</code>; <code>type</code> defaults to <code>"float"</code>).
|-
| <code>onParamChanged(index, value)</code> || — || A parameter was set via OSC, Python or JS at <code>.../clip/media/1/param/<index+1></code> (0-based <code>index</code>). Store or apply it — the host never caches the value itself.
|}

Parameters are addressed exactly like shader effect parameters, e.g. <code>/mxw/track/2/layer/1/clip/media/1/param/1 0.8</code> or, for a <code>"string"</code>-typed param, <code>/mxw/track/2/layer/1/clip/media/1/param/2 "https://www.mxwendler.net"</code>. The <code>media/1</code> segment reflects the clip's single active media slot (any other index is out of range). Because the host does not persist a param's value, a plugin that wants one to survive a project reload must fold it into its own <code>onSave()</code>/<code>onLoad()</code> and hand the restored value back as <code>onGetParams()</code>'s <code>"default"</code> — which runs after <code>onLoad()</code> already restored the instance state.

=== 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''', 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]).

<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 command reference|Python command 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.
|-
| <code>getProgress()</code> || no || Return <code>0.0 .. 1.0</code> to fill the cell's bottom progress bar (the same bar the built-in advance/fade items draw); <code><= 0</code> draws nothing.
|}

=== Connecting to a TRIGGER item ===

A playlist plugin (e.g. a keyframe timeline) can bind to a TRIGGER item and animate its layer/clip controls. The user drops a trigger either onto the plugin's settings panel or onto its grid cell; the plugin resolves the connection to the trigger's grid <code>(col, row)</code> and enumerates its controls from there. No need to play the trigger first — the controls are read from the connected preload's fixture layer, and the very same <code>(col,row)</code> address resolves the ''live'' layer during playout.

{| class="wikitable"
! Function !! Meaning
|-
| <code>mxw_imgui.accept_trigger_drop()</code> || Makes the current panel window a drop target for a trigger; returns the dropped trigger's 1-based <code>(col, row)</code>, or <code>(-1, -1)</code>. Handles the "drop onto the panel" route.
|-
| <code>mxw.pending_trigger_drop(item_id)</code> || Returns a <code>(col, row)</code> stashed by the host when a trigger was dropped onto ''this'' plugin item's grid cell (pass your own <code>item_id</code>), or <code>(-1, -1)</code>. Handles the "drop onto the grid cell" route.
|-
| <code>mxw.trigger_controls(col, row)</code> || Returns the trigger's animatable (slider) controls as <code>(label, address)</code> pairs — layer, clip, effect and media params. Re-read it every frame: controls the user swaps on the clip appear/vanish live. Each <code>address</code> is usable with <code>mxw.widget(address).setValue()</code>.
|-
| <code>mxw.pending_cell_scrub(item_id)</code> || Returns the 0..1 fraction of an ALT + left-drag across ''this'' plugin item's grid cell (stashed by the host each frame while dragging, consumed on read), or <code>-1.0</code>. Needs the <code>plugin_cell_scrub</code> manifest opt-in. Poll it in <code>onNewFrameAlways()</code> so scrubbing also works while the panel is closed.
|}

Poll both drop routes at the top of <code>onRenderPanel()</code> and store the resulting <code>(col,row)</code>; then call <code>mxw.trigger_controls()</code> to (re)build your control list each frame.

A time connection between the connected clip and the plugin follows from these pieces: the clip's <code>.../clip/Position</code> control (normalized 0..1) is the clip's own time axis. Write it when your playhead moves (scrub → seek) and read it every frame to follow the clip when it is scrubbed — or simply playing. See the timeline plugin's <code>sync_time_link()</code> for a worked example including the echo filtering (a written Position reads back frame-quantized).

=== 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, all in the [https://github.com/mxwendler/mxw-plugins-playlist mxw-plugins-playlist] repository: <code>plugins/playlist/python/plugin_advance_datetime</code> (timed playlist navigation, rich settings panel), <code>plugin_video_writer</code>, <code>plugin_comment</code> (a minimal example: a no-op annotation item).

== Example plugins on GitHub ==

The bundled example plugins are maintained as public repositories under [https://github.com/mxwendler github.com/mxwendler], grouped by type — 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-plugins-media mxw-plugins-media]
|-
| <code>plugin_opengl_cube_direct</code> || media || Approach 3: same cube rendered directly into the media texture || [https://github.com/mxwendler/mxw-plugins-media mxw-plugins-media]
|-
| <code>plugin_web_media</code> || media || A web browser as media source (whole-scheme <code>web://</code> plugin) || [https://github.com/mxwendler/mxw-plugins-media mxw-plugins-media]
|-
| <code>plugin_fragcoord</code>, <code>plugin_shadertoy</code> || media || Shader-as-generative-media (FragCoord.xyz / Shadertoy) || [https://github.com/mxwendler/mxw-plugins-media mxw-plugins-media]
|-
| <code>plugin_advance_datetime</code> || playlist || Timed playlist navigation with a rich settings panel || [https://github.com/mxwendler/mxw-plugins-playlist mxw-plugins-playlist]
|-
| <code>plugin_video_writer</code> || playlist || Write video files from the playlist || [https://github.com/mxwendler/mxw-plugins-playlist mxw-plugins-playlist]
|-
| <code>plugin_comment</code> || playlist || Minimal example: a no-op text annotation item || [https://github.com/mxwendler/mxw-plugins-playlist mxw-plugins-playlist]
|}

=== Developing a new plugin inside a project ===

The most convenient place to develop a plugin is '''inside a project folder''': the plugin travels with the show, needs no write access to the installation, and overrides a same-named bundled plugin. Conceptually:

# '''Create a project folder''' — a plain directory that will hold everything belonging to the show, e.g. <code>D:/shows/particles/</code>.
# '''Save the project file there''' — ''File → Save As..'' into that folder, e.g. <code>D:/shows/particles/particles.mxw</code>. The folder containing the <code>.mxw</code> file ''is'' the project folder; loading the project later makes MXWendler pick up its plugins again.
# '''Create the plugin directory there''' — the project mirrors the installation layout: <code>D:/shows/particles/plugins/media/python/<plugin_folder>/</code> for media plugins (<code>plugins/playlist/python/...</code> for playlist plugins). Enable ''Settings → Python → Check for plugins inside the project folder'' — project plugins have the highest precedence of all plugin locations.

=== Letting Claude Code write the plugin ===

An AI coding agent like [https://claude.com/claude-code Claude Code] can write a complete plugin from the contract described on this page. Start it '''in the project folder''', so it creates the plugin directly where MXWendler looks for it:

<pre>
cd D:/shows/particles
claude
</pre>

Give it the reference material and a precise task — for a generative OpenGL particle system for example:

<pre>
Create an MXWendler media plugin under plugins/media/python/plugin_particle_system/
(folder + mxw_plugin.ini + mxw_main.py).

Reference: the bundled example in <MXWendler install dir>/plugins/media/python/
plugin_opengl_cube_direct/ - follow its structure and hook usage exactly, and the
plugin howto at https://wiki.mxwendler.net/index.php?title=Python_plugin_reference.

The plugin is a generative OpenGL particle system, addressed as
generative://particle_system, rendered with ModernGL directly into the media
texture via onRenderFrameGL (no readback, no onRenderFrame). Keep per-instance
state keyed by media_id. Emit particles from the center, integrate velocity and
gravity per frame scaled by the clip playback speed (onSetSpeed, onSpeedRange
-5..5). Expose particle count, gravity and start size as sliders in
onRenderPanel (mxw_imgui) and persist them via onSave/onLoad. Respect the GL
rules: attach with moderngl.create_context() lazily on the first render call,
never release the external texture, rebuild the fbo when (texture, w, h)
changes, flip Y in the projection.
</pre>

Then iterate: create the media in a clip (it appears under its <code>plugin_menu_name</code>, or address <code>generative://particle_system</code> directly) and refine with follow-up prompts ("make the particles fade out", "add a color gradient slider", ...). Errors show up in the interpreter console. For playlist plugins, ''Settings → Python → Reload Python Plugins'' hot-reloads the edited source; for media plugins, recreate the media (or restart) to re-import the module.

== 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 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.
[[Category:Reference]]

Python command reference

2026-08-08T15:28:28Z

Admin: Update links after removing '3.' prefix from reference titles (bot)

This page lists the commands of the Python module <code>mxw</code>, MXWendler's general Python command interface. It is available from the script console and from Python plugins (see the [[Python plugin reference|Python Plugin Howto]]). For drawing plugin panels see the [[Python imgui reference|Python ImGui Reference]].

The embedded interpreter is '''Python 3.12'''. Import is implicit in the script console; in a plugin module use <code>import mxw</code>.

'''The presented Python commands supported in version 7.2. and up'''

=== Legend ===
<div>

''FLOATS'' are written with one decimal: <code>0.0 .. 1.0</code> → every float between 0 and 1 inclusive.

''INTEGERS'' are written as plain numbers or ranges: <code>1 .. 5</code> → the integers 1,2,3,4,5.

''STRINGS'' are written between double quotes.

When <u>OR</u> appears, two alternative call formats produce a similar result; use one at a time.

'''Addressing:''' widgets are targeted by their OSC-style address string, e.g. <code>/mxw/track/active/layer/active/clip</code>. The same addresses used over OSC work here.

'''Access model (7.2):''' widget values are read/written through <code>mxw.widget(address)</code>; global functions live in the submodules/factories <code>mxw.playlist</code>, <code>mxw.io</code>, <code>mxw.preload(n)</code>, <code>mxw.media(name)</code>, <code>mxw.grabber(name)</code>.

</div>

=== Reference ===

{| class="wikitable"
|-
! PYTHON COMMAND/SYMBOL !! DESCRIPTION !! EXAMPLE
|-
!colspan="3" |Software Info
|-
|<code>mxw.millis</code> || milliseconds passed since the software was opened || <code>mxw.print_console("passed time is " + str(mxw.millis))</code>
|-
|<code>mxw.width</code> || current frame width in px || <code>mxw.print_console("frame width is " + str(mxw.width))</code>
|-
|<code>mxw.height</code> || current frame height in px || <code>mxw.print_console("frame height is " + str(mxw.height))</code>
|-
|<code>mxw.outwidth</code> || current output width in px || <code>mxw.print_console("output width is " + str(mxw.outwidth))</code>
|-
|<code>mxw.outheight</code> || current output height in px || <code>mxw.print_console("output height is " + str(mxw.outheight))</code>
|-
|<code>mxw.framecounter</code> || number of frames rendered since the software was opened || <code>mxw.print_console("frames rendered: " + str(mxw.framecounter))</code>
|-
|<code>mxw.print_console("text")</code> || print a line to the script console || <code>mxw.print_console("hello")</code>
|-
|<code>mxw.print_statusline("text")</code> || print text on the application status line || <code>mxw.print_statusline("running")</code>
|-
|<code>mxw.makescreenshot("path")</code> || save a full-frame screenshot as PNG (empty path → Desktop) || <code>mxw.makescreenshot("c:/Users/me/Desktop/shot.png")</code>
|-
|<code>mxw.makesectionscreenshot("path", x, y, w, h)</code> || save a cropped screenshot of the region (x, y, w, h) || <code>mxw.makesectionscreenshot("c:/Users/me/Desktop/crop.png", 0, 0, 400, 200)</code>
|-
|<code>mxw.describe()</code> || return a text listing of every operation known to the unified interface registry (auto-docs / discovery) || <code>mxw.print_console(mxw.describe())</code>
|-
!colspan="3" | I/O ( <code>mxw.io</code> )
|-
|<code>mxw.io.dmx(channel)</code> || return the DMX value received on the given channel || <code>v = mxw.io.dmx(4)</code>
|-
|<code>mxw.io.midi(device, channel)</code> || return the MIDI value received from device/channel || <code>v = mxw.io.midi(1, 6)</code>
|-
|<code>mxw.io.keyboard(state, key)</code> || return whether the given key (ASCII) is in the given state || <code>if mxw.io.keyboard(0, 65): pass</code>
|-
|<code>mxw.io.send_dmx(channel, value)</code> || send a DMX value on a channel || <code>mxw.io.send_dmx(4, 255)</code>
|-
|<code>mxw.io.send_midi(device, channel, value)</code> || send a MIDI value to device/channel || <code>mxw.io.send_midi(1, 6, 100)</code>
|-
|<code>mxw.io.pjlink("command", "ip", "pw")</code> || PJLink projector control. Commands: <code>on</code>, <code>off</code>, <code>avmute_on</code>, <code>avmute_off</code>, <code>vmute_on</code>, <code>vmute_off</code> || <code>mxw.io.pjlink("on", "192.168.1.2", "panasonic")</code>
|-
|<code>mxw.io.send_osc("host", port, "address", "tags", *args)</code> || send an OSC message. <code>tags</code> is one char per argument: <code>d</code> float, <code>i</code> int, <code>c</code> string, <code>b</code> blob (list of 0..255) || <code>mxw.io.send_osc("127.0.0.1", 7000, "/cue", "ci", "go", 5)</code>
|-
!colspan="3" |Playlist ( <code>mxw.playlist</code> )
|-
|<code>mxw.playlist.preload_media()</code> || preload the media used by the playlist || <code>mxw.playlist.preload_media()</code>
|-
|<code>mxw.playlist.play()</code> || play the playlist || <code>mxw.playlist.play()</code>
|-
|<code>mxw.playlist.pause()</code> || pause, or restart if already paused || <code>mxw.playlist.pause()</code>
|-
|<code>mxw.playlist.go_pause(True/False)</code> || halt (True) or resume (False) playback || <code>mxw.playlist.go_pause(True)</code>
|-
|<code>mxw.playlist.skiptonext()</code> || skip to the next cue || <code>mxw.playlist.skiptonext()</code>
|-
|<code>mxw.playlist.go_next()</code> || go to the next cue without playing || <code>mxw.playlist.go_next()</code>
|-
|<code>mxw.playlist.go_prev()</code> || go to the previous cue || <code>mxw.playlist.go_prev()</code>
|-
|<code>mxw.playlist.go_first()</code> || go to the first cue || <code>mxw.playlist.go_first()</code>
|-
|<code>mxw.playlist.navigate_index(index)</code> || go to the cue with the given index || <code>mxw.playlist.navigate_index(2)</code>
|-
|<code>mxw.playlist.navigate_string("name")</code> || go to the cue matching the given name || <code>mxw.playlist.navigate_string("BG_video2")</code>
|-
|<code>mxw.playlist.get_active_cue()</code> || return the active cue index (int) || <code>i = mxw.playlist.get_active_cue()</code>
|-
|<code>mxw.playlist.get_cue_count()</code> || return the number of cues (int) || <code>n = mxw.playlist.get_cue_count()</code>
|-
|<code>mxw.playlist.get_cue_names()</code> || return the list of cue names (index matches <code>navigate_index</code>) || <code>for name in mxw.playlist.get_cue_names(): pass</code>
|-
|<code>mxw.playlist.is_rehearsal()</code> || return True if the playlist is in rehearsal mode || <code>if mxw.playlist.is_rehearsal(): pass</code>
|-
!colspan="3" |Preload ( <code>mxw.preload(n)</code> )
|-
|<code>mxw.preload(n).isvalid()</code> || True if preload <code>n</code> exists || <code>if mxw.preload(2).isvalid(): pass</code>
|-
|<code>mxw.preload(n).clear()</code> || clear the selected preload || <code>mxw.preload(2).clear()</code>
|-
|<code>mxw.preload(n).set_media("filename")</code> || set the preload media by filename || <code>mxw.preload(2).set_media("try.mp4")</code>
|-
|<code>mxw.preload(n).set_name("name")</code> || rename the preload || <code>mxw.preload(2).set_name("new_background")</code>
|-
|<code>mxw.preload(n).add_preload()</code> || load the preload into the layers || <code>mxw.preload(2).add_preload()</code>
|-
|<code>mxw.preload(n).trigger_preload()</code> || trigger a layer from the preload || <code>mxw.preload(2).trigger_preload()</code>
|-
|<code>mxw.preload(n).get_activated()</code> || True if the preload is open for edit || <code>mxw.preload(2).get_activated()</code>
|-
|<code>mxw.preload(n).set_activated(True/False)</code> || open/close the preload for edit || <code>mxw.preload(2).set_activated(False)</code>
|-
|<code>mxw.preload(n).get_layer_position()</code> || return the preload's layer index || <code>mxw.preload(2).get_layer_position()</code>
|-
|<code>mxw.preload(n).get_track_position()</code> || return the preload's track index || <code>mxw.preload(2).get_track_position()</code>
|-
|<code>mxw.preload(n).set_layer_position(pos)</code> || set the preload's layer index || <code>mxw.preload(2).set_layer_position(2)</code>
|-
|<code>mxw.preload(n).set_track_position(pos)</code> || set the preload's track index || <code>mxw.preload(2).set_track_position(2)</code>
|-
|<code>mxw.preload(n).get_preload_names()</code> || return the list of preload comment/name strings || <code>names = mxw.preload(2).get_preload_names()</code>
|-
|<code>mxw.preload(n).get_image_sample_cvmat(w, h)</code> || return a <code>w</code>×<code>h</code> RGBA image sample of the preload as a buffer (OpenCV Mat) || <code>img = mxw.preload(2).get_image_sample_cvmat(64, 64)</code>
|-
!colspan="3" |Widgets ( <code>mxw.widget(address)</code> )
|-
|<code>mxw.widget("/mxw/path").getValue()</code> || return the widget's normalized value (float) || <code>o = mxw.widget("/mxw/track/active/layer/active/opacity").getValue()</code>
|-
|<code>mxw.widget("/mxw/path").setValue(v)</code> || set the widget's normalized value || <code>mxw.widget("/mxw/track/active/layer/active/opacity").setValue(0.5)</code>
|-
|<code>mxw.widget("/mxw/path").getStringValue()</code> || return the widget's string value (e.g. a cue/clip name) || <code>mxw.print_console(mxw.widget("/mxw/playlist/container/1/column/0/row/1").getStringValue())</code>
|-
|<code>mxw.widget("/mxw/path").setStringValue("text")</code> || set the widget's string value (e.g. name a cue) || <code>mxw.widget("/mxw/playlist/container/1/column/0/row/1").setStringValue("background videoclip")</code>
|-
|<code>mxw.widget("/mxw/path").setWidgetRealValue(d)</code> || set the widget's real (un-normalized) value || <code>mxw.widget("/mxw/path").setWidgetRealValue(120.0)</code>
|-
|<code>mxw.widget("/mxw/path").animate(initvalue, incomingvalue, duration, delta, type)</code> || animate the widget value over <code>duration</code> ms || <code>mxw.widget("/mxw/path").animate(0.0, 1.0, 1000, 0.0, 0)</code>
|-
|<code>mxw.widget("/mxw/path").info()</code> || return a list describing the widget. For a '''clip''': <code>[length, width, height, millis_per_frame, cache_state, media_path]</code>. Returns <code>[]</code> if the address does not resolve || <code>length, w, h, mspf, cache, path = mxw.widget("/mxw/track/active/layer/active/clip").info()</code>
|-
!colspan="3" |Media ( <code>mxw.media(name)</code> )
|-
|<code>mxw.media("name").isvalid()</code> || True if the named media exists || <code>if mxw.media("USB Cam").isvalid(): pass</code>
|-
|<code>mxw.media("name").reference(True/False)</code> || add (True) or remove (False) a reference that keeps the media loaded || <code>mxw.media("clip.mov").reference(True)</code>
|-
|<code>mxw.media("name").unload_media_full_if_not_used_by_clips()</code> || unload the media if no clip uses it (returns bool) || <code>mxw.media("clip.mov").unload_media_full_if_not_used_by_clips()</code>
|-
|<code>mxw.media("name").get_image_sample_cvmat(w, h)</code> || return a <code>w</code>×<code>h</code> RGBA image sample of the media (OpenCV Mat) || <code>img = mxw.media("clip.mov").get_image_sample_cvmat(64, 64)</code>
|-
|<code>mxw.media("name").get_image_sample_cvmat_async(w, h)</code> || non-blocking variant of the image sample || <code>img = mxw.media("clip.mov").get_image_sample_cvmat_async(64, 64)</code>
|-
|<code>mxw.media("name").get_capture_device_names()</code> || return the list of available capture-device names || <code>devs = mxw.media("").get_capture_device_names()</code>
|-
|<code>mxw.media("name").ptz("ptz_is_supported")</code> || return whether the (NDI) camera supports PTZ || <code>mxw.media("USB Cam").ptz("ptz_is_supported")</code>
|-
|<code>mxw.media("name").ptz("ptz_zoom", value)</code> || zoom, 0 (in) .. 1 (out) || <code>mxw.media("USB Cam").ptz("ptz_zoom", 0.5)</code>
|-
|<code>mxw.media("name").ptz("ptz_zoom_speed", value)</code> || zoom speed, -1 (out) .. 1 (in) || <code>mxw.media("USB Cam").ptz("ptz_zoom_speed", 0.5)</code>
|-
|<code>mxw.media("name").ptz("ptz_pan_tilt", pan, tilt)</code> || absolute pan/tilt, -1 .. 1 || <code>mxw.media("USB Cam").ptz("ptz_pan_tilt", -0.5, 0.2)</code>
|-
|<code>mxw.media("name").ptz("ptz_pan_tilt_speed", pan_speed, tilt_speed)</code> || pan/tilt speed, -1 (right/down) .. 1 (left/up) || <code>mxw.media("USB Cam").ptz("ptz_pan_tilt_speed", -0.3, 0.8)</code>
|-
|<code>mxw.media("name").ptz("ptz_store_preset", n)</code> || store position/focus/zoom into preset 0 .. 99 || <code>mxw.media("USB Cam").ptz("ptz_store_preset", 75)</code>
|-
|<code>mxw.media("name").ptz("ptz_recall_preset", n, speed)</code> || recall preset 0 .. 99 at speed 0 .. 1 || <code>mxw.media("USB Cam").ptz("ptz_recall_preset", 4, 0.5)</code>
|-
|<code>mxw.media("name").ptz("ptz_auto_focus")</code> || toggle auto-focus || <code>mxw.media("USB Cam").ptz("ptz_auto_focus")</code>
|-
|<code>mxw.media("name").ptz("ptz_focus", value)</code> || absolute focus, 0 (infinity) .. 1 (closest) || <code>mxw.media("USB Cam").ptz("ptz_focus", 0.5)</code>
|-
|<code>mxw.media("name").ptz("ptz_focus_speed", value)</code> || focus speed, -1 (out) .. 1 (in) || <code>mxw.media("USB Cam").ptz("ptz_focus_speed", -0.2)</code>
|-
|<code>mxw.media("name").ptz("ptz_white_balance_auto")</code> || auto white balance || <code>mxw.media("USB Cam").ptz("ptz_white_balance_auto")</code>
|-
|<code>mxw.media("name").ptz("ptz_white_balance_indoor")</code> || indoor white balance || <code>mxw.media("USB Cam").ptz("ptz_white_balance_indoor")</code>
|-
|<code>mxw.media("name").ptz("ptz_white_balance_outdoor")</code> || outdoor white balance || <code>mxw.media("USB Cam").ptz("ptz_white_balance_outdoor")</code>
|-
|<code>mxw.media("name").ptz("ptz_white_balance_oneshot")</code> || set white balance once from current brightness || <code>mxw.media("USB Cam").ptz("ptz_white_balance_oneshot")</code>
|-
|<code>mxw.media("name").ptz("ptz_white_balance_manual", red, blue)</code> || manual white balance, 0.0 .. 1.0 each || <code>mxw.media("USB Cam").ptz("ptz_white_balance_manual", 0.1, 0.7)</code>
|-
|<code>mxw.media("name").ptz("ptz_exposure_auto")</code> || auto exposure || <code>mxw.media("USB Cam").ptz("ptz_exposure_auto")</code>
|-
|<code>mxw.media("name").ptz("ptz_exposure_manual", level)</code> || manual exposure iris, 0.0 (dark) .. 1.0 (light) || <code>mxw.media("USB Cam").ptz("ptz_exposure_manual", 0.4)</code>
|-
|<code>mxw.media("name").ptz("ptz_exposure_manual_v2", iris, gain, shutter)</code> || manual exposure iris/gain/shutter, 0.0 .. 1.0 each || <code>mxw.media("USB Cam").ptz("ptz_exposure_manual_v2", 0.4, 0.2, 0.5)</code>
|-
!colspan="3" |Grabber ( <code>mxw.grabber(name)</code> )
|-
|<code>mxw.grabber("name").isvalid()</code> || True if the named keystone grabber exists || <code>if mxw.grabber("cam").isvalid(): pass</code>
|-
|<code>mxw.grabber("name").getGrabSizeX()</code> || grabber width in px || <code>mxw.grabber("cam").getGrabSizeX()</code>
|-
|<code>mxw.grabber("name").getGrabSizeY()</code> || grabber height in px || <code>mxw.grabber("cam").getGrabSizeY()</code>
|-
|<code>mxw.grabber("name").getData()</code> || return the grabber's pixels as a byte list (RGBA, width×height×4) || <code>px = mxw.grabber("cam").getData()</code>
|}

=== See also ===

* [[Python imgui reference|Python ImGui Reference]] – drawing plugin panels with <code>mxw_imgui</code>
* [[Python plugin reference|Python Plugin Howto]] – writing media and playlist plugins
[[Category:Reference]]

Tutorial Eventmaster Toolset Controlling MXWendler by e.g. e2 S3 Image Processor

2026-08-08T15:28:26Z

Admin: Update links after removing '3.' prefix from reference titles (bot)

This tutorial applies to all different OS and MXWendler versions > 6.0.04

== Introduction==
This tutorial explains how to set up a Barco Eventmaster to trigger and control media playback on StageDesigner or FXServer.

==Control Setup==

1. Open SD (StageDesigner) and load a clip into preload 1:

[[File:e2_01.png|600px]]

2. Open Settings->IO->Barco e2 and activate TCP listening. Also note down the port number.

[[File:e2_02.png|600px]]

3. In the Barco Eventmaster Toolset, create an 'External Device', name it e.g. 'StageDesigner'.

[[File:e2_03.png|600px]]

4. In the 'Adjust: StageDesigner' tab, set IP address and port number.

[[File:e2_04.png|600px]]

5. In the 'Adjust: StageDesigner' tab, add a new command. Store the command content, e.g.
* /mxw/preload/1 play to start a clip
* /mxw/preload/1 play to stop a clip

More possible commands are in the OSC control section: [[MXW_OSC_command_reference]]

[[File:e2_05.png|600px]]

6. In the 'Cue' section, add a cue.

[[File:e2_06.png|600px]]

7. In this 'Cue', add actions.

[[File:e2_07.png|600px]]

8. From 'External Devices' drop an available command onto the 'Commands' field of the action.

[[File:e2_08c.png|600px]]

9. Play this cue, a clip should be started in the StageDesigner

Controlling MXW through Python

2026-08-08T15:28:25Z

Admin: Update links after removing '3.' prefix from reference titles (bot)