Csd

class csoundengine.csoundlib.Csd(sr=44100, ksmps=64, nchnls=2, a4=442.0, options=None, nodisplay=False, carry=False, nchnls_i=None, numthreads=0, reservedTables=0)

Bases: object

Build a csound script by adding global code, instruments, score events, etc.

Parameters:

• sr (int) – the sample rate of the generated audio

• ksmps – the samples per cycle to use

• nchnls – the number of output channels

• nchnls_i (int | None) – if given, the number of input channels

• a4 – the reference frequency

• options (list[str]) – any number of command-line options passed to csound

• nodisplay – if True, avoid outputting debug information

• carry – should carry be enabled in the score?

• reservedTables – when creating tables, table numbers are autoassigned from python. There can be conflicts of any code uses ftgen

Example

>>> from csoundengine.csoundlib import *
>>> csd = Csd(ksmps=32, nchnls=4)
>>> csd.addInstr('sine', r'''
...   ifreq = p4
...   outch 1, oscili:a(0.1, ifreq)
... ''')
>>> source = csd.addSndfile("sounds/sound1.wav")
>>> csd.playTable(source)
>>> csd.addEvent('sine', 0, 2, [1000])
>>> csd.write('out.csd')

Attributes Summary

sr

Methods Summary

addEmptyTable(size[, tabnum, sr, ...])	Add an empty table to this Csd
addEvent(instr, start, dur[, args, comment])	Add an instrument ("i") event to the score
addGlobalCode(code[, acceptDuplicates])	Add code to the instr 0
addInstr(instr, body[, instrComment])	Add an instrument definition to this csd
addOptions(*options)	Adds options to this csd
addSndfile(sndfile[, tabnum, start, ...])	Add a table which will load this sndfile
addTableFromData(data[, tabnum, start, ...])	Add a table definition with the data
copy()	Copy this csd
cropScore([start, end])	Crop the score at the given boundaries
destroyTable(tabnum, time)	Schedule ftable with index source to be destroyed at time time
dump()	Returns a string with the .csd
dumpScore()	rtype: None
freeTable(tabnum, time)	Free a table
playTable(tabnum, start[, dur, gain, speed, ...])	Add an event to play the given table
removeEndMarker()	Remove the end-of-score marker
run(output[, csdfile, inputdev, backend, ...])	Run this csd.
scoreDuration()	rtype: float
setComment(comment)	Add a comment to the renderer output soundfile
setCompressionBitrate([bitrate, format])	Set the compression quality by defining a bitrate
setCompressionQuality([quality])	Set the compression quality
setEndMarker(time)	Add an end marker to the score
setOutfileFormat(fmt)	Sets the format for the output soundfile
setSampleEncoding(encoding)	Set the sample encoding for recording
strset(s, index)	Add a strset to this csd
write(csdfile)	Write this as a .csd

Attributes Documentation

sr

Methods Documentation

addEmptyTable(size, tabnum=0, sr=0, numchannels=1, time=0.0)

Add an empty table to this Csd

A table remains valid until the end of the csound process or until the table is explicitely freed (see freeTable())

Parameters:

• tabnum (int) – use 0 to autoassign an index

• size (int) – the size of the empty table

• sr (int) – if given, set the sr of the empty table to the given sr

• numchannels – the number of channels in the table

• time – when to do the allocation.

Return type:

int

Returns:

The index of the created table

addEvent(instr, start, dur, args=None, comment='')

Add an instrument (“i”) event to the score

Parameters:

• instr (int | float | str) – the instr number or name, as passed to addInstr

• start (float) – the start time

• dur (float) – the duration of the event

• args (Optional[Sequence[float | str]]) – pargs beginning at p4

• comment – if given, the text is attached as a comment to the event line in the score

Return type:

None

addGlobalCode(code, acceptDuplicates=True)

Add code to the instr 0

Return type:

None

addInstr(instr, body, instrComment='')

Add an instrument definition to this csd

Parameters:

• instr (int | str) – the instrument number of name

• body (str) – the body of the instrument (the part between ‘instr’ / ‘endin’)

• instrComment – if given, it will be added at the end of the ‘instr’ line

Return type:

None

addOptions(*options)

Adds options to this csd

Options are any command-line options passed to csound itself or which could be used within a <CsOptions> tag. They are not checked for correctness

Return type:

None

addSndfile(sndfile, tabnum=0, start=0.0, skiptime=0, chan=0, asProjectFile=False)

Add a table which will load this sndfile

Parameters:

• sndfile (str) – the output to load

• tabnum – fix the table number or use 0 to generate a unique table number

• start – when to load this output (normally this should be left 0)

• skiptime – begin reading at skiptime seconds into the file.

• chan – channel number to read. 0 denotes read all channels.

• asProjectFile – if True, the sndfile is included as a project file and copied to a path relative to the .csd when writing

