focuscast

A terminal UI application that automatically shows/hides OBS scene items based on which window is currently focused.

Features

• Monitors the active window in real-time
• Automatically enables/disables OBS scene items based on configurable mappings
• TUI interface for creating and managing window-to-source mappings
• Persists configuration to disk

Requirements

• OBS Studio with WebSocket server enabled (v5.x)
• Rust toolchain (for building from source)

Installation

Important

Make sure, if on macos, that the terminal you use to run the application has the correct accessibility permissions to read the opened applications and such. these should be in "Privacy & Security" -> "Accessibility"

There are a few ways to install this program, the easiest of which are:

NPM

Run npx focuscast

Homebrew

Run brew install focuscast/tap/focuscast

Cargo

Run cargo install focuscast

You can also clone this repo and build it using

cargo install --path .

Or build manually:

cargo build --release

The binary will be at target/release/focuscast.

Configuration

Configuration is stored at:

• macOS: ~/Library/Application Support/focuscast/config.json
• Linux: ~/.config/focuscast/config.json
• Windows: %APPDATA%\focuscast\config.json

Example Configuration

{
  "obs": {
    "host": "127.0.0.1",
    "port": 4455,
    "password": "your-obs-websocket-password"
  },
  "mappings": {
    "Scene Name": [
      {
        "app_name": "Firefox",
        "source_name": "Browser Capture"
      },
      {
        "app_name": "Terminal",
        "source_name": "Terminal Capture"
      }
    ]
  }
}

OBS Connection Settings

Field	Default	Description
host	127.0.0.1	OBS WebSocket server host
port	4455	OBS WebSocket server port
password	null	WebSocket password (if authentication is enabled)

The obs section is optional. If omitted, defaults to 127.0.0.1:4455 with no password.

Usage

1. Enable the OBS WebSocket server in OBS Studio (Tools > WebSocket Server Settings)
2. Configure the connection in config.json if needed
3. Run the application:

focuscast

CLI Commands

Manage mappings directly from the CLI (also updates the config file):

focuscast mappings list
focuscast mappings list --scene "Scene Name"
focuscast mappings get --scene "Scene Name" --app "Firefox"
focuscast mappings toggle --scene "Scene Name" --app "Firefox"

Use --format json for machine-readable output:

focuscast mappings list --format json

Keyboard Controls

Key	Action
Tab	Switch between Main and Config screens
q	Quit

Config Screen

Key	Action
1 / 2 / 3	Select Windows / Scene Items / Mappings pane
j / Down	Move selection down
k / Up	Move selection up
Enter / m	Create mapping from selected window and scene item
d / Delete	Delete selected mapping
r	Refresh windows and scene items

How It Works

1. The app connects to OBS via WebSocket
2. It monitors the currently focused window on your system
3. When the focused window matches a configured mapping, it enables that scene item and disables others in the mapping group
4. Scene changes in OBS are detected automatically and mappings are re-applied

License

MIT