https://github.com/cropalato/obs_switchscene
A lightweight command-line tool to quickly switch between OBS Studio scenes. Perfect for streamers and content creators who need fast scene transitions through hotkeys or automation.
https://github.com/cropalato/obs_switchscene
automation broadcast cli content-creation go golang obs obs-studio scene-switcher streamdeck streaming streaming-tools twitch websocket youtube
Last synced: 30 days ago
JSON representation
A lightweight command-line tool to quickly switch between OBS Studio scenes. Perfect for streamers and content creators who need fast scene transitions through hotkeys or automation.
- Host: GitHub
- URL: https://github.com/cropalato/obs_switchscene
- Owner: cropalato
- License: mit
- Created: 2021-05-04T20:51:28.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-10-31T16:37:28.000Z (over 1 year ago)
- Last Synced: 2025-03-02T16:13:17.186Z (over 1 year ago)
- Topics: automation, broadcast, cli, content-creation, go, golang, obs, obs-studio, scene-switcher, streamdeck, streaming, streaming-tools, twitch, websocket, youtube
- Language: Go
- Homepage:
- Size: 4.15 MB
- Stars: 1
- Watchers: 3
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: license
Awesome Lists containing this project
README
# OBS Scene Switcher
[](https://opensource.org/licenses/MIT)
A robust Go utility to toggle between two OBS Studio scenes with configurable options and improved error handling.
## Features
- Quick switching between two predefined scenes in OBS Studio
- Configurable connection settings (host, port, timeout)
- Scene validation to prevent errors
- Verbose logging option for debugging
- Connection timeout protection
- Lightweight and easy to use
- Uses OBS WebSocket for secure scene management
## Prerequisites
- OBS Studio
- OBS WebSocket plugin installed and configured
- Go programming environment (1.13 or higher recommended)
## Installation
1. Clone the repository:
```bash
git clone https://github.com/your-username/obs_switchscene.git
cd obs_switchscene
```
2. Build the project:
```bash
go build
```
## Usage
### Basic Usage
```bash
./obs_switchscene
```
### Advanced Usage with Options
```bash
./obs_switchscene [options]
```
### Available Options
```
-host string
OBS WebSocket host (default "localhost")
-port string
OBS WebSocket port (default "4455")
-password string
OBS WebSocket password
-password-file string
Path to file containing OBS WebSocket password (default "~/.obspwd")
-timeout duration
Connection timeout (default 5s)
-verbose
Enable verbose logging
```
**Notes**:
- If both `-password` and `-password-file` are provided, the `-password` flag takes precedence.
- If connection fails without any password specified, the application will automatically retry using the password from the default file (`~/.obspwd`).
### Examples
Basic scene switching:
```bash
./obs_switchscene "Gaming" "Streaming"
```
Custom host and port:
```bash
./obs_switchscene -host=192.168.1.100 -port=4455 "Gaming" "Streaming"
```
With password authentication:
```bash
# Using command-line password
./obs_switchscene -password="your-password" "Gaming" "Streaming"
# Using password from default file (~/.obspwd)
echo "your-password" > ~/.obspwd
chmod 600 ~/.obspwd
./obs_switchscene "Gaming" "Streaming"
# Using password from custom file
./obs_switchscene -password-file="/path/to/password" "Gaming" "Streaming"
```
With longer timeout and verbose logging:
```bash
./obs_switchscene -timeout=10s -verbose "Gaming" "Streaming"
```
## Configuration
The program supports various configuration options through command-line flags:
| Flag | Description | Default |
| ------------- | ------------------------------------ | ---------- |
| host | OBS WebSocket host address | localhost |
| port | OBS WebSocket port number | 4455 |
| password | OBS WebSocket password | |
| password-file | Path to file with password | ~/.obspwd |
| timeout | Connection timeout duration | 5s |
| verbose | Enable detailed logging | false |
## Error Handling
The program includes robust error handling for common scenarios:
- Connection timeouts
- Invalid scene names
- OBS connection failures
- Scene switching failures
When running with `-verbose`, detailed error information and operational status will be logged.
## Dependencies
- [goobs](https://github.com/andreykaipov/goobs) - OBS WebSocket 5.x client library
## Contributing
Contributions are welcome! Here are some ways you can contribute:
- Report bugs
- Suggest new features
- Submit pull requests
- Improve documentation
### Development Setup
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## Planned Features
- Configuration file support
- Scene transition effects
- Connection health monitoring
- Multiple scene group support
## Troubleshooting
### Common Issues
1. **Connection Timeout**
- Verify OBS is running
- Check if OBS WebSocket plugin is installed
- Confirm the correct host and port settings
2. **Scene Not Found**
- Verify scene names match exactly (case-sensitive)
- Check for extra spaces in scene names
- Use `-verbose` flag to see available scenes
3. **Port Already in Use**
- Verify no other instance is running
- Check if the specified port is available
## Support
For support, please:
1. Check the troubleshooting section
2. Enable verbose logging with `-verbose` flag
3. Open an issue on GitHub with the error logs