Classes and functions

Carla

class pycarla.carla.Carla(proj_path: str, server_options: List[str] = [], min_wait: float = 0, nogui: bool = True)

__make_carla_popen(proj_path)

exists(ports=['Carla:events*', 'Carla:audio*'])

simply checks if the Carla process is running and ports are available

ports is a list of string name representing Jack ports; you can use

‘*’, ‘?’ etc.

Returns

bool – running, false otherwise

Return type

True if all ports in ports exist and the Carla process is

get_ports()

kill()

kill carla and wait for the server

kill_carla()

kill carla, but not the server

restart()

Restarts both the server and Carla!

restart_carla()

Only restarts Carla, not the Jack server!

start()

Start carla and Jack and wait self.min_wait seconds after a Carla instance is ready.

wait_exists()

Waits until a Carla instance is ready in Jack

pycarla.carla.download()

pycarla.carla.is_within_directory(directory, target)

pycarla.carla.run_carla()

pycarla.carla.safe_extract(tar, path='.', members=None, *, numeric_owner=False)

Jack Server

class pycarla.jackserver.JackServer(options)

kill()

Just calls self.process.kill() and reset this object

restart()

Wait for the duration of this ExternalProcess, then kill and restart. If the duration is not set, it doesn’t return

start()

Starts the server if not already started

Playing MIDI

class pycarla.midiplayer.MIDIPlayer

MIDI_PORT = 'Carla'

activate()

Activate the MIDI player client and set the connections.

If the Carla instance is not found, this method rase a RuntimeWarning. To avoid it, use Carla.exists method. Note that Carla.start already does that!

clear()

clears the _messages list

synthesize_messages(messages: ~typing.List[mido.Message], sync=False, condition=<function MIDIPlayer.<lambda>>, **kwargs)

Synthesize a list of messages

1. Connect the port of this jack client to Carla if not yet done

2. Send the list of messages to the Carla instance

If sync is True, this function waits until all messages have been processed, otherwise, it suddenly returns. You can wait by calling the wait method of this object.

This function is compatible with freewheeling mode. Freewheel prevents jack from waiting between return calls. This allows for the maximum allowed speed, but not output/input operation is done with system audio (i.e. you cannot listen/recording to anything while in freewheeling mode).

condition is a function checked in the playing callback. If condition() is False, no message is sent. The callback start playing at the cycle after the one in which condition() becomes True.

kwargs are passed to wait if sync is True.

Note: Mido numbers channels 0 to 15 instead of 1 to 16. This makes them easier to work with in Python but you may want to add and subtract 1 when communicating with the user.

synthesize_midi_file(midifile: Any, **kwargs) → Process

Send midi messages contained in filename using self.synthesize_messages. All keywords from that method can be used here.

midifile can be a mido.MidiFile object or a string

After the playback, ports are resetted

synthesize_midi_note(pitch: int, velocity: int, duration: float, sustain: int = 0, soft: int = 0, sostenuto: int = 0, channel: int = 0, program: int = 0, **kwargs) → Process

set up a list of messages representing one note and then calls self.synthesize_messages. All keywords from that method can be used here.

Recording Audio

class pycarla.audiorecorder.AudioRecorder

AUDIO_PORT = 'Carla'

activate()

Activate the recording client and set the connections. Set self.channels and create one input port per each Carla output port.

If the Carla instance is not found, this method rase a RuntimeWarning. To avoid it, use Carla.exists method. Note that Carla.start already does that!

clear()

Clears the recorded array

save_recorded(filename)

Save the recorded array to file. Extensions supported by libsndfile!

start_frame is the frame from which recorded is saved (use it to discard initial delays due to Jack setup).

start(duration=None, sync=False, condition=<function AudioRecorder.<lambda>>, **kwargs)

Record audio for duration seconds. Note that this function blocks if sync is True, otherwise, this returns suddenly and you should wait/stop by calling the wait method of this object which constructs the recorded array in self.recorded

condition is a function checked in the recording callback. If condition() is False, blocks are discarded. The callback start recording at the cycle after the one in which condition() becomes True.

This function is compatible with Jack freewheeling mode to record offline sessions.

kwargs are passed to wait if sync is True.

wait(timeout=None, in_fw=False, out_fw=False)

Wait until recording is finished. If timeout is a number, it should be the maximum number of seconds until which the recording stops. A boolean is returned representing if timeout is reached. (returns False if timeout is not set)

The recording stops when timeout or the duration passed when calling start is reached. In these cases, the recording client is deactivated and the callback stopped.

waits while setting freewheeling mode to in_fw it then set freewheeling mode to out_fw before exiting