API reference

Synth

class vita.Synth(*args, **kwargs)

Bases: object

A headless Vital synthesizer.

A new Synth starts on the init preset. Load a different one with load_preset or load_json, adjust it through get_controls, then call render or render_file.

Give each thread its own Synth. render, render_file, load_preset, load_json and to_json all release the GIL, so separate instances render in parallel. Sharing one instance across threads is safe but serialized, so it gains you nothing.

__init__(self) → None

clear_modulations(self) → None

Disconnect every modulation, leaving other controls untouched.

connect_modulation(self, source: str, destination: str) → bool

Connects a modulation source to a destination by name.

disconnect_modulation(self, source: str, destination: str) → None

Disconnects a modulation source from a destination by name.

get_control_details(self, name: str) → vita.vita.ControlInfo

Get metadata for a control.

Parameters:

name (str) – Control name, e.g. “delay_style”.

Returns:

Range, scale, default and display information.

Return type:

ControlInfo

Raises:

RuntimeError – If no control has that name.

get_control_text(self, name: str) → str

Get the formatted display text for a control’s current value.

Parameters:

name (str) – Control name, e.g. “delay_style”.

Returns:

The value as Vital would show it, e.g. “Ping Pong”.

Return type:

str

get_controls(self) → dict

Return every control, keyed by name.

Returns:

Live handles – setting one takes effect on this Synth immediately.

Return type:

dict[str, ControlValue]

load_init_preset(self) → None

Reset to the initial preset, clearing any modulations.

load_json(self, json: str) → bool

Load a preset from a JSON string.

Parameters:

json (str) – Contents of a .vital preset.

Returns:

True if the preset was loaded, False if it was malformed or came from a newer version of Vital.

Return type:

bool

load_preset(self, filepath: str) → bool

Load a preset from a .vital file.

Parameters:

filepath (str) – Path to the .vital preset.

Returns:

True if the preset was loaded, False otherwise.

Return type:

bool

render(self, midi_note: int, midi_velocity: float, note_dur: float, render_dur: float) → numpy.ndarray[dtype=float32, shape=(2, *)]

Renders audio to a NumPy array.

Releases the GIL during the render, so threads that each own a separate Synth render in parallel.

Parameters:

• midi_note (int) – MIDI note to render.

• midi_velocity (float) – Velocity of the note [0-1].

• note_dur (float) – Length of the note sustain in seconds.

• render_dur (float) – Length of the audio render in seconds.

Returns:

float32 array shaped (2, render_dur * sample_rate).

Return type:

numpy.ndarray

render_file(self, output_path: str, midi_note: int, midi_velocity: float, note_dur: float, render_dur: float) → bool

Renders audio to a file.

Parameters:

• output_path (str) – Path to the output audio file.

• midi_note (int) – MIDI note to render.

• midi_velocity (float) – Velocity of the note [0-1].

• note_dur (float) – Length of the note sustain in seconds.

• render_dur (float) – Length of the audio render in seconds.

Returns:

True if rendering was successful, False otherwise.

Return type:

bool

set_bpm(self, bpm: float) → None

Set the tempo used by synced LFOs and delays.

Parameters:

bpm (float) – Beats per minute.

set_sample_rate(self, sample_rate: float) → None

Set the render sample rate.

Parameters:

sample_rate (float) – Samples per second, e.g. 44100.

to_json(self) → str

Serialize the current state to a JSON string.

Returns:

Preset JSON, in the same format as a .vital file.

Return type:

str

ControlValue

A live handle to one of a synth’s controls, obtained from vita.Synth.get_controls().

class vita.vita.ControlValue

Bases: object

get_normalized(self) → float

Get control value as normalized 0-1 range

get_text(self) → str

Get formatted display text for the control

set(self, value: int) → None

set(self, value: float) → None

set_normalized(self, value: float) → None

Set control value using normalized 0-1 range

value(self) → float

ControlInfo

Metadata describing a control’s range and presentation, returned by vita.Synth.get_control_details().

class vita.vita.ControlInfo(*args, **kwargs)

Bases: object

property default_value

(self) -> float

property display_multiply

(self) -> float

property display_name

(self) -> str

property display_units

(self) -> str

property is_discrete

(self) -> bool

property max

(self) -> float

property min

(self) -> float

property name

(self) -> str

property options

Display names for a discrete control’s values, in value order.

Empty for continuous controls. A few controls accept more values than Vital has names for, in which case this is shorter than max - min + 1 and the surplus values have no name.

property post_offset

(self) -> float

property scale

(self) -> vita.vita.constants.ValueScale

property version_added

(self) -> int

Module functions

vita.get_modulation_sources() → list

Returns a list of allowed modulation sources.

vita.get_modulation_destinations() → list

Returns a list of allowed modulation destinations

Constants

vita.constants holds the named values for discrete controls.