kf Python library

The kf library has a number of objects useful for building performance control scripts and GUIs. It is included in several zip packages and the individual files can be browsed at kf.

Contents

• kf Python library

  • Core Modules (non-GUI)

    • kf.midi

    • kf.app

    • kf.valve

  • Core GUI Modules

    • kf.QtConfig

    • kf.QtLog

    • kf.QtMPD218

Core Modules (non-GUI)

kf.midi

Objects related to MIDI event processing.

class kf.midi.MIDIEncoder

Abstract class for composing MIDI messages.

channel_pressure(channel, value)

Send a Channel Pressure (aftertouch) message.

Parameters

• channel – MIDI channel, integer on [1,16]

• value – MIDI value, integer on [0,127]

control_change(channel, controller, value)

Send a Controller Change message.

Parameters

• channel – MIDI channel, integer on [1,16]

• controller – MIDI controller index, integer on [0,127]

• value – MIDI value, integer on [0,127]

message(message)

Overridable method to output a single MIDI message.

Parameters

message – list of integers constituting a MIDI message

note_off(channel, note, velocity=0)

Send a Note On message.

Parameters

• channel – MIDI channel, integer on [1,16]

• note – MIDI note, integer on [0,127]

• velocity – optional MIDI velocity, integer on [0,127], normally zero, default zero

note_on(channel, note, velocity)

Send a Note On message.

Parameters

• channel – MIDI channel, integer on [1,16]

• note – MIDI note, integer on [0,127]

• velocity – MIDI velocity, integer on [0,127]

polyphonic_key_pressure(channel, key, pressure)

Send a Polyphonic Key Pressure message.

Parameters

• channel – MIDI channel, integer on [1,16]

• note – MIDI note, integer on [0,127]

• pressure – MIDI aftertouch, integer on [0,127]

class kf.midi.MIDIProcessor

Abstract class for processing MIDI events. Provides a callback for the specific MIDI events we use in our systems so this may be subclassed to implement a MIDI stream processor. This defines an informal protocol for MIDI input. This may be extended to more event times as needed.

channel_pressure(channel, value)

Function to receive messages starting with 0xD0 through 0xDF.

Parameters

• channel – integer from 1 to 16

• value – integer from 0 to 127

control_change(channel, control, value)

Function to receive messages starting with 0xB0 through 0xBF.

Parameters

• channel – integer from 1 to 16

• control – integer from 0 to 127; some have special meanings

• value – integer from 0 to 127

decode_message(message)

Decode a MIDI message expressed as a list of integers and perform callbacks for recognized message types.

Parameters

message – list of integers containing a single MIDI message

decode_mpd218_cc(cc)

Interpret a MPD218 knob control change event as a knob index and bank position. The MPD218 uses a non-contiguous set of channel indices so this normalizes the result. The knob index ranges from 1 to 6 matching the knob labels. Bank 0 is the A bank, bank 1 is the B bank, bank 2 is the C bank.

Parameters

cc – an integer MIDI control channel identifier

Returns

(knob, bank)

decode_mpd218_key(key)

Interpret a MPD218 pad event key value as a row, column, and bank position. Row 0 is the front/bottom row (Pads 1-4), row 3 is the back/top row (Pads 13-16). Column 0 is the left, column 3 is the right. Bank 0 is the A bank, bank 1 is the B bank, bank 2 is the C bank.

Parameters

key – an integer MIDI note value

Returns

(row, column, bank)

note_off(channel, key, velocity)

Function to receive messages starting with 0x80 through 0x8F.

Parameters

• channel – integer from 1 to 16

• key – integer from 0 to 127

• velocity – integer from 0 to 127

note_on(channel, key, velocity)

Function to receive messages starting with 0x90 through 0x9F.

Parameters

• channel – integer from 1 to 16

• key – integer from 0 to 127

• velocity – integer from 0 to 127

polyphonic_key_pressure(channel, key, value)

Function to receive messages starting with 0xA0 through 0xAF.

Parameters

• channel – integer from 1 to 16

• key – integer from 0 to 127

• value – integer from 0 to 127

class kf.midi.QtMIDIListener

Object to manage a MIDI input connection.

connect_midi_processor(processor)

Attach an object to receive MIDI input events, generally a subclass of MIDIProcessor.

get_midi_port_names()

Return a list of unique names for the current MIDI input ports. Duplicate names are modified to guarantee the uniqueness condition.

open_MIDI_input(name)

Open the MIDI in port with the given name (a string). If the port is already open, this will close it first.

class kf.midi.QtMIDISender

Object to manage a MIDI output connection using rtmidi.

get_midi_port_names()

Return a list of names of the current MIDI output ports.

message(message)

Send a single MIDI message.

Parameters

message – list of integers constituting a MIDI message

open_MIDI_output(name)

Open the MIDI out port with the given name (a string). If the port is already open, this will close it first.

kf.app

Objects related to the application event loop and life cycle. This uses QtCore but not QtGui so this functionality is compatible with non-graphical command-line programs.

