program file decoder for Mac OS

Usage Instructions

Overview of the workflow

Use Nord Sound Manager to upload Program files (ns4p files) or Preset files (ns4o, ns4n, ns4y) from the NS4 to the computer.
Use the instructions shown below to run ns4decode on one or more of those Program and/or Preset files.
View the resulting output files using a plain text editor (Mac OS comes with one called TextEdit) or your favorite spreadsheet app (Mac OS comes with one called Numbers).

How to use ns4decode

After preparing a Terminal window as described in Preparing to use ns4decode, running ns4decode involves writing commands in that Terminal window. These instructions explain how to form those commands, using drag-and-drop wherever possible.

You can also ask ns4decode itself for instructions by running either of these commands (which are equivalent to each other):

ns4decode --help
ns4decode -h

These usage instructions work for both Program files and Preset files, even though they don't mention Preset files

Example 1: decoding a single Program file

Step 1: Open a Finder window and navigate to a folder that has an Program file that you want to decode. ("Finder" is Mac OS's standard interface for navigating through folders and listing the files that they contain.)
Step 2: In the prepared Terminal window, type
ns4decode
followed by a space, but don't press return yet.
Step 3: Drag-and-drop the Program file from step 1 into the Terminal window. This doesn't move the file, it just appends the file's location to the command that you started forming in step 2.
Step 4: Click once anywhere in the Terminal window to bring it back into focus, and then press return. This runs the command that you formed in steps 2-3.

You should see four output files appear in the same folder with the Program file. If the name of the input file is programName.ns4p, then the output files are:

programName_organ.csv, which has the decoded parameter-values for each organ layer,
programName_piano.csv, which has the decoded parameter-values for each piano layer,
programName_synth.csv, which has the decoded parameter-values for each synth layer,
programName_master.csv, which has the decoded parameter-values not tied to any individual layer. This includes the organ FX parameters, because they're the same for both organ layers.

You might be able to open these files in your default spreadsheet app by double-clicking on them. If that doesn't work, then you can right-click on one of them and select Open With > Numbers (or Open With > TextEdit). The contents are formatted as a table in which each row represents one parameter, and the parameter-values for each layer are in separate columns (here's an example).

When decoding a Preset file, only two output files (per input file) are produced: programName_master.csv and one of the others, depending on which type of Preset file was decoded.

Formatting the output files for a plain text editor

If you choose to view the output files using a plain text editor like TextEdit, then you can align the columns by replacing step 2 above with this:

Step 2: In the prepared Terminal window, type
ns4decode --columnwidth 12
followed by a space, but don't press return yet.

You may replace the "12" with whatever you want the minimum column width to be. This abbreviation is equivalent:

Step 2: In the prepared Terminal window, type
ns4decode -c 12
followed by a space, but don't press return yet.

The other steps are the same as in example 1.

Understanding the output files

Most of the items in the output files should be easy to understand for anybody familiar with the Nord Stage 4's parameters, but a few of them are less obvious. In the Terminal window, run the command

ns4decode --helpwith interpret

to get some tips about how to interpret some of the less-obvious items.

Example 2: decoding multiple Program files

To decode multiple Program files, steps 1 and 2 are the same as before. In step 3, instead of dragging-and-dropping a single Program file into the Terminal window, select multiple Program files and drag them all into the Terminal window, all at once. (Or you can drag them in one-at-a-time, if you prefer.) Step 4 is the same as before. Multiple files with names ending in .csv should appear — a set of four output files for each of the Program files you selected, just as if you had run ns4decode on each of them individually.

In step 2, instead of dragging-and-dropping a set of Program files the Terminal window, you may (if you prefer) drag one or more folders into the Terminal window. Then ns4decode will find all of the files with names ending in .ns4p in those folder(s) (recursively), tell you how many files it found, and ask if you're sure you want to decode them all.

Example 3: sending the outputs to a specified folder

If you don't want the output files to be written in the same folder(s) as the Program files, then you can tell ns4decode where to write them by following these steps:

Step 1: Create a folder to hold the outputs that ns4decode will write. You may give the folder whatever name you want, but this example will pretend that you named it outputFolder. You can create this folder on your Desktop, or you can open a Finder window and navigate to wherever you want to create the folder.
Step 2: In the prepared Terminal window, type either one of the equivalent commands
ns4decode --writeto
ns4decode -w
followed by a space, but don't press return yet.
Step 3: Drag-and-drop outputFolder from step 1 into the Terminal window. This doesn't move the folder, it just appends the folder's location to the command that you started forming in step 2.
Step 4: To tell ns4decode which Program files you want to decode, use steps 3 and 4 from example 2.

You should see the output files (with names ending in .csv) appear in outputFolder.

Example 4: excluding parameters in inactive sections/layers/etc

By default, the output files show the values of all of the parameters that ns4decode knows how to decode, even if those parameters don't affect the sound, like the parameters in a layer that is turned off. You can tell ns4decode to omit the values of most of those parameters. This feature doesn't omit all unused parameters, but it does omit most of the major groupings of unused parameters (sections, layers, and some smaller groupings). To use this feature, replace step 2 above with this one:

Step 2: In the prepared Terminal window, type either one of the equivalent commands
ns4decode --exclude
ns4decode -x
followed by a space, but don't press return yet.

The other steps are the same as before.

Combining options

The options -c, -x, and -w in the preceding examples may be combined. You could replace step 2 in example 1 with this:

Step 2: In the prepared Terminal window, type
ns4decode -c 12 -x
followed by a space, but don't press return yet.

The other steps are the same as in example 1. The Program file(s) should always be dragged-and-dropped last, after the rest of the command is formed. Or you could replace step 2 in example 3 with this:

Step 2: In the prepared Terminal window, type
ns4decode -c 12 -x -w
followed by a space, but don't press return yet.

The other steps are the same as in example 3. Whatever comes right after the -w will be treated as the folder where you want the output files to be written. Everything after that will be treated as a Program file to be decoded.

Example 5: decoding only selected parameters from multiple Program files

To compare only a selected set of parameters across multiple Program files, follow these steps:

Step 1: In the prepared Terminal window, type either one of the equivalent commands
ns4decode --listparams
ns4decode -l
and press return. This gives you a list of available parameters, each with a concise parameter-code next to its name.
Step 2: Decide which parameters you want to compare, and type this in the Terminal window:
    ns4decode (...list of parameter-codes...)
but don't press return yet. If you chose parameters -m 17, -y 2, and -y 3, then the command will look like this:
    ns4decode -c 12 -m 17 -y 2 -y 3
or you can abbreviate it like this:
    ns4decode -c 12 -m 17 -y 2,3
The -c 12 option is included to help align the columns. Make sure there are spaces between the letters and numbers, but no spaces in the comma-delineated list of numbers. Make sure there is a space at the end. Don't press return yet.
Step 3: To finish forming the command, use steps 3-4 from example 2, and then press return to run the command.

That command doesn't write a file, but it does display a table in the Terminal window. The table has one row for each Program file, and it has these columns:

one column showing the bank/location that the Program was in at the time the Program file was uploaded from the NS4,
either 1, 2, or 3 columns (depending on the number of layers) for each of the parameters you specified,
one column showing the name of the Program (deduced from the name of the Program file).

If you want to view the output in Numbers, you can use the mouse to highlight the output text in the Terminal window and then use cmd-C and cmd-V to copy-and-paste it into an open empty Numbers spreadsheet. Or you can tell Terminal to send the output directly to a .csv file by using one of the standard unix tricks that you can learn about by running the command

ns4decode --helpwith tricks

nord stage 4