The Carla Host API. More...

Classes
struct	_CarlaPluginInfo

struct	_CarlaPortCountInfo

struct	_CarlaParameterInfo

struct	_CarlaScalePointInfo

struct	_CarlaTransportInfo

struct	_CarlaRuntimeEngineInfo

struct	CarlaRuntimeEngineDriverDeviceInfo

struct	CarlaInlineDisplayImageSurface

Functions
CARLA_EXPORT uint	carla_get_engine_driver_count (void)

const CARLA_EXPORT char *	carla_get_engine_driver_name (uint index)

const CARLA_EXPORT char const	carla_get_engine_driver_device_names (uint index)

const CARLA_EXPORT EngineDriverDeviceInfo *	carla_get_engine_driver_device_info (uint index, const char *name)

CARLA_EXPORT bool	carla_show_engine_driver_device_control_panel (uint index, const char *name)

CARLA_EXPORT CarlaHostHandle	carla_standalone_host_init (void)

CARLA_EXPORT bool	carla_engine_init (CarlaHostHandle handle, const char driverName, const char clientName)

CARLA_EXPORT bool	carla_engine_close (CarlaHostHandle handle)

CARLA_EXPORT void	carla_engine_idle (CarlaHostHandle handle)

CARLA_EXPORT bool	carla_is_engine_running (CarlaHostHandle handle)

const CARLA_EXPORT CarlaRuntimeEngineInfo *	carla_get_runtime_engine_info (CarlaHostHandle handle)

const CARLA_EXPORT CarlaRuntimeEngineDriverDeviceInfo *	carla_get_runtime_engine_driver_device_info (CarlaHostHandle handle)

CARLA_EXPORT bool	carla_set_engine_buffer_size_and_sample_rate (CarlaHostHandle handle, uint bufferSize, double sampleRate)

CARLA_EXPORT bool	carla_show_engine_device_control_panel (CarlaHostHandle handle)

CARLA_EXPORT void	carla_clear_engine_xruns (CarlaHostHandle handle)

CARLA_EXPORT void	carla_cancel_engine_action (CarlaHostHandle handle)

CARLA_EXPORT bool	carla_set_engine_about_to_close (CarlaHostHandle handle)

CARLA_EXPORT void	carla_set_engine_callback (CarlaHostHandle handle, EngineCallbackFunc func, void *ptr)

CARLA_EXPORT void	carla_set_engine_option (CarlaHostHandle handle, EngineOption option, int value, const char *valueStr)

CARLA_EXPORT void	carla_set_file_callback (CarlaHostHandle handle, FileCallbackFunc func, void *ptr)

CARLA_EXPORT bool	carla_load_file (CarlaHostHandle handle, const char *filename)

CARLA_EXPORT bool	carla_load_project (CarlaHostHandle handle, const char *filename)

CARLA_EXPORT bool	carla_save_project (CarlaHostHandle handle, const char *filename)

const CARLA_EXPORT char *	carla_get_current_project_folder (CarlaHostHandle handle)

const CARLA_EXPORT char *	carla_get_current_project_filename (CarlaHostHandle handle)

CARLA_EXPORT void	carla_clear_project_filename (CarlaHostHandle handle)

CARLA_EXPORT bool	carla_patchbay_connect (CarlaHostHandle handle, bool external, uint groupIdA, uint portIdA, uint groupIdB, uint portIdB)

CARLA_EXPORT bool	carla_patchbay_disconnect (CarlaHostHandle handle, bool external, uint connectionId)

CARLA_EXPORT bool	carla_patchbay_set_group_pos (CarlaHostHandle handle, bool external, uint groupId, int x1, int y1, int x2, int y2)

CARLA_EXPORT bool	carla_patchbay_refresh (CarlaHostHandle handle, bool external)

CARLA_EXPORT void	carla_transport_play (CarlaHostHandle handle)

CARLA_EXPORT void	carla_transport_pause (CarlaHostHandle handle)

CARLA_EXPORT void	carla_transport_bpm (CarlaHostHandle handle, double bpm)

CARLA_EXPORT void	carla_transport_relocate (CarlaHostHandle handle, uint64_t frame)

CARLA_EXPORT uint64_t	carla_get_current_transport_frame (CarlaHostHandle handle)

const CARLA_EXPORT CarlaTransportInfo *	carla_get_transport_info (CarlaHostHandle handle)

CARLA_EXPORT uint32_t	carla_get_current_plugin_count (CarlaHostHandle handle)

CARLA_EXPORT uint32_t	carla_get_max_plugin_number (CarlaHostHandle handle)

CARLA_EXPORT bool	carla_add_plugin (CarlaHostHandle handle, BinaryType btype, PluginType ptype, const char filename, const char name, const char label, int64_t uniqueId, const void extraPtr, uint options)

CARLA_EXPORT bool	carla_remove_plugin (CarlaHostHandle handle, uint pluginId)

CARLA_EXPORT bool	carla_remove_all_plugins (CarlaHostHandle handle)

CARLA_EXPORT bool	carla_rename_plugin (CarlaHostHandle handle, uint pluginId, const char *newName)

CARLA_EXPORT bool	carla_clone_plugin (CarlaHostHandle handle, uint pluginId)

CARLA_EXPORT bool	carla_replace_plugin (CarlaHostHandle handle, uint pluginId)

CARLA_EXPORT bool	carla_switch_plugins (CarlaHostHandle handle, uint pluginIdA, uint pluginIdB)

CARLA_EXPORT bool	carla_load_plugin_state (CarlaHostHandle handle, uint pluginId, const char *filename)

CARLA_EXPORT bool	carla_save_plugin_state (CarlaHostHandle handle, uint pluginId, const char *filename)

CARLA_EXPORT bool	carla_export_plugin_lv2 (CarlaHostHandle handle, uint pluginId, const char *lv2path)

const CARLA_EXPORT CarlaPluginInfo *	carla_get_plugin_info (CarlaHostHandle handle, uint pluginId)

const CARLA_EXPORT CarlaPortCountInfo *	carla_get_audio_port_count_info (CarlaHostHandle handle, uint pluginId)

