Tutorial 4: Metro and Toggle

Automated actions

This tutorial focuses on automated actions and the ability to control them. Almost every automated action is built around a metro object, which produces bang messages at a steady rate. We will first introduce the toggle user interface object as a simple control for the metro object. We will also look further into object arguments and overriding those arguments.

To open the tutorial patch, click on the Open Tutorial button in the upper right-hand corner of the documentation window.

Fun with the toggle object

Take a look at the tutorial patcher. The left-most patch features a series of message boxes and a button connected to a square box. Start by clicking in that box – we see the faint X in the interior brighten. A 1 message was also sent from the object to the number box connected below it. Clicking in the object again will dim the X and send out a 0. That's all this object does – when changed, it outputs either a zero or non-zero value, depending on the new state (off or on). This object’s formal name is toggle, and it is one of the most-used objects in Max programming.

The toggle checkbox can be set or cleared by sending it messages. Click on the message boxes that are connected to the toggle to see their effect on the object’s state. By looking at the connected number box, we see that any number other than 0 turns it to "on" (the X mark is bright); the toggle also echoes the value of the number that turned it on out its outlet. Clicking on the 0 message turns the toggle off, and outputs a 0.

The action of the button object is even more interesting. Clicking on the button switches the toggle object on and off, with the output (seen in the Max Console and in the number box) alternating between 0 and 1. This is the root of the toggle object's name – its ability to "toggle" states based on incoming bang messages.

Introduction to metro: the metronome object

The patch in the center introduces a new object: metro. The metro produces bang messages, much like the button object. However, unlike button, metro objects send these messages repeatedly at the interval specified in its argument. Once started, metro will continue to send bang messages until stopped. Click on the toggle that is connected to the metro, and watch the result – it sends a bang message (in this case, to a button object) once every second. Metros are activated when they receive a non-zero value. We can turn it off by un-checking the toggle, which sends the metro a 0. the metro object is one of the Max objects that can be used to create automated or self-running actions in our programs.

If we click on the button that is connected to the metro we see that it too starts the metro running. If we click on the button again, we see that it triggers an immediate bang out of the metro. Click rapidly on the button, and there is a bang for every click. When we pause there will be a one second wait for the next bang. When a metro receives a bang, the metro will re-start itself and schedule the next bang from the moment we triggered it. When we want to turn it off, we can click on the stop message.

How do we determine the speed at which the metro outputs bang messages? We determine the speed of a metro by setting its period. The metro object takes an argument (the number 1000, in this case) that sets the time interval (in milliseconds) between messages. 1000 milliseconds equals 1 second, which is why we see the bang messages coming out at that rate. How do we change this rate? That is the function of metro object's right inlet – it allows you to send a new time interval setting without having to type in a new argument value. The new value will normally become effective after the current interval is complete. (The exception to this rule is an interval change that is the direct result of the metro bang - that will be effective immediately.)

In our patch, there is a number box with several message boxes connected to it. Click on the 2000 message, and (after the next bang) the output will slow to one bang every two seconds. Click on the 500 and the metro speeds up, sending bang messages twice a second. The message 250 will cause four bangs per second. Changing the interval setting doesn’t change any other aspect of metro (e.g. whether it is "on" or "off").

The time interval of a metro need not be specified in milliseconds. Other time formats are available to specify intervals as beats or rhythm values. Tempo for time stated in beats or rhythm values is controlled by a transport object.

Changing the interval with a message in the right inlet also does not change the argument of the metro. Why not? Wouldn’t it be convenient to see the new value? Perhaps, but it would mean that any changes to the object would change the value saved with the patch – and, most times, you want to maintain the typed-in argument since it functions as the default starting value of the metro. Most Max objects behave in this way: they have one or more arguments that can be overridden by messages sent into inlets.

Running in parallel

The third patcher in our tutorial features a single main toggle attached to three additional toggle objects, each of which is connected to a metro with a different argument. Turn on the main toggle, and the metro objects generate a galloping light show. This is because the three time interval arguments of the metro objects are related: the first metro fires every second (1000 milliseconds), the second triggers three times per second (333.33 ms), and the third fires every quarter-second (250 ms). There is nothing managing this pattern – it just occurs because the scheduled output of the metro objects are constant, so the pattern keeps appearing. Note that the time interval of a metro can be either an integer (e.g. 1000) or a floating-point (e.g. 333.33) number.

Let’s expand on the idea of creating rhythmic patterns by using some of the other ideas we just learned. We can change the pattern by changing the time values of each metro; let’s start by adding three message boxes, of values 500, 200 and 750, and connecting one to the right inlet of each metro. When we click them to change the time intervals of our metro objects, no apparent pattern exists. This is because we need to synchronize the start of the metro objects to see the pattern. This can be accomplished by turning the main toggle off and on again. The result is a quickly flashing center light, with a syncopated outside pattern.

Let’s make another pattern, using message boxes for the values 200, 400, and 600, respectively. However, instead of using the toggle to switch the metro objects off and on, connect a single button object to the left inlet of all three metro objects. Click on the three message boxes, and then click on the button to restart all of the metro objects. The button forces the metro objects to restart in sync, giving us the expected rolling light show.

Summary

Automated actions are at the heart of many Max performance patches, and metro objects are often used as the starting point for these actions. Once started, the scheduling system of Max provides a stable timing system for Max output, and we can allow the events to run without further interaction.

Controlling patches using the checkbox-like toggle object is also a key programming tool, since a single toggle can provide a simple on/off interface to much more complicated processes.

See Also

Name	Description
Timing and Sequencing Events	Timing and Sequencing Events
toggle	Switch between off and on (0/1)
metro	Output a bang message at regular intervals
transport	Control a clock