Guide / Tutorial TARGET SCRIPTING TUTORIAL: Adding sound effects to your scripts

[Clicker]

UPDATED: added default value to volume and loops arguments

Hi all,

One of those things I wanted to do some time back but couldn't work out how.
Well, I've now worked out how.

What you need is 'sounder.exe', a command line wav file player applet which can be downloaded from https://www.elifulkerson.com/projects/commandline-wav-player.php .
The source file is available so you can be assured it does not contain any viruses.
You will also need some sound effects files.
Sounder works with .wav files, which you can can find plenty of within windows itself or on-line.

Running sounder.exe from a command prompt (inside the folder you copied it to) without arguments gives you a help file.
From there you will see what arguments it will accept.
I suggest you try it out from the command prompt first to make sure it's working before you start playing with your TARGET script.

For the purposes of this tutorial, I created a folder on my c:\ drive called 'Thrustmaster\ED_TargetScript' and copied sounder.exe there .
I then created a subfolder called 'sounds', into which I dropped the sound effect files I want.

Here's my fully commented code (more comments than code!!)

Spoiler

//------------------//
// WAV Sound Player //
//------------------//

// Set SoundPath to where you copied sounder.exe. Add any command line arguments you want within 'SoundCMD'!
// Set WAVPath to where you copied any wav files you wish to use
// Run sounder.exe in a command prompt (from where you copied it) with no arguments etc to see a list of options

// Requires:    - sounder.exe ( https://www.elifulkerson.com/projects/commandline-wav-player.php )
//                - SoundPath alias to be correctly set
//                - WAVPath alias to be correct set
//                - <wavfile>.wav to exist inside WAVPath
//
// Optional:    SoundCMD alias for additional command line arguments if required

// GLOBAL VARIABLES
// ----------------

// Below aliases are for example only. You need to set these according to where you copied sounder.exe and your wav files to

alias    SoundPath            = "c:\\Thrustmaster\\ED_TargetScript\\sounder.exe";
alias    WAVPath                = "c:\\Thrustmaster\\ED_TargetScript\\sounds\\";
alias    SoundCMD            = "";

// FUNCTION:    Play WAV file sound effects
// Parameters:    - wavfile = Name of wav file to be played. '.wav' is optional
//                - vol = volume% (some wav files are much quieter than others)
//                - loops = times to play sound
//
// Example1:        fnSoundFX("wding", 75, 5);    // will play 'wding.wav' at 75% volume 5 times
// Example2:        fnSoundFX("tada");                // will play 'tada.wav' at 100% volume once

// NOTE: Some wav files cannot have their volume adjusted...this is a wav file issue and not the sounder.exe application

int fnSoundFX(int wavfile, int vol=100, int loops=1) {

// I use the 'system();' function to call external programs as I cannot get 'Spawn();' to work on Windows 10.

    char    SysCmd;                // Character array to dynamically build the system command
    Dim(&SysCmd, 255);            // Increase buffersize if your entire string exceeds 255 characters
    SysCmd[0] = 0;                // Zero out the array

    sprintf(&SysCmd, "start %s %s /vol %d /loop %d %s%s", &SoundPath, &SoundCMD, vol, loops, &WAVPath, wavfile);

    system(&SysCmd);            // send command to Windows
 
}

You must set the aliases correctly for 'SoundPath' and 'WAVPath' to point to where you copied sounder.exe and the wav files you want to play.
The TARGET Script syntax is included in the comments of the code.

To use this function inside your TARGET script, simply call the function and parse the name of the wav file you want to play, the relative volume and the number of times (loops) to play the sound effect.

Example:

fnSoundFX("tada.wav", 100, 5);

This will play 'tada.wav" at 100% volume, 5 times in a row.
(the .wav extension on the filename in sounder.exe is optional...it expects a .wav file)
EDIT: Volume switch does not work for all .wav files...this is to do with the file...not the app

The system(); call I make here 'starts' sounder.exe in parallel to your script.
This means it should not cause your script to wait for it to finish, thus zero delay impacts on your script.

Technically, you could play .wav music files using this method, however, the system call runs sounder as a background task, so once started, you cannot adjust the volume on the fly or stop it (without going into task manager).
EDIT: You can issue "sounder /stop" to stop playing a .wav file or by using the /id and /stopbyid feature ... see the help

Happy to help anyone who may have issues getting this going.
Post here or PM me.

Have fun.

Clicker

CREDITS: Eli Fulkerson for the sounder.exe command line wav file player utility.

 

[Clicker]

UPDATE: added default value for volume and loops.

NOTE: Volume cannot be adjusted for all WAV files...this is an aspect of the wav file itself and not a limitation or bug in the sounder.exe applet.

Cheers
Clicker