Model

class audonnx.Model(path, *, labels=None, transform=None, device='cpu', num_workers=1, session_options=None)

Model with multiple input and output nodes.

For input nodes an optional transform can be given that transforms the input into the desired representation, otherwise the raw input is used. Use dictionary to assign transform objects to specific nodes if model has multiple input nodes.

For output nodes an optional list of labels can be given to assign names to the last non-dynamic dimension. E.g. if the shape of the output node is (1, 3, -1) three labels can be assigned to the second dimension. By default, labels are generated from the name of the node. Use dictionary to assign labels to specific nodes if model has multiple output nodes.

Model inherites from audobject.Object, which means you can serialize to and instantiate the class from a YAML file. Have a look at audobject.Object to see all available methods.

Parameters

• path (str | ModelProto) – ONNX proto object or path to ONNX file

• labels (Union[Sequence[str], dict[str, Optional[Sequence[str]]], None]) – list of labels or dictionary with labels

• transform (Union[Callable[[ndarray, int], ndarray], Function, dict[str, Callable[[ndarray, int], ndarray] | Function], None]) – callable object or a dictionary of callable objects

• device (str | tuple[str, dict] | Sequence[str | tuple[str, dict]]) – set device ('cpu', 'cuda', or 'cuda:<id>') or a (list of) provider(s)

• num_workers (Optional[int]) – number of threads for running onnxruntime inference on cpu. If None and session_options is None, onnxruntime chooses the number of threads

• session_options (Optional[SessionOptions]) – onnxruntime.SessionOptions to use for inference. If None the default options are used and the number of threads for running inference on cpu is determined by num_workers. Otherwise, the provided options are used and the session_options properties inter_op_num_threads and intra_op_num_threads determine the number of threads for inference on cpu and num_workers is ignored

Examples

>>> import audiofile
>>> import opensmile
>>> transform = opensmile.Smile(
...     opensmile.FeatureSet.GeMAPSv01b,
...     opensmile.FeatureLevel.LowLevelDescriptors,
... )
>>> path = os.path.join("tests", "model.onnx")
>>> model = Model(
...     path,
...     labels=["female", "male"],
...     transform=transform,
... )
>>> model
Input:
  feature:
    shape: [18, -1]
    dtype: tensor(float)
    transform: opensmile.core.smile.Smile
Output:
  gender:
    shape: [2]
    dtype: tensor(float)
    labels: [female, male]
>>> path = os.path.join("tests", "test.wav")
>>> signal, sampling_rate = audiofile.read(path)
>>> model(
...     signal,
...     sampling_rate,
...     outputs="gender",
... ).round(1)
array([-195.1,   73.3], dtype=float32)

__call__()

Model.__call__(inputs, sampling_rate=None, *, outputs=None, concat=False, squeeze=False)

Compute output for one or more nodes.

If inputs is a numpy.ndarray, it is treated as the input signal.

If inputs is a dictionary, the dictionary entries correspond to the input names and input values, and the argument names and values for input transformation.

If outputs is a plain string, the output of the according node is returned.

If outputs is a list of strings, a dictionary with according nodes as keys and their outputs as values is returned.

If outputs is not set and the model has a single output node, the output of that node is returned. Otherwise a dictionary with outputs of all nodes is returned.

If concat is set to True, the output of the requested nodes is concatenated along the last non-dynamic axis and a single array is returned. This requires that the number of dimensions, the position of dynamic axis, and all dimensions except the last non-dynamic axis match for the requested nodes

Use audonnx.Model.outputs to get a list of available output nodes.

Parameters

• inputs (ndarray | dict[str, object]) – model input signal or dictionary with multiple inputs

• sampling_rate (Optional[int]) – sampling rate in Hz

• outputs (Union[str, Sequence[str], None]) – name of output or list with output names

• concat (bool) – if True, concatenate output of the requested nodes

• squeeze (bool) – if True, remove axes of length one from the output(s)

Return type

ndarray | dict[str, ndarray]

Returns

model output

Raises

• RuntimeError – if concat is True, but output of requested nodes cannot be concatenated

• ValueError – if a required model input is missing

arguments

Model.arguments

Returns arguments that are serialized.

Returns

Dictionary of arguments and their values.

Raises

RuntimeError – if arguments are found that are not assigned to attributes of the same name

Examples

