{"id":31801166,"url":"https://github.com/glikely/obs-ptz","last_synced_at":"2026-05-10T15:03:17.194Z","repository":{"id":37027805,"uuid":"307195989","full_name":"glikely/obs-ptz","owner":"glikely","description":"PTZ Controls (for OBS Studio)","archived":false,"fork":false,"pushed_at":"2025-10-07T16:54:35.000Z","size":2545,"stargazers_count":213,"open_issues_count":39,"forks_count":49,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-10-07T17:27:31.842Z","etag":null,"topics":["obs-studio","obs-studio-plugin","onvif","pelco-d","ptz","uvc-camera","visca","visca-over-ip"],"latest_commit_sha":null,"homepage":"https://obsproject.com/forum/resources/ptz-controls.1284/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/glikely.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-10-25T21:27:28.000Z","updated_at":"2025-10-07T15:22:15.000Z","dependencies_parsed_at":"2025-03-24T21:24:31.615Z","dependency_job_id":"318a40b2-bdf1-4e73-8fc1-aa88ebd056ad","html_url":"https://github.com/glikely/obs-ptz","commit_stats":null,"previous_names":[],"tags_count":89,"template":false,"template_full_name":null,"purl":"pkg:github/glikely/obs-ptz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glikely%2Fobs-ptz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glikely%2Fobs-ptz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glikely%2Fobs-ptz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glikely%2Fobs-ptz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/glikely","download_url":"https://codeload.github.com/glikely/obs-ptz/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/glikely%2Fobs-ptz/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005582,"owners_count":26083921,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["obs-studio","obs-studio-plugin","onvif","pelco-d","ptz","uvc-camera","visca","visca-over-ip"],"created_at":"2025-10-10T23:47:14.952Z","updated_at":"2025-10-10T23:47:15.888Z","avatar_url":"https://github.com/glikely.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Pan Tilt Zoom (PTZ) Controls for OBS Studio\n\n[![Push](https://github.com/glikely/obs-ptz/actions/workflows/push.yaml/badge.svg)](https://github.com/glikely/obs-ptz/actions/workflows/push.yaml)\n[![Crowdin](https://badges.crowdin.net/obs-ptz/localized.svg)](https://crowdin.com/project/obs-ptz)\n\nThis is a plugin for controlling PTZ Cameras from OBS studio.\n\nThis plugin adds a new control dock window that can be used to control pan,\ntilt, zoom camera directly from the OBS Studio main window.\nIt also tracks the current active scenes to automatically select the\ncorrect camera for control and can be automated by adding PTZ Actions sources\nto trigger camera actions when scenes change.\n\n![PTZ Controls Screenshot](/doc/ptz-controls-screenshot.png?raw=true \"OBS Studio PTZ Controls\")\n\n![PTZ Controls Screenshot](/doc/ptz-settings-screenshot.png?raw=true \"OBS Studio PTZ Device Settings\")\n\nFeatures:\n\n- Adjuts camera Pan, Tilt, Zoom and Focus settings\n- Toggle between manual and auto focus modes\n- Assign hotkeys to camera controls\n- Use a joystick to control comera position\n- Save and recall camera presets\n- Control multiple cameras from OBS\n- Auto select active camera based on active scene\n- Control camera power\n- Adjust camera whitebalance\n- Supports multiple camera control protocols, including:\n  - VISCA (RS232, RS422, UDP and TCP)\n  - Pelco-P\n  - Pelco-D\n  - ONVIF (experimental)\n  - USB Cameras (Windows and Linux only)\n\n## Websites\n- [OBS project resource page](https://obsproject.com/forum/resources/ptz-controls.1284/)\n- [PTZ Controls on GitHub](https://github.com/glikely/obs-ptz)\n- [PTZ Controls on Crowdin (translations)](https://crowdin.com/project/obs-ptz)\n\n# User Guide\n\n## Installation\n\nGo to the releases page to find the latest binary release for your platform.\nBinaries are created for Windows (x64), MacOS (Arm, x86_64, and Universal),\nand Ubuntu Linux 24.04 (x86_64).\nDownload the package for your platform and install it.\nIf you need support for a different platform (e.g. Linux Arm) then you'll need\nto follow the building from source instructions below.\n\n[OBS PTZ Releases](https://github.com/glikely/obs-ptz/releases)\n\n## Configuration\n\nTo show the controls dock, in the `Docks` menu select `PTZ Controls`.\nThe PTZ Controls window should appear.\nYou can drag the window to any side of the OBS Studio main window to dock it\ninto place, or just leave it floating.\n\nInitially no PTZ cameras will be configured.\nTo add a camera, click on the gear icon at the bottom of the dock window,\nor in the `Tools` menu select `PTZ Controls`.\nThe PTZ Settings window will appear.\n\nThe Settings window has three tabs, `General`, `Cameras` and `About`.\nThe `General` tab has settings that affect every camera.\nThe `Cameras` tab is where you add and remove cameras,\nand change individual camera settings.\nThe `About` tab give some details about the plugin and what version is installed.\n\n### Adding a Camera\nIn this plugin, cameras are associated with OBS Studio video sources.\nTo add a camera, you should first add a source for the camera's video feed in\nthe OBS Studio `Sources` dock.\nOnce you've got the camera video working, add PTZ controls to the source in the\nPTZ Controls settings dialog `Tools-\u003ePTZ Devices'.\n\nOn the `Cameras` tab, click the `+` button in the bottom toolbar to add a\ndevice.\nIt will expand to a list of camera control connections that are available.\nSelect the control protocol that is used by your camera.\nA new entry will be added to the device list.\nClick on the new camera and the camera settings will appear on the right hand\nside of the window.\nYou'll need to enter the camera connection details, either the network address\nor serial port used for control.\nClick the `Apply` button to connect to the camera.\nFinally associate the camera with an OBS source by using the `Source` combo box.\nThis lets the plugin automatically select the right camera for control when\nthe preview or program scene changes in OBS.\n\n### Removing a camera\n\nTo remove a camera, select the camera in the settings dialog can click the `-`\nbutton in the toolbar.\n\n## Controlling Cameras\n\nCameras are controlled with the arrow buttons in the control dock.\nTo adjuat a camera, you needs to be selected from the camera list in the PTZ\ndock (bottom left of the control dock).\nBy default (if `Auto Select Active Camera` is enabled in settings), then the\nplugin will automatically select the correct camera when the current scene\nchanges.\nThen, clicking the camera control buttons will adjust the camera position.\nThe arrow buttons will pan/tilt the camera,\nThe magnifing glass buttons will zoom in and out,\nand the small/large buttons will change the focus.\nYou can also toggle autofocus on and off with the `AF` button and trigger\na one-touch refocus action.\n\nPresets are listed on the right hand side of the dock.\nPresets can be saved, recalled, and renamed from the dock window.\n\nTo save a preset, right click on the preset that you want to change and select\n`Save Preset`.\nSimilarly, to rename a preset, right click and select `Rename Preset`,\nor select `Clear Preset` to reset the name back to default.\n\nDouble click to recall a preset.\n\n### Joystick Control\n\nTo enable joystick control, select the `Joystick Control` check box on the\n`general` tab of the settings dialog.\nAll of the connected joysticks will be shown in the list box.\nClick on the joystick that you want to use for camera control.\nJoystick axis can be mapped to Pan, Tilt, Zoom or Focus.\nJoystick buttons can be mapped to any OBS hotkey action.\n\n## Advanced Features\n\n### Block Moves on Live Camera\n\nIn Studio mode, camera adjustments are usually set up with the source visible\nin the Preview scene before being transitioned over to the live Program scene.\nManual camera movements are avoided on the Program scene because they can\nbe quite abrupt and unpleasant to watch.\n\nOBS PTZ can by default block out manual moves of cameras visible in Program.\nTo enable this feature, check the `Lockout live PTZ moves in studio mode`\ncheckbox in the Setting dialog `About` tab.\n\nWith the feature enabled the pan, tilt, zoom and preset controls will be\ndisabled for any camera visible in Program, preventing live moves.\nIf you need to override the block and do a live movement anyway\nthen you can temporarily override the block by clicking the lock icon in\nthe toolbar.\n\n### Debugging data\n\nThe plugin can generate a large amount of debug data with all the protocol\nmessages sent to and received by the cameras.\nDebug logs appear in the main obs-studio log, but are disable by default.\nTo enable debug logs, select `Write protocol trace to OBS log file` in the\ndevice settings, and run OBS Studio with the --verbose command line option.\n\n# Building from Source\n\nThe build infrastructure for this project comes from the\n[OBS Plugin Template](https://https://github.com/obsproject/obs-plugintemplate]\nrepo. To build this plugin, follow the instructions in the plugin template\n[README.md](doc/plugin-template-README.md)\n\n## Linux Quickstart\n\nThis project should be easy to build on any Linux distro once OBS Studio and\nall of the build dependencies are installed on your machine.\nCheck your distributions documentation for instructions on how to do this.\nThen you can build the plugin with cmake commands:\n\n```\n$ cmake -B build\n$ cmake --build build --config RelWithDebInfo\n$ cmake --install build --config RelWithDebInfo\n```\n\nOn Ubuntu 24.04, you can also use the GitHub action CI script to build the\nplugin, which will also download and install all the build dependencies for you.\n\n```\n$ ./.github/scripts/build-ubuntu\n$ cp release/RelWithDebInfo /usr/\n```\n\n## MacOS Quickstart\n\nThe easiest way to build the plugin is to use the CMake presets.\nUse the following commands to configure, build and install the plugin in your\nOBS Studio plugins directory.\n\n```\n$ cmake -B build_macos --preset macos\n$ cmake --build build_macos --config RelWithDebInfo\n$ cmake --install build_macos --config RelWithDebInfo\n```\n\n## Windows Quickstart\n\nEasiest way to build for windows is to use the GitHub actions build script.\nFirst install Visual Studio and CMake as described in the obs-plugintemplate\ndocumentation linked above.\nThen open the `x64 Native Tools Command Prompt for VS 2022` and run the following commands:\n\n```\nc:\\\u003e pwsh\nPS \u003e cd path/to/obs-ptz\nPS \u003e $env:ci=1\nPS \u003e .github/scripts/Build-Windows.ps1\n```\n\n# Contributing\n\nContributions welcome!\nYou can submit changes as GitHub pull requests.\nSee the github pull request page for details.\nhttps://github.com/glikely/obs-ptz/pulls\n\nHelp is also needed to translate into other languages.\nGo to the Crowdin project page to help: [PTZ Controls on Crowdin](https://crowdin.com/project/obs-ptz)\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for more details.\n\n# Acknowledgements\n\nThank you to everyone who has contributed to his project, either with filing issues,\nasking questions, or contributing to the code.\nAll code and documentation contributors are listed in [AUTHORS](AUTHORS).\n\nThank you also to the OBS Project developers, and the\n[OBS Plugin Template](https://https://github.com/obsproject/obs-plugintemplate]\nrepo that they maintain. This plugin leans heavily on that project.\n\nJoystick support uses the\n[QJoystick library](https://github.com/alex-spataru/QJoysticks).\n\nAnd finally, thank you to everyone who contributes to the Free and Open Source\nSoftware that this project is built upon, including OBS Studio, Qt, Simple\nDirectMedia Layer (SDL), Linux, and countless libraries and tools.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglikely%2Fobs-ptz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fglikely%2Fobs-ptz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fglikely%2Fobs-ptz/lists"}