Using Audio Scripts

Scripts are objects authored in an application that contains a script editor, such as DirectMusic Producer. Although they consist mainly of text, script objects also contain a few binary parameters.

For a conceptual overview, see Audio Scripts.

Load a script by using the IDirectMusicLoader8::GetObject method. Obtain the IDirectMusicScript8 interface, then call IDirectMusicScript8::Init to associate the script with a performance.

The following code loads and initializes a script. Assume that g_pLoader is an IDirectMusicLoader8 interface, g_PPerformance is an IDirectMusicPerformance8 interface, and wstrFileName contains the name of the file.

IDirectMusicScript8*  pScript = NULL;
DMUS_SCRIPT_ERRORINFO errInfo;
HRESULT     hr;
 
if (SUCCEEDED(hr = g_pLoader->LoadObjectFromFile( 
    CLSID_DirectMusicScript, IID_IDirectMusicScript8,
    wstrFileName, (LPVOID*) &pScript)))
{
  hr = pScript->Init( g_pPerformance, &errInfo);
}

Apart from Init, the methods of IDirectMusicScript8 have three main purposes:

• Set and retrieve the value of variables declared in the script. Because script routines do not accept parameters, variables are the only way for the script and the application to exchange information.
• Call routines. A routine must finish executing before the application thread can continue.
• Enumerate routines and variables. These methods are of interest chiefly to script-editing applications.

All the methods of IDirectMusicScript8, except the enumeration methods, retrieve error information in a DMUS_SCRIPT_ERRORINFO structure. An error can occur if a variable is not found or code within a routine fails to execute.

Scripts can also be used without being directly loaded or called by the application. A segment authored in DirectMusic Producer can contain a script track that triggers calls to routines in one or more scripts.