Why a Technical Director Writes Code

A computer has never once done what you meant. It has only ever done what you wrote. Everything in this course is about closing the gap between those two things before an audience is in the room.

Logic gym#

Fifteen minutes, no keyboards, in pairs. This is not a warm-up and it is not a quiz. It is the part of the class that trains the thing the rest of it depends on, and it comes back in every class after this one.

The rule: you say the answer before you check it. Out loud, to the person next to you, in a full sentence. A guess you committed to and got wrong teaches you something. A guess you kept vague so it could be retrospectively right teaches you nothing, and that habit is the actual enemy here.

1. Say what it does, in one sentence#

levels = [0, 0, 0, 0]
for i in range(4):
    levels[i] = i * 25

Not "it loops four times". What is in levels at the end, and what is the general rule. Then: what would you have to change for the last one to be 100 rather than 75, and how many different correct answers are there to that?

2. Find the state#

An operator presses GO. The cue runs. They press GO again halfway through.

Before you decide what should happen, list every piece of information the machine must be holding for that question to even be answerable. There are at least four. Most people get two.

3. The off by one, before you meet it in code#

Fixtures are patched from address 1, eight channels each. What is the address of the tenth fixture? What is its last channel? How many fit in a universe?

Say all three numbers before anybody opens a calculator. Then check. The interesting part is not whether you were right, it is whether the way you got there would still work for a sixteen channel fixture starting at 101.

4. Name the assumption#

"The script renames every photo in the folder to the show name and a number."

Name three things that sentence assumes and does not say. Then name the one that will actually bite, and say why you picked that one.

5. Break it in four ways#

Take any tool you have used this term: QLab, a desk, a spreadsheet. In ninety seconds, name four inputs that would make it behave badly. Then sort them: which are its fault, and which are yours.

That sort is the whole of the fourth question, and it is the sort a technical director does in a production meeting rather than at a keyboard.

What the gym is for#

Every one of these is the same move: hold the state in your head, run it forward, and commit to an answer. That is what reading code is. It is also what reading a cue sheet, a schematic, a risk assessment and a contract is, which is why this course claims to be about more than programming without embarrassment.

The argument#

You are training to be a technical director. Within a few years you will not mostly be writing code. You will be reading it, buying it, judging it, and standing next to it while it either works in front of an audience or does not.

That is a stronger reason to learn programming than becoming a programmer would be.

Consider what is now normal on a mid-scale show. The lighting rig is driven by a console running an operating system. The video wall is fed by a media server whose whole job is executing a program you did not write. The automation is a PLC, which is a computer with a safety rating. The sound is a network of computers that agree on a clock. Somewhere there is a Raspberry Pi in a case, doing something small and essential, and nobody in the building knows exactly what.

Every one of those is a program. When one of them behaves in a way nobody expected, the room turns to the technical director. The useful answer is never "it's a computer thing." The useful answer is "it is doing exactly what it was told, and here is what it was told."

What you will actually use this for#

Not writing an application. Six things, in rough order of how often they come up:

• Automating the repetitive. The rename, the report, the address check, the conversion between two pieces of software that do not talk to each other. Half a day of work, once, replacing a day a week, forever.
• Reading somebody else's. A contractor's cue script, a supplier's control code, the Arduino sketch that came with the prop. Judging it before it is in your show.
• Specifying. Writing a scope of work that a programmer can price and deliver against, because you know which parts are cheap and which are expensive.
• Prototyping. Proving an effect is possible in a week, with a Pi and forty lines, before anybody commits a budget to it.
• Diagnosing. Knowing that a program cannot do anything mysterious, and being the person who narrows the question rather than the person who reboots.
• Directing AI. Which is now most of the writing, and none of the responsibility. More on that at the end of this class, and all of Class 4.

What a computer actually does#

Strip away everything and one machine is doing one thing, extremely fast, forever:

Fetch a number. Do arithmetic on it. Put it somewhere. Decide what to fetch next.

That is it. There is no other operation. Everything else in this course, every list, every cue stack, every frame of video, every fixture that changes colour, is that loop with enough layers on top of it that a human can express what they want in something other than numbers.

The layers matter, because they are where you live and where the faults hide.

Every layer is a promise made by the layer below. A bug is a place where a promise was made carelessly, or where you believed a promise that was never made.

Nobody works at every layer. But when the media server drops a frame, the question "which layer is this?" is the difference between an hour and a week.

The literal machine#

Here is the sentence that costs shows money:

The computer does not know what you meant.

Not "it sometimes gets confused". Not "it needs clear instructions". It has no capacity whatever to mean anything. It will execute a description of a thing that is not what you wanted, perfectly, forever, at full brightness, in front of nine hundred people.

