vwout / obs-visca-control

OBS plugin to control Visca-over-IP based cameras

obs-visca-control

A plugin for OBS to control Visca-over-IP based cameras.

This plugin adds a source to a scene in OBS. With this source, a camera can be controlled. Its main purpose is to automatically switch a camera to a certain preset when the scene is activated. This activation can be as soon as the scene is active in preview, in program, or both.

Besides recalling a pre-made preset, this plugin supports a few more control operations:

• Switch camera On
• Switch camera Off
• Preset Recall
• Set the camera to a defined (absolute) Pan/Tilt/Zoom position
• Zoom (Stop, In - Tele, Out - Wide, Direct)
• Pan/Tilt (Up, Down, Left, Right, Upleft, Upright, Downleft, Downright, Stop, Home, Reset)
• Focus (Manual mode, Automatic mode, Trigger refocus, To infinity, Near, Far)
• Change the camera image settings (Color gain / Saturation, Brightness)

This plugin requires the camera to support Visca over IP via UDP. It follows the specification as designed by Sony and also supports the PTZOptics variant of Visca. This plugin is confirmed to work with at Avonic, BZB Gear, Everet, GlowStream, JVC, PTZOptics and Zowietek cameras. Others may work as well.

Also visit https://obsproject.com/forum/resources/control-visca-over-ip-based-cameras.1173/ for more information.

Installation

The plugin is a script plugin and utilizes the Lua scripting capabilities of OBS. The script works on all recent versions of OBS, but version 28 or higher is recommended.

To use the plugin, add the file obs-visca-control.lua as a script, see below for a detailed instruction. The other .lua files in this repository are also required, but should not be added as scripts in OBS.

The files needed for usage if this plugin are:

• obs-visca-control.lua: The main OBS plugin file
• libvisca.lua: Internal library that implements the Visca communication
• ljsocket.lua: Network (socket) communication library for use with LuaJIT in OBS

Place the files on your computer, e.g. in data\obs-plugins\frontend-tools\scripts\ under your OBS installation folder. In OBS choose Scripts in the Tools menu and click the "+" symbol. Navigate to the location where obs-visca-control.lua is stored and confirm with 'Open'. The plugin settings will show on the right as described in the below.

Configuration

Before the plugin can be used in a scene, it requires configuration in the Script dialog.

Start by enumerating the number of cameras that you want to control. For each camera a set of configuration properties will be shown:

• Name: A friendly name for easy recognition of the camera.
• Version Info: The model, type and firmware (in case available and supported).
• Address: The IP address at which the camera is available.
• Port: The plugin by default uses UDP port 52381. Change this port when needed, e.g. to 1259 for a PTZOptics camera. Setting the port does not change the Visca dialect ('protocol') that is used. Also check the Mode.
• Mode: The operating mode of the plugin. The default is Generic, which follows the original (Sony) Visca specification. Other supported modes are PTZOptics, to send commands according the PTZOptics Visca protocol.
• Hotkey Pan/Tilt speed: The speed that is used for pan and tilt operations triggered by a hotkey. This speed can be manipulated by user-assignable hotkeys.
• Hotkey Zoom/Focus speed: The speed that is used for zoom and focus operations triggered by a hotkey. This speed can be manipulated by user-assignable hotkeys.
• Presets: The list of presets that you want to configure for the camera - these need to match the presets that are configured in the camera itself.

Important: Reload the script after changing the address, port of mode configuration!

Switch between cameras using the drop-down. Reload the plugin to update the names of the cameras in the camera drop-down list.

The preset list contains one preset per line and contains the name for the preset and the number of the preset stored in the camera. The preset follows a specific syntax to link a preset number to a name. The following forms are supported:

• <name> <separator> <preset number>
• <preset number> <separator> <name>

The separator can be :, = or -. Valid examples are 0: Home, 5 = Pastor or Stage - 6. The number of presets that are supported may vary from camera to camera. This script supports up to preset number 254.

Note: Most cameras refer to the first preset as 1, other use 0. The presentation on the interface of the camera might not be clear on this topic, so keep this in mind while testing presets. JVC camera models are known to demonstrate this behavior.

The bottom part of the plugin configuration settings section provides the ability to back up (export) the plugin settings to a 'json' file, restore (import) settings from a backup file. This backup only contains the plugin configuration settings, thus the camera and preset configuration. The scene settings are stored with each scene.

