Skip to main content
Topic: Getting started with NWC2 User Tools (Read 58092 times) previous topic - next topic

Getting started with NWC2 User Tools

NoteWorthy Composer 2 includes a new User Tool facility.

Some facts about the User Tool facility:

  • User Tools are accessed from the Tools, User Tool command, or from the keyboard using Alt+F8.
  • A User Tool processes notation contained in a single staff, or selected portion of a staff.
  • When a User Tool is invoked, NWC2 passes a text description of the staff notation to the tool. This text is commonly called NWC2 Clip Text. Each line of text represents a single object on the NWC2 staff, such as a chord, note, text expression, or tempo item.
  • Each User Tool is actually a stand alone program or script that accepts NWC2 Clip Text as input, and can output new or updated Clip Text back to NWC2.
  • NWC2 fully supports the User Tool mechanism out of the box, but it does not come prepackaged with any actual tools. A starter kit built around the PHP scripting language can be downloaded from this topic.

If you are already using NWC2, then the easiest way to get started with the User Tool facility is by downloading and installing the NWC2 User Tool Starter Kit. It will automatically detect your existing copy of NWC2 and setup a set of scripts for immediate use.

The starter kit includes the following tools:

  • About Starter Kit (nwsw)
    This script simply displays a message describing the start kit and the currently installed version of the utility library.
  • Arpeggiate (nwsw)
    This script adds leading grace notes into selected quarter, half, or whole note chords in order to create an arpeggio sound effect during play back.
  • Retrograde (nwsw)
    This script is used to retrograde selected notation in a staff.
  • Statistics (nwsw)
    This simple script counts the items in the selection and reports back the results.
  • Unjazzify (nwsw)
    This script will find note pairs where the first note is a dotted note, and the second is half the notehead duration of the first and is not dotted. It will convert the pair into two notes of equal duration.
  • Variable Dump for Developers (nwsw)
    Targetted at script writers, this script enables a developer to explore the array tree built by the library included in this package.

The starter kit also includes the following scripts from Andrew Purdam:

  • Compound Autobeam (adp)
    Beams complex time sigs according to user-specified template.
  • Global Modification (adp)
    Permits you to globally modify particular components in a staff.
  • Parts (adp)
    Permits you to separate a part in polyphony.
  • Ranges (adp)
    Script that returns the note ranges in a selection.
  • Transpose Chords (adp)
    A script which will automatically transpose chords written as text.

Using prompts when invoking a User Tool

Reply #1
This example demonstrates prompting for data before invoking a User Tool.

The actual tool script looks like this:

Code: (nwsw_PromptExample.php) [Select · Download]
// nwsw_PromptExample.php Version 1.0
// This script demonstrates the prompting mechanism in NWC2 User Tools.
// Copyright © 2004 by NoteWorthy Software, Inc.
// All Rights Reserved
// History:
// 2004-12-12: Initial release (1.0)

$clip = new NWC2Clip('php://stdin');

$raw_argv = print_r($argv,true);

echo <<<___EOTEXT
This script demonstrates one method for passing command line
arguments into a user tool. This demonstration accepts three
options, each of which are prompted on the scripts behalf
by NWC2.

The built-in argc and argv variables are set as follows:
\$argc = $argc
\$argv = $raw_argv

The result of the example processing of the options is
shown below. To see how this was done, simply look at
the source for this script.


