IO-Darts-Agent: Features

Overview

IO-Darts-Agent is a local hub between the Autodarts platform and various action modules. It receives your board's real-time events and forwards them to the configured modules (lighting, display, voice announcements).

IO-Darts-Agent is an unofficial project and not affiliated with Autodarts. The hub is built for use in a local network and must not be reachable from the internet. License: PolyForm Noncommercial 1.0.0, free for private, non-commercial use.

Core Features

1. Autodarts Integration

Authentication

• Login with email and password at the official Autodarts API (auth service v1, api.autodarts.com/auth/v1)
• Automatic refresh of the access token before it expires; if a refresh is rejected, a new login with the stored password
• No support for two-factor authentication (2FA)
• Credentials are only stored locally on the hub machine (dist/config/hub.config.json, plain text)
• Entered in the setup wizard or later under Settings > Autodarts

WebSocket Connection

• Persistent WebSocket connection to the Autodarts server
• Short-lived ticket per connection, requested again on every reconnect
• Automatic reconnection after connection loss

Event Processing

Native events (from Autodarts):

Synthetic events (generated by the EventParser):

Note on array rotation: Autodarts rotates the player array after each leg. The synthetic events therefore contain both playerName/winnerName and playerIndex/winnerPlayerIndex for robust player detection. Details in the developer guide.

Note on game: match.state, throw.detected, turn.finished, player.change, game.finished, match.finished, match.result, cricket.state and cricket.closed additionally carry data.game = { variant, mode, cutThroat }, with mode one of x01, cricket, tactics or other. In Cricket/Tactics, throw.detected also carries marks (this dart's marks) and turnMarks (the turn's marks up to and including this dart); turn.finished only carries turnMarks.

2. Modular Plugin System

Module Architecture

• Built-in modules: WLED, Game Display, Darts Caller
• Each module describes its events, configuration and translations in a module.json
• Modules can have their own web UI (e.g. the Game Display at /module-ui/game-display/)
• Further modules can be installed from Git repositories or a local path and run as separate Node processes

Module Lifecycle

Installation > Configuration > Start > Running > Stop > Uninstall

Event Handling and Intents

• Modules subscribe to specific events
• Errors in one module do not affect others
• Intent system for module-to-module communication, configurable under Intent Reactions

3. Web Interface

Setup Wizard

• Step 1: optional login for the web interface
• Step 2: Autodarts credentials and board ID with connection test
• Step 3: summary and finish

Dashboard

• Active modules, uptime, events today
• Autodarts connection status with disconnect and connect, active match
• Module list and live event feed

Module Management

• Installed and available built-in modules
• Start, stop, restart, autostart
• Module configuration, intent reactions, statistics
• Install new modules (Git or local), uninstall

Player Management

• Player profiles with name, color, avatar and optional Autodarts user ID

Media Library

• Animations, sounds and images with folders, search, upload (up to 50 MB) and copy URL

AI Providers

• API keys, default models and connection test for all AI providers

Console

• Real-time log with event, module and system entries
• Filters, search, pause, auto-scroll, export, clear

Settings

• Language, server (host, port), web authentication, Autodarts access, developer mode
• The server host is stored but currently ignored: the hub always binds to 0.0.0.0

Developer Tools

• Simulate matches, throws and turns without a real board (after enabling developer mode)

Multi-Language

• Interface in 10 languages: German, English, Spanish, French, Italian, Japanese, Dutch, Russian, Ukrainian, Chinese
• German and English complete, the others partly translated

4. Player Management

Player Profiles

• Name, color (palette or hex code), avatar
• Matched to Autodarts players by name (case-insensitive)

Color System

• Profile colors are passed to WLED and the Game Display
• For players without a profile, WLED uses position colors (up to 6 players)

5. Configuration System

