TouchDesigner | Delay Scripts

It’s hard to appreciate some of the stranger complexities of working in a programming environment until you stumble on something good and strange. Strange how Matt? What a lovely question, and I’m so glad that you asked!

Time is a strange animal – our relationship to it is often changed by how we perceive the future or the past, and our experience of the now is often clouded by what we’re expecting to need to do soon or reflections of what we did some time ago. Those same ideas find their way into how we program machines, or expect operations to happen – I need some-something to happen at some time in the future. Well, that’s simple enough on the face of it, but how do we think about that when we’re programming?

Typically we start to consider this through operations that involve some form of delay. I might issue the command for an operation now, but I want the environment to wait some fixed period of time before executing those instructions. In Python we have a lovely option for using the time module to perform an operation called sleep – this seems like a lovely choice, but in fact you’ll be oh so sorry if you try this approach:

	import time

	# it may be tempting to do this, but
	# this is not the correct way to delay
	# an operation in Python inside of
	# TouchDesigner

	time.sleep(1)
	print("oh, hello there")

view raw

how-not-to-delay-in-TouchDesigner.py

hosted with ❤ by GitHub

But whyyyyyyyy?!

Well, Python is blocking inside of TouchDesigner. This means that all of the Python code needs to execute before you can proceed to the next frame. So what does that mean? Well, copy and paste the code above into a text DAT and run this script.

time.sleep

If you keep an eye on the timeline at the bottom of the screen, you should see it pause for 1 second while the time.sleep() operation happens, then we print “oh, hello there” to the text port and we start back up again. In practice this will seem like Touch has frozen, and you’ll soon be cursing yourself for thinking that such a thing would be so easy.

So, if that doesn’t work… what does? Is there any way to delay operations in Python? What do we do?!

Well, as luck would have it there’s a lovely method called run() in the td module. That’s lovely and all, but it’s a little strange to understand how to use this method. There’s lots of interesting nuance to this method, but for now let’s just get a handle on how to use it – both from a simple standpoint, and with more complex configurations.

To get started let’s examine the same idea that we saw above. Instead of using time.sleep() we can instead use run() with an argument called delayFrames. The same operation that we looked at above, but run in a non-blocking way would look like this:

	# delay scripts example

	# first we write out script as a string
	delay_print = "print('hello world')"

	# next we run this string, and specify
	# how many frames we want to wait before
	# we run this operation.
	run(delay_print, delayFrames = 60 )

view raw

delay-script-ex1.py

hosted with ❤ by GitHub

If you try copying and pasting the code above into a text DAT you should have much better results – or at least results where TouchDesigner doesn’t stop running while it waits for the Python bits to finish.

Okay… so that sure is swell and all, so what’s so complicated? Well, let’s suppose you want to pass some arguments into that script – in fact we’ll see in a moment that we sometimes have to pass arguments into that script. First things first – how does that work?

	# delay scripts example

	# first we write out script as a string
	delay_print = '''print(
	'{noun} sure does {verb} {adj}'.format( noun=args[0],
	verb=args[1],
	adj=args[2]))'''

	noun = "Matthew"
	verb = "love"
	adj = "TouchDesigner"

	# next we run this string.
	# this time we'll pass in arguments for our script.
	# args are accessed as a list called args. Arguments
	# go in order in the run command, and you can see in
	# how the script is formatted how we access them.

	run(delay_print, noun, verb, adj, delayFrames = 60 )

view raw

delay-script-args-v1.py

hosted with ❤ by GitHub

Notice how when we wrote our string we used args[some_index_value] to indicate how to use an argument. That’s great, right? I know… but why do we need that exactly? Well, as it turns out there are some interesting things to consider about running scripts. Let’s think about a situation where we have a constant CHOP whose parameter value0 we want to change each time in a for loop. How do we do that? We need to pass a new value into our script each time it runs. Let’s try something like:

	# delay scripts example

	# first we write out script as a string
	delay_script = "constant_op.par.value0 = args[0]"
	constant_op = op('constant1')

	# next we run our script
	for each_time in range(10):
	run(delay_script, (each_time+1), delayFrames = 60 * (each_time + 1))

view raw

args-and-delay.py

hosted with ❤ by GitHub

What you should see is that your constant CHOP increments every second:

for-loop-delay

But that’s just the tip of the iceberg. We can run strings, whole DATs, even the contents of a table cell.

This approach isn’t great for everything… in fact, I’m always hesitant to use delay scripts too heavily – but sometimes they’re just what you need, and for that very reason they’re worth understanding.

If you’ve gotten this far and are wondering why on earth this is worth writing about – check out this post on the forum: Replicator set custom parms error. It’s a pretty solid example of how and why it’s worth having a better understanding of how delay scripts work, and how you can make them better work for you.

Happy Programming.

Like this: