# StreamDeck + VDO.Ninja Mixer - Quick Setup Guide

## 🎥 Welcome to VDO.Ninja Control!

Tired of limited control in other streaming platforms? VDO.Ninja's API lets you create a professional control setup using your Elgato StreamDeck. Switch between layouts, control cameras, manage guests - all with simple HTTP GET requests!

1

### Generate Your API Key

First, choose a unique API key. This key links your StreamDeck commands to your VDO.Ninja mixer session. It should be hard for others to guess.

Your API Key: YOUR_UNIQUE_API_KEY (e.g., MySecretMixerKey2025)
💡 Tip: Make your API key memorable for you but secure. You'll need to use this exact same key in both VDO.Ninja and your StreamDeck button configurations. It can be any combination of letters and numbers that you make up.
2

### Open VDO.Ninja Mixer with API Enabled

Open your VDO.Ninja Mixer page in your browser, adding your API key as a URL parameter. Replace `YOUR_UNIQUE_API_KEY` with the key you chose in Step 1:

https://vdo.ninja/mixer?api=YOUR_UNIQUE_API_KEY

If your mixer URL already has other parameters (e.g., `?room=MyRoom`), add the API key with an ampersand (`&`):

https://vdo.ninja/mixer?room=MyRoom&api=YOUR_UNIQUE_API_KEY

This allows the mixer page to listen for commands associated with your API key.

⚠️ Important: You must add the `?api=YOUR_UNIQUE_API_KEY` (or `&api=YOUR_UNIQUE_API_KEY`) parameter to your VDO.Ninja Mixer URL, otherwise, the StreamDeck commands will not work! The VDO.Ninja page needs to be open and have this API key in its URL to receive commands.
3

### Configure StreamDeck Buttons for HTTP Requests

On your Stream Deck, you'll create buttons that send HTTP GET requests to the VDO.Ninja API.

The recommended method for simplicity is using the Stream Deck's built-in "Website" action:

- Open the Stream Deck software on your computer.
- From the actions list on the right (usually categorized), find the "System" category.
- Drag the "Website" action onto an empty key on your Stream Deck layout.
- Configure the "Website" action for the key:
  - Title: Give your button a descriptive name (e.g., "Layout 0", "Mute Mic").
  - URL: This is where you'll put the VDO.Ninja API command URL (see examples below). Make sure to replace `YOUR_UNIQUE_API_KEY` in the URL with the key you chose in Step 1.
  - Access in background: Crucially, ensure this checkbox is CHECKED. This makes the Stream Deck send the request without trying to open a web browser window.