const CARLA_EXPORT CarlaPortCountInfo *	carla_get_midi_port_count_info (CarlaHostHandle handle, uint pluginId)

const CARLA_EXPORT CarlaPortCountInfo *	carla_get_parameter_count_info (CarlaHostHandle handle, uint pluginId)

const CARLA_EXPORT CarlaParameterInfo *	carla_get_parameter_info (CarlaHostHandle handle, uint pluginId, uint32_t parameterId)

const CARLA_EXPORT CarlaScalePointInfo *	carla_get_parameter_scalepoint_info (CarlaHostHandle handle, uint pluginId, uint32_t parameterId, uint32_t scalePointId)

const CARLA_EXPORT ParameterData *	carla_get_parameter_data (CarlaHostHandle handle, uint pluginId, uint32_t parameterId)

const CARLA_EXPORT ParameterRanges *	carla_get_parameter_ranges (CarlaHostHandle handle, uint pluginId, uint32_t parameterId)

const CARLA_EXPORT MidiProgramData *	carla_get_midi_program_data (CarlaHostHandle handle, uint pluginId, uint32_t midiProgramId)

const CARLA_EXPORT CustomData *	carla_get_custom_data (CarlaHostHandle handle, uint pluginId, uint32_t customDataId)

const CARLA_EXPORT char *	carla_get_custom_data_value (CarlaHostHandle handle, uint pluginId, const char type, const char key)

const CARLA_EXPORT char *	carla_get_chunk_data (CarlaHostHandle handle, uint pluginId)

CARLA_EXPORT uint32_t	carla_get_parameter_count (CarlaHostHandle handle, uint pluginId)

CARLA_EXPORT uint32_t	carla_get_program_count (CarlaHostHandle handle, uint pluginId)

CARLA_EXPORT uint32_t	carla_get_midi_program_count (CarlaHostHandle handle, uint pluginId)

CARLA_EXPORT uint32_t	carla_get_custom_data_count (CarlaHostHandle handle, uint pluginId)

const CARLA_EXPORT char *	carla_get_parameter_text (CarlaHostHandle handle, uint pluginId, uint32_t parameterId)

const CARLA_EXPORT char *	carla_get_program_name (CarlaHostHandle handle, uint pluginId, uint32_t programId)

const CARLA_EXPORT char *	carla_get_midi_program_name (CarlaHostHandle handle, uint pluginId, uint32_t midiProgramId)

const CARLA_EXPORT char *	carla_get_real_plugin_name (CarlaHostHandle handle, uint pluginId)

CARLA_EXPORT int32_t	carla_get_current_program_index (CarlaHostHandle handle, uint pluginId)

CARLA_EXPORT int32_t	carla_get_current_midi_program_index (CarlaHostHandle handle, uint pluginId)

CARLA_EXPORT float	carla_get_default_parameter_value (CarlaHostHandle handle, uint pluginId, uint32_t parameterId)

CARLA_EXPORT float	carla_get_current_parameter_value (CarlaHostHandle handle, uint pluginId, uint32_t parameterId)

CARLA_EXPORT float	carla_get_internal_parameter_value (CarlaHostHandle handle, uint pluginId, int32_t parameterId)

const CARLA_EXPORT float *	carla_get_peak_values (CarlaHostHandle handle, uint pluginId)

CARLA_EXPORT float	carla_get_input_peak_value (CarlaHostHandle handle, uint pluginId, bool isLeft)

CARLA_EXPORT float	carla_get_output_peak_value (CarlaHostHandle handle, uint pluginId, bool isLeft)

const CARLA_EXPORT CarlaInlineDisplayImageSurface *	carla_render_inline_display (CarlaHostHandle handle, uint pluginId, uint32_t width, uint32_t height)

CARLA_EXPORT void	carla_set_active (CarlaHostHandle handle, uint pluginId, bool onOff)

CARLA_EXPORT void	carla_set_drywet (CarlaHostHandle handle, uint pluginId, float value)

CARLA_EXPORT void	carla_set_volume (CarlaHostHandle handle, uint pluginId, float value)

CARLA_EXPORT void	carla_set_balance_left (CarlaHostHandle handle, uint pluginId, float value)

CARLA_EXPORT void	carla_set_balance_right (CarlaHostHandle handle, uint pluginId, float value)

CARLA_EXPORT void	carla_set_panning (CarlaHostHandle handle, uint pluginId, float value)

CARLA_EXPORT void	carla_set_ctrl_channel (CarlaHostHandle handle, uint pluginId, int8_t channel)

CARLA_EXPORT void	carla_set_option (CarlaHostHandle handle, uint pluginId, uint option, bool yesNo)

CARLA_EXPORT void	carla_set_parameter_value (CarlaHostHandle handle, uint pluginId, uint32_t parameterId, float value)

CARLA_EXPORT void	carla_set_parameter_midi_channel (CarlaHostHandle handle, uint pluginId, uint32_t parameterId, uint8_t channel)

CARLA_EXPORT void	carla_set_parameter_mapped_control_index (CarlaHostHandle handle, uint pluginId, uint32_t parameterId, int16_t index)

CARLA_EXPORT void	carla_set_parameter_mapped_range (CarlaHostHandle handle, uint pluginId, uint32_t parameterId, float minimum, float maximum)

CARLA_EXPORT void	carla_set_parameter_touch (CarlaHostHandle handle, uint pluginId, uint32_t parameterId, bool touch)

CARLA_EXPORT void	carla_set_program (CarlaHostHandle handle, uint pluginId, uint32_t programId)

CARLA_EXPORT void	carla_set_midi_program (CarlaHostHandle handle, uint pluginId, uint32_t midiProgramId)

CARLA_EXPORT void	carla_set_custom_data (CarlaHostHandle handle, uint pluginId, const char type, const char key, const char *value)

CARLA_EXPORT void	carla_set_chunk_data (CarlaHostHandle handle, uint pluginId, const char *chunkData)

CARLA_EXPORT void	carla_prepare_for_save (CarlaHostHandle handle, uint pluginId)

CARLA_EXPORT void	carla_reset_parameters (CarlaHostHandle handle, uint pluginId)

