Values and messages

Value dataclass

One entry of a control's <values>: its live state.

Parameters:

Name	Type	Description	Default
key	str	x, y, touch, text or page, depending on the control.	'touch'
locked	bool	Whether the value is locked against user interaction.	False
locked_default_current	bool	Whether the lock holds the current value rather than the default.	False
default	bool | float | str	The value the control starts at.	False
default_pull	int	How strongly the value returns to its default, 0 to 100.	0

Source code in src/py2tosc/messages.py

@dataclass
class Value:
    """One entry of a control's `<values>`: its live state.

    Args:
        key: `x`, `y`, `touch`, `text` or `page`, depending on the control.
        locked: Whether the value is locked against user interaction.
        locked_default_current: Whether the lock holds the current value rather
            than the default.
        default: The value the control starts at.
        default_pull: How strongly the value returns to its default, 0 to 100.
    """

    key: str = "touch"
    locked: bool = False
    locked_default_current: bool = False
    default: bool | float | str = False
    default_pull: int = 0

Messages

OscMessage dataclass

An OSC binding.

The default sends the control's x value to /<control name> on every change, over every connection.

Parameters:

Name	Type	Description	Default
enabled	bool	Whether the binding is active.	True
send	bool	Whether the control transmits.	True
receive	bool	Whether the control accepts incoming messages.	True
feedback	bool	Whether received messages are echoed back.	False
no_duplicates	bool	Whether to suppress repeated identical messages.	False
connections	str	One character per connection slot, 1 for enabled.	ALL_CONNECTIONS
triggers	list[Trigger]	What causes the message to be sent.	_default_triggers()
path	list[Partial]	The partials that build the OSC address.	_default_path()
arguments	list[Partial]	The partials that build the OSC arguments.	_default_arguments()

Source code in src/py2tosc/messages.py

@dataclass
class OscMessage:
    """An OSC binding.

    The default sends the control's `x` value to `/<control name>` on every
    change, over every connection.

    Args:
        enabled: Whether the binding is active.
        send: Whether the control transmits.
        receive: Whether the control accepts incoming messages.
        feedback: Whether received messages are echoed back.
        no_duplicates: Whether to suppress repeated identical messages.
        connections: One character per connection slot, `1` for enabled.
        triggers: What causes the message to be sent.
        path: The partials that build the OSC address.
        arguments: The partials that build the OSC arguments.
    """

    enabled: bool = True
    send: bool = True
    receive: bool = True
    feedback: bool = False
    no_duplicates: bool = False
    connections: str = ALL_CONNECTIONS
    triggers: list[Trigger] = field(default_factory=_default_triggers)
    path: list[Partial] = field(default_factory=_default_path)
    arguments: list[Partial] = field(default_factory=_default_arguments)

MidiMessage dataclass

A MIDI binding.

The default sends the control's x value as CC 0 on channel 0, scaled to 0-127.

Parameters:

Name	Type	Description	Default
enabled	bool	Whether the binding is active.	True
send	bool	Whether the control transmits.	True
receive	bool	Whether the control accepts incoming messages.	True
feedback	bool	Whether received messages are echoed back.	False
no_duplicates	bool	Whether to suppress repeated identical messages.	False
connections	str	One character per connection slot, 1 for enabled.	ALL_CONNECTIONS
triggers	list[Trigger]	What causes the message to be sent.	_default_triggers()
message	MidiCommand	The status bytes to send.	MidiCommand()
values	list[MidiValue]	The three slots the data bytes are drawn from.	_default_midi_values()

Source code in src/py2tosc/messages.py

