✨ soir
soir
Soir is a Python library for live coding music. It provides facilities to create and manipulate audio tracks, and to interact with external synthesizers. There are two important concepts in Soir:
-
Live functions (
@live
decorator) that are executed each time the code is changed. They are used to setup the environment, and to create tracks and instruments. -
Loops functions (
@loop
decorator) that are rescheduled every given number of beats. They are used to create patterns and sequences.
# Live function
@live
def setup():
bpm.set(120)
# Loop function
@loop(beats=1)
def kick():
log('beat')
Soir's facilities are organized in modules that are accessible from
the global context. For example, to set the BPM, you can use
bpm.set(120)
without having to explicitly import the bpm
module. The available modules are:
Cookbook
Minimalistic Example
@live
def setup():
bpm.set(120)
tracks.setup({
'sampler': tracks.mk_sampler(muted=False, volume=100),
})
s = sampler.new('passage')
@loop(track='sampler', beats=4)
def kick():
for i in range(4):
s.play('kick')
sleep(1)
Reference
Modules:
Name | Description |
---|---|
bpm |
The bpm module provides a way to set the tempo of the current |
cli |
|
ctrls |
The ctrls module contains facilities to control settings of soir |
errors |
The errors module contains exceptions raised by the Soir engine to |
fx |
The |
midi |
The midi module provides a way to communicate with external |
rnd |
The rnd module provides facilities to introduce randomness in the |
sampler |
Info |
system |
The system module provides access to low-level facilities |
tracks |
The |
Functions:
Name | Description |
---|---|
ctrl |
Get a control by its name. |
current_loop |
Get the current loop. |
live |
Decorator to create a live function that is executed each time the code is changed. |
log |
Log a message to the console. |
loop |
Decorator to create a loop that is rescheduled every given number of beats. |
sleep |
Sleep for the given duration in beats in the current loop. |
ctrl(name)
Get a control by its name.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
name
|
str
|
The name of the control. |
required |
Returns:
Type | Description |
---|---|
Control
|
The control. |
current_loop()
Get the current loop.
Raises:
Type | Description |
---|---|
NotInLiveLoopException
|
If we are not in a loop. |
live()
log(message)
loop(track=None, beats=4, align=True)
Decorator to create a loop that is rescheduled every given number of beats.
The concept of a loop is similar to Sonic
Pi's live loops. Code within a loop is
executed using temporal recursion, and can be updated in
real-time: the next run of the loop will execute the updated
version. This provides a way to incrementally build audio
performances by editing code. Loops should not be blocking as it
would freeze the main thread. For this reason, blocking facilities
such are sleep
are provided by the
engine.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
track
|
str
|
The track to use. |
None
|
beats
|
int
|
The duration of the loop in beats. |
4
|
align
|
bool
|
Whether to align the loop on its next beat sequence. |
True
|
Returns:
Type | Description |
---|---|
callable
|
A decorator registering and scheduling the function in a loop. |
sleep(beats)
Sleep for the given duration in beats in the current loop.
In this example, we define a 4-beats loop that plays a kick sample every beats, and sleeps for 1 beat between each sample.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
beats
|
float
|
The duration to sleep in beats. |
required |
Raises:
Type | Description |
---|---|
NotInLiveLoopException
|
If we are not in a loop. |