TouchDesigner Python API

Native Python interface for controlling Lightpath from inside TouchDesigner. The LightpathAPI.tox component (provided by Digital Ambiance) wraps the HTTP API and exposes everything two ways: as custom parameters you can wire in the editor, and as extension methods you can call from any DAT via op.LIGHTPATH_API.MethodName().

Setup

1. Load LightpathAPI.tox into your .toe. The component self-installs the LIGHTPATH_API global op shortcut, so you can reach it from anywhere as op.LIGHTPATH_API.

2. Configure the server. On the component's Server page, set:

   • Host — the Lightpath server hostname or IP. Leave as localhost if you're running on the same machine.
   • Port — defaults to 3001. Leave as-is unless your install overrides it.

3. Log in. Lightpath's content routes are auth-gated, so the component needs to hold a valid token before it can do anything:

   • Enter your Username and Password on the Server page.
   • Pulse Login. On success, the Status page's Logged In field shows yes (expires …).

4. Sync data. Pulse Sync Data to query the server for all looks, scenes, playlists, outputs, and actions, and populate the dropdown menus on every page. Now you can pick things by name from a dropdown instead of typing them.

   Sync Data auto-fires whenever Host or Port changes, so once you're configured you rarely need to pulse it manually.

That's it — you can now drive Lightpath either by pulsing the parameter buttons on the component, or by calling the extension methods from Python:

op.LIGHTPATH_API.ActivateLook("Sunset")
op.LIGHTPATH_API.FireAction("All Lights On")
op.LIGHTPATH_API.SetDimmer("Facade", 0.75)

Authentication

The component authenticates by calling POST /api/login with the username and password you set on its Server page, then attaches the returned JWT as Authorization: Bearer … on every subsequent request. The token is persisted via TouchDesigner's StorageManager so it survives a .toe save/load — you only need to log in again when the token's server-side TTL elapses (typically 7 days).

Login is the right credential for an interactive TD workflow where you, a person, are driving Lightpath through the network. If you're embedding TD in an unattended show-control rig and want a long-lived credential without storing a user password, mint an integration key in the Lightpath UI (Settings → Integration Keys) and call SetIntegrationKey("lpath_live_…") instead of Login(…). Either credential type is accepted on the same endpoints — the server auto-detects the lpath_ prefix.

Content activation

op.LIGHTPATH_API.ActivateLook("Sunset")
op.LIGHTPATH_API.ActivateScene("Evening")

Each look is bound to one output at design time, so ActivateLook doesn't take a target — the look already knows where it goes. Use scenes or playlists when you want one trigger to drive several outputs at once.

Playlist control

Per-output and global playlists share the same methods — pass output="Name" to control a specific output's playlist, omit it to control the global scene-rotation playlist.

# Per-output
op.LIGHTPATH_API.NextTrack("Output 1")
op.LIGHTPATH_API.SetTrack(2, output="Output 1")
op.LIGHTPATH_API.PausePlaylist(output="Output 1")

# Global
op.LIGHTPATH_API.PausePlaylist()
op.LIGHTPATH_API.SetTrack(2)

Actions

op.LIGHTPATH_API.FireAction("All Lights On")
op.LIGHTPATH_API.FireAction("Projector", targetState=True)
op.LIGHTPATH_API.SetActionState("Projector", True)

Output control

op.LIGHTPATH_API.SetDimmer("Output 1", 0.75)
op.LIGHTPATH_API.SetOutputEnabled("Output 1", False)

Global playback

status = op.LIGHTPATH_API.GetPlaybackStatus()
print(status)

State queries

looks = op.LIGHTPATH_API.GetLooks()
for look in looks.get("looks", []):
    print(look["name"])

Calendar

Calendar events drive scheduled content activation.