CARLA_EXPORT void	carla_randomize_parameters (CarlaHostHandle handle, uint pluginId)

CARLA_EXPORT void	carla_send_midi_note (CarlaHostHandle handle, uint pluginId, uint8_t channel, uint8_t note, uint8_t velocity)

CARLA_EXPORT void	carla_set_custom_ui_title (CarlaHostHandle handle, uint pluginId, const char *title)

CARLA_EXPORT void	carla_show_custom_ui (CarlaHostHandle handle, uint pluginId, bool yesNo)

CARLA_EXPORT void *	carla_embed_custom_ui (CarlaHostHandle handle, uint pluginId, void *ptr)

CARLA_EXPORT uint32_t	carla_get_buffer_size (CarlaHostHandle handle)

CARLA_EXPORT double	carla_get_sample_rate (CarlaHostHandle handle)

const CARLA_EXPORT char *	carla_get_last_error (CarlaHostHandle handle)

const CARLA_EXPORT char *	carla_get_host_osc_url_tcp (CarlaHostHandle handle)

const CARLA_EXPORT char *	carla_get_host_osc_url_udp (CarlaHostHandle handle)

CARLA_EXPORT bool	carla_nsm_init (CarlaHostHandle handle, uint64_t pid, const char *executableName)

CARLA_EXPORT void	carla_nsm_ready (CarlaHostHandle handle, NsmCallbackOpcode opcode)

const CARLA_EXPORT char *	carla_get_complete_license_text (void)

const CARLA_EXPORT char *	carla_get_juce_version (void)

const CARLA_EXPORT char const	carla_get_supported_file_extensions (void)

const CARLA_EXPORT char const	carla_get_supported_features (void)

const CARLA_EXPORT char *	carla_get_library_filename (void)

const CARLA_EXPORT char *	carla_get_library_folder (void)

Detailed Description

The Carla Host API.

This API makes it possible to use the Carla Backend in a standalone host application..

None of the returned values in this API calls need to be deleted or free'd. When a function fails (returns false or NULL), use carla_get_last_error() to find out what went wrong.

Function Documentation

◆ carla_get_engine_driver_count()

CARLA_EXPORT uint carla_get_engine_driver_count ( void )

Get how many engine drivers are available.

◆ carla_get_engine_driver_name()

const CARLA_EXPORT char* carla_get_engine_driver_name ( uint index )

Get an engine driver name.

Parameters

index Driver index

◆ carla_get_engine_driver_device_names()

const CARLA_EXPORT char* const* carla_get_engine_driver_device_names ( uint index )

Get the device names of an engine driver.

Parameters

index Driver index

◆ carla_get_engine_driver_device_info()

const CARLA_EXPORT EngineDriverDeviceInfo* carla_get_engine_driver_device_info	(	uint	index,
		const char *	name
	)

Get information about a device driver.

Parameters

index	Driver index
name	Device name

◆ carla_show_engine_driver_device_control_panel()

CARLA_EXPORT bool carla_show_engine_driver_device_control_panel	(	uint	index,
		const char *	name
	)

Show a device custom control panel.

See also: ENGINE_DRIVER_DEVICE_HAS_CONTROL_PANEL

Parameters

index	Driver index
name	Device name

◆ carla_standalone_host_init()

CARLA_EXPORT CarlaHostHandle carla_standalone_host_init ( void )

Create a global host handle for standalone application usage.

◆ carla_engine_init()

CARLA_EXPORT bool carla_engine_init	(	CarlaHostHandle	handle,
		const char *	driverName,
		const char *	clientName
	)

Initialize the engine. Make sure to call carla_engine_idle() at regular intervals afterwards.

Parameters

driverName	Driver to use
clientName	Engine master client name

◆ carla_engine_close()

CARLA_EXPORT bool carla_engine_close ( CarlaHostHandle handle )

Close the engine. This function always closes the engine even if it returns false. In other words, even when something goes wrong when closing the engine it still be closed nonetheless.

◆ carla_engine_idle()

CARLA_EXPORT void carla_engine_idle ( CarlaHostHandle handle )

Idle the engine. Do not call this if the engine is not running.

◆ carla_is_engine_running()

CARLA_EXPORT bool carla_is_engine_running ( CarlaHostHandle handle )

Check if the engine is running.

◆ carla_get_runtime_engine_info()

const CARLA_EXPORT CarlaRuntimeEngineInfo* carla_get_runtime_engine_info ( CarlaHostHandle handle )

Get information about the currently running engine.

◆ carla_get_runtime_engine_driver_device_info()

const CARLA_EXPORT CarlaRuntimeEngineDriverDeviceInfo* carla_get_runtime_engine_driver_device_info ( CarlaHostHandle handle )

Get information about the currently running engine driver device.

◆ carla_set_engine_buffer_size_and_sample_rate()

CARLA_EXPORT bool carla_set_engine_buffer_size_and_sample_rate	(	CarlaHostHandle	handle,
		uint	bufferSize,
		double	sampleRate
	)

Dynamically change buffer size and/or sample rate while engine is running.

See also: ENGINE_DRIVER_DEVICE_VARIABLE_BUFFER_SIZE; ENGINE_DRIVER_DEVICE_VARIABLE_SAMPLE_RATE

◆ carla_show_engine_device_control_panel()

CARLA_EXPORT bool carla_show_engine_device_control_panel ( CarlaHostHandle handle )

Show the custom control panel for the current engine device.

See also: ENGINE_DRIVER_DEVICE_HAS_CONTROL_PANEL

◆ carla_clear_engine_xruns()

CARLA_EXPORT void carla_clear_engine_xruns ( CarlaHostHandle handle )

Clear the xrun count on the engine, so that the next time carla_get_runtime_engine_info() is called, it returns 0.

◆ carla_cancel_engine_action()

CARLA_EXPORT void carla_cancel_engine_action ( CarlaHostHandle handle )

Tell the engine to stop the current cancelable action.

See also: ENGINE_CALLBACK_CANCELABLE_ACTION

◆ carla_set_engine_about_to_close()

CARLA_EXPORT bool carla_set_engine_about_to_close ( CarlaHostHandle handle )

