Package detail

node-serum2-preset-packager

CharlesBT1.2kMIT1.2.4

Xfer Serum 2 Preset Packager for NodeJS

xfer, serum, serum2, Steve Duda

readme

node-serum2-preset-packager

Encode and decode Xfer Serum 2 .SerumPreset files with TypeScript.

This package provides utilities and a CLI for converting between Serum 2 preset files and JSON, making it easy to inspect, modify, or generate presets programmatically.

Features

  • Unpack: Convert .SerumPreset files to readable JSON.
  • Pack: Convert JSON files back to .SerumPreset format.
  • CLI & API: Use from the command line or integrate into your own TypeScript/Node.js projects.

Installation

# using npm
npm install node-serum2-preset-packager
# or using pnpm
pnpm install node-serum2-preset-packager
# run build scripts for dependencies @mongodb-js/zstd
pnpm approve-builds

Usage

Programmatic API

import { unpack, pack } from 'node-serum2-preset-packager'

// Unpack a SerumPreset file to JSON
await unpack('input.SerumPreset', 'output.json')

// Pack a JSON file to SerumPreset
await pack('input.json', 'output.SerumPreset')

CLI

# Unpack a SerumPreset file to JSON
node cli.js unpack <file.SerumPreset> <out.json>

# Pack a JSON file to SerumPreset
node cli.js pack <in.json> <out.SerumPreset>

Project Structure

  • dist/ - Distribution files
  • src/ - Core library code
  • test/ - test scripts
  • test/decode/ - Example .SerumPreset files
  • test/encode/ - Example JSON files

Thanks

Special thanks to Kenneth Wussmann for the original Serum 2 preset packager implementation in Python, which inspired this TypeScript version.

Serum 2 Preset Format - JSON Schema