// Below is an example of one technique for evaluating the arguments passed
// to the script
$opts = array();
foreach ($argv as $k => $v) {
  if (!$k) continue;

  if (preg_match('/^\/(opt[1-3])\=(.*)$/',$v,$m)) {
    $optname = $m[1];
    $optvalue = $m[2];
    $opts[$optname] = $optvalue;

if (isset($opts["opt1"])) {
  echo "\nOption 1 is set with the following data: $opts[opt1]\n";

if (isset($opts["opt2"])) {
  echo "\nOption 2 is set with the following data: $opts[opt2]\n";

if (isset($opts["opt3"])) {
  echo "\nOption 3 is set with the following data: $opts[opt3]\n";


The Command used in the NWC2 User Tool Description is as follows:

Code: [Select · Download]
'php\php.exe scripts\nwsw_PromptExample.php "/opt1=<PROMPT:Prompt 1: Select an option from this list:=|Quarter|8th|16th|32nd>" "/opt2=<PROMPT:Prompt 2: Enter a number=#[0,15]>" "/opt3=<PROMPT:Prompt3: Enter some text=*>"'

Backing up your script commands (Re: Getting started with NWC2 User Tools)

Reply #2
I was going to ask this but discovered myself (aint I smart? :D) and wanted to share:

So you have quite a few user tool scripts with various parametres stored under your Tools > User Tool... dialogue as I do? Probably you'd like to to make a backup of them now and then. But how? So simple.

They are stored in a plain text file named nwc2UserTools.ini under the directory defined in Tools > Options > Folders > Config Files, which is by default \NoteWorthy Composer 2\Config.

Backup that file. :)

PS: Thanks Eric, updated per your post!

Re: Getting started with NWC2 User Tools

Reply #3
More precisely, the User Tool setttings are stored in the folder located by Tools, Options, Folders, Config Files.

Re: Getting started with NWC2 User Tools

Reply #4
Version 1.13 of the NWC2 User Tool Starter Kit has now been released. It includes minor updates to many of the scripts.

Re: Getting started with NWC2 User Tools

Reply #5
So...I'm trying to download the User Tools, v1.21, and it tells me my NWC is either not installed or has been altered since installation. 
Duh...I've kept up with the updates to the 2.x beta.

It's not a Firefox issue, I've tried IE and Firefox both.  Is there something else I'm missing somewhere??



Re: Getting started with NWC2 User Tools

Reply #6
This error means that the NWC2 uninstall information does not point to the correct NWC2 program files location. There are two possible causes for this (assuming you actually have NWC2 installed):

  • You manually moved the NWC2 program files from the original location where they were installed.
  • You manually removed the NWC2 uninstall key from the registry.

You can correct this by reinstalling NWC2 or by manually correcting the folder paths found in the following registry area:

Code: [Select · Download]
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\NoteWorthy Composer 2


Reply #7
Can I put comments into a clip text file? It would help diagnosis a lot. And what happens to SYSERR if the script completes OK?

Re: Comments

Reply #9
Can I put comments into a clip text file?
Yes. They will display in the STDOUT popup, but they are discarded when STDOUT is parsed back into the song.
Some further discussion <here>.

what happens to SYSERR if the script completes OK?
If the script completes OK, there can be no SYSERR. One shouldn't care about what happens to it.
Registered user since 1996

Re: Comments

Reply #10
Noteworthy Online - Thank you; I should have found this; I am an idiot; thank you for not telling me so.

Rick G - You are a better coder than me. I often find that the script finishes, but produces something different from what I expected. Without some means of monitoring flow and checking values of variables it is hard to find the bug. Thank you, though.

Re: Comments

Reply #11
Without some means of monitoring flow and checking values of variables it is hard to find the bug. Thank you, though.
If you are coding in JScript or VBScript, I may be able to help.

Put WScript.Quit(99) where your program ends. This will cause NWC2 to display STDOUT to you (comments and all). Comment out the line or change it to: WScript.Quit(0) to test normal operation.

In JScript, I declare an array (e.g., var a = [];) and push things I'm interested in on to it.
At program end, I use: WScript.Echo(a.join("\n"));
Registered user since 1996

Re: Getting started with NWC2 User Tools

Reply #12
One possible use of the new "Run User Tool" tool is to aid in new user tool testing/debugging.

If you run your new clip script via the "RUT" tool, and you check the box to "Display summary of changes, if user tool returns success", then you will see a NWCTXT "delta" of the changes that your script made.  The delta for each staff is shown in turn separately.  At any point, you can make "backdoor" changes to your script, then do a "back" and a "next" in RUT, and see the new results of your script, all without leaving the RUT environment.  Once happy with the changes, you can proceed out of RUT and see your changes applied within NWC2.

The RUT user tool entry to invoke your new user tool could have a command like this:
php\php.exe scripts\prw_RunUserTool.wxphp display all "<yourtoolname>"

The display pre-checks the box to display summaries of changes, and the all says to do all staffs in turn.  Make sure to set an "Input Type" of "File Text", and check the options "Returns File Text" and "Prompts for User Input".


Re: Getting started with NWC2 User Tools

Reply #13
I am trying to create tool that allows the user to enter a specific entity such as an instrument change, clef, dynamic or barline at the current cursor position. I looked at the examples in the User Tools and they all seem to apply changes to the entire file, or a selection of notes. Is there any way of inserting a specific entity at the cursor position?

Re: Getting started with NWC2 User Tools

Reply #14
Is there any way of inserting a specific entity at the cursor position?
It is possible by requiring File text and returning File text. NWC will prompt you to save your work since the change cannot be undone :(

More discussion at: Insert entity at current cursor position working example.
Registered user since 1996