ndi-ptz 0.1.5
A CLI to control NDI-capable PTZ cameras via a joystick.
Requires Python: >=3.12
Keywords: joystick, ndi, obs, ptz, streaming, video

# ndi-ptz

This is a CLI to control an [NDI-enabled][ndi-video] PTZ camera with a joystick.

[ndi-video]: https://ndi.video

## Installation

```shell
uv tool install ndi-ptz

# or
pip install ndi-ptz
```

You also need to install the NDI Runtime,
unless you have the [NDI Tools][ndi-tools] or the [NDI SDK][ndi-sdk] installed

[ndi-tools]: https://ndi.video/tools/
[ndi-sdk]: https://ndi.video/for-developers/ndi-sdk/download/

- Windows: <http://ndi.link/NDIRedistV6>
- MacOS: <http://ndi.link/NDIRedistV6Apple>
- Linux: <https://downloads.ndi.tv/SDK/NDI_SDK_Linux/Install_NDI_SDK_v6_Linux.tar.gz>
  - see also <https://github.com/DistroAV/DistroAV/blob/master/CI/libndi-get.sh>

For further options, like `choco` or `brew`, consult [the DistroAV wiki][distroav].

[distroav]: https://github.com/DistroAV/DistroAV/wiki/1.-Installation#required-components---ndi-runtime

## Quick-Start

```shell
$ ndi-ptz list-sources
Looking for NDI sources in the next 5 seconds
TAIL_AIR_006666 (OBSBOT)

$ ndi-ptz list-joysticks
Looking for joysticks in the next 5 seconds
Nintendo Switch Pro Controller (0)

$ ndi-ptz control --source-name "TAIL_AIR_006666 (OBSBOT)" --joystick-instance 0
```

## Supported Joysticks

Currently only the following joysticks are supported:

- [Nintendo Switch Pro Controller](#nintendo-controller)
- [Xbox Series X Controller](#xbox-controller)
- [Xbox 360 Controller](#xbox-controller)
- [PlayStation 4 Controller](#playstation-controller)
- [PlayStation 5 Controller](#playstation-controller)

### Nintendo Controller

> Only the _Nintendo Switch Pro Controller_ is supported and tested.

- You must hold `L` and `R` constantly to control the PTZ.
- Use the _left stick_ to control pan (left/right) and tilt (up/down).
- Use the _right stick_ to control the zoom (up/down).
- Press the _right stick_ to return the camera to the home position.
- Hold the `A` button to trigger the autofocus.

### Xbox Controller

> Only the _Xbox Series X Controller_ was tested.
> On Mac, it only works when connected via Bluetooth.

- You must hold `L` and `R` constantly to control the PTZ.
- Use the _left stick_ to control pan (left/right) and tilt (up/down).
- Use the _right stick_ to control the zoom (up/down).
- Press the _right stick_ to return the camera to the home position.
- Hold the `B` button to trigger the autofocus.

### PlayStation Controller

> PlayStation controllers are not tested.

- You must hold `L` and `R` constantly to control the PTZ.
- Use the _left stick_ to control pan (left/right) and tilt (up/down).
- Use the _right stick_ to control the zoom (up/down).
- Press the _right stick_ to return the camera to the home position.
- Hold the `O` button to trigger the autofocus.

## Development

This project is managed with [UV](https://docs.astral.sh/uv/).

### Build & Publish

```bash
# edit the project version in pyproject.toml
uv sync
git commit -m "Prepare 0.1.5" .
git tag '0.1.5'
rm -rf dist
uv build
uv publish
git push --tags
git push
```

## Legal

This code is provided under the terms and permissions granted by [the MIT license](./LICENSE).

NDI® is a registered trademark of Vizrt NDI AB.