🎬 ATWITCHEM

Laat je Twitch-kijkers jouw Blackmagic ATEM Mini Pro bedienen via Bits!

---

🇳🇱 Nederlands

Wat is ATWITCHEM?

ATWITCHEM koppelt je Twitch-chat aan je Blackmagic ATEM Mini Pro videomixer. Kijkers doneren Bits in de chat, en jouw ATEM reageert automatisch — camera wisselen, CUT of AUTO overgang, Picture-in-Picture aanpassen, noem maar op.

Alles is instelbaar via een netjes web-dashboard dat meestart in je browser. Geen ATEM Software Control nodig tijdens gebruik.

✨ Functies

• 🎥 Automatisch camera's wisselen via Twitch Bits en/of Channel Points
• ⏱️ Instelbare cooldown per regel — voorkom spam
• ⚡ Ondersteuning voor CUT, AUTO, preview en PiP-acties
• 🌐 Ingebouwd web-dashboard op http://localhost:5000
• 🔄 Automatisch herverbinden als de ATEM wegvalt
• 📋 Regels live beheren vanuit het dashboard (bewaard in config.json)
• 🧪 Test-modus voor zowel Bits als Channel Points simuleren

📋 Vereisten

• Python 3.8 of hoger
• Een Blackmagic ATEM Mini Pro (of vergelijkbaar model) bereikbaar via netwerk
• Een Twitch-account met OAuth-token

📦 Dependencies

Package	Versie	Waarvoor
twitchio	≥ 2.8, < 3.0	Twitch chat & Bits events luisteren
flask	≥ 3.0	Web-dashboard server
flask-socketio	≥ 5.3	Realtime updates in het dashboard

Installeer alles in één keer:

pip install -r requirements.txt

🚀 Opstarten

1. Config instellen

Kopieer het voorbeeldbestand en vul je gegevens in:

# Windows
copy config.json.example config.json

# Linux / macOS
cp config.json.example config.json

Open config.json en pas aan:

{
  "atem_ip": "192.168.1.xxx",
  "twitch_channel": "jouwnaam",
  "twitch_token": "oauth:xxxxxxxxxxxxxx",
  "dashboard_port": 5000,
  "rules": []
}

💡 Twitch OAuth-token aanvragen? Ga naar twitchapps.com/tmi en log in.

🎁 Channel Points gebruiken? Zorg dat je token de scope channel:read:redemptions heeft. Zonder die scope werken Bits-regels gewoon door — Channel Points worden dan stilletjes genegeerd.

2. Starten

# Windows (dubbelklik of via terminal)
start.bat

# Linux / macOS
bash start.sh

# Of direct via Python
python src/main.py

3. Dashboard openen

Ga naar http://localhost:5000 in je browser.

⚙️ Regels instellen

Regels bepalen wat er gebeurt bij een Bits-donatie of Channel Point redemption. Een regel bestaat uit:

Veld	Omschrijving
trigger_type	"bits", "channel_points" of "both"
bits_min	Minimaal aantal Bits (voor Bits/beide)
bits_max	Maximaal aantal Bits (optioneel)
reward_name	Naam van de Channel Point reward om op te matchen (optioneel, gedeeltelijke match)
trigger_text	Tekst in het bericht/gebruikersinput (optioneel)
action	Welke actie uitvoeren (zie hieronder)
value	Waarde voor de actie (bijv. camera-ingang 1–4)
cooldown_seconds	Cooldown in seconden tussen twee triggers (0 = geen)
name	Naam voor in het dashboard

Beschikbare acties:

Actie	Omschrijving	Waarde
switch_program	Wissel live (on-air) camera	ingang 1–4
switch_preview	Wissel preview camera	ingang 1–4
cut	CUT-overgang uitvoeren	—
auto	AUTO-overgang uitvoeren	—
toggle_downstream_key	DSK on-air schakelen	1 of 2
set_pip_source	PiP-bron wisselen	ingang 1–4

Voorbeeld:

{
  "name": "Schakel naar Cam 2",
  "bits_min": 200,
  "trigger_text": "cam2",
  "action": "switch_program",
  "value": 2
}

---

🇬🇧 English

What is ATWITCHEM?