config/
├── hub.config.json         Autodarts access, board, server, web login
├── ai-providers.json       AI providers, API keys, models
├── animation-settings.json Selected engine of the animation generator
├── players.json            Player profiles
└── modules/*.json          Module settings
media/                      Media library (animation, sound, image)
data/voicepacks/            Darts Caller voice packs
data/tts-cache/             Cache for ElevenLabs calls

When running from source these folders live under dist/. Credentials and API keys are stored in plain text.

Built-in Modules

WLED Lighting Controller

Controls WLED-compatible LED controllers based on game events.

Features:

• Action types per event: Preset, Effect, Color, Off, None
• Presets and effects are loaded straight from the controller, with a built-in effect list as fallback
• Effects with up to 3 colors, speed, intensity and brightness
• "Use player color" option per action
• Duration per action, afterwards the active player's color is set again (not the previous WLED state)
• Fade time per action in milliseconds, plus a global fade time in the connection settings
• Single-player support: player color after match start and after every takeout
• Player colors for up to 6 positions as fallback
• Test button per action and quick actions (Rainbow Test, LEDs off, Green, Red)
• Reacts to intents from other modules

Supported events:

There is no "High Finish" event: the hub does not report a checkout value, so the module cannot detect it. "Strong turn" is not a hub event either, but a module-internal key like throw.triple: the module fires it itself once turnMarks reaches the configured threshold (3 to 9, default 6). In Cricket/Tactics the 180 action does not fire; triple, double, bull, bullseye and miss keep firing.

Game Display Module

Shows the current score fullscreen on a separate device. Display URL: http://192.168.1.100:3000/module-ui/game-display/ (IP of the hub machine).

Features:

• Large score display with the player color as background
• Checkout suggestions (threshold adjustable, default 170)
• Throw display (dart 1, 2, 3) and turn sum
• Bar with other players
• Own Cricket view: points of the active player, marks per field (20 to 15, Bull) as /, X, ⊗, dead fields dimmed, other players with their marks at the edge
• Optional game info overlay (position, size, offset adjustable)
• Idle mode: Show Last Game Score, Black Screen, Custom Image
• Match start screen: default (Game On!) or custom image/GIF, duration and background color adjustable
• Results table after the match with chalkboard and statistics, display duration and background color adjustable
• Preview, "Open Display" and "Copy URL" in the configuration
• Full match data is fetched automatically at match start

Animations per event:

• 180, Bull, Double Bull, High Score (threshold adjustable), Checkout, Leg Win, Match Win, Bust
• Cricket: Field Closed, Strong Turn (from marks adjustable, default 6); 180, High Score and Checkout are off in Cricket
• Type: Disabled, Built-in, GIF or Video, each with an optional sound and its own duration
• Leg and match win also with winner name, statistics, effect (Confetti, Fireworks, Sparkles) and colors
• Media via upload, from the media library or as an external URL
• Animation generator right in the Animations tab

Player-specific animations:

• Custom animations per player in the Players tab for: 180, Leg Won, Match Won, Checkout
• Replace the global animation when this player triggers the event
• Without a player entry the global animation applies

Darts Caller Module

Darts caller with browser TTS, voice packs, ElevenLabs or custom audio files.

Features:

• Score calls after each turn
• Checkout calls ("You require ...")
• Special calls: 180, bust, no score, game on, game shot, match shot
• Player change calls with player names
• In Cricket/Tactics: "<field> closed!" (10 to 20, Bull) and "<N> marks!" from an adjustable threshold (3 to 9, default 6), instead of score, checkout, 180, bust and bull/double-bull calls; Game On, player name on change, Game Shot and Match Shot are kept
• Languages: English, German
• Caller types: Browser TTS (played in the browser), AI Voice Pack, ElevenLabs Live AI, Custom Audio Files (played on the speakers of the hub machine)
• Call settings: scores, high scores only, checkouts with an upper limit for "You require ...", player change, game start, game over, 180, busts, bulls, double bulls
• Volume and delay adjustable, browser voice, pitch and speed for Browser TTS
• One configuration for the caller page and the generic module form; changes apply without a module restart, older stored settings are migrated automatically

ElevenLabs:

• Uses the ElevenLabs key from the AI provider settings
• Choice of the voices in your ElevenLabs account
• Voice pack generator: scores 0 to 180, all possible checkouts 2 to 170, special calls and Cricket phrases (closed fields 10 to 20 and Bull, marks 3 to 9), with progress and cancel
• Multiple voice packs (different voices and languages), upload as ZIP, select and delete
• "Generate Missing Announcements" per voice pack: generates only the files still missing (e.g. after new phrases), costs ElevenLabs credits only on click
• Missing player names are generated automatically at match start (with a voice pack active)
• TTS cache for live calls, repeated phrases are not requested again

AI Features

AI Providers

Providers are set up under AI Provider in the sidebar. All of them are optional.

Functions:

• API key, default model, save, test connection, on/off per provider
• Stored on the hub in dist/config/ai-providers.json
• OpenAI and Anthropic: the model list is loaded live from the provider with the saved key. Models that are no longer offered are reported and replaced.
• Higgsfield: key in the format KEY_ID:KEY_SECRET, fixed catalog with 20 text-to-video and 10 text-to-image models, separate selects for video and image model (defaults: Kling 3.0 Standard and Soul Standard)
• Higgsfield requests are adapted per model: allowed duration, supported aspect ratio, audio off
• Runway: fixed catalog with 23 text-to-video models from the Runway API (default: Gen-4.5), visible without a key. Retired models such as Gen-3 are reported and replaced by Gen-4.5.
• Runway requests are adapted per model: allowed aspect ratio matching the orientation, allowed duration, audio off, prompt cut to the maximum length. Generations are sent exactly once (no automatic retry that could bill twice), status requests are retried.
• Paid requests of all cloud providers (text, image, speech, video, embeddings) are sent exactly once. After a server error or timeout the provider may already have billed them, so the hub does not repeat them. Requests such as model lists and status are retried.

Generations cost credits at the respective provider.

Animation Generator

Creates animations for the Game Display with AI. Found in the Game Display configuration in the Animations tab.

• Engine: Runway or Higgsfield, switchable, the choice is stored in dist/config/animation-settings.json
• Model: the provider's default model from the AI settings. Runway generates text-to-video, without a placeholder image.
• Styles: Fire, Ice, Neon, Gold, Cartoon, Minimal, Electric, Confetti, Smoke, Stars or a custom style with name and description
• Events: 180, Bull, Double Bull, High Score (160+), Checkout, Leg Win, Match Win, Bust
• Batch generation: one job per selected event
• Jobs: status, progress, cancel, preview, "Use" (sets the animation for the event), "Clear Finished"
• Result: converted with ffmpeg into a transparent WebM (black background removed). Without ffmpeg the original is kept as MP4.
• Location: media library, Animations, folder ai-generated/<style>

Technical Details

Security

• Built for a trusted local network; do not expose it to the internet, no port forwarding
• Credentials and API keys are stored in plain text on the hub machine
• Connections only to Autodarts, your devices in the network and configured AI providers
• Optional login for the web interface

Compatibility

• Node.js 22 or newer (when running from source)
• Current browsers (Chrome, Firefox, Safari, Edge)
• WLED controllers with JSON API
• ffmpeg optional for transparent animations

API

• REST and WebSocket API, see the API documentation