Tutorial 13: Movie Sequencing

Introduction

In this tutorial, we will work with a few new objects: the rslider, umenu and loadbang objects. The rslider object allows us to select a range of numbers using a single UI element. The umenu object allows us to pick an item from a pop-up menu within a patcher. The loadbang object is a setup object – it allows us to trigger messages when a patcher is first loaded. All of these are important items for more complex patches – and we will use them in the context of making some interesting video-driven programs.

Providing user selections is important once your patch gets complicated – or if you want to share your patch with others. The rslider object is great for selecting loop points (since it gives you the ability to select start and end points with a single mouse swipe), and the umenu object is perfect for selecting among a list of files or display options. Finally, loadbang gives us the ability to set object parameters when a patch is loaded, allowing us to create patchers that require a minimum of setup to get started with.

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

A few new objects: rslider, loadbang, umenu

Take a look at the tutorial patcher. This patch contains a few simple patches at the left, and two larger patches to the right. Let’s start by looking at the left-hand patches, where we are introduced to our three new objects.

The right-most patch is the example patch for the rslider object. Click on the surface, and you will see that the wiper (if any) will will vanish. However, if you click the mouse then drag up or down on the surface, you will see that you can actually select a range of values – reflected in the two outputs of the object. If you shift-click, you can adjust the end closest to the mouse. The name rslider refers to the fact that this is a “range slider”, capable of selecting a range of values with a single mouse movement. The actual range that the rslider covers can be set with a simple message (it defaults to the range 0 to 127), as we'll see later in the tutorial.

The next object is pretty simple, but very important. It is the loadbang object, and it sends out a bang whenever the patcher file is loaded (hence the name). This is most often used for setting up values in a user interface – in this case, we are loading the number box with 55 (it would normally default to 0) each time we open the patch. We can also force the loadbang to fire by double-clicking on it. If we change the connected number box to another number, double-clicking on the loadbang will cause a bang message to hit the message box (containing the message 55), and the number box will again update to its previous value.

Finally, the umenu is shown in the bottom of the three small patches. If you click on the umenu, it displays a set of options as a pop-up menu. Selecting one will produce two forms of output: the left outlet will send the index number of the selection, starting at 0; and the middle outlet will output a symbol containing the text of the menu option.

The items available in a umenu object can be set in a number of ways; in the next section we'll look at how to populate it automatically. First, however, unlock the patcher and open the Inspector for the umenu object on the right-hand toolbar. In the Inspector you'll see a section labeled "Items"; within this section we can view the list of items contained in the umenu (small, medium, etc.). Click on the "Edit" button next to the list and a window should open that will allow us to type in anything we want. Items in the umenu need to be separated by commas. Add to the list (or create an entirely new one), click OK, and close the Inspector. You should see the umenu change to reflect the new items we've just added.

Loading umenu with file info

The first large patch is labeled 1, and has two interesting sections: the top area is used to select movie files from a folder of movies that ship with the Max distribution, while the bottom area is used to loop the playback of these movies within an imovie object. Let’s start by looking at the top section.

What we have here is a rather complete file selection system. A loadbang object is used to trigger a message box that sends the message prefix ./patches/media to the umenu object. If we look at the reference material for the umenu object, we see that prefix is an attribute that sets a menu-wide prefix that is added to the beginning of any selected item. It has a second use as well – it tells the umenu where to load files when it is told to populate (or, in our case, to autopopulate). The umenu object has its autopopulate attribute set in the inspector, so when the prefix message is received, the umenu is loaded with the names of every file in the folder pointed to by the prefix message.