Tell the engine it's about to close. This is used to prevent the engine thread(s) from reactivating. Returns true if there's no pending engine events.

◆ carla_set_engine_callback()

CARLA_EXPORT void carla_set_engine_callback	(	CarlaHostHandle	handle,
		EngineCallbackFunc	func,
		void *	ptr
	)

Set the engine callback function.

Parameters

func	Callback function
ptr	Callback pointer

◆ carla_set_engine_option()

CARLA_EXPORT void carla_set_engine_option	(	CarlaHostHandle	handle,
		EngineOption	option,
		int	value,
		const char *	valueStr
	)

Set an engine option.

Parameters

option	Option
value	Value as number
valueStr	Value as string

◆ carla_set_file_callback()

CARLA_EXPORT void carla_set_file_callback	(	CarlaHostHandle	handle,
		FileCallbackFunc	func,
		void *	ptr
	)

Set the file callback function.

Parameters

func	Callback function
ptr	Callback pointer

◆ carla_load_file()

CARLA_EXPORT bool carla_load_file	(	CarlaHostHandle	handle,
		const char *	filename
	)

Load a file of any type. This will try to load a generic file as a plugin, either by direct handling (SF2 and SFZ) or by using an internal plugin (like Audio and MIDI).

See also: carla_get_supported_file_extensions()

◆ carla_load_project()

CARLA_EXPORT bool carla_load_project	(	CarlaHostHandle	handle,
		const char *	filename
	)

Load a Carla project file.

Note: Currently loaded plugins are not removed; call carla_remove_all_plugins() first if needed.

◆ carla_save_project()

CARLA_EXPORT bool carla_save_project	(	CarlaHostHandle	handle,
		const char *	filename
	)

Save current project to a file.

◆ carla_get_current_project_folder()

const CARLA_EXPORT char* carla_get_current_project_folder ( CarlaHostHandle handle )

Get the currently set project folder.

Note: Valid for both standalone and plugin versions.

◆ carla_get_current_project_filename()

const CARLA_EXPORT char* carla_get_current_project_filename ( CarlaHostHandle handle )

Get the currently set project filename.

Note: Valid only for both standalone version.

◆ carla_clear_project_filename()

CARLA_EXPORT void carla_clear_project_filename ( CarlaHostHandle handle )

Clear the currently set project filename.

◆ carla_patchbay_connect()

CARLA_EXPORT bool carla_patchbay_connect	(	CarlaHostHandle	handle,
		bool	external,
		uint	groupIdA,
		uint	portIdA,
		uint	groupIdB,
		uint	portIdB
	)

Connect two patchbay ports.

Parameters

groupIdA	Output group
portIdA	Output port
groupIdB	Input group
portIdB	Input port

See also: ENGINE_CALLBACK_PATCHBAY_CONNECTION_ADDED

◆ carla_patchbay_disconnect()

CARLA_EXPORT bool carla_patchbay_disconnect	(	CarlaHostHandle	handle,
		bool	external,
		uint	connectionId
	)

Disconnect two patchbay ports.

Parameters

connectionId Connection Id

See also: ENGINE_CALLBACK_PATCHBAY_CONNECTION_REMOVED

◆ carla_patchbay_set_group_pos()

CARLA_EXPORT bool carla_patchbay_set_group_pos	(	CarlaHostHandle	handle,
		bool	external,
		uint	groupId,
		int	x1,
		int	y1,
		int	x2,
		int	y2
	)

Set the position of a group. This is purely cached and saved in the project file, Carla backend does nothing with the value. When loading a project, callbacks are used to inform of the previously saved positions.

See also: ENGINE_CALLBACK_PATCHBAY_CLIENT_POSITION_CHANGED

◆ carla_patchbay_refresh()

CARLA_EXPORT bool carla_patchbay_refresh	(	CarlaHostHandle	handle,
		bool	external
	)

Force the engine to resend all patchbay clients, ports and connections again.

Parameters

external Wherever to show external/hardware ports instead of internal ones. Only valid in patchbay engine mode, other modes will ignore this.

◆ carla_transport_play()

CARLA_EXPORT void carla_transport_play ( CarlaHostHandle handle )

Start playback of the engine transport.

◆ carla_transport_pause()

CARLA_EXPORT void carla_transport_pause ( CarlaHostHandle handle )

Pause the engine transport.

◆ carla_transport_bpm()

CARLA_EXPORT void carla_transport_bpm	(	CarlaHostHandle	handle,
		double	bpm
	)

Set the engine transport bpm.

◆ carla_transport_relocate()

CARLA_EXPORT void carla_transport_relocate	(	CarlaHostHandle	handle,
		uint64_t	frame
	)

Relocate the engine transport to a specific frame.

◆ carla_get_current_transport_frame()

CARLA_EXPORT uint64_t carla_get_current_transport_frame ( CarlaHostHandle handle )

Get the current transport frame.

◆ carla_get_transport_info()

const CARLA_EXPORT CarlaTransportInfo* carla_get_transport_info ( CarlaHostHandle handle )

Get the engine transport information.

◆ carla_get_current_plugin_count()

CARLA_EXPORT uint32_t carla_get_current_plugin_count ( CarlaHostHandle handle )

Current number of plugins loaded.

◆ carla_get_max_plugin_number()

CARLA_EXPORT uint32_t carla_get_max_plugin_number ( CarlaHostHandle handle )

Maximum number of loadable plugins allowed. Returns 0 if engine is not started.

◆ carla_add_plugin()

CARLA_EXPORT bool carla_add_plugin	(	CarlaHostHandle	handle,
		BinaryType	btype,
		PluginType	ptype,
		const char *	filename,
		const char *	name,
		const char *	label,
		int64_t	uniqueId,
		const void *	extraPtr,
		uint	options
	)

Add a new plugin. If you don't know the binary type use the BINARY_NATIVE macro.

Parameters

btype	Binary type
ptype	Plugin type
filename	Filename, if applicable
name	Name of the plugin, can be NULL
label	Plugin label, if applicable
uniqueId	Plugin unique Id, if applicable
extraPtr	Extra pointer, defined per plugin type
options	Initial plugin options

◆ carla_remove_plugin()

