Importing GDTF Files

GDTF (General Device Type Format) is an open standard for describing intelligent lighting fixtures. Importing a GDTF file creates an Art-Net Fixture asset in the Asset Manager. WATCHOUT reads the fixture's channel layout, parameter names, and mode definitions, instead of relying on a built-in generic preset.

Fixture manufacturers publish GDTF files. They are also available from the GDTF Share repository. Import a manufacturer GDTF file when a fixture has more than one mode, named parameters (pan, tilt, color wheel, gobo, dimmer), or high-resolution channels that must be mapped correctly.

What GDTF Contains

A .gdtf file is a ZIP archive. It describes one fixture type with one or more DMX modes. Each mode describes:

DataPurpose
Mode nameThe operating mode name matching the fixture's menu (for example "Extended 32ch" or "Basic 8ch").
Channel listOrdered DMX channels with parameter names and resolution. Channels can be 8-bit (Coarse), 16-bit (Fine), 24-bit (Ultra), or 32-bit (Uber).
Default and highlight valuesPer-channel idle (default) and highlight values.
Channel relationsLinks where one channel scales or overrides another, used for dimmer-intensity relationships.

WATCHOUT reads this information during import and maps it to its internal fixture definition.

Importing a GDTF File

Import a GDTF file by adding it as an asset:

  1. Open the Assets window.
  2. Drag a .gdtf file into the asset list. The Asset Manager parses it and creates an Art-Net Fixture asset.
  3. The fixture asset appears in the Assets window as an Art-Net Fixture.

You can also right-click and choose New → Add Media File, then select the .gdtf file.

Drag the fixture asset onto the timeline to create an Art-Net Fixture cue. Then select the DMX mode that matches the fixture's physical configuration.

Download GDTF files from the fixture manufacturer or from gdtf-share.com. Files from the GDTF Share repository are checked against physical fixtures. This reduces addressing errors.

Generic Presets vs. GDTF

WATCHOUT ships with two generic fixture presets: 1ch Generic and 10 ch Generic. Add one from the Assets window: right-click, choose New, then New Art-Net Fixture, then pick a preset. Each generic preset offers Coarse (8-bit), Fine (16-bit), Ultra (24-bit), and Uber (32-bit) modes with unnamed channels.

Use a generic preset when a GDTF file is not available or a simple channel layout is enough. Use a GDTF file when:

SituationRecommendation
Manufacturer publishes a GDTF fileUse the GDTF file. It provides accurate channel names and modes.
Fixture has named parameters (pan, tilt, color)Use GDTF. Channel names appear in the cue's tween editor.
Fixture has high-resolution (Fine) channelsUse GDTF. The coarse/fine channel pairing is defined precisely.
Simple dimmer or relay with one channelThe 1ch Generic preset is enough.
Prototyping before the fixture is decidedUse a generic preset. Replace it with GDTF when the fixture is confirmed.

Selecting the Correct DMX Mode

Most intelligent fixtures offer several operating modes that differ in channel count and function. Select the mode that matches the physical fixture:

  1. Place the fixture asset on the timeline to create a cue.
  2. Open the Properties panel for the cue.
  3. In the Fixture section, open the Mode dropdown.
  4. Select the mode name that matches the fixture's menu setting (for example "Standard 16ch").

Selecting the wrong mode maps channels to the wrong parameters. The pan channel might drive the color wheel, or channels might be skipped. Confirm the fixture's mode from its on-board display or the manufacturer's channel chart.

Changing the mode replaces the cue's tween data with the new mode's channels. Existing tween keyframes are lost. Set the mode before adding tween keyframes.

Viewing the Fixture and Its Modes

Inspect the imported modes from a cue that uses the fixture:

  • The Mode dropdown in the cue's Fixture section lists every imported mode by name.
  • The cue's tween editor lists each channel by parameter name. High-resolution channels show a Coarse, Fine, Ultra, or Uber label.
  • For channels with named value ranges, the tween editor shows the function for the current value. A shutter channel, for example, reads "closed" near 0 and "open" near 255. This makes the effect of a level visible as you set it.

WATCHOUT does not provide an editor for imported fixture definitions. To change a definition, edit the .gdtf source file and re-import it.

Updating a Fixture Definition

If the manufacturer releases an updated GDTF file, or you need to correct a definition:

  1. Remove all fixture cues that reference the old asset, or note their addressing.
  2. Delete the old fixture asset from the Assets window.
  3. Import the new .gdtf file.
  4. Recreate the fixture cues referencing the new asset.

WATCHOUT does not update an existing fixture asset in place from a new GDTF file. Delete and re-import.

Best Practices

  • Match the GDTF revision to the firmware. Manufacturers update GDTF files when firmware changes the channel layout. Confirm the file matches the firmware on the physical unit.
  • Verify channel count against the fixture's patch. After selecting a mode, compare the channel count to the fixture's data sheet. A mismatch usually means the wrong mode is selected.
  • Name fixture cues after the physical device. Use the cue's Name field to record the fixture label (for example "FOH Spot 1"). This makes large shows navigable.
  • Keep source GDTF files. Store the original .gdtf files with your show archive. Re-import the exact definition from them after a system migration.
  • Art-Net Fixture Cues — placing fixture assets on the timeline, addressing, and tween automation.
  • Asset Types — how Art-Net Fixture assets fit the asset classification.
  • Art-Net Input — receiving DMX data from external lighting consoles.
  • Asset Manager Issues — troubleshooting optimization, transfer, and asset problems.
Previous Next