💡 Alternative (Advanced): For more complex needs (not typically required for VDO.Ninja's basic API), you could explore Stream Deck plugins specifically designed for API/HTTP requests (e.g., "API Ninja" by BarRaider or "HTTP GET Request"). These offer more options like custom headers or parsing responses, but the "Website" action is sufficient for these commands.

Understanding the API URL Structure:

The general format for the VDO.Ninja API URLs you'll use is:

https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/action/target/value

- `YOUR_UNIQUE_API_KEY`: The key from Step 1.
- `action`: The command to perform (e.g., `layout`, `mic`, `camera`).
- `target`: Who or what the action applies to. For self-control in the mixer or for layout changes, this is often `null`. For guest control, it could be a guest slot number (e.g., `1`, `2`).
- `value`: The specific setting for the action (e.g., a layout number like `0` or `1`, or `toggle`, `true`, `false`).

If a parameter like `target` or `value` is not needed for a specific command, it's often represented by `null` in the URL path. Do not use double slashes (//) if a middle parameter is `null`. Always include `null` as part of the path.

#### Layout Controls (Defaults)

Assign these URLs to Stream Deck "Website" actions to switch VDO.Ninja Mixer layouts. Remember to replace `YOUR_UNIQUE_API_KEY`.

Auto Mix (Layout 0)
https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/layout/null/0
Layout 1
https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/layout/null/1
Layout 5
https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/layout/null/5
Layout 7
https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/layout/null/7

#### Essential Controls (Self)

These commands control your own VDO.Ninja instance (the one with the `?api=` parameter). The `target` is `null` as these actions apply to the VDO.Ninja instance itself.

Button Label (Suggestion) | URL Command (for StreamDeck "Website" action) | Function
--- | --- | ---
🎤 Mute/Unmute Mic | `https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/mic/null/toggle` | Toggle your microphone on/off
📹 Mute/Unmute Cam | `https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/camera/null/toggle` | Toggle your camera on/off
🔴 Start Record | `https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/record/null/true` | Start recording (local)
⏹️ Stop Record | `https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/record/null/false` | Stop recording (local)
✋ Toggle Hand | `https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/togglehand/null/null` | Raise/lower your hand

#### Guest Control (For Directors)

If you are using the Director role and have guests in slots, you can control them. Replace `SLOT_NUMBER` with the guest's slot (e.g., `1`, `2`, etc.).

Button Label (Suggestion) | URL Command (Example for Guest in Slot 1) | Function
--- | --- | ---
Mute Guest 1 | `https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/mic/1/toggle` | Toggle Guest 1's microphone
Cam Off Guest 1 | `https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/camera/1/false` | Turn Guest 1's camera off
Add Guest 1 to Scene 0 | `https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/addScene/1/0` | Toggle Guest 1 in/out of Scene 0 (Auto-Mix/Main Scene)
Hangup Guest 2 | `https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/hangup/2/null` | Disconnect guest in slot 2

⚠️ Crucial Reminder: Always replace `YOUR_UNIQUE_API_KEY` with your actual API key in all URLs you configure on your StreamDeck buttons! And ensure "Access in background" is checked for each "Website" action.
4

### Advanced Control Options & Full List

VDO.Ninja offers many more API commands. For a comprehensive list, please refer to the official API documentation (often found on the Companion-Ninja GitHub or VDO.Ninja docs).

Here are a few more examples of what's possible:

#### Scene Management (Director)

Function | URL Command (replace `YOUR_UNIQUE_API_KEY`, `GUEST_SLOT`, `SCENE_ID`)
--- | ---
Add Guest in Slot 1 to Scene 0 | `https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/addScene/1/0`
Mute Guest in Slot 1 in Scene 0 | `https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/muteScene/1/0`

#### Group Controls (Director - Self)

Function | URL Command (replace `YOUR_UNIQUE_API_KEY`, `GROUP_ID`)
--- | ---
Join Group 1 (Self) | `https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/joinGroup/null/1`
Leave Group 2 (Self) | `https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/leaveGroup/null/2`
Toggle Self in/out of Group 3 | `https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/group/null/3`

#### Camera Control (PTZ - for compatible cameras, target can be `null` for self or guest slot)

Function (Self Camera) | URL Command (replace `YOUR_UNIQUE_API_KEY`)
--- | ---
Zoom In (Self) | `https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/zoom/null/0.1`
Zoom Out (Self) | `https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/zoom/null/-0.1`
Pan Left (Self) | `https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/pan/null/-0.1`
Pan Right (Self) | `https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/pan/null/0.1`

💡 Targeting Guests for PTZ: To control a guest's PTZ camera, replace `null` with their guest slot number. For example, to zoom Guest 1's camera in: `https://api.vdo.ninja/YOUR_UNIQUE_API_KEY/zoom/1/0.1`
5

### Quick Start Examples (StreamDeck Button Ideas)

Here are some ideas for StreamDeck button layouts. Remember, you need to create each of these using the "Website" action and the corresponding API URLs as detailed in Step 3.

#### Basic Control Set (for a Performer/Self-Operator)

(These are visual examples of how your StreamDeck might look. Each is a "Website" action.)

Layout 0
(Auto)
Layout 1
Layout 2
Mute Mic
Mute Cam
Start Rec
Stop Rec
Raise Hand

#### Director Control Set (for managing a show with guests)

(These are visual examples of how your StreamDeck might look. Each is a "Website" action.)

Mute G1 Mic
Mute G2 Mic
G1 to Scene 0
G2 to Scene 0
Hangup G1
Hangup G2
Force Key G1
Highlight G1

## 🚀 You're All Set!

With these StreamDeck controls, you now have powerful, tactile command over your VDO.Ninja Mixer sessions. No more frantic clicking through menus during a live production – just press a button for instant control!

Remember: Always keep your API key secure and never share it publicly. Ensure the VDO.Ninja Mixer page with the `?api=` parameter is open in your browser for the commands to work.