Friday Fun - Custom OBS Controller

Open Broadcaster Software, OBS is a handy application for recording / streaming your projects to YouTube, Twitch etc.

So what is the problem?

OBS is ace, but it has SOOOO many things that it can do and when you are recording a video you need quick access to key features and so a custom controller is needed!

If you like what you read...
Would you like to buy me a cup of coffee? It helps me to pay for hosting this blog, and to buy stuff to hack from Poundshops / Dollar Stores which are used in free projects on this blog. Thanks!

So how am I going to build the controller?

I'm not, because Pimoroni already have!

I reviewed the Pimoroni Keybow back in January 2019 for electromaker and it is a solid, if a little expensive piece of kit.
Inside the box we get

• Raspberry Pi Zero WH (soldered pins)
• Keybow PCB with APA102 RGB LEDs
• Linear (quiet) or Clicky keys
• Clear keycaps
• Micro USB
• Laser cut perspex pieces

Following the assembly guide from the Pimoroni website is really easy and only requires a crosshead screwdriver.

So how do we program the controller?

Keybow uses a stripped down version of Raspbian, called Keybow OS. This OS is loaded into RAM on boot leaving the micro SD card free.

To code Keybow I need to copy the Keybow OS to a blank micro SD card, 1GB is plenty!

With Keybow OS on the card, insert the microSD card into the Keybow, and plug it in to your computer. After about 30 seconds the keys will light up and Keybow will appear as a USB keyboard. If this happens, GREAT! If not follow the troubleshooting section on the Pimoroni guide!

Lua?

Keybow OS uses Lua a lightweight language, to create scripts which will control how the keys respond to input.

The structure of the Lua code is

• There is a file called keybow.lua in the root of the drive.
  • This file contains all of the configuration in a similar manner to a Python library / module.
• In keys.lua there are lines of code to enable certain configurations and key layouts.
• Inside layouts are the keyboard layouts for different projects, all of these files are Lua scripts.

Editing keys.lua

This file is found in the root of the microSD card. Open the file using your favourite text editor, I'm using Geany.

I only want two lines of code to be active in this file, and they are on lines 1 and 2.

require "keybow"
require "layouts/obs" -- OBS Controller

Require? --?
In Lua, to import a library / module require is used. In this case I import the keybow library and then the obs file found in the layouts directory.
-- is how Lua adds comments to code.

Save keys.lua before moving on.

Complete code listing for keys.lua

require "keybow"
require "layouts/obs" -- OBS Controller

Editing obs.lua

Move into the layouts directory.
Duplicate the blink.lua file and call it obs.lua.

The first line of code in the file imports the keybow library.

require "keybow"

Next is a function called setup() which is used to configure Keybow.

function setup()

Inside the function, the first two lines disable the PNG animation (the default lights that turned on when you first booted) and clear any LEDs that are lit.

    keybow.auto_lights(false)
    keybow.clear_lights()

I want two keys to light up a certain colour when Keybow starts. These keys are numbers 10 and 11 (top row, second and third keys) and to light them up I will use keybow.set_pixel() and then pass two arguments / parameters. The first is the number of the key to light. The second is the RGB value. So for key 10 to light up red I used.

    keybow.set_pixel(10, 255, 0, 0)

And for key 11 to be green, and to end the function.

    keybow.set_pixel(11, 0, 255, 0)
end

For each key on Keybow, there is a function which is called when the key is pressed. Here for example is the function for Key 0 (Fourth row, first key.)

function handle_key_00(pressed)
    keybow.set_key("0", pressed)
    if pressed then
        keybow.set_pixel(0, 0, 0, 255)
    else
        keybow.set_pixel(0, 0, 0, 128)
    end
end

When the key is pressed, it will print 0 into a open document / terminal / web browser. This is handled via keybow.set_key() If the key is pressed then the LEDs underneath the key (0) will light up blue (0,0,255) and when the key is not pressed, in this case I want a light blue, it will be (0,0,128)

The same code applies for Key 1 (Fourth row, second key) as keys 0 and 1 will be used to switch sources / scenes in OBS.

function handle_key_01(pressed)
    keybow.set_key("1", pressed)
    if pressed then
        keybow.set_pixel(1, 0, 0, 255)
    else
        keybow.set_pixel(1, 0, 0, 128)
    end
end

For keys 2 to 9 the following code is used. This is the default code that was in the blink.lua script. Just remember to change the number for each key.

function handle_key_02(pressed)
    keybow.set_key("2", pressed)
    if pressed then
        keybow.set_pixel(2, 255, 255, 255)
    else
        keybow.set_pixel(2, 0, 0, 0)
    end
end

