Configuration

Source: packages/config/.

Configuration helpers and schema validation for soundor.config.ts files.

InstallCopy Anchor Link

pnpm add -D @soundor/config

UsageCopy Anchor Link

import { defineSoundorConfig } from '@soundor/config';

export default defineSoundorConfig({
  plugin: { id: 'com.acme.reverb', name: 'Acme Reverb' },
  runtimes: [],
  parameters: [],
});

The config is declarative: it describes what the plugin is and exposes, never how. parseConfig validates it and reports every problem with its path.

pluginCopy Anchor Link

nativeCopy Anchor Link

The plugin's typed native API, implemented in C++ and imported by JavaScript from soundor:native:

native: {
  types: {
    Analysis: { struct: { rms: 'number', peak: 'number' } },
    Curve: { enum: ['linear', 'exponential'] },
    Preset: 'handle',
  },
  methods: {
    analyze: { args: { samples: 'Float32Array' }, returns: 'Analysis' },
    setCurve: { args: { curve: 'Curve' } },
    loadPreset: { args: { path: 'string' }, returns: 'Preset', async: true },
  },
}

import { analyze, loadPreset } from 'soundor:native';

const { rms } = analyze(samples);
const preset = await loadPreset('/presets/warm.json');

Methods take positional arguments in the order declared and return returns (default void); async: true methods return a Promise. Type references:

Struct fields may be primitives, enums, structs or arrays of them. Method, argument and field names are camelCase; type names are PascalCase.

signingCopy Anchor Link

How runtimes sign the binaries they build. Optional; nothing here is secret.

signing: {
  macos: { identity: 'Developer ID Application: Acme (ABCDE12345)' },
},

Two environment variables, read by every runtime, take part:

An identity is only a name: codesign finds the private key in the keychain, so key material never goes in the config or these variables, and validation rejects anything that looks like it. Ad-hoc signing is enough to use a plugin on the Mac that built it; distributing one needs a Developer ID identity and notarization (see the JUCE signing guide).

LicenseCopy Anchor Link

MIT

User settingsCopy Anchor Link

Soundor reads optional JSON user settings from:

• Linux and other Unix platforms: $XDG_CONFIG_HOME/soundor/config.json, or ~/.config/soundor/config.json when XDG_CONFIG_HOME is unset or relative.
• macOS: ~/Library/Application Support/Soundor/config.json.
• Windows: %APPDATA%\Soundor\config.json, falling back to ~/AppData/Roaming/Soundor/config.json.

{
  "devtools": { "enabled": true, "port": 4545, "open": false }
}

These are the defaults; the file need not exist. A port must be an integer in 1–65535. loadUserSettings() validates the file using Soundor's config errors; parseUserSettings() validates an object and userConfigPath() resolves its location. An explicit path passed to the loader takes precedence over discovery. User settings are separate from the plugin contract in soundor.config.ts. The resolved portSource distinguishes an omitted port from an explicit 4545: the DevTools server may choose a higher available port only for the default.

locateConfig(cwd) returns the nearest soundor.config.ts path by searching cwd and its parent directories. It throws a ConfigError with kind not-found when discovery fails. Integrations can reuse discovery before calling parseConfig({ path }).