mmScript

Last updated: 2002.05.01

The mmScript program began in 1997 by Ken Johnson , at the University at Buffalo , for the Department of Communicative Disorders and Sciences , under the instruction of Professor Joan E. Sussman , Director of the Speech Perception Lab . It is written using Delphi, a pascal oriented compiler.

mmScript is a Windows program for presenting pictures, text and sound with the intention of tracking user response from the keyboard or mouse. mmScript reads in a text file of commands and options that control the presentation of bitmap images, text messages and waveform audio. Scripts also control the request for user response as either yes/no, fill in the blank or multiple choice. Scripts can be programmed to make value comparisons, store numeric or text values, branch to another script or sub-sections of a script, start external programs (movies, games, whatever) and save information to a text file. Any text editor can be used to develope scripts and Windows can be set to automatically run mmScript by 'opening' a script. Audio control can be written to take advantage of Microsoft's DirectX DirectSound features for asyncronous audio, with on the fly loudness and balance mixing.

Syntax for writing mmScript scripts...

opening screen shot

Tha available commands are divided between six general categories...
Visual , Audio , Input , File , Variables and Control

Uppercase command words are to be spelled as seen. Although case is actually ignored during script interpretation by PercTest.exe, it is used here to clarify what must be spelled exactly. Alternative spellings for commands are indicated by aka (also known as).

References to file names and messages that include spaces must be enclosed in "double quotes". Commands and subsequent options must be seperated by at least a single space character.

Any lines that begin with an unrecognized command are treated as comments.

The alphabetized list of commands includes... Ask , Call , Concat , Delete , Dxsound , Exit , Form , GoTo , Halt, If , IfNo , IfYes , Instruct , Left , Message , Mono , Output , Picture , Play , Point , Quit , Rand , Read , Rename , Right , Save , Set , Start , Stop , Sum , Text , TextPict , Trouble , Wait and YesNo .

Visual Commands...

