# Control

You can control Hyperion by sending specific JSON messages.

TIP

The tan property is supported in these calls, but omitted for brevity.

# Sections

# Set Color

Set a color for all LEDs or provide a pattern of LED colors.

Property Type Required Comment
color Array true An array of R G B Integer values e.g. [R,G,B]
duration Integer false Duration of color in ms. If you don't provide a duration, it's 0 -> indefinite
priority Integer true We recommend 50, following the Priority Guidelines. Min 2 Max 99
origin String true A short name of your application like Hyperion of App . Max length is 20, min 4.
// Example: Set a blue color with indefinite duration at priority 50 
{
  "command":"color",
  "color":[0,0,255],
  "priority":50,
  "origin":"My Fancy App"
}
// Example: Set a cyan color for 12 seconds at priority 20
{
  "command":"color",
  "color":[0,255,255],
  "duration":12000,
  "priority":20,
  "origin":"My Fancy App"
}
// Example: Provide a color pattern, which will be repeated until all LEDs have a color
// One LED has 3 values (Red,Green,Blue) with range of 0-255
// In this case LED 1: Red, LED 2: Red, LED 3: Blue.
{
  "command":"color",
  "color":[255,0,0,255,0,0,0,0,255],
  "duration":12000,
  "priority":20,
  "origin":"My Fancy App"
}

# Set Effect

Set an effect by name. Available names can be found in the serverinfo effect list.

Property Type Required Comment
effect Object true Object with additional properties. e.g. "name":"EffectName".
duration Integer false Duration of effect in ms. If you don't provide a duration, it's 0 -> indefinite
priority Integer true We recommend 50, following the Priority Guidelines. Min 2 Max 99
origin String true A short name of your application like Hyperion of App . Max length is 20, min 4.
// Example: Set the 'Warm mood blobs' effect with indefinite duration
{
  "command":"effect",
  "effect":{
    "name":"Warm mood blobs"
  },
  "priority":50,
  "origin":"My Fancy App"
}
// Example: Set 'Rainbow swirl' effect for 5 seconds
{
  "command":"effect",
  "effect":{
    "name":"Rainbow swirl"
  },
  "duration":5000,
  "priority":50,
  "origin":"My Fancy App"
}
// Example: Set 'Rainbow swirl' effect for 1 second with overridden agrument
// Each effect has different agruments inside the args property that can be overridden.
// WARNING: We highly recommend using the effects configurator in the UI instead. Sending invalid values may cause the effect to misbehave or crash.
{
  "command":"effect",
  "effect":{
    "name":"Rainbow swirl",
    "args":{
      "rotation-time":1
    }
  },
  "duration":5000,
  "priority":50,
  "origin":"My Fancy App"
}

# Set Image

Set a single image. Supports all Qt5 (opens new window) image formats, including png/jpg/gif.

Property Type Required Comment
imagedata String true Data of image as Base64 (opens new window)
format String true Set to auto to let Hyperion parse the image according to type
name String true The name of the image
duration Integer false Duration of image in ms. If you don't provide a duration, it's 0 -> endless
priority Integer true We recommend 50, following the Priority Guidelines. Min 2 Max 99
origin String true A short name of your application like Hyperion of App . Max length is 20, min 4.
// Set an image for 5 seconds
{
  "command":"image",
  "imagedata":"VGhpcyBpcyBubyBpbWFnZSEgOik=",
  "name":"Name of Image",
  "format":"auto",
  "priority":50,
  "duration":5000,
  "origin": "My Fancy App"
}

# Clear

Clear a priority, usually used to revert set color, set effect or set image.

// Clear effect/color/image with priority 50
{
  "command":"clear",
  "priority":50
}
// Clear all effects/colors/images
{
  "command":"clear",
  "priority":-1
}

WARNING

When you clear all, you clear all effects and colors regardless of who set them! Instead, we recommend users provide a list of possible clear targets based on a priority list