class kf.app.MainApp

Root application class for managing common elements of our applications. This is intended to be inherited by an top-level application controller along with other root classes which define specific interface API.

Variables

• config – configuration parser object to hold persistent user selections

• configuration_file_path – path of current configuration file, possibly not yet existing

app_has_started()

Callback to be invoked right after the main event loop begins. This may be extended in child classes to implement startup behaviors which require a running event loop.

app_is_exiting()

Callback invoked right before the program ends, either from a keyboard interrupt window close. This may be extended in child classes to clean up external resources, e.g., close any serial ports to remove associated lock files.

initialize_default_configuration()

Method to add default configuration values. This is intended to be extended in child classes. It is called during object initialization.

load_configuration(path=None)

Method to load the current configuration file if it exists. This is not called by default, it must be invoked explicitly by child classes.

save_configuration(path=None)

Method to save the current configuration file. This is not called by default, it must be invoked explicitly by child classes.

kf.app.add_console_log_handler(level=10)

Add an additional root log handler to stream messages to the console.

kf.app.add_file_log_handler(path, level=10)

Add an additional root log handler to stream messages to a file.

kf.app.add_memory_log_handler(level=10)

Add an additional root log handler to capture messages in memory. Returns the handler object. No default target handler is set. This is intended to capture the early startup log before normal output (e.g. logging window) is established.

kf.valve

Interfaces to hardware valve systems. Uses the QtSerialPort module for communication event processing using the Qt event loop.

class kf.valve.QtSerialValve

Class to manage a serial connection to a hardware valve system using Qt QSerialPort object for data transport. The data protocol is based on the ValveControl Arduino sketch.

available_ports()

Return a list of names of available serial ports.

close()

Shut down the serial connection to the Arduino.

data_received(data)

open()

Open the serial port and initialize communications. If the port is already open, this will close it first. If the current name is None, this will not open anything. Returns True if the port is open, else False.

ping()

read_input()

set_and_open_port(name)

set_port(name)

set_speed(axis, velocity)

Set the constant velocity of one or more target positions.

Parameters

• axis – an integer axis index starting with 0

• velocity – a valve PWM rate ranging from -100 to 100

status_message()

stop()

Send a stop command to shut off all valve flow.

write(data)

Core GUI Modules

kf.QtConfig

PyQt5 widgets to create configuration fields and forms.

class kf.QtConfig.QtConfigComboBox(callback=None, default='<no selection>')

Composite widget enabling a user to select an item from a drop down list.

Parameters

• callback – function called with argument (string)

• default – name of initial selection, defaults to ‘<no selection>’

current_item()

select_item(name)

Called to programmatically select an item; updates the display and applies the callback.

set_items(names)

class kf.QtConfig.QtConfigFileButtons(delegate=None, path=None, extension='config')

Composite widget with buttons to control loading and saving a configuration file.

class kf.QtConfig.QtConfigForm

Composite widget to display a form of user-configuration entries.

addField(prompt, widget)

Add a row to the configuration form.

Parameters

• prompt – string of text to display on the left

• widget – a widget to both display status and receive and validate input

class kf.QtConfig.QtConfigOSCPort(callback=None, address='localhost', portnum=3761)

Composite widget enabling a user to configure an address:portnum field.

Parameters

• callback – function called with arguments (address-string, port-integer)

• address – host address string, defaults to ‘localhost’

• portnum – UDP port integer, defaults to 3761

get_OSC_port()

set_OSC_port(address, portnum)

Set the network address and port display as if entered, validating the result and applying the callback.

validate_input()

Called when the user finishes entering text into the line editor.

class kf.QtConfig.QtConfigText(callback, value=None)

Composite widget enabling a user to configure an field of unvalidated text.

Parameters

• callback – function called with argument (string)

• value – initial string, defaults to None which shows as blank

validate_input()

Called when the user finishes entering text into the line editor.

kf.QtLog

PyQt5 widgets to show and control logging output.

class kf.QtLog.QtLog(level=None, logger=None)

Composite widget including log text output and control widgets.

Parameters

• level – initial logging level, defaults to logging.WARNING

• logger – logger object to which to attach, defaults to root logger

flush_and_remove_memory_handler(mem_handler)

get_logging_level()

set_logging_level(title)

Set the current logging level and level display.

write(string)

Write output to the log text area. This enables this object to be used as a stream for printing.

kf.QtMPD218

A PyQt5 GUI to simulate an Akai MPD218 MIDI controller. The actual controller has pressure-sensitive pads, so the simulation is approximate, this is only intended for testing offline without the physical controller.

class kf.QtMPD218.QtMPD218

A composite window providing a simulated MPD218 drum pad interface. Generated MIDI events are emitted as normal Python callbacks to a user-provided MIDI processor object.

buttonPressed(button)

buttonReleased(button)

connect_midi_processor(processor)

dialMoved(dial, value)

setupUi()

timer_tick()