Skip to content

design(@score/dsl): Synth signature — wave-first vs pitch-first, add .wave() chain method #125

Description

@bwyard

Problem

Synth currently takes (wave, pitch?) — the wave type is the first arg. This is inconsistent with the rest of the DSL (Bass303('A2'), Pad('A3'), SubSynth('C2') are all pitch-first) and creates a silent footgun: Synth('C3') treats 'C3' as the wave type with no error.

Context — how synths work musically

A synth is a voice architecture, not a note. In every major live coding tool, pitch lives in the pattern:

  • TidalCyclesd1 $ sound "bd" # note "c3" — pitch is always at the play site
  • Sonic Piplay :C3 — synth definition is architecture only
  • SuperCollider — synth def is architecture, pitch is a control signal

This means Synth() or Synth(wave) is more musically honest than Synth(pitch). The note belongs in .pattern() or .notes().

Bass303('A2') and Pad('A3') are the exception — they describe a specific voiced line, where the root note is part of the instrument definition. A general Synth is not that.

Proposed resolution

  1. Make Synth() take no required args — default wave is 'sawtooth'
  2. Add .wave() as a chain method so the voice can be described fluently:
    Synth().wave('square').pattern(['C3', 0, 'E3', 0]).volume(0.6)
  3. Remove the pitch constructor arg — pitch always goes in .notes() or .pattern()
  4. Update score-dsl.d.ts, LiveCode/index.tsx defaults, and ReferencePanel.tsx (tracked in fix(gui): update ReferencePanel + LiveCode defaults to chain API #124)

Files to change

  • packages/dsl/src/melodic.ts — Synth factory signature
  • packages/dsl/src/chain.ts — add .wave() to ChainMethods<T>
  • packages/gui/src/renderer/types/score-dsl.d.ts — ambient type declaration
  • packages/gui/src/renderer/components/LiveCode/index.tsx — default snippet
  • packages/gui/src/renderer/components/shared/ReferencePanel.tsx — reference example

Open questions

  • Should .wave() be on all instruments or only Synth / SubSynth? Bass303 and FMSynth have their own timbre controls.
  • Should Synth(pitch?) remain as a convenience overload, or is removing it cleaner?

Blocked by: #124 (ReferencePanel update should land after this is resolved)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions