Documentation Wiki rss-feed

Workbench Tutorial 4

In this Tutorial we will introduce the concept of rigs to the setup created in Tutorial 3. The use of rigs can greatly reduce the apparent complexity of the setup by making a rich group of agents with many inter connections appear as a single agent on the main diagram.

In order to do this, rigs provide several important features. The first is that they create their own isolated space for names. For example, an Agent called 'scaler 1' inside one rig called is distinct from the Agent named 'scaler 1' in a different rig. If you had two such rigs, one called 'clarinet' and one called 'cello' you would then refer to these as 'clarinet scaler 1' and 'cello scaler 1' in addressing them via Belcanto. If you say 'cello listen' in Belcanto, all the Agents inside that rig will then join the conversation.

The second major feature that rigs provide is the rig gateway. This provides a configurable set of gateway ports that allow you to connect things from the inside to the outside and vice versa. You must use this gateway for connections, direct connections from and to the inside of rigs are not possible.

Each gateway port automatically adjusts its range and data type according to what it is connected to, so you do not have to worry about this. You can name these gateway ports with suitable names yourself and you can create inputs or outputs in either side of the rig gateway and you will find they automatically appear on the other side. So, for example, if you create an input port called 'frequency' on the outside of a rig, it will appear on the rig gateway Agent on the inside as an output port called 'frequency'.

The internal workings of the rig can be displayed and adjusted on an separate diagram. As a simple introduction to this concept we will convert one of the audio unit instruments created in the previous setup into a rig.

Open the setup saved at the end of Workbench Tutorial 3.


We are going to make a Rig Agent which contains a Scaler Agent and an Audio Unit Agent.

The first step is to create a Rig Agent. This agent is created in the same way as other agents by using the Create Tool and Selecting Rig from the list of available agents.


Expand Rig 1 by clicking on the triangle on the left hand side. It consists of two ports named input and output. These ports hold the lists of inputs to the rig and outputs from the rig. When the rig agent is created there are no inputs or outputs specified, but they can be created as required by clicking on the button marked '+' on the right hand side of the input and output port.

To do this, we need to know the inputs and outputs that the rig will require. Expand Scaler 2 and Audio Unit 2 so that they are as shown on the diagram above. You will see that Scaler 2 has 5 inputs connected; controller input, key input, pressure input, roll input and yaw input. It also has one output connected (not including the connections to Audio Unit 2, which will be internal to the Rig); light output. Audio Unit 2 has two outputs connected; left audio output and right audio output. All of the input connections to Audio Unit 2 come from Scaler 2 and so will be internal rig connections.

To create an input for the rig, click on the '+' button on the inputs port. A dialog will be displayed


The No. in this dialog refers to the name that will be given to the port. Normally you can accept the default value as you will probably be renaming the port in any case. Click OK.


Now if you expand the input port you will see a new port named '1'. Click on this port with the Edit Tool and change the name to the first of the inputs that our rig requires, 'controller'.


Using the same procedure, add the remaining 4 input ports required; 'key', 'pressure', 'roll', and 'yaw'. Then do the same thing for the output ports, creating outputs named; 'light', left audio' and 'right audio'.

When they are all done the rig should look like this


and it is possible to connect it up. Contract the Scaler 2 and Audio Unit 2 agents so that your setup looks like this.


Select the Wiring Tool and go to the input (green) pin on Scaler 2. Hold down the cmd key (ctrl on windows) and drag the wire away from the pin. Drag the wire to the top level of the Rig 1 agent and release the mouse. Connections should be made to your five rig inputs. With the wiring tool still selected, go to the output pin (red) of Audio Unit 2. Again, holding down the cmd key (ctrl on windows), drag the wire to the top level of Rig 1. Connections should be made to the left and right audio output ports on the rig and your setup should now look like this.


If you select Keygroup Output 2 and play the pico you won't hear anything, because we haven't yet added any internal agents or wiring to the rig. To add these agents and connections click the button labelled 'Open' on the right hand side of the top level of Rig 1. A new tab appears in Workbench with the name 'Rig 1' as shown below. The new diagram contains only 2 agents, the Workbench agent which can be ignored, and an agent named 'Rig Gateway 1' which represents the inside of the Rig 1 agent we just created on the main diagram.


If you expand this agent, you will see that it contains the same ports as the Rig 1 agent,


except that, as we are now looking at the inside of the rig, those that we created as inputs are now shown as outputs, and those that we created as outputs are now shown as inputs.

Now we can add some agents to the rig to create some noise. For this simple demonstration case we will simply add a Scaler Agent and an Audio Unit Agent as in the earlier tutorials in this series.

With the Rig 1 tab selected use the Create Tool to create a Scaler Agent and an Audio Unit agent in the same way as described in Tutorials 1 and 2.


Don't forget to set a plugin in the Audio Unit. Then, using the Wiring Tool, make connections from Rig Gateway 1 to Scaler 1, from Scaler 1 to Audio Unit 1 and from Audio Unit 1 back to Rig Gateway 1.


Select Keygroup Output 2 and you should find that you can play your new rig-based instrument.

If we expand the internal agents in Rig 1 as in the next diagram, we can see how the connections have been made to the relevant inputs and outputs on the Rig Gateway Agent. To improve the clarity of the diagram, a wiring trunk has been added to route the outputs from Audio Unit 1 back across to the left hand side of the diagram.


Finally, we can rename Rig 1 to something more meaningful. Go to the Main workspace tab and click on the top level box of the Rig 1 Agent. The property editor will be displayed. In the box labelled name enter your preferred name and click the set button. In this example we have chosen the name 'audio unit rig 1'


The Rig Agent and the tab are then renamed as shown below.


Save the setup with the short tag Workbench Tutorial 4.

Back To: Building_your_first_setup_from_scratch