Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/grigio/obs-cmd

obs-cmd is a OBS cli for obs-websocket v5 the current obs-studio implementation. It is useful on Wayland Linux or to control OBS via terminal
https://github.com/grigio/obs-cmd

obs obs-remote obs-websocket wayland

Last synced: 3 months ago
JSON representation

obs-cmd is a OBS cli for obs-websocket v5 the current obs-studio implementation. It is useful on Wayland Linux or to control OBS via terminal

Awesome Lists containing this project

README 

          
# obs-cmd



**obs-cmd** is a lightweight, command-line interface for controlling OBS Studio via the obs-websocket v5 protocol. It provides a simple and efficient way to automate your streaming and recording workflows.



[![Latest version](https://img.shields.io/github/release/grigio/obs-cmd.svg)](https://github.com/grigio/obs-cmd/releases/latest)

[![Release](https://github.com/grigio/obs-cmd/workflows/Release/badge.svg)](https://github.com/grigio/obs-cmd/releases)

[![Dependencies status](https://deps.rs/repo/github/grigio/obs-cmd/status.svg)](https://deps.rs/repo/github/grigio/obs-cmd)



## Features



- **Scene Management**: Switch between scenes, get current scene, manage scene collections

- **Recording Control**: Start, stop, pause, resume recording with chapter creation and status monitoring

- **Streaming Control**: Start, stop, toggle streaming with status checking

- **Source Control**: Toggle filters, mute/unmute audio sources, show/hide scene items

- **Virtual Camera**: Start, stop, toggle virtual camera output

- **Replay Buffer**: Manage replay buffer with save functionality and status tracking

- **Media Inputs**: Full media control with play, pause, stop, restart, and seek capabilities

- **Input Management**: Complete CRUD operations for inputs, settings management, and audio control

  - List inputs and available input kinds

  - Create, remove, rename, and manage input settings

  - Audio controls: volume, mute/unmute/toggle, balance, sync offset, monitor type, tracks

  - Get default settings for any input kind

  - List special inputs (desktop audio, microphones)

- **Screenshots**: Capture source screenshots with custom dimensions and compression

- **Hotkeys**: Trigger any OBS hotkey by name

- **Projectors**: Open fullscreen and source-specific projectors on multiple monitors

- **System Info**: Get OBS Studio version and connection information

- **Shell Completion**: Auto-completion support for bash, zsh, fish, and other shells



See [OBS_WEBSOCKET_V5_STATUS.md](./OBS_WEBSOCKET_V5_STATUS.md) for detailed protocol compatibility information.



## Installation



### Binaries



You can download the latest pre-compiled binaries for your operating system from the [Releases](https://github.com/grigio/obs-cmd/releases/latest) page.



**Linux/macOS:**

```bash

# Download and extract the appropriate binary for your system

curl -L https://github.com/grigio/obs-cmd/releases/latest/download/obs-cmd-x64-linux.tar.gz | tar xz

chmod +x obs-cmd

sudo mv obs-cmd /usr/local/bin/

```



### From Source



Ensure you have [Rust](https://www.rust-lang.org/tools/install) installed, then run the following commands:



```bash

git clone https://github.com/grigio/obs-cmd.git

cd obs-cmd

cargo install --path .

```



### Arch Linux



`obs-cmd` is available on the Arch User Repository (AUR). You can install it using an AUR helper like `yay`:



```bash

yay -S obs-cmd

```



### Gentoo Linux



`media-video/obs-cmd` is available on [Project:GURU](https://wiki.gentoo.org/wiki/Project:GURU/Information_for_End_Users).



```bash

sudo emerge -av media-video/obs-cmd

```



## Usage



`obs-cmd` connects to the OBS WebSocket server. By default, it attempts to connect to `obsws://localhost:4455` with the password `secret`. You can configure the WebSocket settings in OBS under **Tools → WebSocket Server Settings**.



To override the default connection settings, you can use the `--websocket` flag or set the `OBS_WEBSOCKET_URL` environment variable:



```bash

# Using the --websocket flag

obs-cmd --websocket obsws://:/ 



# Using an environment variable

export OBS_WEBSOCKET_URL=obsws://:/

obs-cmd 

```



### Commands Reference



#### Scene Management

```bash

# Get current scene

obs-cmd scene current



# Switch to a scene

obs-cmd scene switch "Scene Name"



# Switch scene collection

obs-cmd scene-collection switch "Collection Name"

```



#### Recording Control

```bash

# Start/stop/toggle recording

obs-cmd recording start

obs-cmd recording stop

obs-cmd recording toggle



# Pause/resume recording

obs-cmd recording pause

obs-cmd recording resume

obs-cmd recording toggle-pause



# Create recording chapters (requires Hybrid MP4 format)

obs-cmd recording create-chapter

obs-cmd recording create-chapter "Chapter Name"



# Check recording status

obs-cmd recording status

obs-cmd recording status-active

```



#### Streaming Control

```bash

# Start/stop/toggle streaming

obs-cmd streaming start

obs-cmd streaming stop

obs-cmd streaming toggle



# Check streaming status

obs-cmd streaming status

```



#### Virtual Camera

```bash

# Start/stop/toggle virtual camera

obs-cmd virtual-camera start

obs-cmd virtual-camera stop

obs-cmd virtual-camera toggle

```



#### Replay Buffer

```bash

# Start/stop/toggle replay buffer

obs-cmd replay start

obs-cmd replay stop

obs-cmd replay toggle



# Save last replay

obs-cmd replay save



# Get last replay path

obs-cmd replay last-replay



# Check replay buffer status

obs-cmd replay status

```



#### Audio Control

```bash

# Toggle mute state

obs-cmd audio toggle "Mic/Aux"



# Mute/unmute audio devices

obs-cmd audio mute "Desktop Audio"

obs-cmd audio unmute "Mic/Aux"



# Check audio device status

obs-cmd audio status "Mic/Aux"

```



#### Filter Management

```bash

# Enable/disable filter

obs-cmd filter enable "Source Name" "Filter Name"

obs-cmd filter disable "Source Name" "Filter Name"

obs-cmd filter toggle "Source Name" "Filter Name"

```



#### Scene Items

```bash

# Enable/disable scene items (show/hide)

obs-cmd scene-item enable "Scene Name" "Source Name"

obs-cmd scene-item disable "Scene Name" "Source Name"

obs-cmd scene-item toggle "Scene Name" "Source Name"

```



#### Media Input Control

```bash

# Play/pause/stop/restart media

obs-cmd media-input play "Media Source"

obs-cmd media-input pause "Media Source"

obs-cmd media-input stop "Media Source"

obs-cmd media-input restart "Media Source"



# Set cursor position (format: [hh:]mm:ss)

obs-cmd media-input set-cursor "Media Source" "00:30"

obs-cmd media-input set-cursor "Media Source" "1:23:45"

```



#### Screenshots

```bash

# Save source screenshot

obs-cmd save-screenshot "Webcam" "png" "/path/to/screenshot.png"



# With custom dimensions

obs-cmd save-screenshot "Display Capture" "jpg" "/path/to/screenshot.jpg" --width 1920 --height 1080



# With compression quality (for JPEG)

obs-cmd save-screenshot "Source" "jpg" "/path/to/screenshot.jpg" --compression-quality 90

```



#### Projectors

```bash

# Open fullscreen projector on specific monitor

obs-cmd fullscreen-projector --monitor-index 1



# Open source projector on specific monitor

obs-cmd source-projector "Webcam" --monitor-index 2

```



#### Hotkeys

```bash

# Trigger hotkey by name (check OBS Settings → Hotkeys for exact names)

obs-cmd trigger-hotkey "OBSBasic.StartRecording"

obs-cmd trigger-hotkey "OBSBasic.StopRecording"



# Audio mute/unmute hotkeys

obs-cmd trigger-hotkey "libobs.mute"

obs-cmd trigger-hotkey "libobs.unmute"



# Note: Hotkey functionality comes as-is and may not be reliable

# For most operations, use specific commands like 'recording start' instead

```



#### System Information

```bash

# Get OBS Studio version and info

obs-cmd info

```



#### Shell Completion

`obs-cmd` supports auto-completion for major shells. Generate completion scripts:



```bash

# Bash completion

obs-cmd completion bash > ~/.local/share/bash-completion/completions/obs-cmd

source ~/.local/share/bash-completion/completions/obs-cmd



# Zsh completion

obs-cmd completion zsh > ~/.zsh/completions/_obs-cmd

echo 'fpath+=~/.zsh/completions' >> ~/.zshrc

autoload -U compinit && compinit



# Fish completion

obs-cmd completion fish > ~/.config/fish/completions/obs-cmd.fish



# PowerShell completion

obs-cmd completion powershell | Out-File -Encoding utf8 $PROFILE

```



After setting up completion, you can use `Tab` to auto-complete commands:

```bash

obs-cmd rec        # Completes to "recording"

obs-cmd scene sw   # Completes to "scene switch"

```



### Integration Examples



#### Linux/GNOME Shortcuts

Map `obs-cmd` commands as global keyboard shortcuts in GNOME Settings:



```bash

# Examples for custom shortcuts:

# obs-cmd recording start

# obs-cmd scene switch "Live"

# obs-cmd streaming toggle

```



#### Stream Deck Integration

Use `obs-cmd` with Stream Deck software for one-touch OBS control:

- Add "System: Open" action

- Point to obs-cmd executable with desired command

- Example: `/usr/local/bin/obs-cmd recording toggle`



#### Scripting Examples

```bash

# Bash script for stream start sequence

#!/bin/bash

obs-cmd scene switch "Starting Soon"

sleep 5

obs-cmd streaming start

sleep 2

obs-cmd scene switch "Live"



```



![Example usage on Linux](./static/shortcuts.png)



## Linux Packages



[![Packaging status](https://repology.org/badge/vertical-allrepos/obs-cmd.svg)](https://repology.org/project/obs-cmd/versions)



## Requirements



- **OBS Studio** 30.0+ with obs-websocket v5.5.0+ plugin (for chapter creation support)

- **WebSocket Server** enabled in OBS (Tools → WebSocket Server Settings)

- Default connection: `obsws://localhost:4455` with password `secret`



## Troubleshooting



### Connection Issues

```bash

# Test connection

obs-cmd info



# Check if OBS WebSocket is running

# In OBS: Tools → WebSocket Server Settings → Enable WebSocket Server

```



### Common Errors

- **Connection refused**: Ensure OBS WebSocket server is running

- **Authentication failed**: Check password in OBS WebSocket settings

- **Invalid URL format**: Use `obsws://hostname:port/password` format

- **Chapter creation failed**: Ensure recording is active and using Hybrid MP4 format



### Debug Mode

Set environment variable for verbose output:

```bash

RUST_LOG=debug obs-cmd info

```



## Development



### Traditional Rust Development



```bash

# Build from source

cargo build --release



# Run tests

cargo test



# Format code

cargo fmt



# Lint code

cargo clippy -- -D warnings

```



### Nix Support



This project supports Nix for reproducible builds and development environments.



#### Development with Nix



1. **Enter development shell**:

   ```bash

   nix develop

   ```



2. **Build project**:

   ```bash

   nix build

   ```



3. **Run from Nix store**:

   ```bash

   ./result/bin/obs-cmd --help

   ```



#### Nix Flakes



This project uses Nix Flakes for reproducible builds. The flake provides:

- `obs-cmd` package: Build release binary

- `devShell`: Development environment with Rust tools and dependencies



See [flake.nix](./flake.nix) for full configuration.



## Donations



If you find this project helpful, please consider making a donation to support its development.



- **Monero**: `88LyqYXn4LdCVDtPWKuton9hJwbo8ZduNEGuARHGdeSJ79BBYWGpMQR8VGWxGDKtTLLM6E9MJm8RvW9VMUgCcSXu19L9FSv`

- **Bitcoin**: `bc1q6mh77hfv8x8pa0clzskw6ndysujmr78j6se025`