Python command reference: Difference between revisions

From MXWendler Wiki
Jump to navigation Jump to search
← Older editNewer edit →
Hwendler (talk | contribs)
88 edits
No edit summary
7.2: regenerate from source (unified script interface: widget().info(), mxw.describe(), OO proxies)
Line 1: Line 1:
Here are listed the main commands that can be used for scripting with Python.
<!-- MXWendler wiki page: Python command reference (module mxw) -->
 
<!-- Intended location: https://wiki.mxwendler.net/index.php?title=3._Python_command_reference -->
=== Legend ===
<!-- See also: https://wiki.mxwendler.net/index.php?title=Python_ImGui_Reference -->
<div>
<!-- See also: https://wiki.mxwendler.net/index.php?title=Python_Plugin_Howto -->
 
The standard used to represent the available values for each command is:
 
 
''FLOATS'' are represented with one decimal:
 
<code>0.0 .. 1.0</code> &rarr; all float values between 0 and 1 included
 
 
''INTEGERS'' are represented with numbers or descriptions:
 
<code>1 .. 5</code> &rarr; all integers between 1 and 5 included ( 1 , 2 , 3 , 4 , 5 ) <br>
<code>1 .. (MAX n layers)</code> &rarr; 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 double quotation marks:
 
<code>/mxw/set info </code>
 
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>


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_Howto|Python Plugin Howto]]). For drawing plugin panels see the [[Python_ImGui_Reference|Python ImGui Reference]].


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


Here are listed all the commands that MXW recognizes.
'''Applies to MXWendler StageDesigner 7.2.''' Commands marked '''(new in 7.2)''' or '''(changed in 7.2)''' were introduced or reworked in this version as part of the unified script/OSC interface.


=== Legend ===
=== Legend ===
<div>  
<div>
 
The standard used to represent the available values for each command is:
 
 
''FLOATS'' are represented with one decimal:
 
<code>0.0 .. 1.0</code> &rarr; all float values between 0 and 1 included
 
 
''INTEGERS'' are represented with numbers or descriptions:
 
<code>1 .. 5</code> &rarr; all integers between 1 and 5 included ( 1 , 2 , 3 , 4 , 5 ) <br>
<code>1 .. (MAX n layers)</code> &rarr; 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
''FLOATS'' are written with one decimal: <code>0.0 .. 1.0</code> &rarr; every float between 0 and 1 inclusive.


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


''STRINGS'' are represented between double quotation marks:
''STRINGS'' are written between double quotes.


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


When <code>“name”</code> is contained in the available string variable, then the content is to be substituted with the actual name.
'''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.
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>
'''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>. The older global <code>reg_*</code> helper functions have been removed in favour of this object interface.


</div>


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


