reference

OVERVIEW

Live coding platform for sonic exploration.

@public

Soir is a Python environment 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 decorators (@live decorator) that are executed each time their code is changed. They are used to setup the environment, and to create tracks and instruments.

  • Loop decorators (@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')

DECORATORS

live

live() -> collections.abc.Callable[..., typing.Any]

Decorator to create a live function that is executed each time the code is changed.

@live
def setup:
  tracks.setup({
    'bass': tracks.mk("sampler", 1, muted=False, volume=100),
  })

Returns

– A decorator registering and executing the live function.

↑ back to top

loop

loop(track: str | None = None, beats: int = 4, align: bool = True) -> collections.abc.Callable[..., typing.Any]

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.

@loop('bass', beats=4, track=1)
def my_loop():
  log("Hello World")

Arguments

Name Type Description
track The track to use.
beats The duration of the loop in beats.
align Whether to align the loop on its next beat sequence.

Returns

– A decorator registering and scheduling the function in a loop.

↑ back to top

FUNCTIONS

ctrl

ctrl(name: str) -> soir.rt._ctrls.Control_

Get a control by its name.

Arguments

Name Type Description
name The name of the control.

Returns

– The control.

↑ back to top

log

log(message: str) -> None

Log a message to the console.

This function is used to log messages to the console. It is useful for debugging purposes.

log(f'We are at beat {bpm.beat()}')

Arguments

Name Type Description
message The message to log.
↑ back to top

sleep

sleep(beats: float) -> None

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.

@loop
def my_loop(beats=4, track=1):
   for i in range(4):
      s.play('kick')
      sleep(1)

Arguments

Name Type Description
beats The duration to sleep in beats.

Raises

Exception Description
errors.NotInLiveLoopException If we are not in a loop.
↑ back to top