As a result, we have a umenu loaded with file names from a folder called "media" inside of a folder called "patches" (The "patches" folder is actually found within the Max application bundle. Otherwise this form would refer to folders relative to the folder where Max is installed on your system. Most of the time your paths will be relative to ~users.) When we select one, three things happen, thanks to the trigger object connected to the middle outlet of the umenu. First, the message dispose is sent to the imovie; this clears the imovie object of any video file that is currently loaded into it. Next, the symbol (the s in trigger) containing the name of the file with the folder prefix ./patches/media prepended to it is sent out. The read message is placed in front (via the prepend object) and then sent to the imovie. Third, the trigger object sends a bang through a delay object, which delays the message by 100 milliseconds; this gives the imovie object time to read in the movie. After the delay has expired, the message box below is triggered. It contains a few initialization messages to imovie: length (to query how long the movie is), loop 1 (to tell the movie to loop), and start (to begin playback). In this case, although we have a number box connected to the left outlet, we aren’t doing anything with the umenu object's index – everything is triggered by the middle (text-based) outlet. Note how the trigger object is extremely useful in this case, allowing us to set up a complex series of steps in the correct sequence: dispose the previous movie, read the new movie, find out its length, tell it to loop, and start it.

Select a movie from the umenu, and notice that it will load and quickly begin playing, looping at the end of the clip. If you select a different clip, the previous one with be disposed and the new one will start looping.

Using the rslider to set loop points

In addition to loading and starting the movie, that length, loop 1, start message had another consequence – it forced the movie length out the left outlet of the imovie object, and set a new chain of events in motion. This length message is used to set up the size (i.e. the range) of an rslider, and set the object with its complete range selected (this is what the 0 $1 message does). We can easily change the contents of the rslider by clicking and dragging within it, therefore changing the loop points that the imovie will use. To best see this in action, select the movie “countdown.mov” from the umenu at the top – this is the familiar movie that counts down from 10 to 1.

Now, if we click and drag in the rslider at the bottom of the patch, you can see that we change the start and end points of the loop. The output of the rslider object is sent to a pack object and then used to create a loopset message, which changes the looping "in and out points" honored by imovie. In addition, it rewinds the film to the start of the loop (the $1) message. This section of the patch shows a very common use for the rslider object; it is initialized with the length of a media file, then is used for playback start and end positions.

Setting things up: loadbang and screensize

Finally, we are going to see how loadbang (along with a few other messages) can be used to completely set up a patch for the user when it is first opened. This patch (labeled 2, and on the right), takes the current mouse location and uses it to decide where to place a movie within a 320 x 240 pixel display area. The mousestate is polled, and a rect message puts the currently playing movie, in shrunken form, at the specified location within the imovie object.

To begin, one loadbang message is used to load the “bball.mov” movie file when the patch is first loaded. This way, you (or your user) does not have to find the file themselves. Secondly, another loadbang is used at the top-right of the patch; it sends a bang message to the screensize object. The screensize object outputs a list of four coordinates representing the coordinates of your primary display. The last two elements in this list are, for all intents and purposes, going to give us the width and height, in pixels, of our screen (e.g. 1024 and 768). The mousestate object, as we remember, puts out the position of the mouse within that range starting at 0, so if we subtract 1 from the screensize we can properly scale the output of mousestate into the range 0. to 1. - this is a common trick when working with mouse coordinates, as we seldom use their actual pixel values; more often than not, we simply want to use them to control an entirely different range of numbers.

Once the scale object has its maximum input set by the screensize object, the current mouse position will always yield values between 0.0 and 1.0. These are then multiplied by 240 and 180 to get the upper-left-hand screen location for the video placement within the imovie object. The 80 60 portion of the rect message sets the width and height of the rectangle within the imovie - as a result, for a 320 by 240 window, our maximum input coordinates should be 240 and 180.

Turn on the metro object with the toggle to begin polling the mouse, and click on the start message. Move your mouse around the display. You should see a small version of the basketball movie track your current cursor’s location, and it will always be scaled correctly – no matter what display you run it on.

Summary

In this tutorial, we’ve learned about three very important new objects: rslider for range selection, umenu for the creation and selection of a list of items (or file names), and loadbang for initial state setup. In addition, we saw how the screensize object can be used to find out information about the size of your display. We demonstrated them by creating some complex video playback systems that controlled loop length and display positioning. These objects will be some of the most important tools you will use on future patches.