Skip to content

start

Prepares an embedded Csound engine for performance.

Use start after configuring and compiling a Csound object. The containing instrument then controls its performance with perf(engine).

Syntax

iresult = start(engine)

iresult start engine

Initialization

engine is a Csound object made with engine:Csound = create().

iresult is 0 on success and nonzero on failure. Check it before calling perf or reading the engine's audio. The return value lets the containing instrument decide how to handle a failed start.

start runs at initialization. It prepares the engine's audio I/O according to its options and allocates the buffers used to pass audio between the two engines. Call it once per engine. Calling it again on an engine that has already started returns an error and does not restart performance.

The usual setup order is to create the engine, apply setoption, compile its orchestra with compilestr(engine, Scode) or its CSD file with compilecsd(engine, Sfile), then call start(engine).

Set options before compilation and startup. For an embedded engine whose audio the containing instrument will play, setoption(engine, "-n") prevents a separate sound output file. Audio remains available to the containing instrument.

An engine can also start before a CSD is compiled. In that case, the later CSD's CsOptions section is ignored and its score is sent as real-time events. Compile the CSD first when you want its options and normal score preprocessing.

Performance

start does not run the engine continuously in the background. Call kstatus = perf(engine) on each control cycle where you want it to advance. After that call, aSignal = inch(engine, 1) reads the first output channel. Audio channel numbers start at 1.

Use matching sample rates for audio exchange. The example also uses the same ksmps in both engines.

Keep the engine alive while performing it or reading its output. Arrange delete to release it when the containing instrument ends. destroy releases it immediately at initialization and must not precede later performance calls on that engine.

Examples

A composition can prepare an embedded synthesizer before it needs to play. This example starts the engine at initialization, waits half a second in the containing instrument, then calls perf to play a one-second tone. The wait does not consume the embedded note's duration.

It uses start.csd.

Prepare an engine before performing its first note
 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
<CsoundSynthesizer>
<CsOptions>
-odac -d -m0
</CsOptions>
<CsInstruments>
sr = 48000
ksmps = 32
nchnls = 1
0dbfs = 1

instr PrepareThenPlay
  engine:Csound = create()

  // Configure the embedded engine before compiling or starting it.
  // -n keeps it from writing a sound file. The main engine handles output.
  iOptions = setoption(engine, "-n -d -m0")
  if iOptions != 0 then
    prints("Could not set the embedded engine's options.\n")
    exitnow(1)
  endif

  iCompile = compilestr(engine, {{
    sr = 48000
    ksmps = 32
    nchnls = 1
    0dbfs = 1

    instr Tone
      aEnvelope = linen(0.15, 0.01, p3, 0.1)
      aTone = oscili(aEnvelope, 330)
      out(aTone)
    endin
    schedule("Tone", 0, 1)
  }})
  if iCompile != 0 then
    prints("Could not compile the embedded orchestra.\n")
    exitnow(1)
  endif

  // Prepare the engine now. Its note has not been performed yet.
  iStart = start(engine)
  if iStart != 0 then
    prints("Could not start the embedded engine.\n")
    exitnow(1)
  endif

  // Wait half a second before advancing the embedded engine.
  kElapsed = timeinsts()
  if kElapsed >= 0.5 then
    kStatus = perf(engine)
    aTone = inch(engine, 1)
    out(aTone)
  endif

  // Keep the engine until this instrument ends.
  delete(engine)
endin
</CsInstruments>
<CsScore>
i "PrepareThenPlay" 0 1.5
e
</CsScore>
</CsoundSynthesizer>

See also

setoption, compilestr, compilecsd, perf, inch, delete, destroy, Instrument definitions, instances and opcode objects

Credits

Author Victor Lazzarini, 2025.

New in Csound 7.