SkineticSDK::Skinetic

This class is used as the main API interface.

Public Classes

	Name
class	ConnectionState Enum describing device connection status.
class	DeviceInfo Class returned by a scan and containing all information of an introspected device.
class	DeviceType Enum to define the type of device.
class	EffectProperties Haptic Structure to describe how effect instances reproduce a pattern with variations.
class	EffectState Enum describing the state of an effect instance.
class	ExpAudioPreset Experimental Preset of audio devices.
class	LogLevel Enum Level of logs.
class	OutputType Enum to define the target output mode.

Public Functions

	Name
	init(self self, str log_file_path ="") Instantiate a new Skinetic SDK.
	update_device_list(self self, OutputType output_type =OutputType.AutoDetect, bool blocking =True) Initialize a scanning routine to find all available Skinetic device.
list	get_device_list(self self, bool wait_end_of_scan =False) Get the list of devices.
	connect(self self, OutputType output_type =OutputType.AutoDetect, int serial_number =0, bool blocking =True) Initialize an asynchronous or synchronous connection to a Skinetic device using the selected type of connection.
	disconnect(self self, bool blocking =True) Disconnects the current Skinetic device The disconnection is effective once all resources are released.
ConnectionState	get_connection_state(self self) Check the current status of the connection.
	set_connection_callback(self self, typing. Callable[[ConnectionState, SkineticErrorCode, int], None] callback) Set a callback function fired upon connection changes.
str	get_sdk_version(self self) Get SDK version as a string.
int	get_skinetic_serial_number(self self) Get the connected device's serial number.
str	get_skinetic_serial_number_as_str(self self) Get the connected device's serial number as a string.
str	get_skinetic_version(self self) Get the connected device's version as a string.
DeviceType	get_skinetic_type(self self) Get the connected device's type.
int	get_global_intensity_boost(self self) Get the amount of global intensity boost.
	set_global_intensity_boost(self self, int global_boost) Set the amount of global intensity boost.
int	load_pattern_json(self self, str json_string) Load a pattern from a valid json into a local haptic asset and return the corresponding pattern_id.
	unload_pattern(self self, int pattern_id) Unload the pattern from of the corresponding pattern_id.
int	get_pattern_intensity_boost(self self, int pattern_id) Get the pattern boost value which serves as a default value for the playing effect.
	set_accumulation_window_to_pattern(self self, int main_pattern_id, int fallback_pattern_id, float time_window, int max_accumulation) Enable the effect accumulation strategy on a targeted pattern.
	erase_accumulation_pattern(self self, int main_pattern_id) Disable the effect accumulation strategy on a specific pattern if any set.
int	play_effect(self self, int pattern_id, EffectProperties properties =EffectProperties()) Play a haptic effect based on a loaded pattern and return the effectID of this instance.
	stop_effect(self self, int effect_id, float fadeout =0) Stop the effect instance identified by its effectID.
EffectState	get_effect_state(self self, int effect_id) Get the current state of an effect.
	pause_all(self self) Pause all haptic effect that are currently playing.
	resume_all(self self) Resume the paused haptic effects.
	stop_all(self self) Stop all playing haptic effect.
	exp_enable_legacy_backend(self self, bool enable) [Experimental] Enable legacy backend If boolean is set to true, the legacy backend is used instead of the default backend.
	exp_connect_ash(self self, OutputType output_type =OutputType.AutoDetect, int serial_number =0, str loopback_interface ="", bool blocking =True) [Experimental] Initialize an asynchronous connection to a Skinetic device and use the ASH-fx library for haptic generation.
	exp_connect_audio(self self, ExpAudioPreset preset =ExpAudioPreset.eCustomDevice, str device_name ="default_output", str audio_api ="any_API", int sample_rate =48000, int buffer_size =256, int nb_stream_channels =-1, float suggested_latency =0) [Experimental] Initialize an asynchronous connection to an audio device using the provided settings.
	exp_connect_ash_audio(self self, ExpAudioPreset preset =ExpAudioPreset.eCustomDevice, str device_name ="default_output", str audio_api ="any_API", int sample_rate =48000, int buffer_size =256, int nb_stream_channels =-1, float suggested_latency =0, str loopback_interface ="") [Experimental] Initialize an asynchronous connection to an audio device and use the ASH-fx library for haptic generation.
	exp_set_ash_volume(self self, float volume) [Experimental] Set the volume of the ASH-generated haptic track.
