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, giving WATCHOUT accurate channel layout, parameter names, and mode definitions for that fixture instead of relying on the built-in generic presets.

GDTF files are published by fixture manufacturers and are available from the GDTF Share repository. Importing a manufacturer-provided GDTF file is the recommended approach whenever a fixture has more than one mode, named parameters (pan, tilt, color wheel, gobo, dimmer, etc.), or 16-bit channels that must be mapped correctly.

What GDTF Contains

A .gdtf file is a ZIP archive containing fixture geometry, wheel definitions, and one or more DMX modes, each describing:

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

Importing a GDTF File

1. Open the Assets window.
2. Right-click in the asset list and choose Add ArtNet Fixture... from the context menu.
3. In the fixture picker dialog, click Import from file... (or drag a .gdtf file directly into the Assets window).
4. Browse to your .gdtf file and click Open.
5. If the file contains multiple fixture variants (revisions), WATCHOUT imports the most recent revision automatically.
6. The new fixture asset appears in the Assets window under the Art-Net Fixture type.

Once imported, the fixture asset behaves identically to a built-in preset — you can drag it onto the timeline to create an ArtNet fixture cue, then select the DMX mode that matches the fixture's physical configuration.

Selecting the Correct DMX Mode

Most intelligent fixtures offer multiple operating modes that differ in channel count and functionality. You must select the mode that matches the mode configured on the physical fixture:

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

Selecting the wrong mode causes channels to map to incorrect parameters — for example, the pan channel may drive the color wheel, or some channels may be skipped entirely. Always confirm the fixture's mode from its on-board display or from the fixture manufacturer's channel chart.

GDTF vs. Built-in Generic Presets

WATCHOUT ships with two generic fixture presets (1ch and 10ch). Use these when a GDTF file is not available or when a simple, unnamed channel layout is sufficient. Use a GDTF file when:

Viewing Imported Channel Definitions

After importing a GDTF file, you can inspect the imported channel layout in the Properties panel of the fixture asset itself (not a cue — the asset entry in the Assets window):

• Name / Long Name / Short Name — the fixture identity as published in the GDTF file.
• Modes — the full list of imported modes, each showing its channel count.
• Selecting a mode in the asset's properties shows its channel list: parameter name, resolution (Coarse/Fine/etc.), default value, and highlight value.

This view is read-only for imported GDTF fixtures. To modify a fixture definition, edit the .gdtf source file and re-import.

Updating a Fixture Definition

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

1. Remove all fixture cues on the timeline that reference the old asset (or note their addressing for reference).
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.

Best Practices

• Match the GDTF revision to the firmware version. Fixture manufacturers sometimes update GDTF files when firmware changes the channel layout. Confirm that the GDTF revision matches the firmware installed on the physical unit.
• Verify channel count against the fixture's patch. After selecting a mode, count the channels in the Properties panel and compare 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 (not the asset name) to record the physical fixture's label (e.g., "FOH Spot 1" or "Wash SL"). This makes large shows navigable and simplifies troubleshooting.
• Keep source GDTF files. Store the original .gdtf files with your show archive. If you need to re-import after a system migration, having the exact source file avoids version ambiguity.

Troubleshooting

See Also

• ArtNet Fixture Cues — placing fixture assets on the timeline, addressing, tween automation, and recording
• Asset Types — how Art-Net Fixture assets fit into the broader asset classification
• ArtNet Input — receiving DMX data from external lighting consoles