Sessions and roles
A session is one host and the partners who joined it. The host decides who gets in, what each partner may do, and whose copy everyone takes when copies differ. Everyone else works the same way: each in their own TouchDesigner, on their own copy of the Collab Zone.
Who hosts
- On one network (TCP/IP), the side that listens (Mode server) is the host; partners connect to its address and port.
- In a relay room, the room's opener, the first one in, is the host whenever it is there. While it is away, the partner who has been in the room longest stands in; when the opener comes back, it is the host again.
The host's settings (New Partners May, Ask Before Letting In, Classroom, Partners May Summon, Partners May Save, Partners May Edit Keep Local, and the first three Per-Frame Checks) count for everyone in the session. A partner sees them greyed out.
Ways to connect
- A room on the TDXCollab relay (the default in Set Up): every TouchDesigner connects out to
the hosted relay, so nobody opens a port. A room has a code you can say (
copper-otter-417) and a 24-character random secret; New Room makes both and copies the invite to your clipboard. The invite is one line,tdxcollab://<room>/<secret>: paste it into Join Invite (or Set Up) on the other side. Every message is encrypted end to end with keys made from the secret, so the relay passes it on but cannot read it. A room takes up to 8 people, 32 in a classroom. A secret shorter than 12 characters is refused: a partner's messages can run Python on your machine. - A relay of your own: the same, through a relay you run. The invite carries its address.
- On this network (TCP/IP): a port (7001 by default) and the host's address. Nothing in between, but nothing encrypted either: use it on a network you trust or over a VPN.
Anyone with a room's invite can join it and read its messages. Send invites privately, and press New Room for a fresh room when one has been passed around.
Roles
| Role | What they may do |
|---|---|
| Full Edit | Everything: operators, wires, parameters, expressions, binds, DAT text, whole zones |
| Adjust Parameters | Constant parameter values, pulses and the timeline |
| Observe | Nothing but being there: their pointer, network and selection. They see every change |
- New Partners May (on the host) is the role a partner gets unless the host gives them another. To change someone's role, right-click the menu bar chip ("Dan may: Full Edit…"), or click their role in the TDXCollab window.
- A partner sees their own role in Status. What their role does not reach is not sent, and is refused on every side if it arrives anyway.
- Nothing is blocked on the partner's side. What they change outside their role stays on their side, and a note in the corner of their network editor says so as they do it ("Only on your side: new operators, moves"). Their copy then differs from the host's; Resolve Drift, or the chip's "Take the host's copy, here only…", puts the host's back in their zone.
- Someone who reconnects in the same session keeps their role.
Full Edit can put Python into the shared network, and it runs on every computer in the session. Give it only to people you trust.
Letting people in
With Ask Before Letting In on (the default), whoever connects waits at the door until the host answers. A window lists everyone waiting, with their name and versions: choose the role to let each one in with, or Turn Away. With several waiting, each row has its own buttons and Let Everyone In answers them all.
- While waiting they get nothing and nothing of theirs is taken. Their Status says "Waiting for the host ... to let you in". Turned away, they are refused; switching Active off and on knocks again.
- A closed window opens again from the chip's right-click ("Let Dan in?…"), and the host's Status names who waits.
- Someone let in who reconnects in the same session is back without asking, in the same role.
- Switching Ask Before Letting In off lets everyone waiting in, with New Partners May.
- An Unattended Host asks nobody: member tokens decide.
The menu bar chip
TDXCollab puts a chip in TouchDesigner's main menu bar, showing its Status in colour:
| Colour | Meaning |
|---|---|
| grey | off |
| amber | connecting |
| blue | connected, nobody else here yet |
| green | with partners |
| orange | your copies differ |
| red | refused, or a setting is missing: hover it for the reason |
- Left click: the TDXCollab window (below).
- Right click: its actions: Active, Ask on Drift, Sync Zone, Resolve Drift, while copies differ each copy everyone could take, Restore Replaced Zone, Ping Here, Summon Everyone Here, Jump to the Collab Zone, Set Up, Report a Problem.
- Middle click: jump to the Collab Zone.
- Drop a parameter or an operator on it: the Keep Local menu.
- The tooltip has the whole Status. FNSTools' main menu configurator moves or hides the chip like any other item.
The TDXCollab window
Left-click the chip, or open Set Up during a session. From the top:
- Status, with an Active switch.
- People: everyone in the session with their role (on the host, a click on a role changes it) and Go To, which takes your network editor to where they are. Below them, anyone waiting to be let in.
- The Collab Zone: Jump, Sync Zone, and Resolve Drift and Restore when they apply; a name field and Snapshot; then the kept zones, newest first, each with Restore, Rename and Delete.
- Show: chips for what you see of your partners (Synced Panes, cursor, selection, view, activity), and Ping Here and Summon Everyone Here.
- Keep Local: the rules for what each side keeps for itself, each with a rule button.
- The footer: Parameters (TDXCollab's parameter dialog), Open Table, Set Up… and Close.
Drop a COMP on the window to make it the Collab Zone: at once when you are alone, otherwise after a question, Just for Me or For Everyone (everyone's zone becomes a copy of it, as Sync Zone does). Drop a parameter or an operator for the Keep Local menu. Every button says what it does when you hover over it.
Versions
Everyone in a session needs the same TDXCollab protocol. A relay room takes its opener's and refuses another; over TCP/IP the host refuses a partner on another one. Status then says "Refused by ...". A partner on another TDXCollab version or TouchDesigner build is let in, but warned about in the status bar, and Show Partner Activity notes it on their row. Use the same release on every side.
Saving the host's project
A Full Edit partner may ask the host to save its project file in place when the host allows it (Partners May Save on the host, or always on an Unattended Host): Save Host Project on the parameters, the TDXCollab window or the chip's right-click. The host saves a moment later, once nothing is arriving, and answers with the file name or the reason it did not.
From the first partner edit until a save, every partner sees that the host has unsaved edits. A Full Edit partner is asked whether to save the host too when they save their own project, and when they leave from the TDXCollab window or the chip. The host never saves by itself: a save stops it, its output too, for as long as it takes.
The session log
Log Session (More page, off by default) writes the session to a file in logs/ beside
your project, one file per session and person: the operators each side created, deleted, renamed,
moved, wired or retyped, each parameter or DAT edit as one line once it stops (first and last
value, how many changes), Status as it changes, warnings and errors, each with the time and who
sent it to whom. Pointer and view moves are left out. Open Log Folder opens it.
Everyone writes their own side: read the files side by side to see a session from both ends. The log stays on your computer; it holds what you changed in the zone and your partners' names.
Leaving
Switch Active off: on the chip's right-click, in the TDXCollab window or on the parameters. Your partners' names, colours, cursors and highlights are cleared from your side when they leave, when you disconnect and before every save.