WHAT IS PRELOADING

While you might think that when you tell a really fast computer to start playing a movie, it can do so instantly – but that's not the actually the case. There are many complex steps that must be taken before the first frame can be rendered. Necessary actions like loading the software library that decompresses the movie and then decompressing the first several frames of video from your hard drive are just two of the many steps required to deliver the first frame of video. 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 "Player" actors in Scene XYZ to determine what media to preload. (If the player has a 'visible' input and it is 'off', then it is ignored.)
    • What media to load
    • For movies and sounds, the speed at it which the file will play
    • The starting point for playback, i.e., the 'play start' + 'position' inputs.
  3. After accumulating this information for the new scene, Isadora tells those starts preloading all of these files in the background. It continues to play the current scene while it finishes preloading.
  4. When all of the media is ready to play or be shown, 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. Finally, very high resolution pictures can also make this process slow.

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 Preload actors can help you solve this problem, as they allow you to jump instantly from one scene to the next by letting you preload the media well in advance of when it is needed. However, there are a lot of way to "shoot yourself in the foot" with these actors, so please read the following best practices and suggestions.

WHEN SHOULD I USE A PRELOAD ACTOR?

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.

However, sometimes you need to have the next scene appear instantly after the Jump actor is triggered. That's when you might need one of the Preload actors.

Best Practice: Pay Attention to the "Loaded Media" Indicators in the Status Bar.

If you're going to use any of the Preload actors, you really must pay attention to these values. If these values get bigger and bigger, you're probably doing something wrong. You can release all of the preloaded media by choosing File > Close from the menu and re-opening your file.

Here's an example of the worst case scenario: you place an Enter Scene Trigger -> Preload Scene combo in every scene of your show so that whenever you jump into a scene, the media for the next scene is preloaded. Now, in rehearsal, you click on the last scene in the file and then you keep clicking the previous scene until you get to the beginning. Voilà! The media for every scene in your show loaded into memory! With a complex show, you would have crashed before you got to the beginning.

Solution #1: Use the Preload Scene Actor

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 media will be ready before the Jump actor is triggered and you'll get an instant transition.

Solution #2: Cautiously Use the Video Preload Actor

There are some cases when the Preload Scene actor 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.

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.

SITUATIONS THAT CAN GET YOU INTO TROUBLE

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.

The "Worst Case Scenario" above has come up a few times in support tickets when users decided to use the Preload Scene actor in every scene and added a "Back Button" (i.e., Keyboard Watcher -> Jump -1) to their patches. Again, backing up leaves the preloaded media for the next scene "dangling." You must take steps to avoid this, or at least frequently close and reopen your file to release the preloaded media.

CONCLUSION

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