Skip to content

create

Creates a new instrument definition, instrument instance, or opcode object.

Syntax

var:InstrDef = create(code:S)
var:Instr = create(instr:InstrDef)
var:Opcode = create(opc:OpcodeDef[,overload:i])
var:Opcode[] = create(opc:OpcodeDef,len:i[,overload:i])

var:InstrDef create Scode
var:Instr create instr:InstrDef
var:Opcode create opc:OpcodeDef[,ioverload] 
var:Opcode[]  create opc:OpcodeDef,ilen[,ioverload]

Initialization

code -- String containing Csound language code for an instrument.

instr -- compiled instrument definition.

opc -- opcode definition, supplied directly or looked up by name with opcoderef

overload -- (optional, defaults to 0) opcode overload (version) (see opcodeinfo)

len -- opcode object array length.

All forms run at initialization. The string form takes an instrument body without instr or endin, compiles it and returns an InstrDef. createinstr is another name for this form.

create(definition) allocates an Instr instance without scheduling it. Use init to initialize it, then perf to run it from the calling instrument. For an instance that Csound performs automatically, use play or schedule.

The Opcode form creates one object from the chosen overload. The array form creates a one-dimensional Opcode[] with len independent objects. Use a nonnegative integer for len. Creating an opcode object does not run its initialization or performance code. Use run, or separate init and perf calls, to execute it.

Arrange delete in the owning instrument for cleanup. The object guide explains lifetimes and gives examples of each form.

Instrument definition numbers

Each call to create(code) compiles a new definition in a free instrument-number slot. Assigning the result to the same InstrDef variable changes which definition the variable refers to; it does not replace or remove the previous definition. The variable's name does not name the compiled instrument. Use nstrnum to get the number of the definition it currently holds.

Removing an unused definition can free its number, but a later create call does not guarantee reuse of that number. Keep references to definitions that still need cleanup. delete runs when the containing instrument ends; ensure all notes using the definition have finished first.

If you need to replace an instrument while keeping its number, use compilestr with a complete instr/endin definition using the existing number or instrument name. Do not rely on repeated create calls preserving instrument performance order, for example when one instrument writes an audio bus that another reads.

Examples

This example assigns two definitions to the same variable. Their numbers differ, and a saved reference still refers to the first definition. Both definitions are removed when instrument 1 ends. It uses create-instrdef-numbers.csd and produces no audio.

Creating a new definition does not replace the old one
 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
<CsoundSynthesizer>
<CsOptions>
-n -d -m0
</CsOptions>
<CsInstruments>
sr = 44100
ksmps = 32
nchnls = 1
0dbfs = 1

instr 1
  definition:InstrDef = create({{ prints "First definition\\n" }})
  original:InstrDef = definition
  iFirst = nstrnum(definition)

  ; Reusing the variable does not replace the first definition.
  definition = create({{ prints "Second definition\\n" }})
  iSecond = nstrnum(definition)
  iOriginal = nstrnum(original)

  printfi("First number: %d\n", 1, iFirst)
  printfi("Second number: %d\n", 1, iSecond)
  printfi("Saved reference: %d\n", 1, iOriginal)

  schedule(original, 0, 0.1)
  schedule(definition, 0, 0.1)

  ; Both notes finish before instrument 1 ends.
  delete(original)
  delete(definition)
endin

schedule(1, 0, 0.5)
</CsInstruments>
<CsScore>
f 0 0.5
</CsScore>
</CsoundSynthesizer>

Here is an example of the create opcode. It uses the file create.csd.

Examples of the create opcode.
 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
<CsoundSynthesizer>
<CsOptions>
-o dac
</CsOptions>
<CsInstruments>
0dbfs = 1

opcode Osci(a:k,f:k):a
  xout oscili(a,f)
endop

instr One

 // run at i-time
  myInstr:InstrDef = create({{ out Osci(p4,p5) }})
  myInstance:Instr = create(myInstr)
  err1:i = init(myInstance)

  // env, gliss
  env:k = linen(0.5,0.1,p3,0.1)
  slid:k = expon(440, p3, 880)

  // set p5
  setp(myInstance, 5, slid)
  // run at perf-time, set p4
  err2:k = perf(myInstance,env)

  // run at deinit time
  delete(myInstance) 
  delete(myInstr)

  // schedule instr def
  schedule(Two,0,2,0.5,1000)

endin

instr Two
 obj:Opcode = create(oscili)
 sig:a = init(obj, p4, p5)
 sig:a = perf(obj, p4, p5)
   out(sig*adsr(0.1,0.1,0.5,0.1))
 event_i("e", 0, 3)
endin

schedule(One,0,1)

</CsInstruments>
<CsScore>
</CsScore>
</CsoundSynthesizer>

See also

Instrument definitions, instances and opcode objects, delete, init, perf

Credits

Author: Victor Lazzarini
Maynooth University
Ireland
Csound 7, 2024