For key 10 (first row, second key) I want the keypress to trigger the "M" key and then turn the key red.

function handle_key_10(pressed)
    keybow.set_key("M", pressed)
    if pressed then
        keybow.set_pixel(10, 255, 255, 255)
    else
        keybow.set_pixel(10, 255, 0, 0)
    end
end

For key 11 (first row, third key) I want the keypress to trigger the "U" key and turn the key green.

function handle_key_11(pressed)
    keybow.set_key("U", pressed)
    if pressed then
        keybow.set_pixel(11, 255, 255, 255)
    else
        keybow.set_pixel(11, 0, 255, 0)
    end
end

Complete code lisitng obs.lua

require "keybow"

-- Standard numberpad with light feedback --

function setup()
    keybow.auto_lights(false)
    keybow.clear_lights()
    keybow.set_pixel(10, 255, 0, 0)
    keybow.set_pixel(11, 0, 255, 0)
end

-- Standard number pad mapping --

-- Key mappings --

function handle_key_00(pressed)
    keybow.set_key("0", pressed)
    if pressed then
        keybow.set_pixel(0, 0, 0, 255)
    else
        keybow.set_pixel(0, 0, 0, 128)
    end
end

function handle_key_01(pressed)
    keybow.set_key("1", pressed)
    if pressed then
        keybow.set_pixel(1, 0, 0, 255)
    else
        keybow.set_pixel(1, 0, 0, 128)
    end
end

function handle_key_02(pressed)
    keybow.set_key("2", pressed)
    if pressed then
        keybow.set_pixel(2, 255, 255, 255)
    else
        keybow.set_pixel(2, 0, 0, 0)
    end
end

function handle_key_03(pressed)
    keybow.set_key("3", pressed)
    if pressed then
        keybow.set_pixel(3, 255, 255, 255)
    else
        keybow.set_pixel(3, 0, 0, 0)
    end
end

function handle_key_04(pressed)
    keybow.set_key("4", pressed)
    if pressed then
        keybow.set_pixel(4, 255, 255, 255)
    else
        keybow.set_pixel(4, 0, 0, 0)
    end
end

function handle_key_05(pressed)
    keybow.set_key("5", pressed)
    if pressed then
        keybow.set_pixel(5, 255, 255, 255)
    else
        keybow.set_pixel(5, 0, 0, 0)
    end
end

function handle_key_06(pressed)
    keybow.set_key("6", pressed)
    if pressed then
        keybow.set_pixel(6, 255, 255, 255)
    else
        keybow.set_pixel(6, 0, 0, 0)
    end
end

function handle_key_07(pressed)
    keybow.set_key("7", pressed)
    if pressed then
        keybow.set_pixel(7, 255, 255, 255)
    else
        keybow.set_pixel(7, 0, 0, 0)
    end
end

function handle_key_08(pressed)
    keybow.set_key("8", pressed)
    if pressed then
        keybow.set_pixel(8, 255, 255, 255)
    else
        keybow.set_pixel(8, 0, 0, 0)
    end
end

function handle_key_09(pressed)
    keybow.set_key("9", pressed)
    if pressed then
        keybow.set_pixel(9, 255, 255, 255)
    else
        keybow.set_pixel(9, 0, 0, 0)
    end
end

function handle_key_10(pressed)
    keybow.set_key("M", pressed)
    if pressed then
        keybow.set_pixel(10, 255, 255, 255)
    else
        keybow.set_pixel(10, 255, 0, 0)
    end
end

function handle_key_11(pressed)
    keybow.set_key("U", pressed)
    if pressed then
        keybow.set_pixel(11, 255, 255, 255)
    else
        keybow.set_pixel(11, 0, 255, 0)
    end
end

Setting up OBS hotkeys

Insert the microSD card into Keybow and then connect Keybow to your computer running OBS. Give it a few moments to boot up and be ready for use.

Top Tip!
If your Keybow is not being recognised by your computer, or it is not working as it should, swap the micro USB lead for a known good lead! Trust me I spent a while debugging to find that cause!

I guess that you have already installed OBS? If not follow the guidance on their website.
Open the OBS application.

Look for the Settings menu.

Then in the Settings menu I chose Hotkeys and proceeded to press the keys on my Keybow, to correspond to each function I wish it to do.

• Key 0 = Go to Scene
• Key 1 = Go to close up cam
• Key 7 = Pause / Unpause recording
• Key 8 = Start / Stop recording
• Key 10 = Mute / Unmute microphone

Then click Apply and everything is ready to go! Now I can use OBS like a pro (YMMV, terms and conditions apply, BigLes does not take responsibility for your cred or coolness)

Happy Hacking