Mask

class auglib.transform.Mask(transform, *, start_pos=0, duration=None, step=None, invert=False, unit='seconds', preserve_level=False, bypass_prob=None)

Masked transformation.

Usually a transformation is applied on the whole signal. With auglib.transform.Mask it is possible to mask the transformation within specific region(s). By default, regions outside the mask are augmented. If invert is set to True, regions that fall inside the mask are augmented.

Parameters

• transform (auglib.core.transform.Base) – transform object

• start_pos (typing.Union[int, float, auglib.core.observe.Base, auglib.core.time.Time]) – start masking at this point (see unit).

• duration (typing.Union[int, float, auglib.core.observe.Base, auglib.core.time.Time, None]) – apply masking for this duration (see unit). If set to None masking is applied until the end of the signal

• step (typing.Union[int, float, auglib.core.observe.Base, auglib.core.time.Time, typing.Tuple[typing.Union[int, float, auglib.core.observe.Base, auglib.core.time.Time], typing.Union[int, float, auglib.core.observe.Base, auglib.core.time.Time]], None]) – if not None, alternate between masked and non-masked regions by the given step duration. If two steps are given, the first value defines the length of masked regions, and the second value the steps between masked regions (see unit)

• invert (typing.Union[bool, auglib.core.observe.Base]) – if set to True augment the masked regions

• unit (str) – literal specifying the format of step, start_pos and duration (see auglib.utils.to_samples())

• 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

Reduce the gain of a speech signal by -20 dB, only in the region outside of 0.5 s to 1.0 s.

>>> import audb
>>> import audiofile
>>> import audplot
>>> import auglib
>>> transform = auglib.transform.Mask(
...     auglib.transform.GainStage(-20),
...     start_pos=0.5,
...     duration=0.5,
... )
>>> 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)

Invert the region in which the gain is reduced.

>>> transform = auglib.transform.Mask(
...     auglib.transform.GainStage(-20),
...     start_pos=0.5,
...     duration=0.5,
...     invert=True,
... )
>>> augmented_signal = transform(signal, sampling_rate)
>>> audplot.waveform(augmented_signal)

Repeat a mask of length 0.2 s after a pause of 0.3 s.

>>> transform = auglib.transform.Mask(
...     auglib.transform.GainStage(-20),
...     step=(0.2, 0.3),
... )
>>> augmented_signal = transform(signal, sampling_rate)
>>> audplot.waveform(augmented_signal)

__call__()

Mask.__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

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

Mask.borrowed_arguments

Returns borrowed arguments.

Returns

Dictionary with borrowed arguments.

from_dict()

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

Return type

audobject.core.object.Object

from_yaml()

static Mask.from_yaml(path_or_stream, **kwargs)

Return type

audobject.core.object.Object

from_yaml_s()

static Mask.from_yaml_s(yaml_string, **kwargs)

Return type

audobject.core.object.Object

hidden_arguments

Mask.hidden_arguments

Returns hidden arguments.

Returns

List with names of hidden arguments.

id

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

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

Mask.resolvers

Return resolvers.

Returns

Dictionary with resolvers.

short_id

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

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

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

Convert duration value to samples.

Return type

int

to_yaml()

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

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