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 matfire/matfire/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