Configuration

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

_images/jupyter-config.png

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.

_images/config-edit.png

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