# Adjustments

Adjustments reflect the color calibration. You can modify all properties of serverinfo adjustments.

Property Type Required Comment
red Array false An array of R G B Integer values e.g. [R,G,B]
green Array false An array of R G B Integer values e.g. [R,G,B]
blue Array false An array of R G B Integer values e.g. [R,G,B]
cyan Array false An array of R G B Integer values e.g. [R,G,B]
magenta Array false An array of R G B Integer values e.g. [R,G,B]
yellow Array false An array of R G B Integer values e.g. [R,G,B]
white Array false An array of R G B Integer values e.g. [R,G,B]
gammaRed Number (float) false minimum:0.1 maximum 5.0 step of 0.1
gammaGreen Number (float) false minimum:0.1 maximum 5.0 step of 0.1
gammaBlue Number (float) false minimum:0.1 maximum 5.0 step of 0.1
brightness Integer false minimum: 0 maximum 100 step of 1
brightnessCompensation Integer false minimum: 0 maximum 100 step of 1
backlightThreshold Integer false minimum: 0 maximum 100. Step of 1. (Minimum brightness!) Disabled for effect/color/image
backlightColored Boolean false If true the backlight is colored, false it's white. Disabled for effect/color/image
id String false Short identifier
// Example: Set gammaRed to 1.5
{
  "command":"adjustment",
  "adjustment":{
    "gammaRed":1.5
  }
}
// Example: Set green to [0,236,0]
{
  "command":"adjustment",
  "adjustment":{
    "green":[0,236,0]
  }
}
// Example: Set backlightColored to true
{
  "command":"adjustment",
  "adjustment":{
    "backlightColored":true
  }
}
// Example: Send the 3 examples above at once
{
  "command":"adjustment",
  "adjustment":{
    "backlightColored":true,
    "gammaRed":1.5,
    "green":[0,236,0]
  }
}

# LED mapping

Switch the LED mapping mode for the incoming image.

mappingType value Description
multicolor_mean Mean Color Simple - per LED
unicolor_mean Mean Color Image - applied on all LEDs
multicolor_mean_squared Mean Color Squared - per LED
dominant_color Dominant Color- per LED
dominant_color_advanced Dominant Color Advanced - per LED
// Example: Set mapping mode to multicolor_mean
{
  "command":"processing",
  "mappingType":"multicolor_mean"
}
// Example: Set mapping mode to unicolor_mean
{
  "command":"processing",
  "mappingType":"unicolor_mean"
}

# Video Mode

Switch the video mode. Possible values are: 2D, 3DSBS and 3DTAB.

// Example: Set video mode to 3DTAB
{
 "command":"videomode",
 "videoMode":"3DTAB"
}
// Example: Set video mode to 3DSBS
{
 "command":"videomode",
 "videoMode":"3DSBS"
}

# Control Components

Some components can be enabled and disabled at runtime. To get the current state and available components see Serverinfo Components. See also: Components/IDs explained

// Example: disable LEDDEVICE component
{
 "command":"componentstate",
 "componentstate":{
   "component":"LEDDEVICE",
   "state":false
 }
}
// Example: enable SMOOTHING component
{
 "command":"componentstate",
 "componentstate":{
   "component":"SMOOTHING",
   "state":true
 }
}

WARNING

Hyperion itself needs to be enabled! Check the status of "ALL" in the components list before you change another component!

# Components/IDs explained

Each component has a unique id. Not all of them can be enabled/disabled -- some of them, such as effect and color, are used to determine the source type when examining the priority list.

