SoftMask

The SoftMask class is for creating a time-frequency mask with values in the range [0.0, 1.0]. Like all separation.masks.mask_base.MaskBase objects, SoftMask is initialized with a 2D or 3D numpy array containing the mask data. The data type (numpy.dtype) of the initial mask must be float. The mask is stored as a 3-dimensional boolean-valued numpy array.

SoftMask (like separation.masks.soft_mask.BinaryMask) is one of the return types for the run() methods of separation.mask_separation_base.MaskSeparationBase-derived objects (this is most of the separation methods in nussl.

See also

  • separation.masks.mask_base.MaskBase: The base class for BinaryMask and SoftMask
  • separation.masks.soft_mask.BinaryMask: Similar to BinaryMask, but instead of taking floats, it accepts boolean values.
  • separation.mask_separation_base.MaskSeparationBase: Base class for all mask-based separation methods in nussl.

Examples

Initializing a mask from a numpy array…

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import nussl
import numpy as np

# load a file
signal = nussl.AudioSignal('path/to/file.wav')
stft = signal.stft()

# Make a random soft mask with the same shape as the stft
rand_bool_mask = np.random.random(size=stft.shape)
bin_mask_bool = nussl.SoftMask(rand_bool_mask)

separation.mask_separation_base.MaskSeparationBase-derived methods return separation.masks.mask_base.MaskBase masks, like so…

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import nussl

# load a file
signal = nussl.AudioSignal('path/to/file.wav')

repet = nussl.Repet(signal, mask_type=nussl.SoftMask)  # You have to specify that you want Binary Masks back
assert isinstance(repet, nussl.MaskSeparationBase)  # Repet is a MaskSeparationBase-derived class

[background_mask, foreground_mask] = repet.run()  # MaskSeparationBase-derived classes return MaskBase objects
assert isinstance(foreground_mask, nussl.SoftMask)  # this is True
assert isinstance(background_mask, nussl.SoftMask)  # this is True
class nussl.separation.masks.soft_mask.SoftMask(input_mask=None, mask_shape=None)

Bases: nussl.separation.masks.mask_base.MaskBase

A simple class for making a soft mask. The soft mask is represented as a numpy array of floats between 0.0 and 1.0, inclusive.

Parameters:input_mask (np.ndarray) – 2- or 3-D np.array that represents the mask.
mask_to_binary(threshold=0.5)

Create a new separation.masks.soft_mask.BinaryMask object from this object’s data.

Parameters:threshold (float, Optional) – Threshold (between [0.0, 1.0]) to set the True/False cutoff for the binary mask.
Returns:A new separation.masks.soft_mask.BinaryMask object
invert_mask()

Returns a new mask with inverted values set like 1 - mask for mask.

Returns:A new SoftMask object with values set at 1 - mask.
dtype

(str) Returns the data type of the values of the mask.

classmethod from_json(json_string)

Creates a new MaskBase object from the parameters stored in this JSON string.

Parameters:json_string (str) – A JSON string containing all the data to create a new MaskBase object.
Returns:(SeparationBase) A new MaskBase object from the JSON string.

See also

to_json() to make a JSON string to freeze this object.

get_channel(n)

Gets mask channel n and returns it as a 2D np.ndarray

Parameters:

n (int) – Channel index to return (0-based).

Returns:

np.array with the mask channel

Raises:
  • AttributeError if mask is None
  • ValueError if n is less than 0 or greater than the number of channels that this mask object has.
height

(int) Number of frequency bins this mask has.

inverse_mask()

Alias for invert_mask()

See also

invert_mask()

Returns:

length

(int) Number of time hops that this mask represents.

mask

PROPERTY

The actual mask. This is represented as a three dimensional numpy ndarray object. The input gets validated by _validate_mask(). In the case of separation.masks.binary_mask.BinaryMask the validation checks that the values are all 1 or 0 (or bools), in the case of separation.masks.soft_mask.SoftMask the validation checks that all values are within the domain [0.0, 1.0].

This base class will throw a NotImplementedError if instantiated directly.

Raises:
  • ValueError if mask.ndim is less than 2 or greater than 3, or if values fail validation.
  • NotImplementedError if instantiated directly.
num_channels

(int) Number of channels this mask has.

classmethod ones(shape)

Makes a mask with all ones with the specified shape. Exactly the same as np.ones(). :param shape: Shape of the resultant mask. :type shape: tuple

Returns:

shape

(tuple) Returns the shape of the whole mask. Identical to np.ndarray.shape().

to_json()

Returns:

classmethod zeros(shape)

Makes a mask with all zeros with the specified shape. Exactly the same as np.zeros(). :param shape: Shape of the resultant mask. :type shape: tuple

Returns: