Skip to content

stmcreate

Creates an empty graph builder.

The builder is the mutable stage of a state machine graph. Add nodes and edges to it, then freeze it with stmcompile. See State Machine Graphs for the whole workflow.

Syntax

ibuilder = stmcreate()

ibuilder stmcreate

Initialization

ibuilder -- the handle of the new builder, a positive integer.

The builder belongs to the opcode instance that created it, and its handle is removed when that instance ends. Created in the global space, outside any instrument, it lasts for the whole performance. A definition compiled from it does not depend on it any more.

Up to 4096 builders, definitions and runners can exist at the same time in one Csound instance.

Examples

A texture moves through three nodes, Calm, Build and Burst. Each node is a UDO that writes a shared struct and asks for the next node with stmnext when its time is up. The runner is created inside the instrument, so it lasts as long as the note. It uses the file stm.csd.

A state machine that shapes a texture.
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
<CsoundSynthesizer>
<CsOptions>
; Select audio/midi flags here according to platform
-odac     ;;;realtime audio out
;-iadc    ;;;uncomment -iadc if realtime audio input is needed too
; For Non-realtime ouput leave only the line below:
; -o stm.wav -W ;;; for file output any platform
</CsOptions>
<CsInstruments>
sr = 48000
ksmps = 32
nchnls = 2
0dbfs = 1

; A state machine that shapes a texture. The graph only says which node is
; current and which moves are allowed:
;
;   Calm -> Build -> Burst -> Calm or Build
;
; What each node does is an ordinary UDO. It writes the shared state and,
; when its time is up, asks for the next node with stmnext.

struct Texture cutoff:k, rate:k

opcode CalmNode(r:i, tx:Texture, t:k):void
  tx.cutoff = 500
  tx.rate = 1
  if t >= 3 then
    stmnext(r, "Build")
  endif
endop

opcode BuildNode(r:i, tx:Texture, t:k):void
  tx.cutoff = 500 + t * 1500     ; opens up during the node
  tx.rate = 1 + t * 3
  if t >= 2 then
    stmnext(r, "Burst")
  endif
endop

opcode BurstNode(r:i, tx:Texture, t:k):void
  tx.cutoff = 6000
  tx.rate = 12
  if t >= 1.5 then
    ; a conditional edge: Burst may go to either node
    if random:k(0, 1) < 0.5 then
      stmnext(r, "Calm")
    else
      stmnext(r, "Build")
    endif
  endif
endop

; build the graph once, in the global space
builder:i = stmcreate()
stmaddnode(builder, "Calm")
stmaddnode(builder, "Build")
stmaddnode(builder, "Burst")
stmaddedge(builder, "Calm", "Build")
stmaddedge(builder, "Build", "Burst")
stmaddcondedge(builder, "Burst", ["Calm", "Build"])
gi_definition@global:i = stmcompile(builder)

instr 1
  r:i = stminstance(gi_definition)
  tx:Texture = init(500, 1)

  ; the runtime loop: current node -> its UDO -> stmadvance
  node:S = stmcurrent(r)
  t:k = stmnodetime(r)
  if strcmpk(node, "Calm") == 0 then
    CalmNode(r, tx, t)
  elseif strcmpk(node, "Build") == 0 then
    BuildNode(r, tx, t)
  else
    BurstNode(r, tx, t)
  endif
  status:k, from:k, to:k = stmadvance(r)
  if status == 1 then
    printks("%5.2f s: %s -> %s\n", 0, timeinsts(), stmnodename(r, from), stmnodename(r, to))
  endif

  ; the sound only reads the shared state
  pulse:k = 0.5 + 0.5 * lfo(1, tx.rate, 0)
  cutoff:k = portk(tx.cutoff, 0.1)
  env:k = linseg(0, 0.5, 1, p3 - 1, 1, 0.5, 0)
  sig:a = vco2(0.1, 110) + vco2(0.1, 165) + vco2(0.1, 220.5)
  sig = moogladder(sig, cutoff, 0.4) * pulse * env
  out(sig, sig)
endin
</CsInstruments>
<CsScore>
i 1 0 20
e
</CsScore>
</CsoundSynthesizer>

See also

State Machine Graphs

stmaddnode, stmaddedge, stmcompile

Credits

Author: Pasquale Mainolfi
Italy
New in Csound version 7.0
October 2026