Skip to content

Latest commit

 

History

History
92 lines (71 loc) · 3.73 KB

CLAUDE.md

File metadata and controls

92 lines (71 loc) · 3.73 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

OBS Scene Switcher is a command-line utility written in Go that toggles between two OBS Studio scenes using the OBS WebSocket protocol. The entire application is contained in a single main.go file with a focus on simplicity and reliability.

Build and Development Commands

Building

go build

The build produces a binary named obs_switchscene.

Testing

go test -v ./...

Running the Application

# Basic usage
./obs_switchscene <scene1> <scene2>

# With options (OBS WebSocket 5.x default port is 4455)
./obs_switchscene -host=localhost -port=4455 -timeout=5s -verbose <scene1> <scene2>

# With password authentication (command-line)
./obs_switchscene -password="your-password" <scene1> <scene2>

# With password authentication (from file)
echo "your-password" > ~/.obspwd && chmod 600 ~/.obspwd
./obs_switchscene <scene1> <scene2>

# Show version
./obs_switchscene -version

Release Build

The project uses GoReleaser for cross-platform builds:

goreleaser release --clean

GoReleaser builds for Linux, Windows, and Darwin (amd64) with version information injected via ldflags:

  • -X main.version={{.Version}}
  • -X main.commit={{.Commit}}
  • -X main.date={{.Date}}

Architecture

Single File Design

The entire application is in main.go:1-158 with a straightforward structure:

  1. Config struct (main.go:18-26): Holds all runtime configuration including connection details, password, and scene names
  2. readPasswordFromFile() (main.go:60-82): Reads password from a file, expanding ~ for home directory and handling file existence
  3. parseFlags() (main.go:85-137): Handles CLI argument parsing with custom usage message, version display, and password support (both command-line and file-based). Command-line password takes precedence over password file.
  4. createClient(): Creates OBS WebSocket 5.x client with connection timeout using goroutines and channels
  5. switchScene(): Core logic that:
    • Gets the current active scene from OBS
    • Retrieves scene list and validates both target scenes exist
    • Determines which scene to switch to (toggles between scene1 and scene2)
    • Executes the scene change using the OBS WebSocket 5.x API

Key Dependencies

  • github.com/andreykaipov/goobs: OBS WebSocket 5.x client library (v1.4.0)

Design Patterns

  • Timeout pattern: Uses goroutines and channels for connection timeout
  • Testability: Uses osExit variable (main.go:28) to allow mocking of os.Exit in tests
  • Scene validation: Always validates scene existence before attempting switches to prevent errors
  • OBS WebSocket 5.x: Uses the newer protocol (default port 4455) with optional password authentication
  • Password security: Supports reading password from file (default ~/.obspwd) to avoid exposing passwords in command-line arguments. Command-line -password flag takes precedence over -password-file.
  • Automatic retry: If initial connection fails without a password, automatically retries using the password from the default file (~/.obspwd), providing a seamless experience for users who have configured the password file.

License Header

All Go source files should include the MIT license header:

// filename.go
// Copyright (C) 2024 Ricardo Melo
//
// Distributed under terms of the MIT license.

Release Process

Releases are automated via GitHub Actions (.github/workflows/release.yml) when tags matching v* are pushed. The workflow:

  1. Runs tests with go test -v ./...
  2. Uses GoReleaser to build cross-platform binaries
  3. Creates GitHub releases with archives (tar.gz for Linux/Darwin, zip for Windows)