float	exp_get_ash_volume(self self) [Experimental] Get the volume of the ASH-generated haptic track.
str	serial_number_to_str(int serial_number =0) Convert Skinetic serial number to a formatted string.
	set_log_callback(typing. Callable[[LogLevel, str, str], None] callback =None) Set a callback function to override Skinetic native logger.
list	exp_get_output_device_names() [Experimental] Get names of available output devices.
list	exp_get_loopback_device_names() [Experimental] Get names of available loopback devices.
list	exp_get_output_devices_apis(str output_name) [Experimental] Get available APIs for a given output device identified by name.
dict	exp_get_output_device_info(str name, str api) [Experimental] Get settings extremum values of the output device identified by name and API.
list	exp_get_supported_standard_sample_rates(str output_name, str output_api) [Experimental] Get all supported standard sample rates for the output device identified by name and API.

Public Functions Documentation

function init

__init__(
    self self,
    str log_file_path =""
)

Instantiate a new Skinetic SDK.

Parameters:

• log_file_path (str, optional) path of the file to log in. Leave blank to use the default SkineticSDK.log file. File path can be absolute or relative to the directory containing the library.

function update_device_list

update_device_list(
    self self,
    OutputType output_type =OutputType.AutoDetect,
    bool blocking =True
)

Initialize a scanning routine to find all available Skinetic device.

Parameters:

• output_type (OutputType, optional) type of connection to introspect.
• blocking (bool, optional) defines whether the method is blocking during the scan or not.

function get_device_list

list get_device_list(
    self self,
    bool wait_end_of_scan =False
)

Get the list of devices.

Parameters:

• wait_end_of_scan (bool, optional) A boolean flag to indicate whether to wait for the scan to be finished. Default is False.

Return: list of DeviceInfo

This method retrieves the list of devices that have been scanned. You can optionally wait for the scan to finish before fetching the device list.

function connect

connect(
    self self,
    OutputType output_type =OutputType.AutoDetect,
    int serial_number =0,
    bool blocking =True
)

Initialize an asynchronous or synchronous connection to a Skinetic device using the selected type of connection.

Parameters:

• output_type (OutputType, optional) type of connection device. Defaults to OutputType.AutoDetect.
• serial_number (int, optional) serial number of the Skinetic Device to connect to. Defaults to 0.
• blocking (bool, optional) A boolean flag to indicate whether to wait for the connection to finish. Default is True.

The state of the routine can be obtained from get_connection_state(). If the serial number is set to 0, the connection will be performed on the first found device.

function disconnect

disconnect(
    self self,
    bool blocking =True
)

Disconnects the current Skinetic device The disconnection is effective once all resources are released.

Parameters:

• blocking (bool, optional) A boolean flag to indicate whether to wait for the disconnection to finish. Defaults to True.

The state of the routine can be obtained from get_connection_state().

function get_connection_state

ConnectionState get_connection_state(
    self self
)

Check the current status of the connection.

Return: (ConnectionState) status of connection of the device

The asynchronous connection routine is terminated on failure

function set_connection_callback

set_connection_callback(
    self self,
    typing. Callable[[ConnectionState, SkineticErrorCode, int],
    None] callback
)

Set a callback function fired upon connection changes.

Parameters:

• callback (typing.Callable[[ConnectionState, SkineticErrorCode, int], None]) Client's callback function

The connection callback is implemented by users (you).

The callback is fired at the end of the connection routine whether it succeeded or failed. It is also fired if a connection issue arise. Pass None to set_connection_callback() to disable the callback.

The callback function will be called with the following parameters:

• connection_state (ConnectionState): status of the connection
• error_code (SkineticErrorCode): type of error occurring
• serial_number (int): serial number of the device firing the callback

function get_sdk_version

str get_sdk_version(
    self self
)

Get SDK version as a string.

Return: (str) version string

The format of the string is: major.minor.revision

function get_skinetic_serial_number

int get_skinetic_serial_number(
    self self
)

Get the connected device's serial number.

Return: (int) the serial number of the connected Skinetic device if any, raises an Exception otherwise.

