Mix

class auglib.transform.Mix(aux, *, gain_base_db=0.0, gain_aux_db=0.0, snr_db=None, write_pos_base=0.0, read_pos_aux=0.0, read_dur_aux=None, clip_mix=False, loop_aux=False, extend_base=False, num_repeat=1, unit='seconds', transform=None, preserve_level=False, bypass_prob=None)

Mix two audio signals.

Mix a base signal and auxiliary signal which may differ in length, but must have the same sampling rate. Individual gains can be set for both signals (gain_base_db and gain_aux_db). If snr_db is specified, gain_aux_db is automatically calculated to match the requested signal-to-noise ratio. The signal-to-noise ratio refers only to the overlapping parts of the base and auxiliary signal.

write_pos_base specifies the starting point of adding the auxiliary signal to the the base signal. Selecting a sub-segment of the auxiliary signal is possible with selecting a starting point (read_pos_aux) and/or specifying its duration (read_dur_aux).

In order to allow the looping of the auxiliary signal or its selected sub-segment, the loop_aux argument can be used. In case the auxiliary signal ends beyond the original ending point, the extra portion will be discarded, unless extend_base is set, in which case the base signal is extended accordingly.

By default, the auxiliary signal is mixed into the base signal exactly once. However, the number of repetitions can be controlled with num_repeat. Usually, this only makes sense when reading from random positions or random files.

Parameters

• aux (typing.Union[str, auglib.core.observe.Base, numpy.ndarray, auglib.core.transform.Base]) – auxiliary signal, file, or signal generating transform. If a transform is given it will be applied to a signal with the same length as the base signal containing zeros

• gain_base_db (typing.Union[float, auglib.core.observe.Base]) – gain of base signal

• gain_aux_db (typing.Union[float, auglib.core.observe.Base]) – gain of auxiliary signal. Ignored if snr_db is not None

• snr_db (typing.Union[float, auglib.core.observe.Base, None]) – signal-to-noise (base-to-aux) ratio in decibels

• write_pos_base (typing.Union[int, float, auglib.core.observe.Base, auglib.core.time.Time]) – write position of base signal (see unit)

• read_pos_aux (typing.Union[int, float, auglib.core.observe.Base, auglib.core.time.Time]) – read position of auxiliary signal (see unit)

• read_dur_aux (typing.Union[int, float, auglib.core.observe.Base, auglib.core.time.Time, None]) – duration to read from auxiliary signal (see unit). Set to None or 0 to read the whole signal

• clip_mix (typing.Union[bool, auglib.core.observe.Base]) – clip amplitude values of mixed signal to [-1, 1]

• loop_aux (typing.Union[bool, auglib.core.observe.Base]) – loop auxiliary signal if shorter than base signal

• extend_base (typing.Union[bool, auglib.core.observe.Base]) – if needed, extend base signal to total required length (considering length of auxiliary signal)

• num_repeat (typing.Union[int, auglib.core.observe.Base]) – number of repetitions

• sampling_rate – sampling rate in Hz

• unit (str) – literal specifying the format of write_pos_base, read_pos_aux and read_dur_aux (see auglib.utils.to_samples())

• transform (typing.Optional[auglib.core.transform.Base]) – transformation applied to the auxiliary signal

• preserve_level (typing.Union[bool, auglib.core.observe.Base]) – if True the root mean square value of the augmented signal will be the same as before augmentation

• bypass_prob (typing.Union[float, auglib.core.observe.Base, None]) – probability to bypass the transformation

Examples

Select randomly one of 10 noise files and add it with a SNR of 10 dB to a speech signal. If the noise signal shorter than the speech signal, it will be looped.

>>> import audb
>>> import audiofile
>>> import audplot
>>> import auglib
>>> auglib.seed(0)
>>> db = audb.load("musan", media=".*noise-free-sound-000\d", version="1.0.0")
>>> transform = auglib.transform.Mix(
...     auglib.observe.List(db.files, draw=True),
...     loop_aux=True,
...     snr_db=10,
... )
>>> files = audb.load_media("emodb", "wav/03a01Fa.wav", version="1.4.1")
>>> signal, sampling_rate = audiofile.read(files[0])
>>> augmented_signal = transform(signal, sampling_rate)
>>> audplot.waveform(augmented_signal)

Add a cough to a speech signal, starting at a random position between 0% and 90% of the length of the speech signal.

>>> auglib.seed(0)
>>> files = audb.load_media(
...     "cough-speech-sneeze",
...     "coughing/kopzxumj430_40.94-41.8.wav",
...     version="2.0.1",
...     sampling_rate=16000,
... )
>>> transform = auglib.transform.Mix(
...     files[0],
...     write_pos_base=auglib.observe.FloatUni(0, 0.9),
...     unit="relative",
... )
>>> augmented_signal = transform(signal, sampling_rate)
>>> audplot.waveform(augmented_signal)

__call__()

Mix.__call__(signal, sampling_rate=None)

Apply transform to signal.

Parameters

• signal (numpy.ndarray) – signal to be transformed

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

Return type

numpy.ndarray

Returns

augmented signal

Raises

• ValueError – if the signal shape is not support by chosen transform parameters

• ValueError – if sampling_rate is None, but the transform requires a samling rate

• RuntimeError – if the given sampling rate is incompatible with the transform

arguments

Mix.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

Mix.borrowed_arguments

Returns borrowed arguments.

Returns

Dictionary with borrowed arguments.

from_dict()

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

Return type

audobject.core.object.Object

from_yaml()

static Mix.from_yaml(path_or_stream, **kwargs)

Return type

audobject.core.object.Object

from_yaml_s()

static Mix.from_yaml_s(yaml_string, **kwargs)

Return type

audobject.core.object.Object

hidden_arguments

Mix.hidden_arguments

Returns hidden arguments.

Returns

List with names of hidden arguments.

id

Mix.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

is_loaded_from_dict

Mix.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

resolvers

Mix.resolvers

Return resolvers.

Returns

Dictionary with resolvers.

short_id

Mix.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()

Mix.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 (typing.Optional[str]) – if file is written to disk, set to target directory

Return type

typing.Dict[str, typing.Union[bool, datetime.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_samples()

Mix.to_samples(value, sampling_rate=None, *, length=None, allow_negative=True)

Convert duration value to samples.

Return type

int

to_yaml()

Mix.to_yaml(path_or_stream, *, include_version=True)

Save object to YAML file.

Parameters

• path_or_stream (typing.Union[str, typing.IO]) – file path or stream

• include_version (bool) – add version to class name

to_yaml_s()

Mix.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