Understanding Preloading / Safely Using the Preload Actors

(Click here to jump to a discussion of this Knowledge Base article in the TroikaTronix Forum.)


While you might think that when you tell a really fast computer to start playing a movie, it can do so instantly, that’s just not the case. There are many complex steps that must be taken before the first frame can be rendered. Things like loading the software library that decompresses a particular codec and reading the first several frames of video from your hard drive and decompressing them are just two of the numerous steps required. For codecs like H264 or MP4, this is even more time consuming.

So, starting in v1.3.0f24, to prevent a delay when jumping into a scene, Isadora handles a jump as follows:

  1. Jump actor is triggered; it says “go to scene XYZ”
  2. Isadora scans all the Movie Players in Scene XYZ to see 1) what movie they will play 2), the speed at which they will play and 3) the starting point for playback, i.e., the ‘play start’ + ‘position’ inputs. (Please note that if the movie’s ‘visible’ input is ‘off’, the movie will not be included in this scan.)
  3. Isadora tells those movies to start preloading in the background. It continues to play the current scene while it finishes this task.
  4. When all of the movies are ready to deliver the first frame of video (and after all other media like sound files are loaded) Isadora jumps to Scene XYZ

Step 3 can take a non-trivial amount of time if you’re preloading a lot of movies, especially if their resolutions are high and their codecs are slow when decompressing the video, e.g. H264 or MP4. Loading sound files for the Sound Player actor can also take quite a bit of time if they have a long duration, because these files are loaded into your computer’s RAM memory from the hard drive.

The need to preload media is not unique to Isadora. All software that plays video or audio needs to take this step. But when using an app like QuickTime Player, the 0.1 seconds it takes to preload after you hit play isn’t really noticeable or annoying. But when you’ve got a show that requires really precise cues, this delay can become a problem.


The answer is, only when you really need to do so.

Normally Isadora does a pretty good job of taking care of these preloading operations. We strongly recommend that you let Isadora handle this job for you, because you won’t end up with unexpected problems down the line.

But sometimes there is a cue that needs to appear instantly after the Jump actor is triggered. And that is when people start using the Preload actors so they can make sure the preload operation is done in advance of the Jump, and the next scene will be ready as quickly as possible.

If you need the next scene to start instantly, your first approach should always be to use the Preload Scene actor. When triggered, this actor does exactly what was described in steps 2-4 above. But instead of waiting for the Jump actor to be triggered to take these steps, it allows you to decide when to initiate the preload. That way, the clip or clips can be ready before the Jump actor is triggered.

But there are some cases when this won’t work. Consider a Movie Player whose ‘movie’ input is set to automatically initialize to 0 via the property inspector box. (The box you see when you click on the word ‘movie’ in the Movie Player.) Then, inside the same scene, you have an Enter Scene Trigger -> Trigger Delay -> Trigger Value that sends the number ’4′ into the ‘movie’ input of the Movie Player. In this case, Isadora’s normal preload function won’t help you because it doesn’t know which movie your going to play. (If the ‘movie’ is automatically initialized to 0, movie 0 is the one that will be preloaded; of course, movie 0 means “no movie.”)

At this point, you might resort to the Video Preload actor. But there are some very important caveats you need to understand about this actor, otherwise you may end up accumulating many preloaded movies that are never going to play, eventually leading to an unavoidable crash.

VERY IMPORTANT: The Video Preload actor only works when the Movie Player that will play the movie has these settings:

  • The ‘position’ is 0
  • The ‘play start’ is 0
  • The ‘play length’ is 100
  • The speed is 1

If the target Movie Player is not set in this way, the movie will be preloaded but it won’t get used. (At least not until a Movie Player whose parameters match the settings shown above plays the movie.) Instead a fresh copy of the movie using the current Movie Player settings will be preloaded and then will begin to play. So not only do you end up with a “dangling” preload, your efforts to speed things up were in vain.

This may be confusing for long time Isadora users. Before v1.3.0f24, if you used a Video Preload actor it only considered the movie number –  if the Movie Player wasn’t set as described above, it would discard the preloaded movie and load the movie with the ‘position’, ‘play start’, ‘play length’ and ‘speed’ as specified by the Movie Player. So your preload effort actually slowed things down (because the preload you did wasn’t in fact used) but the preloads didn’t accumulate in memory. But, to accommodate the new preloading behavior introduced in 1.3.0f24, this needed to change.

So, the rule is: only use the Video Preload actor if the Movie Player that will play that movie has a ‘position’ set to 0, the ‘play start’ set to 0, the ‘play length’ set to 100, and the speed set to 1. Otherwise you’ll be end up with preloaded but unplayed movies hanging around in memory.


A simple example I just encountered went like this: each scene used a Video Preload actor to preload the movies for the next scene. The ‘position’ and ‘play start’ inputs were 0, the ‘play length’ input was 100, but the speed was set to 2. That meant that the movies were being preloaded but never actually played. Eventually Isadora crashed due to the massive build up in preloaded movies.

Another scenario I’ve seen a few times now goes like this: each scene has an Enter Scene Trigger connected to a Preload Scene actor. So, upon entering Scene #1, the preload for Scene #2 is initiated immediately. This in of itself isn’t bad, as long as you’re moving forward through the Scene List.

But then, you decide it would be nice to have a “back button” during rehearsal, so that you could back up a few scenes and pick it up from an earlier point in the piece. So you add a Keyboard Watcher connnected to a Jump actor that jumps to the previous scene.

Here is the danger of this setup:

  • You hit the back button, jumping from Scene 4 to Scene 3. The Enter Scene Trigger -> Preload Scene combo in Scene 3 preloads the media for Scene 4.
  • You hit the back button again, jumping from Scene 3 to Scene 2. The Enter Scene Trigger -> Preload Scene combo in Scene 2 preloads the media for Scene 3.
  • You hit the back button yet again, jumping from Scene 2 to Scene 1. The Enter Scene Trigger -> Preload Scene combo in Scene 1 preloads the media for Scene 2.

At this point all of the media for Scenes 2, 3 and 4 are loaded! This only gets worse when you decide to manually activate Scene 21 with the mouse, and then hit the back button a few more times. Now you’ve got loads of media hanging around in memory and, if you don’t eventually go back and activate the Scenes that were preloaded, you might eventually create a build up that leads to a crash.


Hopefully that clears up a few things for all of you and will ensure effective and meaningful use of the Preload Actors.

Comments are closed.