function get_skinetic_serial_number_as_str

str get_skinetic_serial_number_as_str(
    self self
)

Get the connected device's serial number as a string.

Return:

• (str) the serial number as a string of the connected Skinetic device if any, "noDeviceConnected"
• otherwise.

function get_skinetic_version

str get_skinetic_version(
    self self
)

Get the connected device's version as a string.

Return: (str) the version string if a Skinetic device is connected, "noDeviceConnected" otherwise.

The format of the string is: major.minor.revision

function get_skinetic_type

DeviceType get_skinetic_type(
    self self
)

Get the connected device's type.

Return: (DeviceType) type of the connected Skinetic device if it is connected, raises an Exception otherwise.

function get_global_intensity_boost

int get_global_intensity_boost(
    self self
)

Get the amount of global intensity boost.

Return: (int) the global intensity boost.

This boost increase the overall intensity of all haptic effects. However, the higher the boost activation is, the more the haptic effects are degraded. The global boost is meant to be set by the user as an application setting.

function set_global_intensity_boost

set_global_intensity_boost(
    self self,
    int global_boost
)

Set the amount of global intensity boost.

Return: global_boost (int) global boost value

The boost increase the overall intensity of all haptic effects. However, the higher the boost activation is, the more the haptic effects are degraded. The global boost is meant to be set by the user as an application setting.

function load_pattern_json

int load_pattern_json(
    self self,
    str json_string
)

Load a pattern from a valid json into a local haptic asset and return the corresponding pattern_id.

Parameters:

• json_string (str) json describing the pattern.

Return: (int) positive pattern_id on success, raises an Exception otherwise.

function unload_pattern

unload_pattern(
    self self,
    int pattern_id
)

Unload the pattern from of the corresponding pattern_id.

Parameters:

• pattern_id (int) id of the pattern to unload.

function get_pattern_intensity_boost

int get_pattern_intensity_boost(
    self self,
    int pattern_id
)

Get the pattern boost value which serves as a default value for the playing effect.

Parameters:

• pattern_id (int) the ID of the targeted pattern.

Return: (int) the pattern intensity boost of the pattern if it exists, 0 otherwise.

The value is ranged in [-100; 100].

function set_accumulation_window_to_pattern

set_accumulation_window_to_pattern(
    self self,
    int main_pattern_id,
    int fallback_pattern_id,
    float time_window,
    int max_accumulation
)

Enable the effect accumulation strategy on a targeted pattern.

Parameters:

• main_pattern_id (int) the pattern_id of the main pattern
• fallback_pattern_id (int) the pattern_id of the fallback pattern
• time_window (float) the time window during which the accumulation should happen
• max_accumulation (int) max number in [0; infinity[ of extra accumulated effect instances

Whenever an effect is triggered on the main pattern, the fallback one is used instead, if the main is already playing. More details can be found the additional documentation. For the max_accumulation, setting to 0 removes the limit.

If a new call to this function is done for a specific pattern, the previous association is overridden.

function erase_accumulation_pattern

erase_accumulation_pattern(
    self self,
    int main_pattern_id
)

Disable the effect accumulation strategy on a specific pattern if any set.

Parameters:

• main_pattern_id (int) the pattern_id of the main pattern.

function play_effect

int play_effect(
    self self,
    int pattern_id,
    EffectProperties properties =EffectProperties()
)

Play a haptic effect based on a loaded pattern and return the effectID of this instance.

Parameters:

• pattern_id (int) id of the pattern used by the effect instance.
• properties (EffectProperties) specialisation properties of the effect.

Return: (int) id of the effect instance

The instance index is positive. Each call to play_effect() using the same pattern_id generates a new haptic effect instance totally uncorrelated to the previous ones. The instance is destroyed once it stops playing.

The haptic effect instance reproduces the pattern with variations describes in the class EffectProperties(). More information on these parameters and how to use them can be found in the class description. Transformation and boolean operations are not applicable to actuator-based patterns. If the pattern is unloaded, the haptic effect is not interrupted.

function stop_effect

stop_effect(
    self self,
    int effect_id,
    float fadeout =0
)

Stop the effect instance identified by its effectID.

Parameters:

• effect_id (int) index identifying the effect.
• fadeout (float, optional) time duration of the fadeout in second.

The effect is stop in "time" seconds with a fadeout to prevent abrupt transition. If "time" is set to 0, no fadeout is applied and the effect is stopped as soon as possible. Once an effect is stopped, its instance is destroyed and its effect_id invalidated.

function get_effect_state

EffectState get_effect_state(
    self self,
    int effect_id
)

Get the current state of an effect.

Parameters:

• effect_id (int) index identifying the effect.

Return: (EffectState) the current state of the effect.

If the effect_id is invalid, the 'stop' state will be returned.

function pause_all

pause_all(
    self self
)

Pause all haptic effect that are currently playing.

function resume_all

resume_all(
    self self
)

Resume the paused haptic effects.

function stop_all

stop_all(
    self self
)

Stop all playing haptic effect.

function exp_enable_legacy_backend

exp_enable_legacy_backend(
    self self,
    bool enable
)

[Experimental] Enable legacy backend If boolean is set to true, the legacy backend is used instead of the default backend.

Parameters:

• enable set to true to enable, false to disable.

function exp_connect_ash

exp_connect_ash(
    self self,
    OutputType output_type =OutputType.AutoDetect,
    int serial_number =0,
    str loopback_interface ="",
    bool blocking =True
)

[Experimental] Initialize an asynchronous connection to a Skinetic device and use the ASH-fx library for haptic generation.

Parameters:

• output_type (OutputType, optional) type of connection device. Defaults to OutputType.AutoDetect.
• serial_number (int, optional) serial number of the Skinetic Device to connect to. Defaults to 0.
• loopback_interface (str, optional) input loopback interface to use (to feed ASH). Defaults to the default output device of the computer.
• blocking (bool, optional) A boolean flag to indicate whether to wait for the connection to finish. Default is True.

The ASH-fx library generates haptic signals based on the audio of the targeted input loopback interface. The loopback interfaces can be queried by calling getLoopbackDevicesNames(). Setting loopbackInterface to NULL selects the default audio output device of the system.

function exp_connect_audio

exp_connect_audio(
    self self,
    ExpAudioPreset preset =ExpAudioPreset.eCustomDevice,
    str device_name ="default_output",
    str audio_api ="any_API",
    int sample_rate =48000,
    int buffer_size =256,
    int nb_stream_channels =-1,
    float suggested_latency =0
)

[Experimental] Initialize an asynchronous connection to an audio device using the provided settings.

Parameters:

• preset (ExpAudioPreset, optional) preset of audio device.
• device_name name of the targeted audio device, default value "default_output" uses the OS default audio device. If using a specific ExpAudioPreset other than eCustomDevice, the parameter will be ignored.
• audio_api name of the targeted API. Default value "any_API" uses any available API which match the configuration, if any. If using a specific ExpAudioPreset other than eCustomDevice, the parameter will be ignored.
• sample_rate sample rate of the audio stream. If using a specific ExpAudioPreset,the parameter will be ignored.
• buffer_size size (strictly positive) of a chunk of data sent over the audio stream. This parameter MUST be set independently of the used ExpAudioPreset.
• nb_stream_channels number of channels (strictly positive) to use while streaming to the haptic output. If using a specific audio preset, the parameter will be ignored. Setting -1 will use the number of actuator of the layout, or a portion of it.
• suggested_latency desired latency in seconds. The value is rounded to the closest available latency value from the audio API. If using a specific ExpAudioPreset other than eCustomDevice, the parameter will be ignored.

   If ExpAudioPreset is set to anything else other than ExpAudioPreset.eCustomDevice,
   the provided settings are ignored and the ones corresponding to the preset are used instead.
   Notice that this connection is not compatible with the legacy backend.

function exp_connect_ash_audio

exp_connect_ash_audio(
    self self,
    ExpAudioPreset preset =ExpAudioPreset.eCustomDevice,
    str device_name ="default_output",
    str audio_api ="any_API",
    int sample_rate =48000,
    int buffer_size =256,
    int nb_stream_channels =-1,
    float suggested_latency =0,
    str loopback_interface =""
)

[Experimental] Initialize an asynchronous connection to an audio device and use the ASH-fx library for haptic generation.

Parameters:

• preset (ExpAudioPreset, optional) preset of audio device.
• device_name name of the targeted audio device, default value "default_output" uses the OS default audio device. If using a specific ExpAudioPreset other than eCustomDevice, the parameter will be ignored.
• audio_api name of the targeted API. Default value "any_API" uses any available API which match the configuration, if any. If using a specific ExpAudioPreset other than eCustomDevice, the parameter will be ignored.
• sample_rate sample rate of the audio stream. If using a specific ExpAudioPreset,the parameter will be ignored.
• buffer_size size (strictly positive) of a chunk of data sent over the audio stream. This parameter MUST be set independently of the used ExpAudioPreset.
• nb_stream_channels number of channels (strictly positive) to use while streaming to the haptic output. If using a specific audio preset, the parameter will be ignored. Setting -1 will use the number of actuator of the layout, or a portion of it.
• suggested_latency desired latency in seconds. The value is rounded to the closest available latency value from the audio API. If using a specific ExpAudioPreset other than eCustomDevice, the parameter will be ignored.
• loopback_interface (str, optional) input loopback interface to use (to feed ASH). Defaults to the default output device of the computer.

The ASH-fx library generates haptic signals based on the audio of the targeted input loopback interface. The loopback interfaces can be queried by calling getLoopbackDevicesNames(). Setting loopbackInterface to NULL selects the default audio output device of the system. If ExpAudioPreset is set to anything else other than ExpAudioPreset.eCustomDevice, the provided settings are ignored and the ones corresponding to the preset are used instead.

function exp_set_ash_volume

exp_set_ash_volume(
    self self,
    float volume
)

[Experimental] Set the volume of the ASH-generated haptic track.

Parameters:

• volume (float) normalized haptic volume (1 means 100%, values above 1 can be used but might produce clipping).

function exp_get_ash_volume

float exp_get_ash_volume(
    self self
)

[Experimental] Get the volume of the ASH-generated haptic track.

Return: (float) the normalized volume of the ASH-generated haptic track.

function serial_number_to_str

static str serial_number_to_str(
    int serial_number =0
)

Convert Skinetic serial number to a formatted string.

Parameters:

• serial_number (int) serial number to convert.

Return: (str) string representation of the serial number.

function set_log_callback

static set_log_callback(
    typing. Callable[[LogLevel, str, str],
    None] callback =None
)

Set a callback function to override Skinetic native logger.

Parameters:

• callback (typing.Callable[[LogLevel, str, str], None]) Client's callback function

It should be set before initialisation of a Skinetic object. This callback will be called every time a log message is produced by the SDK.

The callback function takes the following arguments:

• level (LogLevel): the level of the log message
• scope (str): string giving information about the SDK scope that send the log
• message (str): string containing the log message

Set the callback to None will disable logging.

function exp_get_output_device_names

static list exp_get_output_device_names()

[Experimental] Get names of available output devices.

Return: (str list) the list of device names.

If no device is available, the list will contain "noDevice".

function exp_get_loopback_device_names

static list exp_get_loopback_device_names()

[Experimental] Get names of available loopback devices.

Return: (str list) the list of device names.

If no device is available, the list will contain "noDevice".

function exp_get_output_devices_apis

static list exp_get_output_devices_apis(
    str output_name
)

[Experimental] Get available APIs for a given output device identified by name.

Parameters:

• output_name (str) name of the output device.

Return: (str list) list of API names

If no API is available, the list will contain "noAPI". This function will fill the list passed as argument with the names of the APIs available to the given output device

function exp_get_output_device_info

static dict exp_get_output_device_info(
    str name,
    str api
)

[Experimental] Get settings extremum values of the output device identified by name and API.

Parameters:

• name (str) name of the output device.
• api (str) name of the API.

Return: (dict) a dictionary containing the values for the specified device and api

function exp_get_supported_standard_sample_rates

static list exp_get_supported_standard_sample_rates(
    str output_name,
    str output_api
)

[Experimental] Get all supported standard sample rates for the output device identified by name and API.

Parameters:

• output_name (str) name of the output device.
• output_api (str) name of the API.

Return: (list) list of sample rates

If the output_name or the output_api are not valid, an error is raised.

---

Updated on 2024-06-05 at 16:05:52 +0000