CARLA_EXPORT bool carla_remove_plugin	(	CarlaHostHandle	handle,
		uint	pluginId
	)

Remove one plugin.

Parameters

pluginId Plugin to remove.

◆ carla_remove_all_plugins()

CARLA_EXPORT bool carla_remove_all_plugins ( CarlaHostHandle handle )

Remove all plugins.

◆ carla_rename_plugin()

CARLA_EXPORT bool carla_rename_plugin	(	CarlaHostHandle	handle,
		uint	pluginId,
		const char *	newName
	)

Rename a plugin. Returns the new name, or NULL if the operation failed.

Parameters

pluginId	Plugin to rename
newName	New plugin name

◆ carla_clone_plugin()

CARLA_EXPORT bool carla_clone_plugin	(	CarlaHostHandle	handle,
		uint	pluginId
	)

Clone a plugin.

Parameters

pluginId Plugin to clone

◆ carla_replace_plugin()

CARLA_EXPORT bool carla_replace_plugin	(	CarlaHostHandle	handle,
		uint	pluginId
	)

Prepare replace of a plugin. The next call to carla_add_plugin() will use this id, replacing the current plugin.

Parameters

pluginId Plugin to replace

Note: This function requires carla_add_plugin() to be called afterwards as soon as possible.

◆ carla_switch_plugins()

CARLA_EXPORT bool carla_switch_plugins	(	CarlaHostHandle	handle,
		uint	pluginIdA,
		uint	pluginIdB
	)

Switch two plugins positions.

Parameters

pluginIdA	Plugin A
pluginIdB	Plugin B

◆ carla_load_plugin_state()

CARLA_EXPORT bool carla_load_plugin_state	(	CarlaHostHandle	handle,
		uint	pluginId,
		const char *	filename
	)

Load a plugin state.

Parameters

pluginId	Plugin
filename	Path to plugin state

See also: carla_save_plugin_state()

◆ carla_save_plugin_state()

CARLA_EXPORT bool carla_save_plugin_state	(	CarlaHostHandle	handle,
		uint	pluginId,
		const char *	filename
	)

Save a plugin state.

Parameters

pluginId	Plugin
filename	Path to plugin state

See also: carla_load_plugin_state()

◆ carla_export_plugin_lv2()

CARLA_EXPORT bool carla_export_plugin_lv2	(	CarlaHostHandle	handle,
		uint	pluginId,
		const char *	lv2path
	)

Export plugin as LV2.

Parameters

pluginId	Plugin
lv2path	Path to lv2 plugin folder

◆ carla_get_plugin_info()

const CARLA_EXPORT CarlaPluginInfo* carla_get_plugin_info	(	CarlaHostHandle	handle,
		uint	pluginId
	)

Get information from a plugin.

Parameters

pluginId Plugin

◆ carla_get_audio_port_count_info()

const CARLA_EXPORT CarlaPortCountInfo* carla_get_audio_port_count_info	(	CarlaHostHandle	handle,
		uint	pluginId
	)

Get audio port count information from a plugin.

Parameters

pluginId Plugin

◆ carla_get_midi_port_count_info()

const CARLA_EXPORT CarlaPortCountInfo* carla_get_midi_port_count_info	(	CarlaHostHandle	handle,
		uint	pluginId
	)

Get MIDI port count information from a plugin.

Parameters

pluginId Plugin

◆ carla_get_parameter_count_info()

const CARLA_EXPORT CarlaPortCountInfo* carla_get_parameter_count_info	(	CarlaHostHandle	handle,
		uint	pluginId
	)

Get parameter count information from a plugin.

Parameters

pluginId Plugin

◆ carla_get_parameter_info()

const CARLA_EXPORT CarlaParameterInfo* carla_get_parameter_info	(	CarlaHostHandle	handle,
		uint	pluginId,
		uint32_t	parameterId
	)

Get parameter information from a plugin.

Parameters

pluginId	Plugin
parameterId	Parameter index

See also: carla_get_parameter_count()

◆ carla_get_parameter_scalepoint_info()

const CARLA_EXPORT CarlaScalePointInfo* carla_get_parameter_scalepoint_info	(	CarlaHostHandle	handle,
		uint	pluginId,
		uint32_t	parameterId,
		uint32_t	scalePointId
	)

Get parameter scale point information from a plugin.

Parameters

pluginId	Plugin
parameterId	Parameter index
scalePointId	Parameter scale-point index

See also: CarlaParameterInfo::scalePointCount

◆ carla_get_parameter_data()

const CARLA_EXPORT ParameterData* carla_get_parameter_data	(	CarlaHostHandle	handle,
		uint	pluginId,
		uint32_t	parameterId
	)

Get a plugin's parameter data.

Parameters

pluginId	Plugin
parameterId	Parameter index

See also: carla_get_parameter_count()

◆ carla_get_parameter_ranges()

const CARLA_EXPORT ParameterRanges* carla_get_parameter_ranges	(	CarlaHostHandle	handle,
		uint	pluginId,
		uint32_t	parameterId
	)

Get a plugin's parameter ranges.

Parameters

pluginId	Plugin
parameterId	Parameter index

See also: carla_get_parameter_count()

◆ carla_get_midi_program_data()

const CARLA_EXPORT MidiProgramData* carla_get_midi_program_data	(	CarlaHostHandle	handle,
		uint	pluginId,
		uint32_t	midiProgramId
	)

Get a plugin's MIDI program data.

Parameters

pluginId	Plugin
midiProgramId	MIDI Program index

See also: carla_get_midi_program_count()

◆ carla_get_custom_data()

const CARLA_EXPORT CustomData* carla_get_custom_data	(	CarlaHostHandle	handle,
		uint	pluginId,
		uint32_t	customDataId
	)

Get a plugin's custom data, using index.

Parameters

pluginId	Plugin
customDataId	Custom data index

See also: carla_get_custom_data_count()

◆ carla_get_custom_data_value()

const CARLA_EXPORT char* carla_get_custom_data_value	(	CarlaHostHandle	handle,
		uint	pluginId,
		const char *	type,
		const char *	key
	)

Get a plugin's custom data value, using type and key.

