Attention!

As of this commit, miditoobs is officially deprecated and will be/is publicly archived.

miditoobs started in 2017 in a gutefrage.net thread (a german version of quora) with a very basic but functional first commit on Sep 17, 2017. Back then there were basically no tools to do what miditoobs did, this sparked the initial development. Now the codebase (mostly the setup) is fairly outdated and a big patchwork of years of adding stuff. Also the complete lack of any abstraction would make migrating to obs-websocket 5 a complete rewrite of everything, which would also break every single config file out there.

A big thanks to every single person who relied on it over the years and everyone who contributed to the project in any form.

If you are looking for alternatives have a look at the Resources List in the OBS forum. The current version of miditoobs will continue to work as long as the OBS project provides obs-websocket v4 compat versions of the websocket plugin (Which probably is still a few months as of writing this).

---

Original Readme from here on

Midi OBS what???

This script lets you use one or multiple MIDI controllers (like the Novation Launchpad, Ableton Push, Akai LPD or the Korg nanoPAD to mention a few) to switch scenes, start/stop recording/streaming, control volume/filter settings/gain/opacity/t-bar/delay/transition time and more in obs-studio.

If you want to play it safe, use the latest release. If you want to use the latest features then just clone the master branch.

Requirements

• Obviously a (USB) MIDI controller
• Python 3
• A few pip packages
  • TinyDB
  • mido
  • python-rtmidi
  • websocket-client
  • dbj
• obs-websocket plugin:
  • If you're using OBS < 28: obs-websocket plugin version 4.9.1
  • If you're using OBS >= 28: The obs-websocket plugin version 4.9.1-compat as long as it's still available

Setup Part 1

• Install Python 3.x.x (whatever the latest version is)
• On Windows: Make sure you tick "Add Python 3.x to PATH" in the setup
• Make sure you also install pip
• For instructions how to install TinyDB click here
• For instructions how to install mido and python-rtmidi click here
• For instructions how to install websocket-client click here or here for 4.9.1-compat
• For instructions how to install dbj click here

If you want to install all packages in one go, run pip install -r requirements.txt

Setup Part 2 OBS Websocket

