Callbacks

Players are a great feature of LiveCode, they can play audio or video allowing you to create rich media applications. Players can be stopped, paused, rewound - all the abilities you would expect of any media player - but one of the features that makes Revolution players really powerful is callbacks.

In this lesson we will see how you can use callbacks to make a fun and interesting application.

You can download the stack from this lesson here: https://tinyurl.com/y9x2qbfo

What is a callback?

Callbacks are a property of a player and are a list of entries, one per line, which allow you to trigger scripts at specific points during playback.

Each entry has the form:

intervalNumber, messageName

The intervalNumber is a positive integer expressed in the internal player time format, this depends on the timescale of the player where the timescale is the number of intervals per second. In a player with a timescale of 500 interval 1000 would be 2 seconds into the movie or sound.

The message messageName is sent when the currentTime of the player reaches the given interval, allowing the user to synchronize other actions with the playback of a movie or sound file.

What can callbacks be used for?

One possible application of callbacks would be to create a talking storybook, a fun and educational program for children learning to read or a foreign language teaching tool. Callbacks can be used to change the graphics as the story is being read or show the text along with the voiceover.

To use callbacks to display text and graphics, you simply identify the intervals where you want them to change and set the callbacks of the player to send a message when it reaches those intervals.

Creating the Stack

Creating the Stack

For a simple talking story book first we need is a new stack with a field called "words" to display our text (1) and a player called "story" (2) to play our sound file.

Our resources

Our resources

Now we need the sound file we want to play and the text we want to display. I have a sound file of the first chapter of Alice in Wonderland being read aloud and the text of the first chapter stored in a text file. I have split the text file up into individual lines as we only want to show one line at a time.

Now we need a way to select our sound file and text file. We'll add 2 buttons to the stack Select Sound File (1) and Select Text File(2). These 2 button use the answer command to allow you to select the files you want to use. These in turn call handlers on the card that load in the files ready to be used.

Add this code to the "Select Sound File" button

on mouseUp
   local tSoundFile

   answer file "Please choose a sound file"
   
   if the result is not "cancel" then
      // The user has not cancelled the dialog
      put it into tSoundFile
      loadSoundFile tSoundFile
   end if
end mouseUp

Add this code to the "Select Text File" button

on mouseUp
   local tTextFile

   answer file "Please choose a text file"
   
   if the result is not "cancel" then
      // The user has not cancelled the dialog
      put it into tTextFile
      loadTextFile tTextFile
   end if
end mouseUp

Add the loadSoundFile and loadTextFile handlers to the Card Script.

local sStoryText

on loadSoundFile pSoundFile
	set the filename of player "story" to pSoundFile
end loadSoundFile

on loadTextFile pTextFile
	put url ("file:" & pTextFile) into sStoryText
end loadTextFile

Remember to declare a script local variable to hold the story text.

Using Callbacks

Now we could just put the text into the field and start the player but that is not particularly interesting. What we will do instead is use callbacks to show one line of text at a time, along with the audio file.

To set up callbacks we need a handler that we can call when the player reaches a certain point, this handler will display the relevant text.

on showText pLine
	put line pLine of sStoryText into field "words"
end showText

We can call this handler with a line number to have that line of text displayed, sStoryText is the variable we populated from the text file earlier.

Add the showText handler to the Card Script.

Calling back

Calling back

The callbacks of a player are a list of commands to be called when the player reaches certain points.

These points are specified by the interval or currentTime of the player. So in order for the talking storybook to work you need to know the points at which the showText handler should be called.

On different platforms the timescale of the player can be different for the same sound file so we will specify the times in milliseconds in the file and convert them into the correct intervals for the player in code.

This is the list of callbacks for this example

762, showText 1
6400,showText 2
12581,showText 3
18160,showText 4
22691,showText 5
29201,showText 6
34241,showText 7
38291,showText 8
41951,showText 9
45821,showText 10
48551,showText 11
52781,showText 12
55091,showText 13
59531,showText 14
63791,showText 15
68473,showText 16
73515,showText 17
78737,showText 18
81797,showText 19

All we need to do is set the callbacks property of the player to the list of callbacks.

Add a button Select Callbacks File and add this code to it

on mouseUp
   local tCallbacksFile
   
   answer file "Please choose a callbacks file"
     
   if the result is not "cancel" then
      // The user has not cancelled the dialog
      put it into tCallbacksFile
      loadCallbacks tCallbacksFile
   end if
end mouseUp

And then add the loadCallbacks handler to the card script

on loadCallbacks pFile
   local tCallbacks
   
   put url ("file:" & pFile) into tCallbacks
   
   // The callbacks are stored in the file in milliseconds
   // The times must be converted to intervals using the timescale of the player
   repeat with x = 1 to the number of lines in tCallbacks
      put round(the timescale of player "story" * (item 1 of line x of tCallbacks/1000)) into item 1 of line x of tCallbacks
   end repeat
   
   set the callbacks of player "story" to tCallbacks
end loadCallbacks

Then select the callbacks file and start the player and the text will appear along with the audio file.

Further development

To make our story book more appealing we can add images and graphics as well.

2 Comments

Trevor Roberts

Hi,
This is a fantastic feature! I have downloaded the sample stack, but it doesn't work. It opens with the last line of the text showing.

I added an extra button to capture the current time of the player ("get the currentTime of player "story" put it into tTime") and saved that in the callbacks.txt file, but it still doesn't sync correctly.

When I click on play, it did show the first line, after that it only shows the last line again.

Elanor Buchanan

Hi Trevor

Thanks for bringing this to our attention. I have updated the lesson and example stack. We have made some changes to how our player works since this lesson was written so it was a bit out of date.

The main issue was that players can have different timescales on different platforms, even for the same audio file, so I changed the callbacks file to specify the times in milliseconds and added code to convert from milliseconds to the correct intervals based on the timescale of the player. What was happening was that on Windows all the callbacks were being set very quickly one after another because of the timescale of the player.

If there are still issues with the new version please let us know.

Kind regards

Elanor

Add your comment

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.