{| class="wikitable"
{| class="wikitable"
Line 76: Line 35:
!colspan="3" |Software Info
!colspan="3" |Software Info
|-
|-
|<code>mxw.millis</code>|| returns the amount of milliseconds passed since opening the software|| <code>mxw.print_console("current passed time is" + str(mxw.millis) );</code>  
|<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>||returns the current frame width in px|| <code>mxw.print_console("frame width is" + str(mxw.width) );</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>||returns the current frame height in px|| <code>mxw.print_console("frame height is" + str(mxw.height));</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>||returns current output width|| <code>mxw.print_console("output height is" + str(mxw.outwidth));</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>||returns the current output height|| <code>mxw.print_console("output width is" + str(mxw.outheight));</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>||returns the amount of frames rendered since opening the software|| <code>mxw.print_console("total number of frames rendered is" + str(mxw.framecounter));</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" + mxw.widget("/mxw/path").getStringValue())</code> || prints the name of the desired playlist cue || <code>mxw.print_console("The clip name in the second cue is" + mxw.widget("/mxw/playlist/container/1/column/0/row/1").getStringValue());</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 status line|| <code>print text on status line()</code>
|<code>mxw.print_statusline("text")</code> || print text on the application status line || <code>mxw.print_statusline("running")</code>
|-
|-
!colspan="3" | I/O
|<code>mxw.makescreenshot("path")</code> || save a full-frame screenshot as PNG (empty path &rarr; Desktop) || <code>mxw.makescreenshot("c:/Users/me/Desktop/shot.png")</code>
|-
|-
|<code>mxw.dmx()</code> ||returns the DMX value received from the specified universe and channel|| <code>mxw.print_console("DMX value in u. 1, ch. 4 is" + mxw.dmx(1,4));</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.midi()</code>||returns the MIDI value received from the specified device and channel|| <code>mxw.print_console("MIDI value in dev. 1, ch. 6 is" + mxw.midi(1,6));</code>  
|<code>mxw.describe()</code> || '''(new in 7.2)''' return a text listing of every operation known to the unified interface registry (auto-docs / discovery) || <code>mxw.print_console(mxw.describe())</code>
|-
|-
|<code>mxw.keyboard("ASCII_code")</code> || returns if the specified key is pressed or not || <code>mxw.keyboard(65)</code>
!colspan="3" | I/O ( <code>mxw.io</code> )
|-
|-
|<code>mxw.io.pjlink("on", "IP_ADDRESS", "pj_password")</code> || sends a.io.pjlink command to the selected projector and turns it on || <code>mxw.io.pjlink("on", "192.168.1.2", "panasonic")</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.pjlink("off", "IP_ADDRESS", "pj_password")</code> || sends a.io.pjlink command to the selected projector and turns it off|| <code>mxw.io.pjlink("off", "192.168.1.2", "panasonic")</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.pjlink("avmute_on", "IP_ADDRESS", "pj_password")</code> || sends a.io.pjlink command to the selected projector and mutes audio and video || <code>mxw.io.pjlink("avmute_on", "192.168.1.2", "panasonic")</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.pjlink("avmute_off", "IP_ADDRESS", "pj_password")</code> || sends a.io.pjlink command to the selected projector and unmutes audio and video || <code>mxw.io.pjlink("avmute_off", "192.168.1.2", "panasonic")</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.pjlink("vmute_on", "IP_ADDRESS", "pj_password")</code> || sends a.io.pjlink command to the selected projector and mutes video || <code>mxw.io.pjlink("vmute_on", "192.168.1.2", "panasonic")</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("vmute_off", "IP_ADDRESS", "pj_password")</code> || sends a.io.pjlink command to the selected projector and unmutes video || <code>mxw.io.pjlink("vmute_off", "192.168.1.2", "panasonic")</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.media("camera_name").ptz("ptz_is_supported")</code> || control if a NDI Camera supports PTZ || <code>mxw.media("USB Cam").ptz("ptz_is_supported")</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>
|-
|-
|<code>mxw.media("camera_name").ptz("ptz_zoom", value)</code> || control the zoom of a NDI PTZ Camera, values from 0(zoomed in) to 1(zoomed out) || <code>mxw.media("USB Cam").ptz("ptz_zoom", 0.5)</code>
!colspan="3" |Playlist ( <code>mxw.playlist</code> )
|-
|-
|<code>mxw.media("camera_name").ptz("ptz_pan_tilt", value_pan, value_tilt)</code> || control the pan and tilting of a NDI PTZ Camera (values from -1 to 1) || <code><code>mxw.media("USB Cam").ptz("ptz_pan_tilt", -0.5, 0.2)</code>
|<code>mxw.playlist.preload_media()</code> || preload the media used by the playlist || <code>mxw.playlist.preload_media()</code>
|-
|-
|<code>mxw.media("camera_name").ptz("ptz_zoom_speed", value)</code> || control the zoom speed a NDI PTZ Camera, values from -1(zoom outwards) to 1 (zoom inwards) || <code><code>mxw.media("USB Cam").ptz("ptz_zoom", 0.5)</code>
|<code>mxw.playlist.play()</code> || play the playlist || <code>mxw.playlist.play()</code>
|-
|-
|<code>mxw.media("camera_name").ptz("ptz_pan_tilt_speed", pan_speed, tilt_speed)</code> || control the pan and tilt speed a NDI PTZ Camera, values -1 (move right/down) to 1 (move left/up) || <code>mxw.media("USB Cam").ptz("ptz_pan_tilt_speed", -0.3, 0.8)</code>
|<code>mxw.playlist.pause()</code> || pause, or restart if already paused || <code>mxw.playlist.pause()</code>
|-
|-
|<code>mxw.media("camera_name").ptz("ptz_store_preset", preset_number)</code> || store current position, focus, zoom, values 0 to 99 || <code>mxw.media("USB Cam").ptz("ptz_store_preset", 75)</code>
|<code>mxw.playlist.go_pause(True/False)</code> || halt (True) or resume (False) playback || <code>mxw.playlist.go_pause(True)</code>
|-
|-
|<code>mxw.media("camera_name").ptz("ptz_recall_preset",preset_number, speed)</code> || recalls a previously stored preset,values 0 to 99 and changes to it at a specific speed (values 0 to 1) || <code>mxw.media("USB Cam").ptz("ptz_recall_preset", 4, 0.5 )</code>
|<code>mxw.playlist.skiptonext()</code> || skip to the next cue || <code>mxw.playlist.skiptonext()</code>
|-
|-
|<code>mxw.media("camera_name").ptz("ptz_auto_focus")</code> || activates or deactivates the camera in auto-focus || <code>mxw.media("USB Cam").ptz("ptz.autofocus")</code>
|<code>mxw.playlist.go_next()</code> || go to the next cue without playing || <code>mxw.playlist.go_next()</code>
|-
|-
|<code>mxw.media("camera_name").ptz("ptz_focus", focus_value)</code> || focus to absolute value (0= focused to infinity, 1= focus the closest possible)|| <code>mxw.media("USB Cam").ptz("ptz_focus", 0.5)</code>
|<code>mxw.playlist.go_prev()</code> || go to the previous cue || <code>mxw.playlist.go_prev()</code>
|-
|-
|<code>mxw.media("camera_name").ptz("ptz_focus_speed", speed_value)</code> || focus at a particular speed, values from -1(outwards), to 1 (inwards)|| <code>mxw.media("USB Cam").ptz("ptz_focus_speed", -0.2)</code>
|<code>mxw.playlist.go_first()</code> || go to the first cue || <code>mxw.playlist.go_first()</code>
|-
|-
|<code>mxw.media("camera_name").ptz("ptz_white_balance_auto")</code> || put the camera in auto white-balance mode || <code>mxw.media("USB Cam").ptz("ptz_white_balance_auto")</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.media("camera_name").ptz("ptz_white_balance_indoor")</code> || put the camera in indoor white balance || <code> mxw.media("USB Cam").ptz("ptz_white_balance_indoor")</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.media("camera_name").ptz("ptz_white_balance_outdoor")</code> || put the camera in outdoor white balance || <code> mxw.media("USB Cam").ptz("ptz_white_balance_outdoor")</code>
|<code>mxw.playlist.get_active_cue()</code> || return the active cue index (int) || <code>i = mxw.playlist.get_active_cue()</code>
|-
|-
|<code>mxw.media("camera_name").ptz("ptz_white_balance_oneshot")</code> ||use the current brightness to automatically set the current white balance|| <code>mxw.media("USB_Cam").ptz("ptz_white_balance_oneshot")</code>
|<code>mxw.playlist.get_cue_count()</code> || '''(new in 7.2)''' return the number of cues (int) || <code>n = mxw.playlist.get_cue_count()</code>
|-
|-
|<code>mxw.media("camera_name").ptz("ptz_white_balance_manual", red value, blue value)</code> || Set the manual camera white balance using the R, B values, (0.0 = not red/not blue , 1.0 = very red/very blue)|| <code>mxw.media("camera_name").ptz("ptz_white_balance_manual", 0.1, 0.7)</code>
|<code>mxw.playlist.get_cue_names()</code> || '''(new in 7.2)''' 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.media("camera_name").ptz("ptz_exposure_auto")</code> || put the camera in auto-exposure mode || <code>mxw.media("USB_Cam").ptz("ptz_exposure_auto")</code>
|<code>mxw.playlist.is_rehearsal()</code> || '''(new in 7.2)''' return True if the playlist is in rehearsal mode || <code>if mxw.playlist.is_rehearsal(): pass</code>
|-
|-
|<code>mxw.media("camera_name").ptz("ptz_exposure_manual", exposure_level)</code> || manually set the camera exposure iris, values from 0.0(dark) to 1.0(light)|| <code>mxw.media("USB_Cam").ptz("ptz_exposure_manual", 0.4)</code>
!colspan="3" |Preload ( <code>mxw.preload(n)</code> )
|-
|-
|<code>mxw.media("camera_name").ptz("ptz_exposure_manual_v2", iris_level, gain_level, shutter_speed)</code> || Manually set the camera exposure parameters, values iris from 0.0(dark) to 1.0(light), values gain from 0.0(dark) to 1.0(light), values shutter_speed from 0.0(slow) to 1.0(fast) || <code> mxw.media("USB_Cam").ptz("ptz_exposure_manual_v2", 0.4, 0.2, 0.5) </code>
|<code>mxw.preload(n).isvalid()</code> || True if preload <code>n</code> exists || <code>if mxw.preload(2).isvalid(): pass</code>
|-
|-
!colspan="3" |Playlist Control
|<code>mxw.preload(n).clear()</code> || clear the selected preload || <code>mxw.preload(2).clear()</code>
|-
|-
|<code>mxw.playlist.preload_media()</code> || preload used media || <code>mxw.playlist.preload_media()</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.playlist.pause()</code> || pause the playlists or restart if already paused|| <code>mxw.playlist.pause()</code>
|<code>mxw.preload(n).set_name("name")</code> || rename the preload || <code>mxw.preload(2).set_name("new_background")</code>
|-
|-
|<code>mxw.playlist.play()</code> || play the playlist || <code>mxw.playlist.play()</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> || '''(new in 7.2)''' 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> || '''(new in 7.2)''' return a <code>w</code>&times;<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> || '''(new in 7.2)''' 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>&times;<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.playlist.go_pause()( true/false )</code> || pause the playlist (when true), unpause the playlist (when false) || <code>mxw.playlist.go_pause()(true)</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.playlist.skiptonext()</code> || skip to the next cue || <code>mxw.playlist.skiptonext()</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.playlist.go_next()</code> || go to the next cue without playing || <code>mxw.playlist.go_next()</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.playlist.go_prev()</code> || go to previous cue || <code>mxw.playlist.go_prev()</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.playlist.go_first()</code> || go to the first cue || <code>mxw.playlist.go_first()</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.playlist.get_active_cue()</code> || return active cue index|| <code>index = mxw.playlist.get_active_cue()</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.playlist.navigate_index(index_value)</code> || go to the specified cue index|| <code>mxw.playlist.navigate_index(2)</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.playlist.navigate_string("index_string")</code> || go to the specified cue string|| <code>mxw.playlist.navigate_string("BG_video2")</code>
|<code>mxw.media("name").ptz("ptz_auto_focus")</code> || toggle auto-focus || <code>mxw.media("USB Cam").ptz("ptz_auto_focus")</code>
|-
|-
!colspan="3" |Preload Control
|<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.preload(preload_number).clear()</code> || clears the selected preload || <code>mxw.preload(2).clear()</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.preload(preload_number).set_media("media_name")</code> || set a media in the preload with a filename string || <code>mxw.preload(2).set_media("try.mp4")</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.preload(preload_number).set_name("new_media_name")</code> || renames a preload || <code>mxw.preload(2).set_name("new_background")</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.preload(preload_number).add_preload()</code> || load a preload in the layers || <code>mxw.preload(2).add_preload()</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.preload(preload_number).trigger_preload()</code> || trigger a layer from the preload || <code>mxw.preload(2).trigger_preload()</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.preload(preload_number).get_activated()</code> || requests if the preload is editable || <code>mxw.preload(2).get_activated()</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.preload(preload_number).set_activated(true/false)</code> || opens the preload for edit and viceversa || <code>mxw.preload(2).set_activated(false)</code>
|<code>mxw.media("name").ptz("ptz_exposure_auto")</code> || auto exposure || <code>mxw.media("USB Cam").ptz("ptz_exposure_auto")</code>
|-
|-
|<code>mxw.preload(preload_number).get_layer_position()</code> || returns the layer index of the preload|| <code>mxw.preload(2).get_layer_position()</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.preload(preload_number).get_track_position()</code> || returns the track index of the preload|| <code>mxw.preload(2).get_track_position()</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>
|-
|-
|<code>mxw.preload(preload_number).set_layer_position(layer_pos)</code> || set layer index of the preload|| <code>mxw.preload(2).set_layer_position(2)</code>
!colspan="3" |Grabber ( <code>mxw.grabber(name)</code> )
|-
|-
|<code>mxw.preload(preload_number).set_track_position(track_pos)</code> || set the track index of the preload|| <code>mxw.preload(2).set_track_position(2)</code>
|<code>mxw.grabber("name").isvalid()</code> || True if the named keystone grabber exists || <code>if mxw.grabber("cam").isvalid(): pass</code>
|-
|-
|<code>mxw.makesectionscreenshot("directory_saving_path", initial_x, initial_y, size_x, size_y)</code> || saves a cropped screenshot in the set path|| <code>mxw.makesectionscreenshot("c:/Users/MXWendler/Desktop/b.png", 0,1, 400, 200)</code>
|<code>mxw.grabber("name").getGrabSizeX()</code> || grabber width in px || <code>mxw.grabber("cam").getGrabSizeX()</code>
|-
|-
|<code>mxw.widget("/mxw/path").setStringValue("named by script")</code> || set the name of a cue in the playlist|| <code>mxw.widget("/mxw/playlist/container/1/column/0/row/1").setStringValue("background videoclip")</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&times;height&times;4) || <code>px = mxw.grabber("cam").getData()</code>
|}