In case of interaction problems between this plugin and a camera, it might be of use to enable verbose logging. This will provide detailed information about the plugin functionality in the Script Log. Activate verbose logging and attach the log when reaching out for help.

Usage

In a scene

To control a camera, add a Visca Camera Control source to a scene.

In the source settings, select the camera and the action that should be executed.

• Camera: The camera configured in the plugin (see configuration)
• Action: Select the action that needs to be executed
  • When a camera supports standby mode, Power On/Off can be used in a scene to activated or suspend te camera.
  • The action Image Settings configures the Color Gain (Saturation) and/or Brightness. The current setting is automatically retrieved from the camera when this action is chosen. To show the value, hit the 'Defaults' button and select the 'Image Settings' action again. To set one of the settings, check the configuration item and change the slider value. Note: Your camera may not support all values that can be configured by the sliders.
  • When the action Preset Recall is chosen, the preset also needs to be chosen. These presets need to be configured per camera in the script settings, see configuration.
  • To not recall a predefined preset, but set the camera to an absolute position, choose Pan/Tilt/Zoom Absolute position and retrieve the current position of the camera to be recalled later by pressing the button.
  • For the action Pan/Tilt Direction, the camera will move in the configured direction. The direction and speed also needs to be selected. Note that this action does not use a specific starting position, the pan action starts from the camera position that is actual when the scene becomes active.
  • For Zoom In and Zoom Out, the animation speeds determines the zoom speed.
  • The Custom Command action allows sending a custom Visca command to the camera at activation or deactivation of a scene. See Custom Command action execution overview for details on how custom command actions are processed. This command must be in the documentation of the camera and consists of a series of hexadecimal values. When these values are not know, or the manual is not understood, don't use this action.
• Action Active: The camera action is executed when either the scene in which the source is used becomes active in preview, in program, or both, depending on the selected entry in the selection.
• To make sure that a preview does not change settings of a camera that is on program. Select the checkbox 'Run action on preview only when the camera is exclusive on preview, not active on program' ('on preview exclusive'). Note: Apply action on preview exclusive when running OBS in Studio Mode, otherwise the action will never be executed.
• Delay Action: When not set (left to 0), the action is immediately executed when the scene becomes active. To delay the action execution, for example to synchronize after completion of a transition, set it to the number of milliseconds to wait. This delay can also be used to run multiple actions in sequence

Camera actions configured for a scene are executed as configured when the scene is activated or deactivated on preview or on program.

Tip: To temporarily suppress execution of scene actions, configure the hotkey Suppress actions on scenes. As long as the hotkey is pressed, actions are not executed. To permanently disable execution, without removing the configuration, change the visibility of the Visca Camera Control source in the scene to hidden.

Custom Command action execution overview

	Load scene on preview	Transition to program	Transition back to preview	Unload scene on preview2
Action Active: Always On preview exclusive: No	Send start command	Send start command	Send stop command	Send stop command
Action Active: Always On preview exclusive: Yes1	-	Send start command	Send stop command	-
Action Active: Preview On preview exclusive: No	Send start command	-	-	Send stop command
Action Active: Preview On preview exclusive: Yes1	-	-	-	-
Action Active: Program On preview exclusive: N/A	-	Send start command	Send stop command	-

Notes:

• ¹ This only applies when the checkbox 'Run action on preview only...' is checked and for the same camera a Visca action is active (visible) on program. In case no Visca camera is active on program, or a different Visca camera is active, the table result for 'No' apply.
• ² The scene unload is executed when another scene is selected on preview. The camera multiview acts as multiple preview screens. When the multiview window is closed, stop actions are also executed for all scenes visible in multiview.

Hotkeys

The plugin adds a number of hotkeys to the global OBS settings. All hotkeys apply to a specific camera, except for Suppress actions on scenes (see the previous paragraph). Presets 0-9 recall, Color Gain (Saturation) increase/decrease, Brightness increase/decrease, Pan/Tilt actions up/down/left/right and Zoom in/out can be activated via hotkey next to (in addition) to a scene action. These hotkeys are independent of scene actions and can be applied at any moment. Focus commands can only be called via a hotkey. The pan/tilt and zoom/focus hotkey commands use the speed that is configured per camera in the configuration. This (default) speed can be changed dynamically using a hotkey.