Parameters

pluginId	Plugin
type	Custom data type
key	Custom data key

See also: carla_get_custom_data_count()

◆ carla_get_chunk_data()

const CARLA_EXPORT char* carla_get_chunk_data	(	CarlaHostHandle	handle,
		uint	pluginId
	)

Get a plugin's chunk data.

Parameters

pluginId Plugin

See also: PLUGIN_OPTION_USE_CHUNKS and carla_set_chunk_data()

◆ carla_get_parameter_count()

CARLA_EXPORT uint32_t carla_get_parameter_count	(	CarlaHostHandle	handle,
		uint	pluginId
	)

Get how many parameters a plugin has.

Parameters

pluginId Plugin

◆ carla_get_program_count()

CARLA_EXPORT uint32_t carla_get_program_count	(	CarlaHostHandle	handle,
		uint	pluginId
	)

Get how many programs a plugin has.

Parameters

pluginId Plugin

See also: carla_get_program_name()

◆ carla_get_midi_program_count()

CARLA_EXPORT uint32_t carla_get_midi_program_count	(	CarlaHostHandle	handle,
		uint	pluginId
	)

Get how many MIDI programs a plugin has.

Parameters

pluginId Plugin

See also: carla_get_midi_program_name() and carla_get_midi_program_data()

◆ carla_get_custom_data_count()

CARLA_EXPORT uint32_t carla_get_custom_data_count	(	CarlaHostHandle	handle,
		uint	pluginId
	)

Get how many custom data sets a plugin has.

Parameters

pluginId Plugin

See also: carla_get_custom_data()

◆ carla_get_parameter_text()

const CARLA_EXPORT char* carla_get_parameter_text	(	CarlaHostHandle	handle,
		uint	pluginId,
		uint32_t	parameterId
	)

Get a plugin's parameter text (custom display of internal values).

Parameters

pluginId	Plugin
parameterId	Parameter index

See also: PARAMETER_USES_CUSTOM_TEXT

◆ carla_get_program_name()

const CARLA_EXPORT char* carla_get_program_name	(	CarlaHostHandle	handle,
		uint	pluginId,
		uint32_t	programId
	)

Get a plugin's program name.

Parameters

pluginId	Plugin
programId	Program index

See also: carla_get_program_count()

◆ carla_get_midi_program_name()

const CARLA_EXPORT char* carla_get_midi_program_name	(	CarlaHostHandle	handle,
		uint	pluginId,
		uint32_t	midiProgramId
	)

Get a plugin's MIDI program name.

Parameters

pluginId	Plugin
midiProgramId	MIDI Program index

See also: carla_get_midi_program_count()

◆ carla_get_real_plugin_name()

const CARLA_EXPORT char* carla_get_real_plugin_name	(	CarlaHostHandle	handle,
		uint	pluginId
	)

Get a plugin's real name. This is the name the plugin uses to identify itself; may not be unique.

Parameters

pluginId Plugin

◆ carla_get_current_program_index()

CARLA_EXPORT int32_t carla_get_current_program_index	(	CarlaHostHandle	handle,
		uint	pluginId
	)

Get a plugin's program index.

Parameters

pluginId Plugin

◆ carla_get_current_midi_program_index()

CARLA_EXPORT int32_t carla_get_current_midi_program_index	(	CarlaHostHandle	handle,
		uint	pluginId
	)

Get a plugin's midi program index.

Parameters

pluginId Plugin

◆ carla_get_default_parameter_value()

CARLA_EXPORT float carla_get_default_parameter_value	(	CarlaHostHandle	handle,
		uint	pluginId,
		uint32_t	parameterId
	)

Get a plugin's default parameter value.

Parameters

pluginId	Plugin
parameterId	Parameter index

◆ carla_get_current_parameter_value()

CARLA_EXPORT float carla_get_current_parameter_value	(	CarlaHostHandle	handle,
		uint	pluginId,
		uint32_t	parameterId
	)

Get a plugin's current parameter value.

Parameters

pluginId	Plugin
parameterId	Parameter index

◆ carla_get_internal_parameter_value()

CARLA_EXPORT float carla_get_internal_parameter_value	(	CarlaHostHandle	handle,
		uint	pluginId,
		int32_t	parameterId
	)

Get a plugin's internal parameter value.

Parameters

pluginId	Plugin
parameterId	Parameter index, maybe be negative

See also: InternalParameterIndex

◆ carla_get_peak_values()

const CARLA_EXPORT float* carla_get_peak_values	(	CarlaHostHandle	handle,
		uint	pluginId
	)

Get a plugin's peak values.

Parameters

pluginId Plugin

◆ carla_get_input_peak_value()

CARLA_EXPORT float carla_get_input_peak_value	(	CarlaHostHandle	handle,
		uint	pluginId,
		bool	isLeft
	)

Get a plugin's input peak value.

Parameters

pluginId	Plugin
isLeft	Wherever to get the left/mono value, otherwise right.

◆ carla_get_output_peak_value()

CARLA_EXPORT float carla_get_output_peak_value	(	CarlaHostHandle	handle,
		uint	pluginId,
		bool	isLeft
	)

Get a plugin's output peak value.

Parameters

pluginId	Plugin
isLeft	Wherever to get the left/mono value, otherwise right.

◆ carla_render_inline_display()

const CARLA_EXPORT CarlaInlineDisplayImageSurface* carla_render_inline_display	(	CarlaHostHandle	handle,
		uint	pluginId,
		uint32_t	width,
		uint32_t	height
	)

Render a plugin's inline display.

Parameters

pluginId Plugin

◆ carla_set_active()

CARLA_EXPORT void carla_set_active	(	CarlaHostHandle	handle,
		uint	pluginId,
		bool	onOff
	)

Enable or disable a plugin.

Parameters

pluginId	Plugin
onOff	New active state

◆ carla_set_drywet()

CARLA_EXPORT void carla_set_drywet	(	CarlaHostHandle	handle,
		uint	pluginId,
		float	value
	)

Change a plugin's internal dry/wet.

Parameters

pluginId	Plugin
value	New dry/wet value

◆ carla_set_volume()

