obs-switch 0.0.41

OBS Studio and Nintendo Switch controller integration via Kafka

OBS Switch Controller Integration

This project integrates OBS Studio with Nintendo Switch controller inputs via Kafka messaging. It allows for automated control of both OBS scenes/recording and Nintendo Switch controller inputs based on events received through Kafka.

Components

• OBS Controller: Connects to OBS Studio via WebSocket protocol to control scenes and recording.
• Switch Controller: Connects to NXBT webapp to send controller inputs to Nintendo Switch.
• Kafka Integration: Uses Kafka to receive events that trigger actions on either OBS or Switch controller.
• Runner: Coordinates between all components, listening for Kafka messages and executing appropriate actions.

Requirements

• Python 3.8+
• OBS Studio with WebSocket plugin (v4.9.0+)
• NXBT webapp running (for Nintendo Switch controller emulation)
• Kafka server running

Installation

From Source

1. Clone the repository
2. Install the package in development mode:

pip install -e .

Using pip

pip install obs-switch

Usage

Running the Integration

Start the runner with default settings:

obs-switch

Or customize the connection parameters:

obs-switch --obs-host localhost --obs-port 4455 --switch-url http://localhost:8000 --kafka-topics spl_replay_service

Running from Source

If you've installed the package in development mode, you can also run it directly:

python -m obs_switch.cli

Kafka Message Format

The runner listens for Kafka messages in the following formats:

Change OBS Scene

{
  "event_type": "obs_scene_change",
  "scene_name": "Scene Name"
}

Control OBS Recording

{
  "event_type": "obs_recording",
  "action": "start|stop|toggle"
}

Press Switch Buttons

{
  "event_type": "switch_button",
  "buttons": ["A", "B", "X", "Y"],
  "delay": 0.1
}

Move Switch Stick

{
  "event_type": "switch_stick",
  "stick": "L_STICK",
  "x_value": 100,
  "y_value": 0,
  "delay": 0.1
}

Enter Replay Code

{
  "event_type": "switch_replay_code",
  "code": "1234-5678-9012"
}

Architecture

The system uses a modular architecture with the following components:

1. OBS Controller (obs_controller.py): Handles communication with OBS Studio via WebSocket.
2. Switch Controller (switch_controller.py): Manages Nintendo Switch controller inputs via NXBT.
3. Kafka Consumer (async_consumer.py): Listens for events from Kafka topics.
4. Switch Handler (switch_handler.py): Processes complex Switch input sequences like replay codes.
5. Runner (runner.py): Coordinates all components and processes incoming Kafka messages.
6. Macros (obs_switch.macros): Provides a set of helper functions for fixed in-game actions.
7. Actions (obs_switch.actions): Provides a set of helper functions for complex actions that involves OBS and Switch.

Development

PyTesseract

Tesseract is used for OCR (Optical Character Recognition) to extract text from images, will be used to extract information from OBS screenshots.

Ensure that you have the tesseract executable in your PATH.

Tesseract docs: https://tesseract-ocr.github.io/tessdoc/Installation.html

PyTesseract docs: https://pypi.org/project/pytesseract/

REPL-Command based Development

ControlNotebook.ipynb and HandlerPlaybook.ipynb contain Jupyter notebooks that can be used to test and debug the integration without using Kafka.

Adding New Event Types

To add support for new event types:

1. Modify the _process_kafka_message method in runner.py
2. Add a new condition for your event type
3. Implement the corresponding action logic

Extending Controller Functionality

To add new controller actions:

1. Implement the new functionality in the appropriate controller class
2. Update the runner to expose the new functionality via Kafka messages

Troubleshooting

• Ensure OBS Studio is running with the WebSocket plugin enabled
• Verify the NXBT webapp is running and accessible
• Check that Kafka server is running and the topics exist
• Review logs for connection errors or message processing issues

License

This project is licensed under the MIT License - see the LICENSE file for details.