To use any of these actions, configure a hotkey in the global OBS settings.

Pressing the configured key combination will perform an immediate zoom, pan or tilt step at the camera. The amount of effective zoom, pan, tilt or focus change may vary from camera to camera. When any of the focus commands is used, the camera will be switched to manual focus (except for the command to switch to automatic mode). The actions will obviously only be executed when the camera actually supports zooming, panning or tilting.

Credits

This plugin uses luajitsocket, a library that implements socket support for LuaJIT, since the Lua socket library is not available in OBS.

obs-visca-control's Issues

Unable to load script

@vwout

As shown in the following figure：

Modify camera moving speed

@vwout How have you been?

I hope to have two shortcut keys to increase and decrease the camera's moving speed.

Preset recall fails for preset numbers >127

For cameras supporting greater than 128 presets (such as PTZOptics 30x zoom models), attempting to recall preset numbers greater than 127 result in the wrong preset number being recalled.

Stop Command not triggering

Here you will see a custom down command triggering but when the stop command is supposed to be triggered it does not.

Down tilt command = 01 06 01 01 01 03 02
Stop command = 01 06 01 01 01 03 03

"19:56:40.949: [Lua: obs-visca-control.lua] source_signal_processor (1167): Show visca source 'Down Tilt (Visca)' (camera 1): no action
19:56:40.949: [Lua: obs-visca-control.lua] source_signal_processor (1167): Activate visca source 'Down Tilt (Visca)' (camera 1): process
19:56:40.949: [Lua: obs-visca-control.lua] do_cam_action_start (563): Start cam 1 action 26 (args custom_start=table: 0x021db2829088, speed=0, custom_stop=table: 0x021db2854f18, direction=0)
19:56:41.049: [Lua: obs-visca-control.lua] ? (524): Connection ACK received for camera 1 (seq_nr 112)
19:56:41.049: [Lua: obs-visca-control.lua] ? (795): Poll camera 1 (table: 0x021db27fb7a8): 90 41 FF
19:56:41.149: [Lua: obs-visca-control.lua] ? (431): Connection Completion received for camera 1 (seq_nr 112)
19:56:41.149: [Lua: obs-visca-control.lua] ? (795): Poll camera 1 (table: 0x021db27fb7a8): 90 51 FF
19:56:46.682: [Lua: obs-visca-control.lua] source_signal_processor (1167): Hide visca source 'Down Tilt (Visca)' (camera 1): no action
19:56:46.683: [Lua: obs-visca-control.lua] source_signal_processor (1167): Deactivate visca source 'Down Tilt (Visca)' (camera 1): process
19:56:46.683: [Lua: obs-visca-control.lua] camera_active_in_scene (1068): Current program scene is Chapel Wide
19:56:46.683: [Lua: obs-visca-control.lua] camera_active_in_scene (1073): Camera ref: 1 active on program: 1
19:56:46.683: [Lua: obs-visca-control.lua] camera_active_in_scene (1068): Current program scene is Chapel Wide
19:56:46.683: [Lua: obs-visca-control.lua] source_signal_processor (1232): Not running stop action for source 'Down Tilt (Visca)', because it is currently active on program"

Many thanks

gamepad support

Hello and thank you for this script.
Do you think it is possible to add the support for a gamepad? In case I want to control the camera freely?

Stop Commands Not Processing

When we move scenes the stop command on the custom action does not process leading to the camera not listening to other scenes. If we put a separate scene with the stop command as the start command on a custom action it works

Add support for camera picture options Brightness and ColorSaturation

Can Brightness and ColorSaturation also be added? please please😟😟

Originally posted by @PoWeR-Ding in #6 (comment)

NewTek NDI PTZ1 compatibility: don't use message counter

The sequence number in Visca messages in incorrectly handled by the NewTek NDI PTZ1. This camera is only capable of handling messages with seq_nr 1, 2 or 3 and it always responds with seq_nr=1. The work around is to not use sequence numbers:

modify libvisca.lua at line 941 and change:
message.seq_nr = self.last_seq_nr
to
message.seq_nr = 0

The original issue is reported on the OBS forum:

I tried the PTZOptics Mode but with that i had no camera movement at all. I added two logs from the OBS scriptlog. The first one shows 4 scene changes with 3 successfull cam preset recalls and the last one failing. The second log shows some unfinished messages that i get when i reload my script.

The workaround to not use sequence number is also confirmed there.

Want to capture camera current PTZ values and save them in the scene

Here are my versions of your control and libvisca LUA scripts for your review/comment etc. Ive only changed the names so my development work remained separate from your original scripts

obs-visca-controlPTZ_V3.zip
.

Support for TCP control?

The camera I'm using (RGBLink ePTZ) seems to only work on UDP, thus getting the below error for the VISCA Camera Control.
Any support for TCP possible?

[obs-visca-control.lua] Failed to call get_properties for Visca Camera Control: ...obs-plugins/frontend-tools/scripts/obs-visca-control.lua:1260: Error in obs_property_list_add_int (arg 3), expected 'long long' got 'nil'

Increase/Decrease Pan/Tilt Speed not immediately effective

Yesterday, when using the PTZOptics mode, I found that the "Increase Pan/Tilt Speed" adn "Decrease Pan/Tilt Speed"(A) did not take effect immediately on the camera. I need to press the refresh button(C) in the lower left corner to take effect, but the value here has changed（B）.

Originally posted by @PoWeR-Ding in #8 (comment)

Stop Command not Processing when other VISCA commands are visible

This is a very similar issue to those seen in the past but I was unable to find a fix.
If there are 1 or more Visca Sources visible, the stop function does not work. However if I hide all other Visca sources the stop function will work just fine. g
For example... If a preset is a called and completes and then I activate the tilt function, the tilt function will execute but when it is hidden again the stop command will not work.

Many thanks for all your help and time so far. This is a great script

Failed to call calldata_signal_callback for calldata_signal_callback:

I believe I have installed the files in the right place set up the configuration and tried the default port and the configured the Visca port set in the camera. The IP address should be right as well but I am getting these errors back when I switch scenes:

[obs-visca-control.lua] do_cam_action_start (96): Start cam 1 @192.168. action 0 (arg 1)
[obs-visca-control.lua] Failed to call calldata_signal_callback for calldata_signal_callback: ...le/data/obs-plugins/frontend-tools/scripts//ljsocket.lua:417: cannot resolve symbol 'gai_strerror': The specified procedure could not be found.

[obs-visca-control.lua] do_cam_action_start (96): Start cam 1 @192.168. action 2 (arg 1)
[obs-visca-control.lua] Failed to call calldata_signal_callback for calldata_signal_callback: ...le/data/obs-plugins/frontend-tools/scripts//ljsocket.lua:417: cannot resolve symbol 'gai_strerror': The specified procedure could not be found.

[obs-visca-control.lua] do_cam_action_start (96): Start cam 1 @192.168. action 0 (arg 2)
[obs-visca-control.lua] Failed to call calldata_signal_callback for calldata_signal_callback: ...le/data/obs-plugins/frontend-tools/scripts//ljsocket.lua:417: cannot resolve symbol 'gai_strerror': The specified procedure could not be found.

[obs-visca-control.lua] do_cam_action_start (96): Start cam 1 @192.168. action 2 (arg 1)
[obs-visca-control.lua] Failed to call calldata_signal_callback for calldata_signal_callback: ...le/data/obs-plugins/frontend-tools/scripts//ljsocket.lua:417: cannot resolve symbol 'gai_strerror': The specified procedure could not be found.

[obs-visca-control.lua] do_cam_action_start (96): Start cam 1 @192.168. action 0 (arg 2)
[obs-visca-control.lua] Failed to call calldata_signal_callback for calldata_signal_callback: ...le/data/obs-plugins/frontend-tools/scripts//ljsocket.lua:417: cannot resolve symbol 'gai_strerror': The specified procedure could not be found.

[obs-visca-control.lua] do_cam_action_start (96): Start cam 1 @192.168. action 2 (arg 1)
[obs-visca-control.lua] Failed to call calldata_signal_callback for calldata_signal_callback: ...le/data/obs-plugins/frontend-tools/scripts//ljsocket.lua:417: cannot resolve symbol 'gai_strerror': The specified procedure could not be found.

Any idea what to look at to get this working?

EDIT: Using OBS 27.0.0-rc3 on a Windows 10 PRO PC