Skip to content

setoption

Sets command-line options on an embedded Csound engine.

Use setoption to configure a Csound object before compiling code or starting it. It sets options for the supplied engine and does not replace the containing CSD's CsOptions section.

Syntax

iresult = setoption(engine, Soptions)

iresult setoption engine, Soptions

Initialization

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

Soptions contains one or more Csound command-line options, separated by spaces. For example, "-n -d -m0" disables the engine's sound output, disables displays and reduces its messages. Supply the options themselves, without the csound command name.

iresult is 0 when the option parser reports success and nonzero when it reports an error or the engine has already started. Check it before continuing. Some unknown long options produce a warning and are ignored while the result remains 0, so also check option messages. A zero result does not guarantee that every option was recognized or that later compilation and startup will succeed.

Call setoption after create and before compilestr, compilecsd or start on that engine. You can make several calls during setup. Once the engine has started, setoption returns 1 without applying the new options.

The opcode runs at initialization. Changing the string during performance does not update the engine's options.

Examples

An embedded engine can generate audio for the main engine to mix or process. In this example, -n stops the embedded engine from writing its own sound file. Its audio remains available through inch, and the main engine sends that audio to its output.

The options apply before compilation and startup. The example checks each return value and uses delete to release the embedded engine when the containing instrument ends.

It uses setoption.csd.

Configure an embedded engine for audio processing
 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
<CsoundSynthesizer>
<CsOptions>
-odac -d -m0
</CsOptions>
<CsInstruments>
sr = 48000
ksmps = 32
nchnls = 1
0dbfs = 1

instr EmbeddedTone
  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.5)
  }})
  if iCompile != 0 then
    prints("Could not compile the embedded orchestra.\n")
    exitnow(1)
  endif

  iStart = start(engine)
  if iStart != 0 then
    prints("Could not start the embedded engine.\n")
    exitnow(1)
  endif

  // Run the embedded engine and read its first output channel.
  kStatus = perf(engine)
  aTone = inch(engine, 1)
  out(aTone)

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

See also

Csound options, compilestr, delete, Instrument definitions, instances and opcode objects

Credits

Author Victor Lazzarini, 2025.

New in Csound 7.