Take a normal production sentence:

"When the door opens, bring the corridor light up, then start the music."

A human stage manager hears that and runs it correctly on the first performance. There is nothing ambiguous about it to a person. Now count the decisions a computer must be given, none of which are in that sentence:

• What counts as "opens"? The sensor changing state, or staying changed for 200 ms, or reaching a position?
• How fast is "up"? To what level? Following which curve?
• Does "then" mean after the fade finishes, or after it starts?
• What if the door opens again while the fade is running?
• What if the door never opens, because the sensor cable was pinched during the get-in?
• What if the music is already playing?

Six questions. A person answers them from context without noticing. A program answers them the way somebody wrote them down, including the ones nobody wrote down, which get answered by accident.

Most show software failures are not bugs in the ordinary sense. They are the accidental answers to questions nobody realised were being asked. That is why this course spends more time on reading than on writing.

The four questions you ask any program#

You need one method that works on code you have never seen, in a language you do not know, at 23:40 during a technical rehearsal. This is it, and it is used in every remaining class of this course.

1. What state does it hold? What does it remember between one moment and the next, and where does that memory live? A program with no state is a calculator. Everything interesting, and everything that fails oddly, has state.

2. What happens on each pass? What does it do, in order, when it runs once? If it loops, what does one turn of the loop do, and how often does the loop turn?

3. What does it assume? What must already be true for it to work? A file that exists, a device at an address, a value between 0 and 255, a network that is up, a frame rate that does not change. Assumptions are almost never written down and they are where the show breaks.

4. What happens when it is wrong? Does it stop, hang, hold its last value, or carry on with nonsense? This is the professional question. Anybody can read what code does when it works.

Two of the other courses I teach ask a version of these. Show Networking and Control Systems asks five questions of any protocol, and its fifth is "what happens when it does not arrive", which is our fourth question aimed at a wire instead of at a program. You do not need that course to follow this one. The echo is there because it is one habit of mind, and meeting it twice from two positions is what makes it stick.

Applied to eleven lines#

import time

level = 0
while True:
    if door_is_open():
        level = level + 5
        if level > 255:
            level = 255
        set_light(level)
    time.sleep(0.02)

State: one variable, level, held in memory only. Power cycle and it is 0 again, whatever the light is actually doing.

Each pass: check the door; if open, add 5 to the level, clamp it, send it. Then wait 20 ms. So the loop turns fifty times a second and the light takes about a second to reach full.

Assumes: door_is_open() answers immediately and truthfully. set_light() reaches the fixture. The loop actually gets 20 ms of attention, which on a general-purpose computer nobody promised.

When wrong: the light never comes back down. There is no path in this program that lowers level. If the door opens during a scene change, the corridor stays lit for the rest of the act and the only cure is a restart. This is not a hypothetical failure mode. It is the most common one in show code written by a competent person in a hurry.

A cue as a state machine#

Most of the show code you meet is a state machine, whether or not the person who wrote it knew the term. There is a small set of states the system can be in, a small set of events that move it between them, and a rule for each.

The value of drawing it is not neatness. It is that a diagram of states and transitions makes the missing transitions visible, and the missing transition is the fault. What happens if the go button is pressed while the fade is already running? If there is no line on your diagram for it, there is no line in the code either, and the machine will do whatever falls out.

Three questions to ask of any state machine, including the ones inside consoles you did not write:

1. What state is it in at power-up, before anybody has done anything?
2. Which transitions are missing, and what does the system do when one of those events arrives?
3. Is there any state it can enter that it cannot leave without a restart?

The third one has a name in this industry. Everybody has met it, usually at the worst moment.

Build it before you type it#

Do this one now, before you read on. Three events arrive: GO at zero seconds, STOP at four, GO again at six. Make the cyc go somewhere sensible on each. The third one is where people come unstuck, because a program that only knows how to start from zero snaps to black before it fades up, and the audience sees the snap.

There is no syntax in that workspace, and there is no simplification either. The panel on the right is your program written out as Python, as JavaScript and as a cue sheet, generated from the same tree that just ran. They are four notations for one thing, and the only difference is who is expected to read it.

Then make it remember something:

Three GOs, and the third one has to be different. Nothing outside the program tells it which GO this is, so it has to hold a number between events. That number is the whole difference between a script and a machine, and it is why the four questions start with "what does it hold".

Then write the same machine as code:

Six cases. Five of them are the table you were just given. The sixth is an event nobody planned for, and what your program does with that is the difference between a machine and a hope.

What it costs to automate, honestly#