CARLA_EXPORT void carla_set_volume	(	CarlaHostHandle	handle,
		uint	pluginId,
		float	value
	)

Change a plugin's internal volume.

Parameters

pluginId	Plugin
value	New volume

◆ carla_set_balance_left()

CARLA_EXPORT void carla_set_balance_left	(	CarlaHostHandle	handle,
		uint	pluginId,
		float	value
	)

Change a plugin's internal stereo balance, left channel.

Parameters

pluginId	Plugin
value	New value

◆ carla_set_balance_right()

CARLA_EXPORT void carla_set_balance_right	(	CarlaHostHandle	handle,
		uint	pluginId,
		float	value
	)

Change a plugin's internal stereo balance, right channel.

Parameters

pluginId	Plugin
value	New value

◆ carla_set_panning()

CARLA_EXPORT void carla_set_panning	(	CarlaHostHandle	handle,
		uint	pluginId,
		float	value
	)

Change a plugin's internal mono panning value.

Parameters

pluginId	Plugin
value	New value

◆ carla_set_ctrl_channel()

CARLA_EXPORT void carla_set_ctrl_channel	(	CarlaHostHandle	handle,
		uint	pluginId,
		int8_t	channel
	)

Change a plugin's internal control channel.

Parameters

pluginId	Plugin
channel	New channel

◆ carla_set_option()

CARLA_EXPORT void carla_set_option	(	CarlaHostHandle	handle,
		uint	pluginId,
		uint	option,
		bool	yesNo
	)

Enable a plugin's option.

Parameters

pluginId	Plugin
option	An option from PluginOptions
yesNo	New enabled state

◆ carla_set_parameter_value()

CARLA_EXPORT void carla_set_parameter_value	(	CarlaHostHandle	handle,
		uint	pluginId,
		uint32_t	parameterId,
		float	value
	)

Change a plugin's parameter value.

Parameters

pluginId	Plugin
parameterId	Parameter index
value	New value

◆ carla_set_parameter_midi_channel()

CARLA_EXPORT void carla_set_parameter_midi_channel	(	CarlaHostHandle	handle,
		uint	pluginId,
		uint32_t	parameterId,
		uint8_t	channel
	)

Change a plugin's parameter MIDI channel.

Parameters

pluginId	Plugin
parameterId	Parameter index
channel	New MIDI channel

◆ carla_set_parameter_mapped_control_index()

CARLA_EXPORT void carla_set_parameter_mapped_control_index	(	CarlaHostHandle	handle,
		uint	pluginId,
		uint32_t	parameterId,
		int16_t	index
	)

Change a plugin's parameter mapped control index.

Parameters

pluginId	Plugin
parameterId	Parameter index
cc	New control index

◆ carla_set_parameter_mapped_range()

CARLA_EXPORT void carla_set_parameter_mapped_range	(	CarlaHostHandle	handle,
		uint	pluginId,
		uint32_t	parameterId,
		float	minimum,
		float	maximum
	)

Change a plugin's parameter mapped range.

Parameters

pluginId	Plugin
parameterId	Parameter index
minimum	New mapped minimum
maximum	New mapped maximum

◆ carla_set_parameter_touch()

CARLA_EXPORT void carla_set_parameter_touch	(	CarlaHostHandle	handle,
		uint	pluginId,
		uint32_t	parameterId,
		bool	touch
	)

Change a plugin's parameter in drag/touch mode state. Usually happens from a UI when the user is moving a parameter with a mouse or similar input.

Parameters

pluginId	Plugin
parameterId	Parameter index
touch	New state

◆ carla_set_program()

CARLA_EXPORT void carla_set_program	(	CarlaHostHandle	handle,
		uint	pluginId,
		uint32_t	programId
	)

Change a plugin's current program.

Parameters

pluginId	Plugin
programId	New program

◆ carla_set_midi_program()

CARLA_EXPORT void carla_set_midi_program	(	CarlaHostHandle	handle,
		uint	pluginId,
		uint32_t	midiProgramId
	)

Change a plugin's current MIDI program.

Parameters

pluginId	Plugin
midiProgramId	New value

◆ carla_set_custom_data()

CARLA_EXPORT void carla_set_custom_data	(	CarlaHostHandle	handle,
		uint	pluginId,
		const char *	type,
		const char *	key,
		const char *	value
	)

Set a plugin's custom data set.

Parameters

pluginId	Plugin
type	Type
key	Key
value	New value

See also: Custom Data Types and Custom Data Keys

◆ carla_set_chunk_data()

CARLA_EXPORT void carla_set_chunk_data	(	CarlaHostHandle	handle,
		uint	pluginId,
		const char *	chunkData
	)

Set a plugin's chunk data.

Parameters

pluginId	Plugin
chunkData	New chunk data

See also: PLUGIN_OPTION_USE_CHUNKS and carla_get_chunk_data()

◆ carla_prepare_for_save()

CARLA_EXPORT void carla_prepare_for_save	(	CarlaHostHandle	handle,
		uint	pluginId
	)

Tell a plugin to prepare for save. This should be called before saving custom data sets.

Parameters

pluginId Plugin

◆ carla_reset_parameters()

CARLA_EXPORT void carla_reset_parameters	(	CarlaHostHandle	handle,
		uint	pluginId
	)

Reset all plugin's parameters.

Parameters

pluginId Plugin

◆ carla_randomize_parameters()

CARLA_EXPORT void carla_randomize_parameters	(	CarlaHostHandle	handle,
		uint	pluginId
	)

Randomize all plugin's parameters.

Parameters

pluginId Plugin

◆ carla_send_midi_note()

CARLA_EXPORT void carla_send_midi_note	(	CarlaHostHandle	handle,
		uint	pluginId,
		uint8_t	channel,
		uint8_t	note,
		uint8_t	velocity
	)

Send a single note of a plugin. If velocity is 0, note-off is sent; note-on otherwise.

Parameters

pluginId	Plugin
channel	Note channel
note	Note pitch
velocity	Note velocity

◆ carla_set_custom_ui_title()

CARLA_EXPORT void carla_set_custom_ui_title	(	CarlaHostHandle	handle,
		uint	pluginId,
		const char *	title
	)