• Download the installer and run it
• Start OBS, open the "Tools" menu and select "WebSockets Server Settings"
• Make sure that "Enable WebSockets server" is checked, "Server Port" is 4444, "Enable authentication" is unchecked and "Enable System Tray Alerts" is unchecked (trust me, you don't want that on)

Setup Part 3

• Download the latest Release or clone it if you want to test the bleeding edge features and bugfixes
• Connect your MIDI controller
• Launch OBS Studio
• Run setup.py
• If you are on Windows, double click or the "Run Setup.bat"
• If you are on MacOS, run python3 setup.py from your Terminal in the MIDItoOBS folder (ensuring you have activated whatever Python/venv you installed the packages in)
• If you run the setup for the first time and have not setup a device yet, it will automatically start the device configuration:
• You will get a list of available MIDI devices. Type the number you want to select and press Enter
• You will be asked if you want to ad another device.
• If you only have a single device choose 2 and press Enter, otherwise select 1 and you will get a list with remaining devices.
• Now you will be asked to press a button or move a fader on your MIDI controller, do that
• If your MIDI controller sends control change messages, you will also be asked for the type of the input (fader or button)
• Select an action from the list and press enter. The names represent the request-type in obs-websocket
• Depending on the action, you will also be asked for the scene and source name (selecting always works by typing in the number and pressing enter). If no source of that type is available and you are prompted to "select 0--1:" then you know that is no such source available in obs and the script will crash trying to select anything. Just add the required object and restart the setup script in this case. (This is already on the todo list for a further update)

Available for buttons:

• SetCurrentScene: Switches to the scene
• SetPreviewScene: Puts a scene into preview when in studio mode
• TransitionToProgram: Transitions the current preview scene to program
• SetCurrentTransistion: Sets the transition that is used with SetCurrentScene
• SetSourceVisibility: Hides or unhides a source
• ToggleSourceVisibility: Toggles the visibility of a source
• ToggleMute: Toggles the mute status from a source
• SetMute: Mutes or unmutes a source
• StartStopStreaming: Toggles the Streaming
• StartStreaming: Starts streaming
• StopStreaming: Stops streaming
• StartStopRecording: Toggles the Recording
• StartRecording: Starts recording
• StopRecording: Stops recording
• StartStopReplayBuffer: Toggles the replay buffer
• StartReplayBuffer: Starts the replay buffer
• StopReplayBuffer: Stops the replay buffer
• SaveReplayBuffer: Save the replay buffer
• PauseRecording: Pauses the recording
• ResumeRecording: Resume the recording that was previously paused
• SetTransitionDuration: Sets the length of the currently selected transition if supported(fade)(in ms) to a predefined value
• SetCurrentProfile: Changes to the selected obs profile
• SetCurrentSceneCollection: Changes to the selected obs scene collection
• ResetSceneItem: Resets a scene item
• SetTextGDIPlusText: Sets the text of a GDI text sourc
• SetBrowserSourceURL: Sets the url of a BrowserSource
• ReloadBrowserSource: Reloads a BrowserSource
• TakeSourceScreenshot: Don't be fooled by the name; Takes a screenshot of the selected source or complete scene and saves it inside the MIDItoOBS folder as a png image
• EnableSourceFilter: Enables a filter that is on a source (Works with "Audio Filters" and Video "Effect Filters")
• DisableSourceFilter: Disables a filter that is on a source (Works with "Audio Filters" and Video "Effect Filters")
• ToggleSourceFilter: Toggles the status of a filter on a source for each button press
• SetAudioMonitor: Sets the audio monitor option on a source
• EnableStudioMode: Enables Studio Mode
• DisableStudioMode: Disables Studio Mode
• ToggleStudioMode: Toggles Studio Mode
• TriggerHotkeyByName: Triggers an obs event, see the obs-websocket wiki for details
• TriggerHotkeyBySequence: Triggers an obs event based on the configured keyboard combination, see the obs-websocket wiki for details
• PlayPauseMedia: Start or Pause Media/VLC Source playback
• ToggleMediaState: Toggle Media/VLC Source playback
• RestartMedia: Restart Media/VLC Source playback
• StopMedia: Stop Media/VLC Source playback
• NextMedia: Jump to the next playlist item. Only works with the vlc source.
• PreviousMedia: Jump to the previous playlist item. Only works with the vlc source.

Available for faders/knobs:

• SetVolume: Sets the volume of a source (unlike other solutions this will actually make the fader move in a visual linear way inside obs(Like a % slider))
• SetSyncOffset: Sets the sync offset of a source [in ns]
• SetSourcePosition: Sets the x or y position of a source [in px]
• SetSourceCrop: Set the crop from any edge (left/right/top/bottom) [in px]
• SetSourceRotation: Sets the rotation of a source [in degree]
• SetSourceScale: Sets the scale for x/y OR both of a source (For the scaling 1 = original scale). You can also select around which position the source will be scaled(align).
• SetTransitionDuration: Sets the length of the currently selected transition if supported (fade) [in ms]
• SetGainFilter: Sets the volume gain value inside the gain filter of a source (For the scaling -30 to 30 is a valid range you can work in). This will automatically default to the first gain filter found in a source!
• MoveTbar: This will move the transition T-Bar. Make sure you always completely finish a T-Bar move by going to one end to the other otherwise obs will stay in the "a transition is currently happening"-state. Be careful because the state might go "out of sync" with the physical fader if you use any other tools that move the t-bar.
• Filter/Chroma Key - Contrast: This controls the "Contrast" value for a "Chroma Key" Filter [-1 - 1]
• Filter/Chroma Key - Brightness: This controls the "Brightness" value for a "Chroma Key" Filter [-1 - 1]
• Filter/Chroma Key - Gamma: This controls the "Gamma" value for a "Chroma Key" Filter [-1 - 1]
• Filter/Chroma Key - Opacity: This controls the "Opacity" value for a "Chroma Key" Filter [0 - 100]
• Filter/Chroma Key - Spill Reduction: This controls the "Key Color Spill Reduction" value for a "Chroma Key" Filter [0 - 1000]
• Filter/Chroma Key - Similarity: This controls the "Similarity" value for a "Chroma Key" Filter [0 - 1000]