Streaming convert NKSF files to preview audio with using Bitwig Studio.
npm install bitwig-nks-preview-generatorsh
npm install bitwig-nks-preview-generator -g
install WebSocket RPC server Bitwig Studio Extension
bws-nksf2ogg install
`
Local Install
sh
mkdir my-nks-preview-project
cd my-nks-preview-project
npm init
npm install bitwig-nks-preview-generator --save-dev
install WebSocket RPC server Bitwig Studio Extension
npx bws-nksf2ogg install
`
Command Options
$ bws-nksf2ogg --help
Usage: bws-nksf2ogg [options] [command] Streaming convert NKSF files to preview audio with using Bitwig Studio.
Options:
-V, --version output the version number
-h, --help output usage information
Commands:
exec [options]
Generate preview audio from .nksf preset files.
install [options] Install Bitwig Studio WebSockets RPC server extension.
list [options] List .nksf or .nksf.ogg files.
clean [options] Delete .previews folders recursively.
$ bws-nksf2ogg exec --help
Usage: exec [options]
Generate preview audio from .nksf preset files recursively. Options:
-d, --debug console verbosity level in testing,
0:none 1:ERROR 2:INFO 3:DEBUG 4:Bitwig Studio (default: 0)
-r, --dry-run just check mapper function, generating process is not executed
-b, --bitwig Bitwig Studio execution file path (default: "")
-u, --url Bitwig Studio WebSockets URL (default: "ws://localhost:8887")
-s, --skip-error skip on error, continue processing
-k, --skip-exist skip .nksf file that already has preview audio
-h, --show-plugin show plugin window
-c, --clip .bwclip MIDI clip or [.js | .coffee] mapper program
(default: "/Bitwig Studio Files/NKS-Preview-C2-Single.bwclip")
-f, --fxb directory for store intermediate .fxb files (default: "temp/fxb")
-w, --wav directory for store intermediate .wav files (default: "temp/wav")
-t, --timeout timeout msec for launch & connect Bitwig Studio (default: 30000)
-a, --wait-plugin wait msec for loading plugin (default: 7000)
-i, --wait-preset wait msec for loading .fxb preset (default: 5000)
-e, --tempo BPM for bouncing clip. (default: 120)
-f, --freq sampling rate for output .ogg audio (default: 44100)
-d, --fadeout fadeout duration seconds from end (default: 0.25)
-l, --silence threshold level for removing silence from end, dB or 0-100% (default: "-90dB")
-q, --quality quality of .ogg audio. 0-10 (default: 6)
-h, --help output usage information
$ bws-nksf2ogg install --help
Usage: install [options]
Install Bitwig Studio WebSockets RPC server extension.
Options:
-e, --extension-dir Bitwig Studio Extension directory (default: "")
-h, --help output usage information
$ bws-nksf2ogg list --help
Usage: list [options]
List .nksf or .nksf.ogg files recursively.
Options:
-a, --absolute list files as absolute path
-r, --relative list files as relative path from
-m, --missing list preset files that doesn't have preview
-u, --useless list preview files that doesn't have preset
-f, --sox list files as result of sox --i
-h, --help output usage information
$ bws-nksf2ogg clean --help
Usage: clean [options]
Delete .previews folders recursively.
Options:
-y, --yes no comfirmation
-c, --corrupted find corrupted .nksf.ogg files and clean them
-h, --help output usage information
Procedure for Generating Preview Audio
1. Check WebSocket RPC Server module is enabled in controller preferences panel of Bitwig Studio.
1. Close Bitwig studio application if already it's opened.
1. Execute command on terminal.
1. Bitwig Studio will automatically launch after command.
1. If you see popup message "Please click first clip" on Bitwig Studio, Click (not launch) the clip at Track 1, Slot 1. It's just needed to take focus of Bitwig Studio window for remote automation once at initial time. If note editor is not shown in window, double click might be better because
progress of bouncing can be visually observed.
1 After processing is started, using other application is OK. But don't touch anything on Bitwig Studio.
1. When processing is done, Bitwig Studio will shutdown automatically.$3
`
$ tree -a
└── nksf
├── Repro-1
│ ├── 01\ Solo\ Trumpet.nksf
│ └── 02\ Frequency\ Modulation\ Bells.nksf
└── Serum
├── PL\ Beepy\ ting\ [GI].nksf
└── PL\ Big\ Bells\ [AS].nksf
$ bws-nksf2ogg exec nksf
progress [========================================] 100% | ETA: 0s | 4/4 | PL Big Bells [AS].nksf.ogg
Execution completed with result: 4 files succeeded.
$ tree -a
├── nksf
│ ├── Repro-1
│ │ ├── .previews
│ │ │ ├── 01\ Solo\ Trumpet.nksf.ogg
│ │ │ └── 02\ Frequency\ Modulation\ Bells.nksf.ogg
│ │ ├── 01\ Solo\ Trumpet.nksf
│ │ └── 02\ Frequency\ Modulation\ Bells.nksf
│ └── Serum
│ ├── .previews
│ │ ├── PL\ Beepy\ ting\ [GI].nksf.ogg
│ │ └── PL\ Big\ Bells\ [AS].nksf.ogg
│ ├── PL\ Beepy\ ting\ [GI].nksf
│ └── PL\ Big\ Bells\ [AS].nksf
└── temp
├── fxb
│ ├── Repro-1
│ │ ├── 01\ Solo\ Trumpet.fxb
│ │ └── 02\ Frequency\ Modulation\ Bells.fxb
│ └── Serum
│ ├── PL\ Beepy\ ting\ [GI].fxb
│ └── PL\ Big\ Bells\ [AS].fxb
└── wav
├── Repro-1
│ ├── 01\ Solo\ Trumpet.wav
│ └── 02\ Frequency\ Modulation\ Bells.wav
└── Serum
├── PL\ Beepy\ ting\ [GI].wav
└── PL\ Big\ Bells\ [AS].wav
Adjust Timings
There is no way to know via remote automaition when the plugin or preset loading is finished so far. These timings are depends on plugin and your environment. The options must be set large enough value. Approximate setting time on my environment:
- Hive --wait-preset 1000
- Serum
- Spire
- UVIWorkstation(Key Suite Digital) MIDI Clip Mapper
The mapper .js program allows for mapping NKS sound infomation to your custom MIDI clip.
sh
bws-nksf2ogg exec --clip clip-mapper-example.js
`
An example
js
// use logger to follow --debug option
const log = require('bitwig-nks-preview-generator').logger('custom-mapper')
/**
* Example NKS Preview MIDI clip mapper for UVI Key Suite Digital.
*
* @param {Object} soundInfo - NKS Sound Info (metadata).
* @return {String} - Bitwig Studio MIDI clip file path.
*/
module.exports = function(soundInfo) {
var clip
if (soundInfo.types[0][0] === 'Bass') {
// return absolute path or relative path from this .js file's directory.
clip = 'Bitwig Studio Files/NKS-Preview-C1-Single.bwclip'
} else if (soundInfo.types[0][1].includes('Piano')) {
clip = 'Bitwig Studio Files/NKS-Preview-Cmaj-Chord.bwclip'
} else {
clip = 'Bitwig Studio Files/NKS-Preview-C2-Single.bwclip'
}
log.info('NKS Info:', soundInfo, 'Clip:', clip)
return clip
}
`
- Custom MIDI clip should contains only MIDI data. When edit and save it on Bitwig Studio, don't forget to delete device.
- Support async function.
- Support CoffeeScript.Fadeout
In most case, fadeout doesn't function, beacause note length(1bar) is enough smaller than clip length(2bar). This option is designed to fade out a very slow-release tone or sequence pattern. so I added 8 or 4 note length to clip length for fade margine.
Just for reference, SoX audio filter graph is as follows:
[reverse] -> [fade] -> [silence] -> [reverse] -> [rate]
Module Use
The following modules are available for general use.
$3
#### Usage
js
const gulp = require('gulp');
const nksf2fxb = require('bitwig-nks-preview-generator').nksf2fxb;
gulp.task('nksf2fxb', function() {
return gulp.src('./nksf/*/.nksf')
.pipe(nksf2fxb(options))
.pipe(gulp.dest('./fxb'));
});
`
#### Options Default
js
{
skipError: false // skip on error, need gulp-plumber, default: false
}
`$3
#### Usage
js
const gulp = require('gulp');
const wav2ogg = require('bitwig-nks-preview-generator').wav2ogg;
gulp.task('wav2ogg', function() {
return gulp.src('./wav/*/.wav')
.pipe(wav2ogg(options))
.pipe(gulp.dest('./ogg'));
});
`
#### Options Default
js
{
dotPreviews: true, // append '.prevews' to dirname
nksfDotOgg: true, // rename extension to '.nksf.ogg'
freq: 44100, // sampling rate for output .ogg audio
fadeout: 0.25, // fadeout duration seconds from end
silence: '-90dB', // threshold level for removing silnce from end
quality: 6, // quality of .ogg audio. 0-10'
skipError: false // skip on error, need gulp-plumber, default: false
}
``