There is a real decision here, and "write a script" is not always the right side of it.

A task that takes you 10 minutes, done once, costs 10 minutes. Writing a program to do it costs perhaps two hours the first time you have ever written one, then it costs almost nothing per run, plus a maintenance cost every time the input changes shape.

So the arithmetic is:

Automate when (times you will do it × how long it takes) is comfortably more than (time to write it + time to maintain it), or when doing it by hand is dangerous.

That second clause carries more weight than the first. Checking two hundred DMX addresses by eye is not slow, it is unreliable, and a program that checks them is right every time in a way a tired person at 01:00 is not. Automate the error-prone before the merely tedious.

And be honest about the failure mode of automation. A person who mistypes one address gets one fixture wrong. A script with a wrong assumption gets all two hundred wrong, instantly, and with total confidence. Scale cuts both ways, which is why nothing in this course is complete until it has been proved on something you can afford to lose.

Do the arithmetic rather than the enthusiasm#

Three cases, and the second one is the one worth sitting with: the same task, twice a show, two shows, and the script loses by four hours. Most of the tools you will want to write are that case. Knowing which are and which are not is the difference between a technical director who ships and one with a folder of half-finished utilities.

The same question at product scale, with money in it, is the systems page, and it is the decision you will actually be paid to make.

How a program fails, and which failure you want#

When something goes wrong, a program has four broad options. Whoever wrote it chose one, on purpose or by accident.

Consider the same failure across three departments. A fixture that loses DMX holds its last look, because a blackout mid-scene is worse than a stale one. An amplifier that loses its clock mutes, because a burst of noise through a big PA is worse than silence. A hoist that loses its control signal stops and holds, because a moving load with no supervision is the worst thing in this list.

None of these is the default. Each was specified by somebody who thought about that department's worst case. When you write show code, you are the person doing that thinking, and the default that happens if you do not is "carry on regardless."

Where AI sits in this#

You can now describe what you want in English and get working code back in seconds. That is real, it is not going away, and pretending otherwise would waste your time.

What it changes: the cost of the first draft, which used to be the barrier. Things not worth two hours are now worth four minutes, so the break-even line above moves a long way in favour of automating. It also removes the excuse that you do not know the syntax. You do not need to.

What it does not change, at all:

• The code still executes literally. The machine has not become more forgiving.
• The four questions still have to be asked, and now you are asking them about code you did not write and therefore do not already know the assumptions of.
• You are still responsible. "The AI wrote it" is not a sentence that can be said in an incident report. It will be your name on the risk assessment.
• It is confidently wrong, in a way a search engine never was. A search result that does not exist looks like nothing. A generated function that does not exist looks exactly like one that does.

The rule for this course, and the one thing to take from today if you take nothing else:

Never run code you cannot answer the four questions about. Not "code you wrote". Code you understand. Where it came from is not the point.

Class 4 is entirely about this: how these models actually work, what that predicts about where they fail, and the verification loop that turns a fast draft into something you would put in front of an audience.

Where this course is going#

Six classes, and the shape is deliberate. You are not being trained to be a programmer, because the industry has those and they are better at it than you will be. You are being trained to be the person who can decide what gets built, read what came back, and say what it does when it fails — and the only way to reach that is to have written enough to know what you are reading.

Three reference pages carry the parts of this that do not fit in twenty four hours: boards for what Arduino, ESP32 and Pi actually do on a stage; systems for the products you will meet and when to write your own; and the model box, which is a whole show system at 1:25 for the price of one seat, and the best place to break all of this where it costs an afternoon.

The spine of this course#

Everything from here hangs off one sentence:

Code is a description of what should happen, executed literally, on a deadline you do not control. AI changes who writes the first draft and nothing about who is responsible for it.

By Class 6 you should be able to defend every clause of that with something you built.

Numbers from this class#

Self test with model answers

Answer it yourself first, out loud or on paper, then open the answer. Reading the answer without attempting the question teaches you almost nothing.

1. 1A colleague says the media server "glitched" during the show. Why is that not an explanation, and what are the three things it could actually be?
2. 2Apply the four questions to a program that fades a light up while a door sensor reads open, and say what is missing.
3. 3You do a task in 10 minutes, forty times a season. Should you automate it? Show the reasoning, not just the answer.
4. 4Name the four ways a program can fail and say which one a lighting fixture chooses, which one an amplifier chooses, and why they differ.
5. 5Why does the arrival of AI coding tools make reading code more important rather than less?

Note. These are model answers, not the only correct ones. If yours differs and you can defend it with the arithmetic and a measurement, that is worth more than matching the wording.