TOOLBOOKDEVELOPER.COM

Audio Player User Guide

It's

Audio Player Widget - About the Widget

Developed for:	Click2Learn ToolBook Instructor version 8.5 or higher
Works in:	Native, Neuron, and DHTML ToolBook Projects
Type of Tool:	Catalog Object

Installation

When you download the program, it will self extract into your Program Files directory into a folder for NirvanaBound\AudioPlayer##\. At the end of the extraction process it will run a utility (written in ToolBook :-) to find your Instructor file and will install the Widget into your catalog folder. The next time you open ToolBook Use the Customize Catalog feature to import this new Audio Player category.

How to upgrade to ToolBook 90

When you upgrade from ToolBook 2004 (8.5/8.9) to ToolBook 9+ you must remove the old Audio Player Widget from the upgraded book and install the new version (TB90) of the Audio Player Widget. To keep from re-entering the audio file names manually I have provided an Upgrade90.tbk book in the installation file, open this book and read the instructions to speed up the process.

How to Use the Widget

Please note that the following details are quite voluminous, this not a refection on the easy of use of this tool, however, it will demonstrate the depth of functionally. It is truly very simple to use when simplicity is all that you need but it has the ability to work, control and be controlled in very complex interactive programs.

1.	Open your ToolBook project and drag the Audio Player Widget from the Catalog to the background of your project. You can put the Widget on either the background or foreground. Where is the best place to put the widget? I recommend if you have a lot of audio in your project that you put the audio player on the background. There are known problems with ToolBook in author mode when you start to get too many ActiveX controls in your project. The program will start to slow down significantly and will eventually crash. I will not be able to help you if that happens to your project. One of the features of the Audio Player widget is that it makes it easy to put the Audio Player on the background* so take advantage of the tool you have invested in :-) That said, if you simply need to play an audio on a handful of pages, then you may want to put the player on the foreground of each page. *Obviously your project will be more efficient if you use less backgrounds, so I recommend keeping your backgrounds to a minimum.
2.	After the Audio Player has been added to your background, the extended properties for the Player will pop-up. Add the audio file name (the full name including the extension for example myaudio.mp3 or hearthis.wav) do not include the path. Then, check the features you wish to set for the audio player. Keep in mind that if the Audio Player is on the background, the settings that you choose will apply to every page that shares that background. BUT, the audio file name won’t because that information goes into a recordField for the page. What are the Features: Audio Control is visible at reader. (Default is checked) If you do not wish to allow your users control the Audio Player then uncheck this option. WARNING!! With this option checked and if there is an invalid audio file then the Audio Player will automatically set the "Audio Off" and the user will not be able to turn "Audio On". Audio File recordField is visible at reader. (Default is NOT checked) When checked the recordField will be visible at reader, this allows you to see the audio file names as you navigate through your program. The Audio Control will also need to be visible at reader:-) Typically you would have this turned on whist you are developing and turn it off before you signoff your program. Enter Audio File name at reader. (Default is NOT checked) When checked you will be able to edit the Audio File name at reader. Note that changes at reader level will not take effect until you move away from the page and then come back. i.e. If there is gday.mp3 and you change it to howdy.mp3, when you click the play button you will hear G'day. This is because the Action code to load the audio file is in the On load page event.
3.	Make sure that your audio files are in a folder called: audio. That folder must be at the same level as your ToolBook project. Keep in mind that these audio files ARE NOT added to your resources. That means that it is your responsibility to make sure that the audio files are in the right location in order for them to be played (that would be a folder named “audio” at the same level as your ToolBook for Native and Neuron deployments.
4.	Give it a whirl! Hit F3 and go into runtime and when you enter the page, the audio should play. If your audio does not play, consult the Troubleshooting Guide.
5.	Ready to add an audio to the next page? Advance to the next page. If the Audio Player Widget is on the background, you will see the recordField. Simply enter the name of your audio into the recordField. Continue to do this for every page. If you come to a page where you do not have an audio, just don’t put anything into the record field.
6.	If your deployment method is for DHTML then after exporting your program you will need to copy the audio folder to the WebExport/(bookname}/audio folder. So if you ToolBook was called myBook.tbk in the c:\ToolBookProgs folder then you will need to copy the folder c:\ToolBookProgs\audio to c:\ToolBookProgs\WebExport\mybook\audio folder. Do not move the folder, as each time you export your book the ...\mybook\ folder (and all sub folders) is deleted!
Triggering Your Audio
1.	Audio Trigger The Audio Player Widget is set to play the audio when your user enters the page. However, you can trigger the audio to play whenever you wish if you use the Audio Trigger. Simply drag and drop this Audio Trigger object from the catalog to your page. The Extended Properties Editor for the Audio Trigger will pop up. Enter the name of your audio file. Now, it is up to you to Trigger this object, this can be done either via an Action in another object or by adding an Action Trigger from the catalog. Remember, that the audio file should reside in the audio folder. Important: You will always need an Audio Player Widget on your background if you use this object. Tip: If you have more than one Audio Trigger on any given page, make sure that you give each Audio Trigger object a unique name.
2.	Audio List Trigger Use the Audio List Trigger to play a series of audios, one after another. Simply add your audio names to the list, separated by commas. It is up to you to Trigger this object, this can be done either via an Action in another object or by adding an Action Trigger from the catalog. Remember, that the audio file should reside in the audio folder. Important: You will always need an Audio Player Widget on your background if you use this object. Tip: If you have more than one Audio List Trigger on any given page, make sure that you give each Audio Trigger object a unique name.

Special Features of the Audio Player Widget

If your program cannot find your audio, it will turn off the audio player so your users do not get an error message on every page. Typically you will ensure that the audios are available and this will never happen, however, we both know that some things are sent to try us:-( Think of this feature, as a debugging tool to help you, maybe you are just testing you program and have not uploaded the audio files to the internet as yet, or you are still waiting for them to be produced??

There are 6 global variables used by the Audio Player Widget:

	Name	Default	Description
1	AudioFileName	Null	The audio file including the path.
2	AudioOn	true	Audio on/off flag
3	AudioPath	../audio/	The DHTML path, this is changed to the value in AudioPathNative when in Native mode.
4	AudioPathNative	audio\	Used to load AudioPath in Native mode.
5	AudioPlayList	null	List of audio files to play in sequence.
6	AudioTriggersOn	false	A flag used to determine if Audio Triggers are sent to the current page - true/false.

This widget uses Action Methods and you can execute these Methods from other ToolBook objects. To read about how to use Methods click here.

	Name	Description
1	AudioCompleted	Executed by the WMP On end of stream...This in turn executes AudioTriggerPage with this message.
2	AudioContinued	Executed by the WMP On play state changed... This would be after the user has pressed the play button after pressing the pause button. This in turn executes AudioTriggerPage with this message.
3	AudioError	Executed by the WMP On error... The error massage is displayed and the AudioOff method is executed. This in turn executes AudioTriggerPage with this message.
4	AudioLoaded	Executed by the WMP On new stream...This in turn executes AudioTriggerPage with tthis message.
5	AudioOff	Executed when the user clicks on the AudioOff button and when an error occurs. This in turn executes AudioTriggerPage with this message.
6	AudioOn	Executed when the user clicks on the AudioOn button. This in turn executes AudioTriggerPage with this message.
7	AudioPaused	Executed by the WMP On play state changed... This would be after the user has pressed the pause button or when the PauseAudio method is executed. This in turn executes AudioTriggerPage with this message.
8	AudioReset	This Method is executed in the On unload page... event in the Audio Player Widget and will clear the global variable AudioFileName and clear the audio file from the Windows Media Player. You can execute this Method prior to executing the setAudioFileName Method.
9	AudioReStarted	Not currently implemented.
10	AudioStarted	Executed by the WMP On play state changed... This would be after the user has pressed the play button or when the extFileName is changed and extAutoStart is set to true of the WMP or when the PlayAudio method is executed. This in turn executes AudioTriggerPage with tthis message.
11	AudioStopped	Executed by the WMP On play state changed... This would be after the user has pressed the stop button. This in turn executes AudioTriggerPage with this message.
12	AudioSuspendTriggers	This Method has a single parameter of True or False, if True the there will be no AudioTriggers sent to the current page. See AudioTriggerPage (Next). This Method is executed by the On unload page... event passing True- thus making the default for the next page "do not send Audio Triggers". As an alternative to executing this Method you can simply set the global variable AudioTriggersOn (See above) e.g.: Set AudioTriggersOn to true
13	AudioTriggerPage	This Method is executed by most of the other Methods in the Audio Player. It has a single parameter that is the actual trigger sent to the page. This Method will first check if the global variable AudioTriggersOn is set to true, if it is then the passed parameter is then sent to the On user ... event to the current page and is in the value parameter. You would turn on the AudioTriggersOn to add interactivity for the current page. As an example you may wish to play a looping animation when the page audio starts and then stop the animation when the page audio finishes. This would be accomplished by intercepting the AudioStarted and the AudioCompleted triggers and then using the play and stop animation Actions respectively. All of the audio triggers have been provided in the Audio Player Widget, all you need to do is edit the On user ... event in the control. Then select all of the Actions and copy them. Now edit the Actions for the page and in the On user ... event do a paste. The last step is to insert the appropriate Action for the appropriate trigger. I would advise that you delete all if the "Else if ..." statements that you do not need. Just reading this probably doesn't make any sense, so you will need to follow the instructions and look at the details:-)
14	getAdioFileName	This Method is executed in the On load page... event in the Audio Player Widget and will load the global variable AudioFileName using the data in the recordField "AudioFileName" and add the AudioPath.
15	PauseAudio	This Method will pause the audio that is currently playing, you can execute this Method from another ToolBook object.
16	PlayAudio	This Method will play the audio that is currently currently assigned to the global variable AudioFileName, you can execute this Method from another ToolBook object.
17	PlayNextPlayListAudio	This Method is executed from the AudioCompleted Method. It determines if there is data in the AudioPlayList global variable and then play the next audio file.
18	PopPlayList	This Method is a simple form of the pop function in ToolBook and is use to get the next audio from the AudioPlayList global variable.
19	setAudioControls	This Method will determine which of the AudioOn or AudioOff buttons is visible.
20	setAudioFileName	This Method is executed in the On load page... event in the Audio Player Widget and will assign the audio file to the Windows Media Player. The Method has two parameters, fileName and autoPlay. The fileName can be is the audio file to be played and must include the path, when executed in the On load page... event the global variable AudioFileName is passed and the value of autoPlay is true. You can execute this Method from any ToolBook object, allowing you to play any audio based on user interaction with your program.
21	setAudioPlayList	This Method has two parameters: PlayList and StartPlayList. When executed it will load the global variable AudioPlayList with the passed parameter PlayList and if the StartPlayList is true it will execute the Method PlayNextPlayListAudio Method.
22	StopAudio	This Method will stop the audio that is currently playing, you can execute this Method from another ToolBook object.

You can turn the Audio Triggers on at any time via Actions. With this feature you can create interactive applications. When AudioTriggersOn is set to true the Audio Player Widget will send 13 triggers to the current page. This is done via the On user... event Actions in the current page and you can write simple Actions to create interactive effects. The triggers are:

	Name	Description
1	AudioCompleted	Sent when the audio file finishes playing.
2	AudioContinued	Sent when the play button is pressed after the audio has been paused.
3	AudioError	Sent when there is an error when trying to load and/or play the audio.
4	AudioLoaded	Sent when the audio file is loaded in the WMP via the extFileName property.
5	AudioTurnedOff	Sent when the user clicks on the AudioOff button.
6	AudioTurnedOn	Sent when the user clicks on the AudioOn button.
7	AudioPaused	Sent when the user clicks on the pause button.
8	AudioReStarted	Not currently implemented.
9	AudioStarted	Sent when the audio file starts to play.
10	AudioStopped	Sent when the user clicks on the stop button.
11	AudioEndPlayList	Sent when the last audio file in a sequence of audio files is completed.
12	AudioNextPlayListAudio	Sent when the next audio file is loaded from the list of audios to be played in a sequence.
13	AudioStartPlayList	Sent when the first audio file is loaded from the list of audios to be played in a sequence.

Audio Player Widget Limitations

1.	As the Audio Player Widget uses the Windows Media Player, it will not work in DHTML courses through the Netscape Browser.
2.	Users of your program must have the Windows Media Player installed on their computer.
3.	The Audio Player Widget requires sound files that can be run through the Windows Media Player (ie. .mp3, wav, etc.). Unlike the functionality built into the ToolBook Universal Media Player, the Audio Player Widget will not compress or otherwise alter your sound files. If your project uses really BIG sound files, they will remain really BIG when you deploy your course.
4.	The following is NOT required for TB9.0! There is an additional step required when your exported ToolBook DHTML program is run locally and you or your user has the Windows Media Player version 9 installed. You must have TB8.9 (2004) and the Audio Player Widget 8.9 version. Open your ToolBook, edit the book properties, click the Web tab, click the Import... button, navigate to the Audio Player Widget 8.9 install folder e.g. C:\Program Files\NirvanaBound\AudioPlayer\TB89\ Now select the WMP9_Local.js JavaScript file. Note how this only has one function, FixAudioPathLocal() with a parameter of AudioPath. Now for the last step, edit the Actions for the book, the "On load book ..." event and add the following: Execute Script FixAudioPathLocal(HTML); store return value in AudioPath You will need to double click on the script icon to open the dialog and enter the global variable AudioPath as the passing parameter.

Frequently Asked Questions

After I export and test locally the audios don't play?
The Microsoft update WMP9 (Windows Media Player version 9) has changed the ability for the player to find the audio file using an internet (URL) based path when played locally:-( This means that the DHTML path of ../audio will not work in the browser when you launch the exported ToolBook program. We need to change this path to the full PC path. e.g. C:\MyToolBooks\Project1\WebExport\project1\audio
With TB8.9 (2004) we have the ability to include JavaScript:-) Included with the Audio Player Widget is WMP9_Local.js which is a JavaScript file that you can use to convert the relative URL path to the full path on the PC. However, you do need to add an Action. See above for the details.

How many audios can I have on a page?
The Audio Player Widget will automatically play a single audio file, however, there is no limit to the number of audio files that you can play via multiple Audio Triggers or by implementing your own Actions and executing the Action Methods of the Audio Player Widget.

What audio formats can I use?
The Audio Player Widget uses the WMP (Windows Media Player), therefore the file formats are restricted to those files that the WMP will play. Click here to read about file Formats Supported by Windows Media Player Versions 6.0 and Later.

What are the Error codes for the Audio Player Widget?
If there are many errors this widget will report and they all come from WMP, this widget will show error codes and a description of the error. Sometimes these errors are a little obscure and your users may not understand the implication, for a list of the error codes, click here to read about Windows Media Player Error Code Information.

What do I need to do after I export my program?
Typically the exported (DHTML) files are created in a folder called WebExport\{myBookName}\ where {myBookName} is the name of your ToolBook program (without the .TBK extension:-). You MUST copy the audio folder to this folder. Let's assume you ToolBook program is called myBook.tbk and it is in a folder called C:\myProgs. In the myProgs you will have a folder called audio which contains all of your audio files. After exporting myBook.tbk you MUST copy the folder C:\myProgs\audio\ to C:\myProgs\WebExport\mybook\ this will create a folder: C:\myProgs\WebExport\mybook\audio\

How do I change the default audio file folder?
The default audio file folder is called audio, to change this you will need to change the global variables AudioPath and AudioPathNative. Note that the AudioPath is set for use in your exported DHTML files and the default is ../audio/.
The AudioPathNative default value is audio\ and is used in Native mode only, there is OpenScript in the Audio Player Widget that assumes this is a relative path, relative to your ToolBook program. The OpenScript is:
AudioPath = ASYM_PathOfFile(name of this book) & AudioPathNative
Whilst I have not tested this you could change the global variable AudioPath using Actions:-) (WARNING! going in and out of reader will reset this via the above OpenScript). These two global variables do not need to use the same folder name.

Troubleshooting

My audio is not playing in reader mode.	Is "Audio On" or "Audio Off"? If you have changed the audio file name and/or just added one then you need to navigate away and then back to the page. Is the audio file name in the audio folder? Have you just gone from author mode to reader mode? Does the audio file name have a valid extension for the WMP?
My audio is not playing in Native runtime mode.	Is "Audio On" or "Audio Off"? Is the audio file name in the audio folder? Does the audio file name have a valid extension for the WMP?
My audio is not playing in DHTML mode.	Is "Audio On" or "Audio Off"? Have you copied the audio folder to the WebExport\{myBookName}\ folder? Is the audio file name in the audio folder? Is the file extenstion mp3 and will the server allow .mp3 files through? Does the audio file name have a valid extension for the WMP?

Privacy Statement

Please contact the webmaster with comments/questions about this website.