<aside> 🐡 This describes the showfile format for having ONE controller in a file. The changes are mostly additive if you have more than one controller per file, but they are described in a different document. Only having one controller per file is supported on the Cinema/TV branch, and should not be used on the Architectural Lighting branch.
</aside>
The meta section contains a few things that are required and/or boilerplate:
version
This key should always be set to 1. This defines the format of this file, if new formats come along that are incompatible with this format, we will assign them different numbers.
parent_uuid
This key defines which system the showfile is for. The easiest place to find this is in the URL for the systems page:
The text after id= is the uuid of the system.
The controllers section contains an array of controller documents, each defining one controller. In cinema/tv mode, we only support a single controller, so it should generally look like this:
"controllers": [{
"controller_id": 1,
"label": "Ben's Desk",
"controller_mac": "BC:DD:C2:C9:00:3F",
"type": 10
}],
controller_id
This key defines the ID number of this controller. It is an arbitrary number, but required.
label
This is the text label for the controller. It will overwrite the label on the website when uploaded, but is not used anywhere else.
controller_mac
This is the string that defines which controller we are uploading for. This must be in this format with capital letters and : between octets. Using any other format will not work.
type
This defines which type of controller we're talking to. If it's a Miranda DMX or CineMiranda, this should be 10.
A very small showfile might look like this:
{
"meta": {
"version": 1,
"parent_uuid": "b0d0084b-449f-412a-bf50-e41243e1f14f"
},
"controllers": [{
"controller_id": 1,
"label": "Ben's Desk",
"controller_mac": "BC:DD:C2:C9:00:3F",
"type": 10
}],
"palette": [],
"patch": [{
"controller": 1,
"channel_map": [1, 2, 3, 4],
"start_address": 1,
"fixture_type": 1,
"num_channels": 4,
"fixture_id": 1,
"label": "RGBI Fixture"
}
],
"stack": {
"version": 1,
"cuestacks": [{
"cuestack_id": 1,
"cuesteps": [{
"fixtures": [{
"color": {
"intensity": 26241,
"red": 37196,
"green": 65535,
"blue": 0
},
"fade": 1000,
"fixture_id": 1
}],
"wait": 1000
}],
"label": "Yellow Look",
"loop": false
}]
}
}
This is an empty array for future use.
The patch is an array of fixture definition documents. In this simple case, we only have a single fixture. Each controller supports up to 300 fixtures.
The fixture document defines a single fixture, including profile.
controller
This key defines which controller the fixture is on. It should match the controller_id the controller definition used. Any fixtures whose controller id doesn't match the current controller will be ignored.
start_address
This defines the DMX start address for this fixture. 1-512 are on the first universe, 513-1024 are on the second.
<aside> 🐡 It is possible to define a fixture that spans multiple universes, Miranda will happily split this across the outputs, but is probably not what you want to do.
</aside>
fixture_type
This has no particular use, but must be defined. In sACN input node mode, this is used to define remote fixture_id.
num_channels
This defines how many DMX slots this fixture occupies. It should be the same number as the number of elements in the channel_map array.
fixture_id
This is a number that identifies this fixture on the controller. It can be any number 1-65535, but must be unique (per controller). That is, you cannot have two fixture_id 2.
label
This is an ASCII text label. The full label is used on the website, only the first 20 characters are stored on the controller.
channel_map
This defines the mapping between the fixtures DMX slots and its attributes. It also, indirectly, defines which attributes are supported on the fixture.
{
"controller": 1,
"start_address": 1,
"fixture_type": 1,
"num_channels": 4,
"fixture_id": 1,
"label": "RGBI Fixture",
"channel_map": [1, 2, 3, 4],
}
Values which are "Yes" supported are 16-bit, so from 0-65535. Values that are 8-bit only are 0-255.
The JSON name is relevant to the cuestack format, defined next.
The stack section contains definitions for the cues. Miranda's showfile format defines a series of cues that each consist of one or more cuesteps which consist of one or more cuefixes. A cuefix defines a single fixture's move in this step.
A cue can be looping or not. A looping cue will loop forever. It is possible to think of a Miranda cue as an effect rather than a cue, but either view is valid.
<aside> ⚠️ Miranda is strongly tracking by attribute.
</aside>
We're going to walk through the stack format by starting with a single cuefix:
This document has three top level keys:
fixture_id
This defines which fixture this cuefix affects.
fade
This optional key defines how many milliseconds to fade this fixture in. If it is not specified, it will use the cuestep's wait time.
color
This key's document specifies which attributes are in this cuefix. The names of the keys map to the channel_map values through the able above.
Any attributes not included are left-as-is. That is, if you omit red, the fixture's existing red channel is unaffected. See note above about being strongly tracking.
If you include attributes that the fixture does not have, nothing bad happens, it just doesn't affect anything.
<aside>
🐡 intensity is required to be defined somewhere. That is, even if a fixture doesn't have an actual intensity attribute, you need to bring the intensity up to 65535 to output the other attributes. This only applies to the attributes Red, Green, Blue and White, but if you have patched and RGB fixture and cannot see it, make sure you have set intensity to full somewhere.
</aside>
{
"color": {
"intensity": 26241,
"red": 37196,
"green": 65535,
"blue": 0
},
"fade": 1000,
"fixture_id": 1
}
Stepping back to the cuestep:
This particular cue only has a single cuestep (with a single fixture).
cuesteps only have two keys in them.
fixtures
This is an array of cuefixes, described above.
wait
This is the time in milliseconds to wait before executing the next cuestep.
{
"fixtures": [{
"color": {
"intensity": 26241,
"red": 37196,
"green": 65535,
"blue": 0
},
"fade": 1000,
"fixture_id": 1
}],
"wait": 1000
}