Error Handling

SoundFlow uses Javascript exceptions for error handling.

Whenever an error occurs in a SoundFlow action, it will throw an exception. If that exception is not caught by the script in a try/catch block, the exception will bubble up to the internal SF code running your command and it will then report the exception as an error and display it to the user.

You can however catch those exceptions if you'd like to, and decide what to do in your script. It might be something simple like just displaying a different error message and aborting the script, or you may wish to do something else.

Try/catch blocks

Catching exceptions in Javascript is done in try/catch blocks.

Here's an example that tries to select the Audio 1 track by name. If the action fails, it will throw an exception.

Since the action call is inside a try block, the exception thrown inside the try block will be caught by the try block's corresponding catch block.

So when the error occurs, the try block will stop executing and the script will jump to the catch block.

In this example we're logging a custom error message and then calling throw 0 to silently abort the script.

try {
  sf.ui.proTools.trackSelectByName({
    names: ['Audio 1'],
    deselectOthers: true,
  });
  //If there was an error in the trackSelectByName call,
  //this line won't be executed:
  log('Successfully selected the track');
} catch(err) {
  //Handle the error
  log('Could not select Audio 1 track');
  throw 0; //abort the script
}

An alternative way to do log('something'); followed by throw 0 would be to do simply throw 'something'; which will abort the script and display 'something' as an error.

Error callbacks

All actions in SF accept a 2nd argument after the {...} object (the {...} specifies the options for the action). The 2nd argument can be either an error callback function, or an error message.

If you specify an error callback function as the 2nd argument, the action won't throw an exception if it encounters an error - it will instead call the error function. So this example will do the same as the previous example.

sf.ui.proTools.trackSelectByName({
  names: ['Audio 1'],
  deselectOthers: true,
}, function(err) {
  //Here, we can handle the error
  log('Could not select Audio 1 track');
  throw 0; //abort the script
});

log('Successfully selected the track');

Here, the function(err) { ... } is our error callback function. I've named the first parameter err, but it could be named anything. In that parameter the function will receive the actual underlying error, which you can then choose to display to the user or not.

Error message specifiers

The shortest way of getting custom error messages for each action call is specifying the error message as a string in the 2nd argument.

In this example, if the action fails, it will display the error message 'Could not select Audio 1 track' and terminate the script. If it succeeds, it will ignore the error message we supplied and move on with the script and execute the log('Successfully selected the track');

sf.ui.proTools.trackSelectByName({
  names: ['Audio 1'],
  deselectOthers: true,
}, 'Could not select Audio 1 track');

log('Successfully selected the track');

Consequently, this example would also behave the same as the other two examples. It's just a matter of preference which approach is more convenient for you.