ComponentID Component Enable/Disable Comment
SMOOTHING Smoothing Yes Smoothing component
BLACKBORDER Blackborder detector Yes Black bar detection component
FORWARDER JSON/Proto forwarder Yes JSON/Proto forwarder component
BOBLIGHTSERVER Boblight server Yes Boblight server component
GRABBER Screen capture Yes Screen Capture component
V4L V4L capture device Yes USB capture device component
AUDIO AUDIO capture device Yes Audio capture device component
LEDDEVICE LED device Yes LED device component start/stops output of the configured LED device
ALL SPECIAL: Hyperion Yes Enable or disable Hyperion. Recovers/saves last state of all other components
COLOR Solid color No All colors that has been set belongs to this component
EFFECT Effect No All effects belongs to this component
IMAGE Solid Image No All single/solid images belongs to this. NOT for streaming
FLATBUFSERVER Flatbuffers Server No All image stream sources from Flatbuffers server
PROTOSERVER Protobuffer Server No All image stream sources from Protobuffer server

# Source Selection

Sources are always selected automatically by priority value (lowest value is the highest priority). You need to know the priority value of the source you want to select -- these priority values are available in the serverinfo Priorities.

// Example: Set priority 50 to visible
{
  "command":"sourceselect",
  "priority":50
}

If you get a success response, the priorities_autoselect-status will switch to false (see serverinfo Autoselection Mode). You are now in manual mode, to switch back to auto mode send:

{
  "command":"sourceselect",
  "auto":true
}

After which, the priorities_autoselect-status will return to true.

WARNING

You can only select priorities which are active:true!

# Control Instances

An instance represents an LED hardware instance. It runs within its own scope with it's own plugin settings, LED layout and calibration. Before selecting you can instance, you should first get information about the available instances from serverinfo.

// Command to start instance 1
{
  "command" : "instance",
  "subcommand" : "startInstance",
  "instance" : 1
}
// Command to stop instance 1
{
  "command" : "instance",
  "subcommand" : "stopInstance",
  "instance" : 1
}

# API Instance handling

On connection to the API you will be connected to instance 0 by default. You can control only one instance at the same time within a single connection, and subscriptions are in the context of the selected instance.

It's possible to switch to another instance with the following command:

// Switch to instance 1
{
  "command" : "instance",
  "subcommand" : "switchTo",
  "instance" : 1
}

This will return a success response or an error if the instance isn't available.

WARNING

It's possible that an instance will stop while you are connected to it. In this case connections on that instance will automatically be reset to instance 0. Keep watching the instance data via subscription if you need to handle this case. See: Instance updates.

# Live Image Stream

You can request a live image stream (if the current source priority supports it, otherwise here may be no response).

{
  "command":"ledcolors",
  "subcommand":"imagestream-start"
}

You will receive "ledcolors-imagestream-update" messages with a base64 encoded image. Stop the stream by sending:

{
  "command":"ledcolors",
  "subcommand":"imagestream-stop"
}

HTTP/S

This feature is not available for HTTP/S JSON-RPC

# Live LED Color Stream

You can request a live LED color stream with current color values in RGB for each single LED. The update rate is 125ms.

{
  "command":"ledcolors",
  "subcommand":"ledstream-start"
}

You will receive "ledcolors-ledstream-update" messages with an array of all LED colors. Stop the stream by sending:

{
  "command":"ledcolors",
  "subcommand":"ledstream-stop"
}

HTTP/S

This feature is not available for HTTP/S JSON-RPC

# Control Hyperion

Control the Hyperion system as a whole with the following subcommands;

subcommand Description
suspend Suspend all components and instances
resume Resume from suspend
toggleSuspend Toggle between suspend and resume
idle Suspend, but keep LED on and run a background effect, if configured
toggleIdle Toggle between idle and resume
restart Restart Hyperion
// Command to suspend Hyperion
{
  "command" : "system",
  "subcommand" : "suspend"
}
// Command to resume Hyperion from suspend
{
  "command" : "system",
  "subcommand" : "resume"
}
// Command to toggle between suspend and resume
{
  "command" : "system",
  "subcommand" : "toggleSuspend"
}
Last Updated: 3/13/2024, 8:51:42 PM