>>> import audobject.testing
>>> o = audobject.testing.TestObject("test", point=(1, 1))
>>> o.arguments
{'name': 'test', 'point': (1, 1)}

borrowed_arguments

Model.borrowed_arguments

Returns borrowed arguments.

Returns

Dictionary with borrowed arguments.

from_dict()

static Model.from_dict(d, root=None, **kwargs)

Return type

Object

from_yaml()

static Model.from_yaml(path_or_stream, **kwargs)

Return type

Object

from_yaml_s()

static Model.from_yaml_s(yaml_string, **kwargs)

Return type

Object

hidden_arguments

Model.hidden_arguments

Returns hidden arguments.

Returns

List with names of hidden arguments.

id

Model.id

Object identifier.

The ID of an object ID is created from its non-hidden arguments.

Returns

object identifier

Examples

>>> class Foo(Object):
...     def __init__(self, bar: str):
...         self.bar = bar
>>> foo1 = Foo("I am unique!")
>>> foo1.id
'893df240-babe-d796-cdf1-c436171b7a96'
>>> foo2 = Foo("I am different!")
>>> foo2.id
'9303f2a5-bfc9-e5ff-0ffa-a9846e2d2190'
>>> foo3 = Foo("I am unique!")
>>> foo1.id == foo3.id
True

inputs

Model.inputs

Input nodes

is_loaded_from_dict

Model.is_loaded_from_dict

Check if object was loaded from a dictionary.

Returns True if object was initialized from a dictionary, e.g. after loading it from a YAML file.

Returns

True if object was loaded from a dictionary,

otherwise False

labels()

Model.labels(outputs=None)

Collect labels of output nodes.

Parameters

outputs (Union[str, Sequence[str], None]) – name of output or list with output names. Selects all output nodes by default

Return type

Sequence[str]

Returns

list with labels

outputs

Model.outputs

Output nodes

path

Model.path

Model path

resolvers

Model.resolvers

Return resolvers.

Returns

Dictionary with resolvers.

sess

Model.sess

Interference session

short_id

Model.short_id

Short object identifier.

The short ID consists of eight characters and is created from its non-hidden arguments.

Returns

short object identifier

Examples

>>> class Foo(Object):
...     def __init__(self, bar: str):
...         self.bar = bar
>>> foo1 = Foo("I am unique!")
>>> foo1.id
'893df240-babe-d796-cdf1-c436171b7a96'
>>> foo1.short_id
'171b7a96'
>>> foo2 = Foo("I am different!")
>>> foo2.short_id
'6e2d2190'
>>> foo3 = Foo("I am unique!")
>>> foo1.short_id == foo3.short_id
True

to_dict()

Model.to_dict(*, include_version=True, flatten=False, root=None)

Converts object to a dictionary.

Includes items from audobject.Object.arguments. If an argument has a resolver, its value is encoded. Usually, the object can be re-instantiated using audobject.Object.from_dict(). However, if flatten=True, this is not possible.

Parameters

• include_version (bool) – add version to class name

• flatten (bool) – flatten the dictionary

• root (Optional[str]) – if file is written to disk, set to target directory

Return type

Mapping[str, Union[bool, datetime, dict, float, int, list, None, str]]

Returns

dictionary that represent the object

Examples

>>> import audobject.testing
>>> o = audobject.testing.TestObject("test", point=(1, 1))
>>> o.to_dict(include_version=False)
{'$audobject.core.testing.TestObject': {'name': 'test', 'point': [1, 1]}}
>>> o.to_dict(flatten=True)
{'name': 'test', 'point.0': 1, 'point.1': 1}

to_yaml()

Model.to_yaml(path, *, include_version=True)

Save model to YAML file.

If ONNX model was loaded from a byte stream, it will be saved in addition to the YAML file under the same path with file extension .onnx.

Parameters

• path (str) – file path, must end on .yaml

• include_version (bool) – add version to class name

Raises

ValueError – if file path does not end on .yaml

to_yaml_s()

Model.to_yaml_s(*, include_version=True)

Convert object to YAML string.

Parameters

include_version (bool) – add version to class name

Return type

str

Returns

YAML string

Examples

>>> import audobject.testing
>>> o = audobject.testing.TestObject("test", point=(1, 1))
>>> print(o.to_yaml_s(include_version=False))
$audobject.core.testing.TestObject:
  name: test
  point:
  - 1
  - 1