Do I need to add "waitforaudio" in StoryInit (or can it be in any passage)?

Sugarube 3.31.1

Just want to double check this: can I add waitforaudio macro to any passage — and that’s the passage that will load only once all audio has been cached. There’s quite a long load time with waitforaudio in the StoryInit, so ideally I’d like to let the user know to expect that, and then add pass through a waitforaudio passage.

Thanks! Ben

1 Like

I don’t have any experience working with audio. However, going by the docs, <<waitforaudio>> must be called after using <<cacheaudio>> to define which tracks to wait for. The note inside the <<cacheaudio>> docs say:

The StoryInit special passage is normally the best place to set up tracks.

I’m inferring from the use of “normally is the best place” here that it means you can use it anywhere.

The one issue I see would be if you attempted to play a track that hasn’t been cached yet. This would happen if you load a save on, say, passage 3 where the music was cached on passage 2. That’s why StoryInit is preferable, because it would safely cache the tracks for any save.

1 Like

Yeah. I don’t think it works if called after the load screen is dismissed, since the whole point is that is preloads the audio while the loader is being displayed. That said, you can call it anywhere in StoryInit, so you can wait on some tracks and not others if that’s what you’re trying to do.

The <<waitforaudio>> macro may be called in any passage, but I do not recommend it as it acquires a loading screen lock and holds it until all currently registered audio has been loaded/aborted.

You, generally, do not want to invoke it after startup for a couple of reasons:

  1. If a track has already been loaded/aborted, it will be reattempted—by calling the <AudioTrack>.load() method on it—which should not be done lightly as the warning therein makes clear.
  2. There’s no way to select tracks after track registration, it simply attempts to load all registered tracks, which is unlikely to be what you want after startup.

If you’re going to use it at all, then the best place is in the StoryInit special passage—or a passage included only by StoryInit, for organizational purposes.

NOTE: If you need a more granular solution for loading your audio, then you may use the SimpleAudio API directly, either rather than or in addition to using <<waitforaudio>>.

A good point, which is one of the examples in its documentation.

That’s probably not really necessary. If you’re loading them piecemeal or in stages after startup, then you can simply use the <AudioTrack>.hasData() method to check if each track is loaded (enough) for playback.

If loading individual tracks in stages, then I’d suggest making an audio group for each stage and then simply loading the group at the appropriate time, which should be somewhat before you actually need them.

1 Like

Hi all,

These are all very useful options. Apologies for the lengthy reply that follows!

I initially added <<waitforaudio>> when I noticed that the tracks in the 2nd half of the project weren’t loading properly. Sound ran smoothly up to a certain point, and then it started to experience drop-outs, tracks not playing, etc. It was like the StoryInit passage only had time to ‘read’ the first half of the cacheaudio list (which is sequential for the project), before the land page loaded, and then never got around to loading/caching the second half of the list.

<<waitforaudio>> solved that, but at the expense of long loading screen lock before any passage loads. My aim is to either a) reduce the length of the loading screen lock, or b) let the user know there may be a loading time of up to a minute.

For b): The project has a series of landing and on-boarding passages, several of which occur before any audio plays. So, one solution could be to add <<waitforaudio>> to one of them, and then on the link to that passage include a line of text like “may take up to a minute to load.” This was the idea behind my original question. Which sounds like it might be a solution, as long as no sound has been played up to that point?

For a): Because the <<cacheaudio>> list is sequential for the project, and the sound ran smoothly up to a certain point in the project, I could try reversing the cacheaudio sequence, and using <<waitforaudio>> about halfway through. So essentially, I’m saying: make sure the tracks in the second half have loaded, then we can start. My concern would be I’d have drop outs in the first half of the project, but that could be tested.

I could also, as suggested, create groups and load the groups at specific stages in the story. I have a couple of questions around this. First of all, can I ask if there is a difference between SimpleAudio.load() and <<cacheaudio>>, and SimpleAudio.loadWithScreen() and <<waitforaudio>>? Are the macros just simpler ways of executing the SimpleAudio commands, or is there a difference? (The warnings in the documentation made a little bit wary of using the SimpleAudio). If it’s just the same thing by another name, I could give it a try. Or, as suggested by the documentation, does SimpleAudio Load start downloading the tracks to the user’s device directly, as opposed to cacheing it in their browser?

Given that I’m basically trying to either let the user know to expect a wait as the project loads, or, reduce the lock screen time, or a combination of the above, which direction might be most useful and reliable: 1) moving <<waitforaudio>> to a later passage, but before any sound has played; 2) flipping the sequence of the <<cacheaudio>> list and placing waitforaudio in the middle, or 3) using the SimpleAudioApi to group and load the groups as needed throughout the project.

Thanks as always, Ben


  1. Moving the <<waitforaudio>> to a later passage
    Didn’t work, I had audio dropping out in the same place.

  2. Flipping the <<cacheaudio>> order also didn’t work — early tracks didn’t play.

  3. I’m going to test the SimpleAudioApi - but would anyone be able to answer my question above about how this is or is not different from using <<cacheaudio>> and <<waitforaudio>>?

Thanks, ben

Is there a way I can add a message/text to the loading screen lock?

All of the audio macros work through the SimpleAudio API and, by and large, simply provide access to it in a non-JavaScript way.

As to what those two macros do. Specifically, <<cacheaudio>> provides access to SimpleAudio.tracks.add() static method and <<waitforaudio>> provides access to SimpleAudio.loadWithScreen() static method.

The SimpleAudio.tracks.add() method registers a track with the given sources and, by default, requests that the browser preload its metadata—the browser is free to load more than that if it so chooses. As noted above, this is what <<cacheaudio>> invokes.

The SimpleAudio.load() static method loads all registered tracks from scratch—the sole exception is tracks that are currently loading at that moment.

The SimpleAudio.loadWithScreen() method is simply SimpleAudio.load() with the loading screen. As noted above, this is what <<cacheaudio>> invokes.

To load tracks either piecemeal or in stages, you want to invoke each track instance’s <AudioTrack>.load() method. There are several ways to go about doing that—I suggested one previously.

One possible example

In your StoryInit special passage:

/* Register audio that may be needed soon-ish after startup. */
<<cacheaudio "bgm_a"    "media/audio/bgm_a.mp3">>
<<cacheaudio "bgm_b"    "media/audio/bgm_b.mp3">>
<<cacheaudio "sfx_boop" "media/audio/sfx_boop.mp3">>

/* Load all currently registered tracks (meaning: "bgm_a", "bgm_b", and "sfx_boop") */

/* Register audio that likely will not be need until later. */
<<cacheaudio "bgm_c"      "media/audio/bgm_c.mp3">>
<<cacheaudio "bgm_d"      "media/audio/bgm_d.mp3">>
<<cacheaudio "bgm_finale" "media/audio/bgm_d.mp3">>

In some later passage when the need for the unloaded passages is drawing near:

<<script>>"bgm_c bgm_d bgm_finale").load();

SEE: static method and <AudioRunner>.load() method.

1 Like

Hey, after a few tweaks this is working really well. Thanks so much!

I have a new predicament, which I’ll link to in a new thread. Any ideas why the sound is so glitchy on ipad? Thanks! Ben