FORMAT FormatName option1 option2

  • sets up the display screen with as many as 4 picture frames in various arrangements.
  • Choices thus far are: 1, 2, 3, 4 or ScriptSelect
  • Most choices set the individual frame size to cover 25% of the screen (half the height by half the width).
  • Use these abbreviations when resolving the following options: A=Across (left to right), T=Top, B=Bottom, C=Center, D=Down (top to bottom), R=Right & L=Left
  • When there are 4 frames being used, there is only one arrangement and so any options are ignored. Frame #1 will be in the TL, #2 in the TR, #3 in the BL and #4 in the BR.
  • When displaying only 1 frame, use a number between 10 and 100 to indicate its size, and either TL, TC, TR, BL, BC, BR, CL, CC or CR to indicate its position. The default is CC 75
  • When there are 2 frames, the options are AT, AB, AC, DL, DR, DC and diagonaly TRBL or TLBR. The default is AT
  • When there are 3 frames, the options for #1 & 2 across the top with #3 on the bottom are: ATBL, ATBC, ATBR; for #1 on the top and #2 & 3 across the bottom: TLAB, TCAB, TRAB; #1 & 2 down the left and #3 on the right: DLTR, DLCR, DLBR and finally, #1 on the left and #2 & 3 down the right: TLDR, CLDR, BLDR. The deafult is ATBC.
  • aka: F, FORM

    PICTURE "name of picture file.BMP" /#

  • Loads a picture into next logical picture frame within the form, or within the optionaly specified frame # (1~4).
  • /Stretch turns on picture stretching, /UNStretch
  • /Hide will hide the frame, /UNHide will reveal the frame
  • Aka: P, PIC, PICT

    MESSAGE "something you should know about."

  • displays a message box with an OK button
  • aka: M, MESS

    TEXT "line 1" "line 2" "etc" /options

  • displays a large text box with no buttons
  • Each quoted sentence appears on its own line
  • options include /Show /Hide /Empty /Position /Add (a blank line) /Left /Right /Center and /Wait (one second)
  • These options may be abbreviated to include just the / and the first letter, upper or lower case, and should not be quoted unless they are to be displayed literally.
  • the /Wait option allows for a delay before any subsequent text appears
  • /Empty clears the contents of the box
  • the justification options /L /R /C must preceed the text that it applies to
  • the /Position option should be followed by one of the aspect descriptions: Top Height Left or Width, which in turn should be followed by a numerical value representing the percentage of screen size that aspect is to have. Example: /P W 50 sets the width of the text box to 50 % of the screens width.
  • aka: T, TEX

    TEXTPICT # "Message"
    TEXTPICT # /Hide

  • Displays Message within boundary of corresponding picture frame # 1 through 4. Uses a very large font, center justified, typically one word, rather than having a picture.
  • aka: TP, TPICT, TEXTP

    ^

    Audio Commands...

    PLAY "name of wave file.wav"

  • Plays the wave file and continues immediatly with the next command in the script. Lingering audio is cancelled by next playback.
  • aka: PL, PLA

    INSTRUCT "name of wave file .wav"

  • Plays the wave file and waits till it is finished before continuing with the script.

    LEFT ##
    RIGHT ##
    MONO ## ##

  • Controls the hardware audio mixer's left, right or both channels of the wave out device. The default is no (0) attenuation if none is specified. Range is between 0 and 50 deciBells in 2 dB increments and is designed to work with SoundBlaster or compatible sound cards using the Windows(tm) interface

    DXSOUND FileName.wav /START /STOP /LOOP /RIGHT /LEFT /CENTER /INCREASE /DECREASE
    DXSOUND /DB -##

  • Dxsound commands can contain any number of options on a line. The first time the command comes across filename.wav, it is loaded into memory and also becomes the default wave. This only prepares the system for further commands. Subsequent occurences of filename.wav simply resets that wave to be the default for more yet commands. /Start plays the wave once. /Stop halts the default sound. /Right /Left and /Center control the default sound's panning or balance between speakers. /Loop plays the default wave continuously repeating until the /Stop command is issued. Since up to 1000 waves can be loaded into memory, the filename.wav should be included in the line before issuing controls to stop or change panning, loudness, etc. The options /increase and /decrease adjust the loudness by 5 dB and are cumulative. For finer loudness control, use the /db command and specify how many db the loudness should be reduced, relative to the waves original loudness. The DirectX sound functions provided by Microsoft for Windows need to be installed on the computer. These loudness functions can only control the decrease in volume relative to the wavefile's original level. Unfortunately they cannot be set to boost sounds that are too soft, therefore all numeric values following the /db option are treated as negative values, whether or not they are written as such.

    ^

    User Input Commands...

    ASK "What is your answer?" "optional default response" "optional title"

  • Prompts the user to type in something. The result is stored in the variable %ask as soon as the user presses the [enter] key or clicks on [OK]
  • aka: A, AS

    YESNO "Do you like this message ?"

  • Displays the message with Yes and No buttons. Result is stored in variable %yesno as 'yes' or 'no'. See IFYES, IFNO
  • aka: YN

    READ #

  • Waits for # of seconds for keystroke from keyboard or for mouse click on a picture. If # is negative then READ will wait indefinelty, otherwise the response will be 'timeout' if there is no response within # of seconds. The keystroke's character is stored in the variable %r
  • aka: R, RE, REA

    File Commands...

    OUTPUT FileName what ever you want to save, %variables too

  • This will append one line of text to the specified file with tabs delimiting each word or text string specified in the command.
  • Aka: OUT, OUTP, SAVE

    RENAME SourceFileName TargetFileName

  • This will rename the file with the SourceFileName to become TargetFileName.

    DELETE FileName

  • This will remove the file bearing the FileName.

    ^

    Variables...

    SET TargetVariable value

  • Stores the value as text in target variable. Up to 100 varaibles can be made. After having been set, variables can be used elsewhere in the script by prefixing them with the % symbol. The PercTest intperpreter will resolve such variables before the command is processed.
  • Aka: $, S, SE

    POINT TargetVariable %SourceVariable

  • Stores the contents of SourceVariable within the variable named TargetVariable. Useful when SourceVariable actualy contains the name of another variable whose contents are of interest.
  • Aka: POINTER ^

    SUM TargetVariable value1 value2 etc

  • Stores the numeric sum of all legitimate values into the TargetVariable.
  • Aka: +, ADD

    RAND

  • %rand will be a decimal between 0.000 and 1.000
    RAND #
  • %rand will be an integer between 1 and #

    CONCAT TargetVariable string1 string2 etc

  • Combines all the strings into one and stores the results in TargetVariable.
  • C, CON, CONC

    QUOTE MyVariable

  • Insures that the string contained within MyVariable begins and ends with " (double quotes)
  • aka: Q

    ^

    Program Control Commands...

    WAIT #

  • Waits for # of seconds before proceeding with the next command in the script.
  • aka: W, WA, WAI

    IF x o y THEN command...

  • Runs command... based on operators < = > or !
  • Variables must resolve to a single word or quoted word string.

    IFYES command...
    IFNO command...

  • Runs the command... based on the response to the most recent YESNO command.
  • Similar to the command- IF %yesno = yes THEN command...
  • Aka: IFY, IFN

    :Label optional_comment

  • Indicates the beginning of a script section typically used as a sub-routine. Must begin with : (colon) and consist of only one word (no spaces). Any text after that can be used as a remark to further describe the section.
  • Example-
  • :calculate_score (this is a comment within the parenthesis)

    GOTO label
    GOTO label script_file
    GOTO label script_file parameter1 parameter2 etc

  • Program control jumps to the next occurence of :label relative to the current line being interpreted. Multiple instances of the label are thus allowed.
  • To goto a :label within a different script file- specify the file's name as the second item in the command.
  • To pass information along to the subroutine, include a 3rd (or more) item in the command. Up to 9 items of information can be passed this way. Commands within the sub-routine can then use those parameters as variables %1 %2 through %9 . Beware that these variable will change with each GOTO command.
  • To GOTO a sub-routine within the current script, without having to spell out the entire file name, use a . symbol as the name.
  • aka: G, GO2, G2, GO, GT

    CALL label
    CALL label script_file
    CALL label script_file parameter1 parameter2 etc

  • Very similar to the GOTO command except that program control will eventually return to the next line in the current script, after encountering either the end of the 'called' file, or after encountering one of the commands: EXIT or RETURN.

    EXIT

  • Stops reading the current script and returns to the parent script. Aka: EX, RETURN

    START MyProgram.exe
    START FileName.AssociatedExtension
    START Program.exe Document.doc
    START program.exe "/switches" "directory"

  • Runs any program by name. Options are available for command switches and the 'home' directory.
  • Examples-
  • Start "notepad" "c:\myscript.lst"
  • Start "c:\sounds\sample1.wav" will start playing the waveform 'sample1' with the default playback accessory.
  • Start "c:\jmp\jmp.exe" "PercTestOutput.txt" "c:\My Documents\Data Folder"
  • aka: RUN

    HALT

  • Stops the program and returns to the Windows(tm) operating system.
  • aka: STOP, QUIT

    Multiple Commands On One Line...

  • Use the | (pipe) symbol to seperate multiple commands.
  • Example-
  • set a 1 | set b 2 |
  • set x 1 | set y 2 | sum z %x %y results in %z being invalid since x and y were evaluated when the line was read in from disk. Hopefully, future versions of the program may have this annomoly fixed.

    TROUBLE ON
    TROUBLE OFF
    TROUBLE #

  • Turns troubleshooting mode on or off. Can also specify a number such as 0 for off, 1 for on, 2 or higher turns on advanced levels of troubleshooting. Messages pop up identifying the subroutines being engaged and the parameters with which they are dealing.
  • aka: TRO, TROUB, TRUB, TROUBLESHOOTING

    ^