Configuration

Many defaults can be configured via csoundengine.config.config (an instance of configdict.ConfigDict, see https://configdict.readthedocs.io).

Note

To modify defaults in a persistent manner, call ConfigDict.save() to save the current version. The changes will be loaded the next time this module is imported

Example

import csoundengine as ce
# Modify the default number of channels, force it to 2
ce.config['nchnls'] = 2

# Set default A4 value
ce.config['A4'] = 443

# Larger number of audio buses
ce.config['num_audio_buses'] = 200

# If you would like to set these as defaults, call save. The next time using
# csoundengine, these settings will be the default.
ce.config.save()

# To revert the changes to the default, use reset:
ce.config.reset()

Any Engine created after this will pick up these new defaults:

>>> from csoundengine import *
>>> engine = Engine()
>>> engine.numAudioBuses
200
>>> engine.A4
443

Edit the config interactively

from csoundengine import *
config.edit()

This will open the config in a text editor and any changes there will be reflected back in the config. Which application is used depends on the os settings for handling yaml files.

---

Keys

sr:

Default: 0 – int

Choices: 0, 22050, 24000, 44100, 48000, 88200, 96000, 144000, 192000

samplerate - 0=default sr for the backend

rec_sr:

Default: 44100 – int

Choices: 0, 22050, 24000, 44100, 48000, 88200, 96000, 144000, 192000

default samplerate when rendering

nchnls:

Default: 0 – int

Between 0 - 128

Number of output channels. 0=default for used device

nchnls_i:

Default: 0 – int

Between 0 - 128

Number of input channels to use. 0 = default for used device

ksmps:

Default: 64 – int

Choices: 16, 32, 64, 128, 256, 512, 1024

corresponds to csound’s ksmps

rec_ksmps:

Default: 64 – int

Choices: 16, 32, 64, 128, 256, 512, 1024

samples per cycle when rendering

rec_sample_format:

Default: float – (int, str)

Choices: 16, 24, 32, float

Sample format used when rendering

rec_suppress_output:

Default: False – bool

Supress debugging output when rendering offline

buffersize:

Default: 0 – int

-b value. 0=determine buffersize depending on ksmps & backend

numbuffers:

Default: 0 – int

determines the -B value as a multiple of the buffersize. 0=auto

linux_backend:

Default: jack, pulse, pa_cb – str

a comma separated list of backends (possible backends: jack, pulse, pa_cb, alsa)

macos_backend:

Default: pa_cb – str

a comma separated list of backends (possible backends: pa_cb, auhal)

windows_backend:

Default: pa_cb – str

a comma separated list of backends (possible backends: pa_cb, pa_bl)

A4:

Default: 442 – int

Between 410 - 460

Frequency for A4

numthreads:

Default: 1 – int

Number of threads to use for realtime performance. This is an experimental feature if csound and might not necessarily result in better performance

rec_numthreads:

Default: 0 – int

Number of threads to use when rendering online. If not given, the value set in `numthreads` is used

check_pargs:

Default: False – bool

Check number of pargs passed to instr

max_pfields:

Default: 1900 – int

The size limit for pfields in an event

offline_score_table_size_limit:

Default: 1900 – int

size limit when writing tables as f score statements via gen2. If a table is bigger than this size, it is saved as a datafile as gen23 or wav

dynamic_pfields:

Default: True – bool

If True, use pfields for dynamic parameters (named args starting with k). Otherwise, dynamic controls are implemented via a global table

fail_if_unmatched_pargs:

Default: False – bool

Fail if the number of passed arguments doesnt match the number of defined arguments

set_sigint_handler:

Default: True – bool

Set a sigint handler to prevent csound crash with CTRL-C

disable_signals:

Default: True – bool

Disable atexit and sigint signal handler

generalmidi_soundfont:

Default: ‘’ – str

Default soundfont used for general midi rendering

suppress_output:

Default: True – bool

Suppress csound´s debugging information

unknown_parameter_fail_silently:

Default: True – bool

Do not raise if a synth tries to set an unknown parameter

define_builtin_instrs:

Default: True – bool

If True, a Session with have all builtin instruments defined

sample_fade_time:

Default: 0.02 – float

Fade time (in seconds) when playing samples via a Session

prefer_udp:

Default: True – bool

If true and a udp server was defined, prefer UDP over the API for communication

start_udp_server:

Default: False – bool

Start an engine with udp communication support

num_audio_buses:

Default: 64 – int

Num. of audio buses in an Engine/Session

num_control_buses:

Default: 512 – int

Num. of control buses in an Engine/Session. This sets the upper limit to the number of simultaneous control buses in use

html_theme:

Default: light – str

Choices: dark, light

Style to use when displaying syntax highlighting in jupyter

html_args_fontsize:

Default: 12px – str

Font size used for args when outputing html (in jupyter)

synth_repr_max_args:

Default: 12 – int

Max. number of pfields shown when in a synth’s repr

synth_repr_show_pfield_index:

Default: False – bool

Show the pfield index for named pfields in a Synths repr

synthgroup_repr_max_rows:

Default: 4 – int

Max. number of rows for a SynthGroup repr. Use 0 to disable

synthgroup_html_table_style:

Default: font-size: smaller – str

Inline css style applied to the table displayed as html for synthgroups

jupyter_synth_repr_stopbutton:

Default: True – bool

When running inside a jupyter notebook, display a stop buttonfor Synths and SynthGroups

jupyter_synth_repr_interact:

Default: True – bool

When inside jupyter, add interactive widgets if a synth hasnamed parameters

jupyter_instr_repr_show_code:

Default: True – bool

Show code when displaying an Instr inside jupyter

ipython_load_magics_at_startup:

Default: True – bool

Load csoundengine.magic at startup when inside ipython. If False, magics can still be loaded via `%load_ext csoundengine.magic`

magics_print_info:

Default: False – bool

Print some informative information when the csounengine.magic extension is loaded

jupyter_slider_width:

Default: 80% – str

CSS Width used by an interactive slider in jupyter

timeout:

Default: 2.0 – float

Timeout for any action waiting a response from csound

sched_latency:

Default: 0.05 – float

Time delay added to any event scheduled to ensure that simultameous events arenot offset by scheduling overhead

datafile_format:

Default: gen23 – str

Choices: gen23, wav

Format used when saving a table as a datafile

max_dynamic_args_per_instr:

Default: 10 – int

Between 2 - 512

Max. number of dynamic parameters per instr

session_priorities:

Default: 10 – int

Between 1 - 99

Number of priorities within a session

dynamic_args_num_slots:

Default: 10000 – int

Between 10 - 9999999

Number of slots for dynamic parameters. args slices. Dynamic args are implemented as a big array divided in slices. This parameter sets the max. number of such slices, and thus the max number of simultaneous events with named args which can coexist. The size of the allocated table will be size = num_dynamic_args_slices * max_instr_dynamic_args. For 10000 slots, theamount of memory is ~0.8Mb

instr_repr_show_pfield_pnumber:

Default: False – bool

Add pfield number when printing pfields in instruments

spectrogram_colormap:

Default: inferno – str

Choices: cividis, inferno, magma, plasma, viridis

samplesplot_figsize:

Default: 12:4 – str

The figure size of the plot in the form ‘<width>:<height>’

spectrogram_figsize:

Default: 24:8 – str

The figure size of the plot in the form ‘<width>:<height>’

spectrogram_maxfreq:

Default: 12000 – int

Highest freq. in a spectrogram

spectrogram_window:

Default: hamming – str

Choices: hamming, hanning