{
  "metadata": {
    "fileType": "SerumPreset",
    "hash": "f7e5b9fc64e4a1f69aff9b8cef5bbb81",
    "presetAuthor": "",
    "presetDescription": "",
    "presetName": "temp1",
    "product": "Serum2",
    "productVersion": "2.0.19",
    "tags": ["Wavetable", "Poly"],
    "url": "https://xferrecords.com/",
    "vendor": "Xfer Records",
    "version": 7
  },
  "data": {
    "Arp0": {
      "plainParams": "default"
    },
    "ArpClip0": {
      "clip": {},
      "plainParams": "default"
    },
    "ArpClip1": {
      "clip": {},
      "plainParams": "default"
    },
    "ArpClip10": {
      "clip": {},
      "plainParams": "default"
    },
    "ArpClip11": {
      "clip": {},
      "plainParams": "default"
    },
    "ArpClip2": {
      "clip": {},
      "plainParams": "default"
    },
    "ArpClip3": {
      "clip": {},
      "plainParams": "default"
    },
    "ArpClip4": {
      "clip": {},
      "plainParams": "default"
    },
    "ArpClip5": {
      "clip": {},
      "plainParams": "default"
    },
    "ArpClip6": {
      "clip": {},
      "plainParams": "default"
    },
    "ArpClip7": {
      "clip": {},
      "plainParams": "default"
    },
    "ArpClip8": {
      "clip": {},
      "plainParams": "default"
    },
    "ArpClip9": {
      "clip": {},
      "plainParams": "default"
    },
    "ClipPlayer": {
      "kUIParamPianoRollNotePreview": 1,
      "kUIParamPreviewClip": 0,
      "kUIParamSelectedClip": 0
    },
    "ClipPlayer0": {
      "plainParams": "default"
    },
    "Env0": {
      "plainParams": {
        "kParamCurve1": 50,
        "kParamCurve2": 66.60000000000001,
        "kParamCurve3": 66.60000000000001
      }
    },
    "Env1": {
      "plainParams": {
        "kParamCurve1": 50,
        "kParamCurve2": 66.60000000000001,
        "kParamCurve3": 66.60000000000001
      }
    },
    "Env2": {
      "plainParams": {
        "kParamCurve1": 50,
        "kParamCurve2": 66.60000000000001,
        "kParamCurve3": 66.60000000000001
      }
    },
    "Env3": {
      "plainParams": {
        "kParamCurve1": 50,
        "kParamCurve2": 66.60000000000001,
        "kParamCurve3": 66.60000000000001
      }
    },
    "FXRack0": {
      "FX": [],
      "displayName": "",
      "plainParams": "default"
    },
    "FXRack1": {
      "FX": [],
      "displayName": "",
      "plainParams": "default"
    },
    "FXRack2": {
      "FX": [],
      "displayName": "",
      "plainParams": "default"
    },
    "Filter": {
      "kUIParamMixOrGain": 0
    },
    "Global0": {
      "plainParams": "default"
    },
    "GranularOsc": [
      {
        "kUIParamDisplayXYInput": 0
      },
      {
        "kUIParamDisplayXYInput": 0
      },
      {
        "kUIParamDisplayXYInput": 0
      }
    ],
    "LFO0": {
      "curveData": {},
      "pathData": {},
      "plainParams": "default"
    },
    "LFO1": {
      "curveData": {},
      "pathData": {},
      "plainParams": "default"
    },
    "LFO2": {
      "curveData": {},
      "pathData": {},
      "plainParams": "default"
    },
    "LFO3": {
      "curveData": {},
      "pathData": {},
      "plainParams": "default"
    },
    "LFO4": {
      "curveData": {},
      "pathData": {},
      "plainParams": "default"
    },
    "LFO5": {
      "curveData": {},
      "pathData": {},
      "plainParams": "default"
    },
    "LFO6": {
      "curveData": {},
      "pathData": {},
      "plainParams": "default"
    },
    "LFO7": {
      "curveData": {},
      "pathData": {},
      "plainParams": "default"
    },
    "LFO8": {
      "curveData": {},
      "pathData": {},
      "plainParams": "default"
    },
    "LFO9": {
      "curveData": {},
      "pathData": {},
      "plainParams": "default"
    },
    "LFOPointModBus0": {
      "plainParams": "default"
    },
    "LFOPointModBus1": {
      "plainParams": "default"
    },
    "LFOPointModBus10": {
      "plainParams": "default"
    },
    "LFOPointModBus11": {
      "plainParams": "default"
    },
    "LFOPointModBus12": {
      "plainParams": "default"
    },
    "LFOPointModBus13": {
      "plainParams": "default"
    },
    "LFOPointModBus14": {
      "plainParams": "default"
    },
    "LFOPointModBus15": {
      "plainParams": "default"
    },
    "LFOPointModBus2": {
      "plainParams": "default"
    },
    "LFOPointModBus3": {
      "plainParams": "default"
    },
    "LFOPointModBus4": {
      "plainParams": "default"
    },
    "LFOPointModBus5": {
      "plainParams": "default"
    },
    "LFOPointModBus6": {
      "plainParams": "default"
    },
    "LFOPointModBus7": {
      "plainParams": "default"
    },
    "LFOPointModBus8": {
      "plainParams": "default"
    },
    "LFOPointModBus9": {
      "plainParams": "default"
    },
    "Macro0": {
      "plainParams": "default"
    },
    "Macro1": {
      "plainParams": "default"
    },
    "Macro2": {
      "plainParams": "default"
    },
    "Macro3": {
      "plainParams": "default"
    },
    "Macro4": {
      "plainParams": "default"
    },
    "Macro5": {
      "plainParams": "default"
    },
    "Macro6": {
      "plainParams": "default"
    },
    "Macro7": {
      "plainParams": "default"
    },
    "MidiClip0": {
      "clip": {},
      "plainParams": "default"
    },
    "MidiClip1": {
      "clip": {},
      "plainParams": "default"
    },
    "MidiClip10": {
      "clip": {},
      "plainParams": "default"
    },
    "MidiClip11": {
      "clip": {},
      "plainParams": "default"
    },
    "MidiClip2": {
      "clip": {},
      "plainParams": "default"
    },
    "MidiClip3": {
      "clip": {},
      "plainParams": "default"
    },
    "MidiClip4": {
      "clip": {},
      "plainParams": "default"
    },
    "MidiClip5": {
      "clip": {},
      "plainParams": "default"
    },
    "MidiClip6": {
      "clip": {},
      "plainParams": "default"
    },
    "MidiClip7": {
      "clip": {},
      "plainParams": "default"
    },
    "MidiClip8": {
      "clip": {},
      "plainParams": "default"
    },
    "MidiClip9": {
      "clip": {},
      "plainParams": "default"
    },
    "ModSlot0": {
      "plainParams": "default"
    },
    "ModSlot1": {
      "plainParams": "default"
    },
    "ModSlot10": {
      "plainParams": "default"
    },
    "ModSlot11": {
      "plainParams": "default"
    },
    "ModSlot12": {
      "plainParams": "default"
    },
    "ModSlot13": {
      "plainParams": "default"
    },
    "ModSlot14": {
      "plainParams": "default"
    },
    "ModSlot15": {
      "plainParams": "default"
    },
    "ModSlot16": {
      "plainParams": "default"
    },
    "ModSlot17": {
      "plainParams": "default"
    },
    "ModSlot18": {
      "plainParams": "default"
    },
    "ModSlot19": {
      "plainParams": "default"
    },
    "ModSlot2": {
      "plainParams": "default"
    },
    "ModSlot20": {
      "plainParams": "default"
    },
    "ModSlot21": {
      "plainParams": "default"
    },
    "ModSlot22": {
      "plainParams": "default"
    },
    "ModSlot23": {
      "plainParams": "default"
    },
    "ModSlot24": {
      "plainParams": "default"
    },
    "ModSlot25": {
      "plainParams": "default"
    },
    "ModSlot26": {
      "plainParams": "default"
    },
    "ModSlot27": {
      "plainParams": "default"
    },
    "ModSlot28": {
      "plainParams": "default"
    },
    "ModSlot29": {
      "plainParams": "default"
    },
    "ModSlot3": {
      "plainParams": "default"
    },
    "ModSlot30": {
      "plainParams": "default"
    },
    "ModSlot31": {
      "plainParams": "default"
    },
    "ModSlot32": {
      "plainParams": "default"
    },
    "ModSlot33": {
      "plainParams": "default"
    },
    "ModSlot34": {
      "plainParams": "default"
    },
    "ModSlot35": {
      "plainParams": "default"
    },
    "ModSlot36": {
      "plainParams": "default"
    },
    "ModSlot37": {
      "plainParams": "default"
    },
    "ModSlot38": {
      "plainParams": "default"
    },
    "ModSlot39": {
      "plainParams": "default"
    },
    "ModSlot4": {
      "plainParams": "default"
    },
    "ModSlot40": {
      "plainParams": "default"
    },
    "ModSlot41": {
      "plainParams": "default"
    },
    "ModSlot42": {
      "plainParams": "default"
    },
    "ModSlot43": {
      "plainParams": "default"
    },
    "ModSlot44": {
      "plainParams": "default"
    },
    "ModSlot45": {
      "plainParams": "default"
    },
    "ModSlot46": {
      "plainParams": "default"
    },
    "ModSlot47": {
      "plainParams": "default"
    },
    "ModSlot48": {
      "plainParams": "default"
    },
    "ModSlot49": {
      "plainParams": "default"
    },
    "ModSlot5": {
      "plainParams": "default"
    },
    "ModSlot50": {
      "plainParams": "default"
    },
    "ModSlot51": {
      "plainParams": "default"
    },
    "ModSlot52": {
      "plainParams": "default"
    },
    "ModSlot53": {
      "plainParams": "default"
    },
    "ModSlot54": {
      "plainParams": "default"
    },
    "ModSlot55": {
      "plainParams": "default"
    },
    "ModSlot56": {
      "plainParams": "default"
    },
    "ModSlot57": {
      "plainParams": "default"
    },
    "ModSlot58": {
      "plainParams": "default"
    },
    "ModSlot59": {
      "plainParams": "default"
    },
    "ModSlot6": {
      "plainParams": "default"
    },
    "ModSlot60": {
      "plainParams": "default"
    },
    "ModSlot61": {
      "plainParams": "default"
    },
    "ModSlot62": {
      "plainParams": "default"
    },
    "ModSlot63": {
      "plainParams": "default"
    },
    "ModSlot7": {
      "plainParams": "default"
    },
    "ModSlot8": {
      "plainParams": "default"
    },
    "ModSlot9": {
      "plainParams": "default"
    },
    "MultiSampleOsc": [
      {
        "kUIParamMultiSampleOverviewMouseTag": 0
      },
      {
        "kUIParamMultiSampleOverviewMouseTag": 0
      },
      {
        "kUIParamMultiSampleOverviewMouseTag": 0
      }
    ],
    "Osc": [
      {
        "kUIParamAutoSyncSlicing": 0,
        "kUIParamShowMarkerAnimations": 0,
        "kUIParamZoomToStartEnd": 0
      },
      {
        "kUIParamAutoSyncSlicing": 0,
        "kUIParamShowMarkerAnimations": 0,
        "kUIParamZoomToStartEnd": 0
      },
      {
        "kUIParamAutoSyncSlicing": 0,
        "kUIParamShowMarkerAnimations": 0,
        "kUIParamZoomToStartEnd": 0
      },
      {
        "kUIParamAutoSyncSlicing": 0,
        "kUIParamShowMarkerAnimations": 0,
        "kUIParamZoomToStartEnd": 0
      },
      {
        "kUIParamAutoSyncSlicing": 0,
        "kUIParamShowMarkerAnimations": 0,
        "kUIParamZoomToStartEnd": 0
      }
    ],
    "Oscillator0": {
      "GranularOsc0": {
        "plainParams": "default"
      },
      "MultiSampleOsc0": {
        "plainParams": "default"
      },
      "SampleOsc0": {
        "plainParams": "default"
      },
      "SpectralOsc0": {
        "plainParams": "default"
      },
      "WTOsc0": {
        "flex": {},
        "numChannels": 1,
        "numFrames": 18432,
        "plainParams": "default",
        "relativePathToWT": "S2 Tables/Default Shapes.wav",
        "sampleRate": 44100
      },
      "plainParams": "default"
    },
    "Oscillator1": {
      "GranularOsc1": {
        "plainParams": "default"
      },
      "MultiSampleOsc1": {
        "plainParams": "default"
      },
      "SampleOsc1": {
        "plainParams": "default"
      },
      "SpectralOsc1": {
        "plainParams": "default"
      },
      "WTOsc1": {
        "flex": {},
        "numChannels": 1,
        "numFrames": 18432,
        "plainParams": "default",
        "relativePathToWT": "S2 Tables/Default Shapes.wav",
        "sampleRate": 44100
      },
      "plainParams": "default"
    },
    "Oscillator2": {
      "GranularOsc2": {
        "plainParams": "default"
      },
      "MultiSampleOsc2": {
        "plainParams": "default"
      },
      "SampleOsc2": {
        "plainParams": "default"
      },
      "SpectralOsc2": {
        "plainParams": "default"
      },
      "WTOsc2": {
        "flex": {},
        "numChannels": 1,
        "numFrames": 18432,
        "plainParams": "default",
        "relativePathToWT": "S2 Tables/Default Shapes.wav",
        "sampleRate": 44100
      },
      "plainParams": "default"
    },
    "Oscillator3": {
      "NoiseOsc3": {
        "detuneFactor": 0.4758218478413068,
        "numChannels": 1,
        "numFrames": 78241,
        "plainParams": "default",
        "relativePathToNoiseSample": "Organics/AC hum1.wav",
        "sampleRate": 44100
      },
      "plainParams": "default"
    },
    "Oscillator4": {
      "SubOsc4": {
        "plainParams": "default"
      },
      "plainParams": "default"
    },
    "PitchQuantizer0": {
      "plainParams": "default",
      "scale": [0, 2, 0, 2, 0, 0, 2, 0, 2, 0, 2, 0],
      "scaleName": "Major"
    },
    "RetriggerState0": {
      "plainParams": "default"
    },
    "RoutingSlot0": {
      "plainParams": "default"
    },
    "RoutingSlot1": {
      "plainParams": "default"
    },
    "RoutingSlot2": {
      "plainParams": "default"
    },
    "RoutingSlot3": {
      "plainParams": "default"
    },
    "RoutingSlot4": {
      "plainParams": "default"
    },
    "RoutingSlot5": {
      "plainParams": "default"
    },
    "RoutingSlot6": {
      "plainParams": "default"
    },
    "SerumGUI": {
      "kUIParamShowKeyboard": 1,
      "kUIParamShowMidiOut": 0
    },
    "SpectralOsc": [
      {
        "kUIParamDisplayXYInput": 0,
        "kUIParamShowWaveformDisplay": 0
      },
      {
        "kUIParamDisplayXYInput": 0,
        "kUIParamShowWaveformDisplay": 0
      },
      {
        "kUIParamDisplayXYInput": 0,
        "kUIParamShowWaveformDisplay": 0
      }
    ],
    "VoiceFilter0": {
      "plainParams": "default"
    },
    "VoiceFilter1": {
      "plainParams": "default"
    },
    "VoicePanel0": {
      "displayName": "",
      "plainParams": "default"
    },
    "WTOsc": [
      {
        "kUIParamWTOverviewMouseTag": 0
      },
      {
        "kUIParamWTOverviewMouseTag": 0
      },
      {
        "kUIParamWTOverviewMouseTag": 0
      }
    ],
    "arpBankDisplayName": "",
    "clipBankDisplayName": "",
    "fileType": "SerumPreset",
    "lockOversampling": false,
    "lockTuning": false,
    "mpeConfig": 0,
    "mpeEnabled": false,
    "mpePitchBendRange": 48,
    "presetAuthor": "",
    "presetDescription": "",
    "presetName": "temp1",
    "product": "Serum2",
    "productVersion": "2.0.19",
    "scalars": {
      "note": {},
      "velo": {}
    },
    "tags": ["Wavetable", "Poly"],
    "url": "https://xferrecords.com/",
    "vendor": "Xfer Records",
    "version": 7
  }
}