PCM Voice Parameters

How to write the YAML file that defines a PCM voice (音色) playing back WAV samples. One file may define multiple voices.

File format

YAML format. Comment lines start with #; blank lines and whitespace-only lines are ignored. Load with one of fileio.LoadPCMVoiceFile / LoadPCMVoiceFileFS / SetPCMVoiceData. Every referenced WAV file is decoded into memory at the same time the YAML itself is parsed (the same WAV file is never decoded twice - its cache is reused).

voiceType: two kinds

oneShot A drum-kit-style voice: an independent WAV sample is assigned to each of several notes. Up to 16 voiceSetting entries per voice. Any loop metadata in the file itself is ignored - it always plays as a one-shot, through to the sample's own natural end. loop / baseNote / envelope are ignored.

long For sustained sounds like a violin. Exactly one voiceSetting. Playback pitch-shifts across the 12-tone scale relative to baseNote depending on the note played. note / volume / pan (on the voiceSetting side) are ignored - the assigned part's own volume/pan are used instead. Supports envelope, LFO, and looped playback.

Common parameters

Key	Range / format	Description
`voiceID`	integer	Uniquely identifies this voice.
`voiceType`	`oneShot` / `long`	The voice type. An unrecognized value is treated as a YAML-level error and aborts loading.
`loop`	true / false	Only meaningful for long. If true and the WAV file itself contains `smpl`-chunk loop points, that region is looped; if it has none, the whole file (start to end) is looped instead. If false, playback never loops regardless of what the WAV file itself specifies (always ignored for oneShot).
`lfo`	true / false	Only meaningful for long (Phase 8). Ignored for oneShot. Defaults to false if omitted.
`lfoDelay` / `lfoFade` / `lfoDepth` / `lfoHz`	Same as FM voices	Defaults: `0.4` / `0.5` / `30` / `6` respectively. See FM Voice Parameters for details.

voiceSetting

Key	oneShot	long	Description
`fileName`	required	required	The WAV file name (mono, 44.1kHz only). Either an absolute path, or - if just a bare file name - resolved relative to the YAML file's own directory (for `LoadPCMVoiceFileFS`, an absolute path from `fsys`'s root, or the YAML's own directory within `fsys` for a bare name).
`note`	required (e.g. `C1`)	ignored	The note name that triggers this sample. Up to 16 per voice, each mapped to a different sample.
`baseNote`	ignored	required (e.g. `A3`)	The note this sample plays back at its original (untransposed) pitch. Missing/invalid falls back to A4 with a warning.
`volume`	0-127	ignored	This sample's own volume (each oneShot sample can be mixed independently).
`pan`	-16(left)-16(right)	ignored	This sample's own pan. 0 = center, continuous (e.g. -7 = slightly left).
`envelope`	ignored	`"attackRate, decay1Rate, sustainLevel, decay2Rate, releaseRate"`	Same format and meaning as an FM voice's envelope. See FM Voice Parameters.

Example

pcmVoice:
  # oneShot type (drum kit)
  - voiceID: 0
    voiceType: oneShot
    loop: false
    voiceSetting:
      - fileName: kick.wav
        note: C1
        volume: 100
        pan: 0
      - fileName: snare.wav
        note: E1
        volume: 100
        pan: 0
      - fileName: hat1.wav
        note: F#1
        volume: 100
        pan: -16

  # long type (sustained, with looping, envelope, and LFO)
  - voiceID: 1
    voiceType: long
    loop: true
    lfo: true
    lfoDelay: 0.3
    lfoFade: 0.4
    lfoHz: 7
    voiceSetting:
      - fileName: uhh.wav
        baseNote: A3
        envelope: "31, 1, 2, 6, 14"

WAV file requirements

Mono, 44.1kHz only.
Looping on a long voice prefers loop points embedded in the WAV file's own smpl chunk, when present.
When the same WAV file is referenced by multiple voices or multiple load calls, it is decoded only once; the in-memory cache is reused afterward (explicitly clearable via memory.ClearPCMWaveCache).

An undefined or invalid value (a minor issue) is logged as a warning and treated as 0, and parsing continues. An unrecognized voiceType, or any WAV file failing to load, is a fatal error that aborts loading.