KSynthLib 0.20.0

KSynthLib

Patch management utilities for Kawai K series digital synthesizers: K4, K5, K5000 and K1 II.

This project creates a .NET library as a NuGet package that can be installed in .NET application projects.

The library is written in C# 10.0 and targets .NET 6.

Installation from NuGet

The library is available on NuGet.

Local installation

You can also use the library locally. Add the local directory containing your NuGet packages to your NuGet configuration file.

Your NuGet configuration file is most likely ~/.nuget/NuGet/NuGet.Config, and your local directory could be something like /Users/Shared/Library/NuGet (you may need to create this directory).

Add the following to the configuration file.

<packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
    <add key="Local" value="/Users/Shared/Library/NuGet" />
</packageSources>

Build the library:

dotnet build

Then package it up:

dotnet pack

Then add it to your local NuGet repository you configured earlier:

nuget add KSynthLib/bin/Debug/KSynthLib.x.y.z.nupkg -source /Users/Shared/Library/NuGet

where "x.y.z" is the version of the library you want to use.

To automate these steps there is also an installation script for the Bash shell, install.sh. To use it, first set the environment variables:

export KSYNTHLIB_VERSION=0.17.2
export KSYNTHLIB_CONFIGURATION=Debug
export LOCAL_NUGET_PATH=/Users/Shared/Library/NuGet

Then run the script:

bash install.sh

Finally, add the package into your project like any NuGet package:

dotnet add package KSynthLib

Packaging for NuGet release

The library is packed for NuGet release like this:

dotnet build --configuration Release
dotnet pack --configuration Release --include-symbols

Testing

There is an associated test project with unit tests created using xUnit. Run the unit tests with:

dotnet test

For testing the K4 features you should first download the original factory patches for the K4 as MIDI System Exclusive dump files from Kawai USA. Then unzip them into a folder called "Kawai K4 Sounds" in your Documents directory.

Remarks

Most of the synthesizer parameters are represented by domain classes. Many of these classes use a custom type for a range of values. This ensures that invalid values are rejected as early as possible in development. Typically each synthesizer has somewhat different range types, so they are defined separately for each synthesizer in a device-specific Types.cs file.

All the ranged types are derived from the abstract base class RangedValue and are backed by an int type. Deriving a new ranged value type could look like this:

public class Volume: RangedValue
{
    public Volume() : this(0) { }
    public Volume(int value) : base("Volume", new Range<int>(0, 127), 0, value) { }
    public Volume(byte value) : this((int)value) { }
    public byte ToByte() => (byte)(this.Value);
}

You should specify the default value (here 0), the minimum and maximum allowed values (here 0 and 127), and a name to use if an ArgumentOutOfRangeException is thrown due to input values that do not fit the range.

For library consumers it is recommended to create a view model that translates between UI layers of the application and the domain objects in this library.

The range implementation uses the Range.NET library.

Synth-specific observations

Kawai K4

Seems like it's not worth it to compare a patch received from K4 and a patch generated by KSynthLib since the machine-originated can have junk in them, which will not be generated.

For example, the effect setting of a single patch: it should be the bits 0...4 of s11, but right in patch A-1 of A401.SYX you get a byte value of 20h (or 100000b), so you need to mask away everything else just to be sure.

Also, there seems to be no point in comparing the checksum of the original and generated patches, because the original may have spurious bits which cause a change in the checksum. To test checksum calculation it is probably necessary to send the generated patch to the synth and see if it responds with a checksum error or not.