@dataclass
class MidiMessage:
    """A MIDI binding.

    The default sends the control's `x` value as CC 0 on channel 0, scaled to
    0-127.

    Args:
        enabled: Whether the binding is active.
        send: Whether the control transmits.
        receive: Whether the control accepts incoming messages.
        feedback: Whether received messages are echoed back.
        no_duplicates: Whether to suppress repeated identical messages.
        connections: One character per connection slot, `1` for enabled.
        triggers: What causes the message to be sent.
        message: The status bytes to send.
        values: The three slots the data bytes are drawn from.
    """

    enabled: bool = True
    send: bool = True
    receive: bool = True
    feedback: bool = False
    no_duplicates: bool = False
    connections: str = ALL_CONNECTIONS
    triggers: list[Trigger] = field(default_factory=_default_triggers)
    message: MidiCommand = field(default_factory=MidiCommand)
    values: list[MidiValue] = field(default_factory=_default_midi_values)

LocalMessage dataclass

A binding to another control in the same layout.

Parameters:

Name	Type	Description	Default
enabled	bool	Whether the binding is active.	True
triggers	list[Trigger]	What causes the message to be sent.	_default_triggers()
type	PartialType | str	Where the sent content comes from.	VALUE
conversion	Conversion | str	The type the content is converted to.	FLOAT
value	str	The value or property key to read.	'x'
scale_min	float	Low end of the output range.	0
scale_max	float	High end of the output range.	1
dst_type	str	The type expected by the destination.	''
dst_var	str	The value or property to write on the destination.	''
dst_id	str	The id of the destination control.	''

Source code in src/py2tosc/messages.py

@dataclass
class LocalMessage:
    """A binding to another control in the same layout.

    Args:
        enabled: Whether the binding is active.
        triggers: What causes the message to be sent.
        type: Where the sent content comes from.
        conversion: The type the content is converted to.
        value: The value or property key to read.
        scale_min: Low end of the output range.
        scale_max: High end of the output range.
        dst_type: The type expected by the destination.
        dst_var: The value or property to write on the destination.
        dst_id: The `id` of the destination control.
    """

    enabled: bool = True
    triggers: list[Trigger] = field(default_factory=_default_triggers)
    type: PartialType | str = PartialType.VALUE
    conversion: Conversion | str = Conversion.FLOAT
    value: str = "x"
    scale_min: float = 0
    scale_max: float = 1
    dst_type: str = ""
    dst_var: str = ""
    dst_id: str = ""

GamepadMessage dataclass

A binding to a game controller button or axis.

Unlike the other three, a gamepad binding is one-directional and carries no triggers: the controller drives the control, so there is nothing to send.

Parameters:

Name	Type	Description	Default
enabled	bool	Whether the binding is active.	True
connections	str	One character per gamepad slot, 1 for enabled. This field is four wide, unlike the ten of an OSC or MIDI binding.	ALL_GAMEPADS
type	str	The button or axis, for example BUTTON_A or AXIS_LEFT_X.	'BUTTON_A'
conversion	Conversion | str	The type the input is converted to.	FLOAT
scale_min	float	Low end of the output range.	0
scale_max	float	High end of the output range.	1
target_type	PartialType | str	Whether the input drives a value or a property.	VALUE
target_var	str	The value or property to write on this control.	'x'

Source code in src/py2tosc/messages.py

@dataclass
class GamepadMessage:
    """A binding to a game controller button or axis.

    Unlike the other three, a gamepad binding is one-directional and carries no
    triggers: the controller drives the control, so there is nothing to send.

    Args:
        enabled: Whether the binding is active.
        connections: One character per gamepad slot, `1` for enabled. This
            field is four wide, unlike the ten of an OSC or MIDI binding.
        type: The button or axis, for example `BUTTON_A` or `AXIS_LEFT_X`.
        conversion: The type the input is converted to.
        scale_min: Low end of the output range.
        scale_max: High end of the output range.
        target_type: Whether the input drives a value or a property.
        target_var: The value or property to write on this control.
    """

    enabled: bool = True
    connections: str = ALL_GAMEPADS
    type: str = "BUTTON_A"
    conversion: Conversion | str = Conversion.FLOAT
    scale_min: float = 0
    scale_max: float = 1
    target_type: PartialType | str = PartialType.VALUE
    target_var: str = "x"

Message module-attribute