Return type:

int

Returns:

the table number

addTableFromData(data, tabnum=0, start=0, filefmt='', sr=0)

Add a table definition with the data

Parameters:

• data (Union[Sequence[float], ndarray]) – a sequence of floats to fill the table. The size of the table is determined by the size of the seq.

• tabnum (int) – 0 to auto-assign an index

• start – allocation time of the table

• filefmt – format to use when saving the table as a datafile. If not given, the default is used. Possible values: ‘gen23’, ‘wav’

• sr – if given and data is a numpy array, it is saved as a soundfile and loaded via gen1

Return type:

int

Returns:

the table number

Note

The data is either included in the table definition (if it is small enough) or saved as an external file. All external files are saved relative to the generated .csd file when writing. Table data is saved as 32 bit floats, so it might loose some precission from the original.

copy()

Copy this csd

Return type:

Csd

cropScore(start=0.0, end=0.0)

Crop the score at the given boundaries

Any event starting earlier or ending after the given times will be cropped, any event ending before start or starting before end will be removed

Return type:

None

destroyTable(tabnum, time)

Schedule ftable with index source to be destroyed at time time

Parameters:

• tabnum (int) – the index of the table to be destroyed

• time (float) – the time to destroy it

Return type:

None

dump()

Returns a string with the .csd

Return type:

str

dumpScore()

Return type:

None

freeTable(tabnum, time)

Free a table

Parameters:

• tabnum (int) – the table number

• time (float) – when to free it

playTable(tabnum, start, dur=-1, gain=1.0, speed=1.0, chan=1, fade=0.05, skip=0.0)

Add an event to play the given table

Parameters:

• tabnum (int) – the table number to play

• start (float) – schedule time (p2)

• dur (float) – duration of the event (leave -1 to play until the end)

• gain – a gain factor applied to the table samples

• chan –

  ??

• fade – fade time (both fade-in and fade-out

• skip – time to skip from playback (enables playback to crop a fragment at the beginning)

Return type:

None

Example

>>> csd = Csd()
>>> source = csd.addSndfile("stereo.wav")
>>> csd.playTable(source, source, start=1, fade=0.1, speed=0.5)
>>> csd.write("out.csd")

removeEndMarker()

Remove the end-of-score marker

Return type:

None

run(output, csdfile='', inputdev='', backend='', suppressdisplay=True, nomessages=False, piped=False, extraOptions=None)

Run this csd.

Parameters:

• output (str) – the output of the csd. This will be passed as the -o argument to csound. If an empty string or None is given, no sound is produced (adds the ‘–nosound’ flag).

• inputdev – the input device to use when running in realtime

• csdfile – if given, the csd file will be saved to this path and run from it. Otherwise a temp file is created and run.

• backend – the backend to use

• suppressdisplay – if True, display (table plots, etc.) is supressed

• nomessages – if True, debugging scheduling information is suppressed

• piped – if True, stdout and stderr are piped through the Popen object, accessible through .stdout and .stderr streams

• extraOptions (list[str] | None) – any extra args passed to the csound binary

Return type:

Popen

Returns:

the _subprocess.Popen object

scoreDuration()

Return type:

float

setComment(comment)

Add a comment to the renderer output soundfile

Return type:

None

setCompressionBitrate(bitrate=128, format='ogg')

Set the compression quality by defining a bitrate

Parameters:

• bitrate – the bitrate in kB/s

• format – the format used (only ‘ogg’ at the moment)

Return type:

None

setCompressionQuality(quality=0.4)

Set the compression quality

Parameters:

quality – a value between 0 and 1

Return type:

None

setEndMarker(time)

Add an end marker to the score

This is needed if, for example, all events are endless events (with dur == -1).

If an end marker has been already set, setting it later will remove the previous endmarker (there can be only one)

Return type:

None

setOutfileFormat(fmt)

Sets the format for the output soundfile

If this is not explicitely set it will be induced from the output soundfile set when running the csd

Parameters:

fmt (str) – the format to use (‘wav’, ‘aif’, ‘flac’, etc)

Return type:

None

setSampleEncoding(encoding)

Set the sample encoding for recording

If not set, csound’s own default for encoding will be used

Parameters:

encoding (str) – one of ‘pcm16’, ‘pcm24’, ‘pcm32’, ‘float32’, ‘float64’

Return type:

None

strset(s, index)

Add a strset to this csd

If s has already been passed, the same index is returned

Return type:

int

write(csdfile)

Write this as a .csd

Any data files added are written to a folder <csdfile>.assets besides the generated .csd file.

Return type:

None

Example

>>> from csoundengine.csoundlib import Csd
>>> csd = Csd(...)
>>> csd.write("myscript.csd")

This will generate a myscript.csd file and a folder myscript.assets holding any data file needed. If no data files are used, no .assets folder is created