ATWITCHEM connects your Twitch chat to your Blackmagic ATEM Mini Pro video switcher. Viewers donate Bits in chat, and your ATEM responds automatically — switch cameras, trigger a CUT or AUTO transition, change Picture-in-Picture sources, and more.

Everything is configurable through a clean web dashboard that starts alongside the bot. No ATEM Software Control needed during operation.

✨ Features

• 🎥 Automatically switch cameras via Twitch Bits and/or Channel Points
• ⏱️ Configurable cooldown per rule — prevent spamming
• ⚡ Support for CUT, AUTO, preview and PiP actions
• 🌐 Built-in web dashboard at http://localhost:5000
• 🔄 Auto-reconnect if the ATEM becomes unreachable
• 📋 Manage rules live from the dashboard (saved to config.json)
• 🧪 Test mode for simulating both Bits and Channel Point events

📋 Requirements

• Python 3.8 or higher
• A Blackmagic ATEM Mini Pro (or similar) reachable on your network
• A Twitch account with an OAuth token

📦 Dependencies

Package	Version	Purpose
twitchio	≥ 2.8, < 3.0	Listen to Twitch chat & Bits events
flask	≥ 3.0	Web dashboard server
flask-socketio	≥ 5.3	Real-time updates in the dashboard

Install everything at once:

pip install -r requirements.txt

🚀 Getting started

1. Configure

Copy the example config and fill in your details:

# Windows
copy config.json.example config.json

# Linux / macOS
cp config.json.example config.json

Open config.json and edit:

{
  "atem_ip": "192.168.1.xxx",
  "twitch_channel": "yourchannel",
  "twitch_token": "oauth:xxxxxxxxxxxxxx",
  "dashboard_port": 5000,
  "rules": []
}

💡 Need a Twitch OAuth token? Visit twitchapps.com/tmi and log in.

🎁 Using Channel Points? Make sure your token has the channel:read:redemptions scope. Without it, Bits rules still work — Channel Points are silently ignored.

2. Run

# Windows (double-click or via terminal)
start.bat

# Linux / macOS
bash start.sh

# Or directly with Python
python src/main.py

3. Open the dashboard

Navigate to http://localhost:5000 in your browser.

⚙️ Setting up rules

Rules define what happens on a Bits donation or Channel Point redemption. A rule consists of:

Field	Description
trigger_type	"bits", "channel_points", or "both"
bits_min	Minimum Bits to trigger (for Bits/both)
bits_max	Maximum Bits (optional)
reward_name	Channel Point reward title to match (optional, partial match)
trigger_text	Text in message/user input (optional)
action	Which action to execute (see below)
value	Value for the action (e.g. camera input 1–4)
cooldown_seconds	Cooldown in seconds between triggers (0 = none)
name	Display name in the dashboard

Available actions:

Action	Description	Value
switch_program	Switch live (on-air) camera	input 1–4
switch_preview	Switch preview camera	input 1–4
cut	Execute a CUT transition	—
auto	Execute an AUTO transition	—
toggle_downstream_key	Toggle DSK on-air	1 or 2
set_pip_source	Change PiP source	input 1–4

Example:

{
  "name": "Switch to Cam 2",
  "bits_min": 200,
  "trigger_text": "cam2",
  "action": "switch_program",
  "value": 2
}

---

📁 Project structuur / Project structure

ATWITCHEM/
├── src/
│   ├── main.py              # Opstartpunt / Entry point
│   ├── atem_controller.py   # UDP-communicatie met ATEM / UDP comms with ATEM
│   ├── twitch_client.py     # Twitch chatbot / Twitch chatbot
│   ├── rule_engine.py       # Bits → acties koppeling / Bits → actions mapping
│   ├── dashboard.py         # Flask web-dashboard
│   └── templates/
│       └── index.html       # Dashboard UI
├── static/
│   ├── css/style.css
│   └── js/dashboard.js
├── config.json              # Jouw instellingen (niet committen!) / Your settings (don't commit!)
├── config.json.example      # Voorbeeldconfig / Example config
├── requirements.txt
├── start.bat                # Windows opstartscript / Windows start script
└── start.sh                 # Linux/macOS opstartscript / Linux/macOS start script

---

Made with ❤️ by DIMENTS