Message = (
    OscMessage | MidiMessage | LocalMessage | GamepadMessage
)

Any binding type a control can carry.

Connection fields

A binding carries one character per connection slot, 1 for enabled. The two constants below are the "all of them" value for each width, and are the defaults on the message types above.

ALL_CONNECTIONS module-attribute

ALL_CONNECTIONS = '1' * 10

ALL_GAMEPADS module-attribute

ALL_GAMEPADS = '1' * 4

Message parts

Trigger dataclass

A condition under which a message is sent.

Parameters:

Name	Type	Description	Default
var	str	The value that is watched, usually x or touch.	'x'
condition	TriggerCondition | str	Whether to fire on any change, or only on a rise or fall.	ANY

Source code in src/py2tosc/messages.py

@dataclass
class Trigger:
    """A condition under which a message is sent.

    Args:
        var: The value that is watched, usually `x` or `touch`.
        condition: Whether to fire on any change, or only on a rise or fall.
    """

    var: str = "x"
    condition: TriggerCondition | str = TriggerCondition.ANY

Partial dataclass

One segment of an OSC address or one OSC argument.

An address like /synth/cutoff is built from partials: a CONSTANT /, then a PROPERTY naming the control, and so on.

Parameters:

Name	Type	Description	Default
type	PartialType | str	Where the segment's content comes from.	CONSTANT
conversion	Conversion | str	The type the segment is converted to before sending.	STRING
value	str	The constant text, property key or value key, depending on type.	'/'
scale_min	float	Low end of the output range, for VALUE partials.	0
scale_max	float	High end of the output range, for VALUE partials.	1

Source code in src/py2tosc/messages.py

@dataclass
class Partial:
    """One segment of an OSC address or one OSC argument.

    An address like `/synth/cutoff` is built from partials: a `CONSTANT` `/`,
    then a `PROPERTY` naming the control, and so on.

    Args:
        type: Where the segment's content comes from.
        conversion: The type the segment is converted to before sending.
        value: The constant text, property key or value key, depending on `type`.
        scale_min: Low end of the output range, for `VALUE` partials.
        scale_max: High end of the output range, for `VALUE` partials.
    """

    type: PartialType | str = PartialType.CONSTANT
    conversion: Conversion | str = Conversion.STRING
    value: str = "/"
    scale_min: float = 0
    scale_max: float = 1

MidiCommand dataclass

The <message> inside a MIDI binding: the status bytes to send.

Parameters:

Name	Type	Description	Default
type	MidiType | str	The MIDI status byte.	CONTROLCHANGE
channel	int	MIDI channel, 0-15.	0
data1	int	First data byte, for example the CC number.	0
data2	int	Second data byte.	0

Source code in src/py2tosc/messages.py

@dataclass
class MidiCommand:
    """The `<message>` inside a MIDI binding: the status bytes to send.

    Args:
        type: The MIDI status byte.
        channel: MIDI channel, 0-15.
        data1: First data byte, for example the CC number.
        data2: Second data byte.
    """

    type: MidiType | str = MidiType.CONTROLCHANGE
    channel: int = 0
    data1: int = 0
    data2: int = 0

MidiValue dataclass

One of the three slots a MIDI message draws its bytes from.

Parameters:

Name	Type	Description	Default
type	PartialType | str	CONSTANT, INDEX, VALUE or PROPERTY.	CONSTANT
key	str	The value or property key, when type needs one.	''
scale_min	float	Low end of the output range.	0
scale_max	float	High end of the output range.	15

Source code in src/py2tosc/messages.py

@dataclass
class MidiValue:
    """One of the three slots a MIDI message draws its bytes from.

    Args:
        type: `CONSTANT`, `INDEX`, `VALUE` or `PROPERTY`.
        key: The value or property key, when `type` needs one.
        scale_min: Low end of the output range.
        scale_max: High end of the output range.
    """

    type: PartialType | str = PartialType.CONSTANT
    key: str = ""
    scale_min: float = 0
    scale_max: float = 15