OBS Scene Banner Version 1.0

Purpose

OBS-Scene-Banner follows scene transitions, prominently displaying the names of the Program scene and active Profile. It adapts automatically to Studio Mode, also revealing the name of the Preview scene along with the applicable Transition (taking into account overrides).

Program Mode

Scene Banner is designed as a banner, best docked immediately below the OBS menu bar.  It can be configured with some convenient buttons and a menu bar by customizing the settings file.


Prerequisites: Tested on Windows 10--not sure about other platforms.

Installation

  1. Download and install the obs websocket 4.9.1 plugin. (When installed on OBS v28+, the 4.9 plugin must be installed, despite the built in support for websockets 5.0).
  2. Download OBS-Scene-Banner-x.x
  3. Extract the folder to your preferred OBS scripts directory. The scripts directory can be anywhere, but the conventional location is "/program files/obs-studio/data/obs-plugins/frontend-tools/scripts".
  4. Edit OBS-Scene-Banner-Settings.js to establish the connection settings, making sure they comport with the Websockets Server settings found in the OBS Tools menu. In most cases, IP address and port defaults work and you only need to be concerned with the password.
  5. Add OBS-Scene-Banner.html to your OBS Custom Browser Docks (on the View menu). It works best docked between the OBS menu bar and the Program/Preview scenes with its height minimized as much as possible.
  6. Customize the horizontal alignment and optional features (see the Customization section, below)

Upgrades

When upgrading or reinstalling, take care to use a different installation folder so that your custom settings can be reapplied from the old one.


Customization

Some features of Scene Banner can be customized by modifying the OBS-Scene-Banner-Settings.js file with notepad or another plain text editor.  Note that the settings file is a series of javascript assignment statements.  Take care, as syntax errors prevent the settings from loading and very well may cause a Websockets authentication failure.

Tip: javascript errors often produce a "script error" popup and are best-diagnosed by opening scene banner in a browser and viewing the console log.

Connection Settings
It is essential for the connection settings to comport with the OBS->Tools->Websockets Server settings.

WEBSOCKET_IP             Defaults 'localhost'
WEBSOCKET_PORT       Defaults '4444'
PASSWORD                      Defaults blank

Horizontal Alignment Settings
Scene banner is comprised of five side-by-side zones, intuitively named:
LEFT    PREVIEW     CENTER     PROGRAM     RIGHT

By default, the zones align with an OBS layout without docks on either side of the Program/Preview scenes. If the defaults are not well-suited to your OBS layout, you can adjust the zone widths to achieve a more appealing alignment and/or to accommodate optional buttons.

Tip: after saving changes to the settings file, Right-Click->Refresh the browser dock to load the revised settings.

For example, when enabled, the GOLIVE_BUTTON appears in the RIGHT zone which defaults to width '0px', effectively hiding the button. To accommodate the button, increase RIGHT_WIDTH (at least '120px' recommended).  Further, if symmetry is important, you may then want to also increase the LEFT_WIDTH for a more balanced look.

Or, if you position another dock to the right of the Program scene, you may want to increase the RIGHT_WIDTH, accordingly, to better align the Preview and Program zones over their respective OBS scenes.

The horizontal alignment settings must be valid CSS width specifications. Fortunately, the defaults for PREVIEW_WIDTH and PROGRAM_WIDTH almost always work well, even adapting to Studio Mode and window scaling (thus their percentage specification). On the other hand, the Left, Center, and Right zones usually need to be adapted to your OBS layout.

The recommended practice is to finalize your Quick Transition names (which affect space between Preview and Program scenes) and the size/positioning of other docks before working on the zone widths in the banner.

Tip: Horizontal alignment effects are sometimes hard to visualize. You can expose the zone boundries by temporarily enabling PANE_BORDERS during horizontal alignment customization.


Buttons

Buttons are optional and must be enabled individually in the customization settings.

The best practice is to designate a PUSH_SCENE to work in conjunction with the Push Button; without one, the Push Button defaults to the Program Scene when the banner loads.  The Push Scene can be dynamically changed to the Preview scene (or Program scene when not in Studio Mode) by right-clicking on the Push Button or the Push action in the menu bar.
By default, the Push Scene is static. However, if PUSH_SCENE_TOGGLE is enabled, the Push Scene alternates with the one leaving Program when a Push is exercised. In that mode, it offers a handy "Push/Pull" sequence, useful, for example, to temporarily mask unwanted moments in the live Program without losing the Preview scene.

Menu Bar

Scene Banner presents a menu bar in its upper half by clicking the Menu button or by right-clicking in the banner. If the menu bar is not desired, it can be suppressed with the HIDE_MENU setting. By default, the menu bar disappears when any of its items is clicked.  Alternatively, the STICKY_MENU setting keeps it visible until dismissed explicitly.

Right-clicking a blank area in the menu bar raises the browser's context menu which is useful for refreshing Scene Banner to adopt new settings or to restart in the rare case of programming or connection error.  If the menu bar is suppressed, the same effect can be achieved by clicking the refresh icon or by right-clicking anywhere in the banner.

The menu bar supports custom links that open in another browser window. To add one, mimic the help file link at the bottom of the settings file. 

Preferred Profile

Scene Banner displays the active Profile above the Program Scene name.  If a PREFERRED_PROFILE is specified in the customization settings, attempts to use a different Profile elicit a warning. The idea is to avoid inadvertently streaming with the wrong profile.

Messages

Scene Banner has a message area below the banner proper. Normally, the message area is unnecessary and can be visually obscured by minimizing the dock height in the OBS layout (then revealed on demand should it be desired). If still obtrusive, it can be unilaterally suppressed with the HIDE_MESSAGE_AREA setting.

Since messages are primarily intended for development/diagnostic purposes, most are suppressed by default. To expose messages, the message area must be visible and messages must be enabled (by type), in settings.

SHOW_NOTICES reveals scene banner messages
SHOW_REQUESTS reveals websocket request messages
SHOW_REPLIES websocket reply messages
SHOW_EVENTS reveals websocket event messages

As message volume can be overwhelming, sometimes it's best to reproduce scenarios in a browser where there is no competition from OBS for screen real estate. Alternatively, messages can be limited to a single line with SHOW_AS_TICKER, which also abbreviates websocket messages to acronyms.

Finally, LOG_MESSAGES records the messages in the console log. That said, the usefulness is limited since to view the console log, Scene Banner must be run in a full browser with diagnostic capabilities.

OBS-Scene-Banner is an HTML page that interacts with OBS using the Websocket protocol. It supports remote control and password authentication, relying on javascript companion files for program logic, connection credentials and other customization settings.

Advanced Customization

For those proficient with HTML and CSS, further customization is possible by manipulating the distributed html and css files.  Examples that come to mind are relocating buttons to different zones or choosing colors that are more compatible with your OBS theme.

Tip: Scene Banner relies extensively on HTML id's and classes. In no case should either be removed or renamed.

Bear in mind, however, that such customizations will need to be reapplied as part of any reinstallation or upgrade process.