|}
=== See also ===
 
* [[Python_ImGui_Reference|Python ImGui Reference]] &ndash; drawing plugin panels with <code>mxw_imgui</code>
* [[Python_Plugin_Howto|Python Plugin Howto]] &ndash; writing media and playlist plugins
* [[3._JavaScript_command_reference|JavaScript command reference]] &ndash; the same object interface from JavaScript

Revision as of 12:49, 8 August 2026


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

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

Applies to MXWendler StageDesigner 7.2. Commands marked (new in 7.2) or (changed in 7.2) were introduced or reworked in this version as part of the unified script/OSC interface.

Legend

FLOATS are written with one decimal: 0.0 .. 1.0 → every float between 0 and 1 inclusive.

INTEGERS are written as plain numbers or ranges: 1 .. 5 → the integers 1,2,3,4,5.

STRINGS are written between double quotes.

When OR 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. /mxw/track/active/layer/active/clip. The same addresses used over OSC work here.

Access model (7.2): widget values are read/written through mxw.widget(address); global functions live in the submodules/factories mxw.playlist, mxw.io, mxw.preload(n), mxw.media(name), mxw.grabber(name). The older global reg_* helper functions have been removed in favour of this object interface.

Reference

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

See also

Retrieved from "https://wiki.mxwendler.net/index.php?title=Python_command_reference&oldid=6112"