{"id":13595662,"url":"https://github.com/grigio/obs-cmd","last_synced_at":"2026-02-23T10:45:42.806Z","repository":{"id":167815839,"uuid":"643338625","full_name":"grigio/obs-cmd","owner":"grigio","description":"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","archived":false,"fork":false,"pushed_at":"2025-04-09T20:19:33.000Z","size":88,"stargazers_count":181,"open_issues_count":14,"forks_count":21,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-09T21:27:49.399Z","etag":null,"topics":["obs","obs-remote","obs-websocket","wayland"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/grigio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"github":"grigio"}},"created_at":"2023-05-20T20:57:57.000Z","updated_at":"2025-04-09T20:19:31.000Z","dependencies_parsed_at":"2024-02-27T21:30:24.898Z","dependency_job_id":"a641866d-b2cd-4a9e-b536-b5bd3511840e","html_url":"https://github.com/grigio/obs-cmd","commit_stats":null,"previous_names":["grigio/obs-cmd"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grigio%2Fobs-cmd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grigio%2Fobs-cmd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grigio%2Fobs-cmd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/grigio%2Fobs-cmd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/grigio","download_url":"https://codeload.github.com/grigio/obs-cmd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248762000,"owners_count":21157658,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["obs","obs-remote","obs-websocket","wayland"],"created_at":"2024-08-01T16:01:55.049Z","updated_at":"2026-02-23T10:45:42.798Z","avatar_url":"https://github.com/grigio.png","language":"Rust","funding_links":["https://github.com/sponsors/grigio"],"categories":["Rust"],"sub_categories":[],"readme":"# obs-cmd\n\n**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.\n\n[![Latest version](https://img.shields.io/github/release/grigio/obs-cmd.svg)](https://github.com/grigio/obs-cmd/releases/latest)\n[![Release](https://github.com/grigio/obs-cmd/workflows/Release/badge.svg)](https://github.com/grigio/obs-cmd/releases)\n[![Dependencies status](https://deps.rs/repo/github/grigio/obs-cmd/status.svg)](https://deps.rs/repo/github/grigio/obs-cmd)\n\n## Features\n\n- **Scene Management**: Switch between scenes, get current scene, manage scene collections\n- **Recording Control**: Start, stop, pause, resume recording with chapter creation and status monitoring\n- **Streaming Control**: Start, stop, toggle streaming with status checking\n- **Source Control**: Toggle filters, mute/unmute audio sources, show/hide scene items\n- **Virtual Camera**: Start, stop, toggle virtual camera output\n- **Replay Buffer**: Manage replay buffer with save functionality and status tracking\n- **Media Inputs**: Full media control with play, pause, stop, restart, and seek capabilities\n- **Input Management**: Complete CRUD operations for inputs, settings management, and audio control\n  - List inputs and available input kinds\n  - Create, remove, rename, and manage input settings\n  - Audio controls: volume, mute/unmute/toggle, balance, sync offset, monitor type, tracks\n  - Get default settings for any input kind\n  - List special inputs (desktop audio, microphones)\n- **Screenshots**: Capture source screenshots with custom dimensions and compression\n- **Hotkeys**: Trigger any OBS hotkey by name\n- **Projectors**: Open fullscreen and source-specific projectors on multiple monitors\n- **System Info**: Get OBS Studio version and connection information\n- **Shell Completion**: Auto-completion support for bash, zsh, fish, and other shells\n\nSee [OBS_WEBSOCKET_V5_STATUS.md](./OBS_WEBSOCKET_V5_STATUS.md) for detailed protocol compatibility information.\n\n\n## Installation\n\n### Binaries\n\nYou can download the latest pre-compiled binaries for your operating system from the [Releases](https://github.com/grigio/obs-cmd/releases/latest) page.\n\n**Linux/macOS:**\n```bash\n# Download and extract the appropriate binary for your system\ncurl -L https://github.com/grigio/obs-cmd/releases/latest/download/obs-cmd-x64-linux.tar.gz | tar xz\nchmod +x obs-cmd\nsudo mv obs-cmd /usr/local/bin/\n```\n\n### From Source\n\nEnsure you have [Rust](https://www.rust-lang.org/tools/install) installed, then run the following commands:\n\n```bash\ngit clone https://github.com/grigio/obs-cmd.git\ncd obs-cmd\ncargo install --path .\n```\n\n### Arch Linux\n\n`obs-cmd` is available on the Arch User Repository (AUR). You can install it using an AUR helper like `yay`:\n\n```bash\nyay -S obs-cmd\n```\n\n### Gentoo Linux\n\n`media-video/obs-cmd` is available on [Project:GURU](https://wiki.gentoo.org/wiki/Project:GURU/Information_for_End_Users).\n\n```bash\nsudo emerge -av media-video/obs-cmd\n```\n\n## Usage\n\n`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**.\n\nTo override the default connection settings, you can use the `--websocket` flag or set the `OBS_WEBSOCKET_URL` environment variable:\n\n```bash\n# Using the --websocket flag\nobs-cmd --websocket obsws://\u003chostname\u003e:\u003cport\u003e/\u003cpassword\u003e \u003ccommand\u003e\n\n# Using an environment variable\nexport OBS_WEBSOCKET_URL=obsws://\u003chostname\u003e:\u003cport\u003e/\u003cpassword\u003e\nobs-cmd \u003ccommand\u003e\n```\n\n### Commands Reference\n\n#### Scene Management\n```bash\n# Get current scene\nobs-cmd scene current\n\n# Switch to a scene\nobs-cmd scene switch \"Scene Name\"\n\n# Switch scene collection\nobs-cmd scene-collection switch \"Collection Name\"\n```\n\n#### Recording Control\n```bash\n# Start/stop/toggle recording\nobs-cmd recording start\nobs-cmd recording stop\nobs-cmd recording toggle\n\n# Pause/resume recording\nobs-cmd recording pause\nobs-cmd recording resume\nobs-cmd recording toggle-pause\n\n# Create recording chapters (requires Hybrid MP4 format)\nobs-cmd recording create-chapter\nobs-cmd recording create-chapter \"Chapter Name\"\n\n# Check recording status\nobs-cmd recording status\nobs-cmd recording status-active\n```\n\n#### Streaming Control\n```bash\n# Start/stop/toggle streaming\nobs-cmd streaming start\nobs-cmd streaming stop\nobs-cmd streaming toggle\n\n# Check streaming status\nobs-cmd streaming status\n```\n\n#### Virtual Camera\n```bash\n# Start/stop/toggle virtual camera\nobs-cmd virtual-camera start\nobs-cmd virtual-camera stop\nobs-cmd virtual-camera toggle\n```\n\n#### Replay Buffer\n```bash\n# Start/stop/toggle replay buffer\nobs-cmd replay start\nobs-cmd replay stop\nobs-cmd replay toggle\n\n# Save last replay\nobs-cmd replay save\n\n# Get last replay path\nobs-cmd replay last-replay\n\n# Check replay buffer status\nobs-cmd replay status\n```\n\n#### Audio Control\n```bash\n# Toggle mute state\nobs-cmd audio toggle \"Mic/Aux\"\n\n# Mute/unmute audio devices\nobs-cmd audio mute \"Desktop Audio\"\nobs-cmd audio unmute \"Mic/Aux\"\n\n# Check audio device status\nobs-cmd audio status \"Mic/Aux\"\n```\n\n#### Filter Management\n```bash\n# Enable/disable filter\nobs-cmd filter enable \"Source Name\" \"Filter Name\"\nobs-cmd filter disable \"Source Name\" \"Filter Name\"\nobs-cmd filter toggle \"Source Name\" \"Filter Name\"\n```\n\n#### Scene Items\n```bash\n# Enable/disable scene items (show/hide)\nobs-cmd scene-item enable \"Scene Name\" \"Source Name\"\nobs-cmd scene-item disable \"Scene Name\" \"Source Name\"\nobs-cmd scene-item toggle \"Scene Name\" \"Source Name\"\n```\n\n#### Media Input Control\n```bash\n# Play/pause/stop/restart media\nobs-cmd media-input play \"Media Source\"\nobs-cmd media-input pause \"Media Source\"\nobs-cmd media-input stop \"Media Source\"\nobs-cmd media-input restart \"Media Source\"\n\n# Set cursor position (format: [hh:]mm:ss)\nobs-cmd media-input set-cursor \"Media Source\" \"00:30\"\nobs-cmd media-input set-cursor \"Media Source\" \"1:23:45\"\n```\n\n#### Screenshots\n```bash\n# Save source screenshot\nobs-cmd save-screenshot \"Webcam\" \"png\" \"/path/to/screenshot.png\"\n\n# With custom dimensions\nobs-cmd save-screenshot \"Display Capture\" \"jpg\" \"/path/to/screenshot.jpg\" --width 1920 --height 1080\n\n# With compression quality (for JPEG)\nobs-cmd save-screenshot \"Source\" \"jpg\" \"/path/to/screenshot.jpg\" --compression-quality 90\n```\n\n#### Projectors\n```bash\n# Open fullscreen projector on specific monitor\nobs-cmd fullscreen-projector --monitor-index 1\n\n# Open source projector on specific monitor\nobs-cmd source-projector \"Webcam\" --monitor-index 2\n```\n\n#### Hotkeys\n```bash\n# Trigger hotkey by name (check OBS Settings → Hotkeys for exact names)\nobs-cmd trigger-hotkey \"OBSBasic.StartRecording\"\nobs-cmd trigger-hotkey \"OBSBasic.StopRecording\"\n\n# Audio mute/unmute hotkeys\nobs-cmd trigger-hotkey \"libobs.mute\"\nobs-cmd trigger-hotkey \"libobs.unmute\"\n\n# Note: Hotkey functionality comes as-is and may not be reliable\n# For most operations, use specific commands like 'recording start' instead\n```\n\n#### System Information\n```bash\n# Get OBS Studio version and info\nobs-cmd info\n```\n\n#### Shell Completion\n`obs-cmd` supports auto-completion for major shells. Generate completion scripts:\n\n```bash\n# Bash completion\nobs-cmd completion bash \u003e ~/.local/share/bash-completion/completions/obs-cmd\nsource ~/.local/share/bash-completion/completions/obs-cmd\n\n# Zsh completion\nobs-cmd completion zsh \u003e ~/.zsh/completions/_obs-cmd\necho 'fpath+=~/.zsh/completions' \u003e\u003e ~/.zshrc\nautoload -U compinit \u0026\u0026 compinit\n\n# Fish completion\nobs-cmd completion fish \u003e ~/.config/fish/completions/obs-cmd.fish\n\n# PowerShell completion\nobs-cmd completion powershell | Out-File -Encoding utf8 $PROFILE\n```\n\nAfter setting up completion, you can use `Tab` to auto-complete commands:\n```bash\nobs-cmd rec\u003cTab\u003e        # Completes to \"recording\"\nobs-cmd scene sw\u003cTab\u003e   # Completes to \"scene switch\"\n```\n\n### Integration Examples\n\n#### Linux/GNOME Shortcuts\nMap `obs-cmd` commands as global keyboard shortcuts in GNOME Settings:\n\n```bash\n# Examples for custom shortcuts:\n# obs-cmd recording start\n# obs-cmd scene switch \"Live\"\n# obs-cmd streaming toggle\n```\n\n#### Stream Deck Integration\nUse `obs-cmd` with Stream Deck software for one-touch OBS control:\n- Add \"System: Open\" action\n- Point to obs-cmd executable with desired command\n- Example: `/usr/local/bin/obs-cmd recording toggle`\n\n#### Scripting Examples\n```bash\n# Bash script for stream start sequence\n#!/bin/bash\nobs-cmd scene switch \"Starting Soon\"\nsleep 5\nobs-cmd streaming start\nsleep 2\nobs-cmd scene switch \"Live\"\n\n```\n\n![Example usage on Linux](./static/shortcuts.png)\n\n## Linux Packages\n\n[![Packaging status](https://repology.org/badge/vertical-allrepos/obs-cmd.svg)](https://repology.org/project/obs-cmd/versions)\n\n\n## Requirements\n\n- **OBS Studio** 30.0+ with obs-websocket v5.5.0+ plugin (for chapter creation support)\n- **WebSocket Server** enabled in OBS (Tools → WebSocket Server Settings)\n- Default connection: `obsws://localhost:4455` with password `secret`\n\n## Troubleshooting\n\n### Connection Issues\n```bash\n# Test connection\nobs-cmd info\n\n# Check if OBS WebSocket is running\n# In OBS: Tools → WebSocket Server Settings → Enable WebSocket Server\n```\n\n### Common Errors\n- **Connection refused**: Ensure OBS WebSocket server is running\n- **Authentication failed**: Check password in OBS WebSocket settings\n- **Invalid URL format**: Use `obsws://hostname:port/password` format\n- **Chapter creation failed**: Ensure recording is active and using Hybrid MP4 format\n\n### Debug Mode\nSet environment variable for verbose output:\n```bash\nRUST_LOG=debug obs-cmd info\n```\n\n## Development\n\n### Traditional Rust Development\n\n```bash\n# Build from source\ncargo build --release\n\n# Run tests\ncargo test\n\n# Format code\ncargo fmt\n\n# Lint code\ncargo clippy -- -D warnings\n```\n\n### Nix Support\n\nThis project supports Nix for reproducible builds and development environments.\n\n#### Development with Nix\n\n1. **Enter development shell**:\n   ```bash\n   nix develop\n   ```\n\n2. **Build project**:\n   ```bash\n   nix build\n   ```\n\n3. **Run from Nix store**:\n   ```bash\n   ./result/bin/obs-cmd --help\n   ```\n\n#### Nix Flakes\n\nThis project uses Nix Flakes for reproducible builds. The flake provides:\n- `obs-cmd` package: Build release binary\n- `devShell`: Development environment with Rust tools and dependencies\n\nSee [flake.nix](./flake.nix) for full configuration.\n\n## Donations\n\nIf you find this project helpful, please consider making a donation to support its development.\n\n- **Monero**: `88LyqYXn4LdCVDtPWKuton9hJwbo8ZduNEGuARHGdeSJ79BBYWGpMQR8VGWxGDKtTLLM6E9MJm8RvW9VMUgCcSXu19L9FSv`\n- **Bitcoin**: `bc1q6mh77hfv8x8pa0clzskw6ndysujmr78j6se025`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrigio%2Fobs-cmd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgrigio%2Fobs-cmd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgrigio%2Fobs-cmd/lists"}