Set a custom title for the plugin UI window created by Carla.

◆ carla_show_custom_ui()

CARLA_EXPORT void carla_show_custom_ui	(	CarlaHostHandle	handle,
		uint	pluginId,
		bool	yesNo
	)

Tell a plugin to show its own custom UI.

Parameters

pluginId	Plugin
yesNo	New UI state, visible or not

See also: PLUGIN_HAS_CUSTOM_UI

◆ carla_embed_custom_ui()

CARLA_EXPORT void* carla_embed_custom_ui	(	CarlaHostHandle	handle,
		uint	pluginId,
		void *	ptr
	)

Embed the plugin's custom UI to the system pointer ptr. This function is always called from the main thread.

Note: This is very experimental and subject to change at this point

◆ carla_get_buffer_size()

CARLA_EXPORT uint32_t carla_get_buffer_size ( CarlaHostHandle handle )

Get the current engine buffer size.

◆ carla_get_sample_rate()

CARLA_EXPORT double carla_get_sample_rate ( CarlaHostHandle handle )

Get the current engine sample rate.

◆ carla_get_last_error()

const CARLA_EXPORT char* carla_get_last_error ( CarlaHostHandle handle )

Get the last error.

◆ carla_get_host_osc_url_tcp()

const CARLA_EXPORT char* carla_get_host_osc_url_tcp ( CarlaHostHandle handle )

Get the current engine OSC URL (TCP).

◆ carla_get_host_osc_url_udp()

const CARLA_EXPORT char* carla_get_host_osc_url_udp ( CarlaHostHandle handle )

Get the current engine OSC URL (UDP).

◆ carla_nsm_init()

CARLA_EXPORT bool carla_nsm_init	(	CarlaHostHandle	handle,
		uint64_t	pid,
		const char *	executableName
	)

Initialize NSM (that is, announce ourselves to it). Must be called as early as possible in the program's lifecycle. Returns true if NSM is available and initialized correctly.

◆ carla_nsm_ready()

CARLA_EXPORT void carla_nsm_ready	(	CarlaHostHandle	handle,
		NsmCallbackOpcode	opcode
	)

Respond to an NSM callback.

◆ carla_get_complete_license_text()

const CARLA_EXPORT char* carla_get_complete_license_text ( void )

Get the complete license text of used third-party code and features. Returned string is in basic html format.

◆ carla_get_juce_version()

const CARLA_EXPORT char* carla_get_juce_version ( void )

Get the juce version used in the current Carla build.

◆ carla_get_supported_file_extensions()

const CARLA_EXPORT char* const* carla_get_supported_file_extensions ( void )

Get the list of supported file extensions in carla_load_file().

◆ carla_get_supported_features()

const CARLA_EXPORT char* const* carla_get_supported_features ( void )

Get the list of supported features in the current Carla build.

◆ carla_get_library_filename()

const CARLA_EXPORT char* carla_get_library_filename ( void )

Get the absolute filename of this carla library.

◆ carla_get_library_folder()

const CARLA_EXPORT char* carla_get_library_folder ( void )

Get the folder where this carla library resides.

Classes

Functions

Detailed Description

Function Documentation

◆ carla_get_engine_driver_count()

◆ carla_get_engine_driver_name()

◆ carla_get_engine_driver_device_names()

◆ carla_get_engine_driver_device_info()

◆ carla_show_engine_driver_device_control_panel()

◆ carla_standalone_host_init()

◆ carla_engine_init()

◆ carla_engine_close()

◆ carla_engine_idle()

◆ carla_is_engine_running()

◆ carla_get_runtime_engine_info()

◆ carla_get_runtime_engine_driver_device_info()

◆ carla_set_engine_buffer_size_and_sample_rate()

◆ carla_show_engine_device_control_panel()

◆ carla_clear_engine_xruns()

◆ carla_cancel_engine_action()

◆ carla_set_engine_about_to_close()

◆ carla_set_engine_callback()

◆ carla_set_engine_option()

◆ carla_set_file_callback()

◆ carla_load_file()

◆ carla_load_project()

◆ carla_save_project()

◆ carla_get_current_project_folder()

◆ carla_get_current_project_filename()

◆ carla_clear_project_filename()

◆ carla_patchbay_connect()

◆ carla_patchbay_disconnect()

◆ carla_patchbay_set_group_pos()

◆ carla_patchbay_refresh()

◆ carla_transport_play()

◆ carla_transport_pause()

◆ carla_transport_bpm()

◆ carla_transport_relocate()

◆ carla_get_current_transport_frame()

◆ carla_get_transport_info()

◆ carla_get_current_plugin_count()

◆ carla_get_max_plugin_number()

◆ carla_add_plugin()

◆ carla_remove_plugin()

◆ carla_remove_all_plugins()

◆ carla_rename_plugin()

◆ carla_clone_plugin()

◆ carla_replace_plugin()

◆ carla_switch_plugins()

◆ carla_load_plugin_state()

◆ carla_save_plugin_state()

◆ carla_export_plugin_lv2()

◆ carla_get_plugin_info()

◆ carla_get_audio_port_count_info()

◆ carla_get_midi_port_count_info()

◆ carla_get_parameter_count_info()

◆ carla_get_parameter_info()

◆ carla_get_parameter_scalepoint_info()

◆ carla_get_parameter_data()

◆ carla_get_parameter_ranges()

◆ carla_get_midi_program_data()

◆ carla_get_custom_data()

◆ carla_get_custom_data_value()

◆ carla_get_chunk_data()

◆ carla_get_parameter_count()

◆ carla_get_program_count()

◆ carla_get_midi_program_count()

◆ carla_get_custom_data_count()

◆ carla_get_parameter_text()

◆ carla_get_program_name()

◆ carla_get_midi_program_name()

◆ carla_get_real_plugin_name()

◆ carla_get_current_program_index()

◆ carla_get_current_midi_program_index()

◆ carla_get_default_parameter_value()

◆ carla_get_current_parameter_value()

◆ carla_get_internal_parameter_value()

◆ carla_get_peak_values()

◆ carla_get_input_peak_value()

◆ carla_get_output_peak_value()