Skip to content

play

Starts an instrument immediately and returns its instance.

Syntax

voice:Instr = play(definition[, ip4, ip5, ...])

voice:Instr play definition[, ip4, ip5, ...]

Initialization

definition is an InstrDef, such as a named instrument or a definition returned by create. The optional numeric arguments supply p4, p5 and the following p-fields.

voice refers to the new instance. play creates and initializes it during the caller's initialization, with p2 set to 0 and p3 set to -1. There is no start-time or duration argument.

Csound adds the instance to the end of its performance list, regardless of its instrument number. The returned reference is ready for use when play returns. Csound performs the instance automatically, so do not also call perf on it.

Use setp to change its p-fields, pause to pause and resume it, or turnoff to stop it. Arrange delete in the owning instrument for cleanup when that instrument ends. Use schedule when a note needs a start time and duration.

Examples

The controller starts a tone, pauses it for half a second and resumes it at a higher pitch. Its delete call cleans up the voice when the controller ends. It uses instance-controls.csd.

Pause a voice and change its pitch
 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
<CsoundSynthesizer>
<CsOptions>
-odac -d -m0
</CsOptions>
<CsInstruments>
sr = 44100
ksmps = 32
nchnls = 1
0dbfs = 1

instr Tone
  aTone poscil p4, p5
  out aTone
endin

instr 1
  voice:Instr = play(Tone, 0.1, 440)
  self:Instr = getinstance()
  running:b = isactive(self)
  if running then
    prints "Controller is active\n"
  endif

  kTime timeinsts
  ; Pause from half a second to one second, then resume.
  kPause = (kTime >= 0.5 && kTime < 1) ? 1 : 0
  pause(voice, kPause)

  activeNow:B = isactive(voice)
  if activeNow then
    kActive = 1
  else
    kActive = 0
  endif
  printk2 kActive

  ; The instance reads its frequency from p5 during performance.
  kFrequency line 440, p3, 660
  setp(voice, 5, kFrequency)
  kAmplitude linseg 0, 0.01, 0.1, p3 - 0.02, 0.1, 0.01, 0
  setp(voice, 4, kAmplitude)

  ; play has no duration argument. The controller owns its cleanup.
  delete(voice)
endin
</CsInstruments>
<CsScore>
i 1 0 1.5
e
</CsScore>
</CsoundSynthesizer>

See also

create, schedule, pause, setp, turnoff, delete, Instrument definitions, instances and opcode objects

Credits

Author Victor Lazzarini.

New in Csound 7.