Stream Deck Skill

Agent-accessible interface for Stream Deck control. Provides persistent daemon management, button task execution, and status querying capabilities.

Architecture

The streamdeck project has two components:

1. CLI Tool (streamdeck command) - Manual operations by users
2. Daemon (this skill) - Persistent service for agent automation

┌─────────────────────────────────────────────────────────────────────┐
│                    AGENT / AUTOMATION                          │
│                                                              │
│  ┌────────────────────────────────────────────────────────┐     │
│  │  Stream Deck Skill (this skill)               │     │
│  │  • Restart daemon                              │     │
│  │  • Execute button tasks                        │◄──►│
│  │  • Query status                                 │     │
│  └────────────────────────────────────────────────────────┘     │
│                          │                                   │
│                          ▼                                   │
│  ┌────────────────────────────────────────────────────────┐     │
│  │  Stream Deck Daemon (persistent service)        │     │
│  │  • Manages Stream Deck hardware               │     │
│  │  • Executes button press events                 │     │
│  │  • Provides status API                         │     │
│  └────────────────────────────────────────────────────────┘     │
│                          │                                   │
│                          ▼                                   │
│  ┌────────────────────────────────────────────────────────┐     │
│  │  Stream Deck CLI (manual operations)        │     │
│  │  • User-invoked commands                     │     │
│  │  • Video chat, lights, monitoring, etc.      │     │
│  └────────────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────────────┘

Quick Start

1. Start the Daemon

# Start the streamdeck daemon in the background
./run.sh daemon start

# Or start in foreground for debugging
./run.sh daemon start --foreground

2. Use Agent Commands

# Restart the daemon
./run.sh restart

# Execute a button task
./run.sh button <button_id> [args...]

# Query daemon status
./run.sh status

# List available buttons
./run.sh list-buttons

# Get daemon logs
./run.sh logs

Commands

Daemon Management

| Command | Description | |----------|-------------| | daemon start | Start the streamdeck daemon (background) | | daemon start --foreground | Start daemon in foreground (for debugging) | | daemon stop | Stop the streamdeck daemon | | daemon restart | Restart the streamdeck daemon | | daemon status | Check if daemon is running | | daemon logs | View daemon logs |

Button Operations

| Command | Description | |----------|-------------| | button <id> | Execute button press event | | button <id> --hold | Execute button long-press event | | list-buttons | List all available button IDs | | button-info <id> | Get information about a button |

Status Queries

| Command | Description | |----------|-------------| | status | Get overall daemon status | | status --json | Get status in JSON format | | status --buttons | Get button states |

Configuration

| Command | Description | |----------|-------------| | config | Show current configuration | | config --set <key> <value> | Set configuration value | | config --get <key> | Get configuration value |

Configuration

The daemon reads configuration from:

1. Environment Variables:

   • STREAMDECK_DAEMON_PORT - Port for daemon API (default: 48970)
   • STREAMDECK_DAEMON_HOST - Host for daemon API (default: 127.0.0.1)
   • STREAMDECK_LOG_LEVEL - Log level (DEBUG, INFO, WARNING, ERROR)

2. Config File: ~/.streamdeck/daemon.json

Example Config

{
  "daemon": {
    "port": 48970,
    "host": "127.0.0.1",
    "log_level": "INFO"
  },
  "buttons": {
    "0": {
      "name": "Video Chat Start",
      "command": "streamdeck videochat start"
    },
    "1": {
      "name": "Video Chat Stop",
      "command": "streamdeck videochat stop"
    },
    "2": {
      "name": "Lights Toggle",
      "command": "streamdeck lights toggle"
    },
    "3": {
      "name": "Time Tracker Toggle",
      "command": "streamdeck time-tracker toggle"
    }
  }
}

Integration with Stream Deck CLI

The daemon works alongside the existing streamdeck CLI:

• CLI - Used for manual operations by humans
• Daemon - Used for automated operations by agents
• Both** share the same configuration and codebase

This dual approach ensures:

• ✅ Human users can continue using familiar CLI commands
• ✅ Agents have reliable daemon for automation
• ✅ No breaking changes to existing functionality
• ✅ Consistent behavior across both interfaces

API Endpoints

The daemon exposes a simple HTTP API:

| Endpoint | Method | Description | |----------|--------|-------------| | GET /status | GET | Get daemon status | | GET /buttons | GET | List all buttons | | GET /buttons/{id} | GET | Get button info | | POST /buttons/{id} | POST | Execute button press | | POST /buttons/{id}/hold | POST | Execute button long-press | | POST /restart | POST | Restart daemon | | POST /stop | POST | Stop daemon |

Example API Usage

# Get status
curl http://127.0.0.1:48970/status

# Execute button
curl -X POST http://127.0.0.1:48970/buttons/0

# Get button info
curl http://127.0.0.1:48970/buttons/0

Troubleshooting

Daemon Won't Start

# Check if port is already in use
lsof -i :48970

# Check logs for errors
./run.sh logs

# Try starting in foreground to see errors
./run.sh daemon start --foreground

Button Not Executing

# Check button configuration
./run.sh button-info <id>

# Verify daemon is running
./run.sh status

# Check logs for errors
./run.sh logs

Permission Issues

The daemon requires access to:

• Stream Deck hardware (USB device access)
• Configuration directory (~/.streamdeck/)
• Network port (48970) for API

On Linux, ensure user has proper permissions:

# Add user to dialout group (for serial port access)
sudo usermod -a -G dialout $USER

# Ensure ~/.streamdeck is writable
chmod 755 ~/.streamdeck

Development

Running Tests

# Run daemon tests
./sanity.sh

# Run with verbose output
./sanity.sh --verbose

Adding New Features

To add new button commands:

1. Add button configuration to ~/.streamdeck/daemon.json
2. Implement command handler in daemon code
3. Test with: ./run.sh button <id>

Data Storage

• Config: ~/.streamdeck/daemon.json - Button configurations and daemon settings
• Logs: ~/.streamdeck/daemon.log - Daemon activity logs
• State: ~/.streamdeck/daemon.state - Current button states (runtime only)

Dependencies

• Python 3.8+
• Stream Deck Python SDK (streamdeck)
• FastAPI (for daemon API)
• Uvicorn (for daemon server)
• Pydantic (for API models)

Install dependencies:

# Via uvx (recommended)
uvx --from "git+https://github.com/grahama1970/streamdeck.git" streamdeck-daemon

# Or manually
pip install streamdeck fastapi uvicorn pydantic

License

MIT License - See LICENSE file for details.