beam-keyboard

Interactive2 Keyboard

A handy keyboard for  Beam interactive 2.
This makes use of interactive-node.

What it does

This script lets you set up a keyboard for your Beam channel by defining a simple set of controls. When viewers use your controls, keys that are defined in corresponding files will do whatever you want them to do, for instance control your content.

This is especially useful for interactive streams.

See it in action on YouPlay!

Installation

1. Globally install the npm package.

   npm install -g beam-keyboard
   

2. Create a profile

3. Run the keyboard with your profile, like this

   beam-keyboard "path/to/my/profiles/GreatGame/myprofile.json"
   

Creating a profile

Prerequisites

1. Enter the  Interactive studio.
2. Create a new Project.
3. Give it a name and optionally fill out other fields.
4. Skip the Build section.
5. At Code grab your version ID. You will need that later on.
   

Setting up

1. Make sure you installed the NPM package.

2. Clone this repository or download it as a .zip file.

3. Copy the config_example directory to a place that makes sense
   (You don't have to adopt the config directory structure here, but I think it's pretty organized the way it is)

4. Inside your own config directory edit auth.json and replace the dummy value with your OAuth token.
   You will need following OAuth scope:

   • interactive:robot:self

5. Check out how the NES example works and copy the directory to your own config directory.

   1. Edit profile.json file and change values as you wish.
   2. For versionID enter the versionID you got here.
   3. Configure layouts and mappings as you wish.
   4. Create a handler for your controls.

6. Do a test run!

   beam-keyboard "./config/profiles/NES/profile.json" 
   

How things work

Currently the only program argument is a JSON file containing the setup for your interactive profile.
You can find an example for everything within the config_example directory.

Profile files

The profile file is the starting point for your interactive "profile" configuration.
It's a JSON file that holds paths to other JSON files and some other stuff:

• auth (String)
  The path to your auth config file.
• handlers (Object)
  This defines the handlers that will be used for your controls.
  Currently there is only button, but support for others (like for joystick) will follow. - path (String)
  That's the path to where the handler NodeJS file is located.
  You can also pass a name of a default handler (e.g. robotjs). - config
  The config your handler needs to get initialized.
  Can be anything you want.
• layout (String)
  The path to your layout config file.
• mapping (String)
  The path to your mapping file.
• versionID (String)
  The versionID for your interactive project (see above).

Layout files

The layout files consist of a JSON object that holds following information:

• extends (String)
  This holds the path for a layout file this layout configuration should extend from.
  Available soon.

• layout (Object)
  This holds the available scenes (only default is used right now) as key-value.
  The name of the scene is the key. - <sceneName> (Array)
  (for example: 'default')
  This holds the configuration of the buttons in JSON format.
  You can design the layout and copy the JSON configuration in the  Interactive studio.

Mapping files

The mapping files consist of a JSON object that holds following information:

• <control identifier> This defines a configuration for each button that's passed to the matching handler.
  
  Example:
  If your handler creates files (for whatever reason) and writes content to them, this is what your config could look like:

  {
  	"a": {
  		"file": "1.txt",
  		"text": "boo"
  	},
  	"b": {
  		"file": "2.txt",
  		"text": "far"
  	}
  }
  

  If you just want to press buttons, you could also just pass strings. It's up to you here, really.

Handlers

As of now, you just need to extend the AbstractHandler class and implement the handle method.
See the DefaultButtonHandler for an example of implementing it.

Contributing

1. Clone this repository

2. Edit the .ts source files in src

3. Run the build command.

   npm run build
   

   (Compiles the TypeScript code to NodeJS code)

4. Run a profile

   node index.js "path/to/my/profiles/GreatGame/myprofile.json"
   

Todo

• Configuration of button actions
  So that you can also let buttons switch scenes for a user, have them update other buttons or scenes or let them do other stuff than just pressing a button.
  This could involve interaction with some kind of Socket or starting a program.
  As of v0.2.0, we got handlers!
• Ban list
  So that you can keep people from going wild on your buttons
• Moderator / team / role lists (may become the same system as ban lists)
  So that you can allow certain people to press certain buttons.
• Layout extending
  So that for example the SNES layout can inherit the NES layout and just add L and R
  (Halfway done, just needs proper backend logic)
• Actual support of multiple scenes
  Right now this only serves a default scene which is filled with generated buttons out of the config files.
• Visual feedback in the console
  Some gauges or graphs, so that you can see what happens.
  Right now it's just some prefixes of messages.
• Visual feedback on buttons, cooldowns and keyboard interaction
  It looks like this isn't quite working with beam-interactive-node2 yet.
  I'll work on it as soon as it's supported.