mindspore 1.10.0__cp37-none-any.whl → 2.0.0rc1__cp37-none-any.whl

mindspore/dataset/audio/utils.py

@@ -24,16 +24,19 @@ from mindspore.dataset.core.validator_helpers import check_non_negative_float32,
 
 class BorderType(str, Enum):
     """
-    Padding Mode, BorderType Type.
+    Padding mode.
 
     Possible enumeration values are: BorderType.CONSTANT, BorderType.EDGE, BorderType.REFLECT, BorderType.SYMMETRIC.
 
-    - BorderType.CONSTANT: means it fills the border with constant values.
-    - BorderType.EDGE: means it pads with the last value on the edge.
-    - BorderType.REFLECT: means it reflects the values on the edge omitting the last value of edge.
-    - BorderType.SYMMETRIC: means it reflects the values on the edge repeating the last value of edge.
+    - BorderType.CONSTANT: Pad with a constant value.
+    - BorderType.EDGE: Pad with the last value on the edge.
+    - BorderType.REFLECT: Reflect the value on the edge while omitting the last one.
+      For example, pad [1, 2, 3, 4] with 2 elements on both sides will result in [3, 2, 1, 2, 3, 4, 3, 2].
+    - BorderType.SYMMETRIC: Reflect the value on the edge while repeating the last one.
+      For example, pad [1, 2, 3, 4] with 2 elements on both sides will result in [2, 1, 1, 2, 3, 4, 4, 3].
 
-    Note: This class derived from class str to support json serializable.
+    Note:
+        This class derived from class str to support json serializable.
     """
     CONSTANT: str = "constant"
     EDGE: str = "edge"
@@ -43,14 +46,14 @@ class BorderType(str, Enum):
 
 class DensityFunction(str, Enum):
     """
-    Density Functions.
+    Density function type.
 
     Possible enumeration values are: DensityFunction.TPDF, DensityFunction.RPDF,
     DensityFunction.GPDF.
 
-    - DensityFunction.TPDF: means triangular probability density function.
-    - DensityFunction.RPDF: means rectangular probability density function.
-    - DensityFunction.GPDF: means gaussian probability density function.
+    - DensityFunction.TPDF: Triangular Probability Density Function.
+    - DensityFunction.RPDF: Rectangular Probability Density Function.
+    - DensityFunction.GPDF: Gaussian Probability Density Function.
     """
     TPDF: str = "TPDF"
     RPDF: str = "RPDF"
@@ -107,12 +110,13 @@ class Interpolation(str, Enum):
 
 class MelType(str, Enum):
     """
-    Mel Types.
+    Mel scale implementation type.
 
     Possible enumeration values are: MelType.HTK, MelType.SLANEY.
 
-    - MelType.NONE: scale the input data with htk.
-    - MelType.ORTHO: scale the input data with slaney.
+    - MelType.HTK: The Hidden Markov Toolkit (HTK) implementation, refer to `HTK <https://htk.eng.cam.ac.uk/>`_ .
+    - MelType.SLANEY: The MATLAB Auditory Toolbox of Slaney implementation,
+      refer to `Auditory Toolbox <https://engineering.purdue.edu/~malcolm/interval/1998-010/>`_ .
     """
     HTK: str = "htk"
     SLANEY: str = "slaney"
@@ -133,12 +137,12 @@ class Modulation(str, Enum):
 
 class NormMode(str, Enum):
     """
-    Norm Types.
+    Normalization mode.
 
     Possible enumeration values are: NormMode.ORTHO, NormMode.NONE.
 
-    - NormMode.ORTHO: means the mode of input audio is ortho.
-    - NormMode.NONE: means the mode of input audio is none.
+    - NormMode.ORTHO: Use an ortho-normal DCT basis.
+    - NormMode.NONE: No normalization.
     """
     ORTHO: str = "ortho"
     NONE: str = "none"
@@ -146,12 +150,12 @@ class NormMode(str, Enum):
 
 class NormType(str, Enum):
     """
-    Norm Types.
+    Normalization type.
 
     Possible enumeration values are: NormType.SLANEY, NormType.NONE.
 
-    - NormType.SLANEY: norm the input data with slaney.
-    - NormType.NONE: norm the input data with none.
+    - NormType.SLANEY: Use an area normalization.
+    - NormType.NONE: No narmalization.
     """
     SLANEY: str = "slaney"
     NONE: str = "none"
@@ -159,12 +163,12 @@ class NormType(str, Enum):
 
 class ResampleMethod(str, Enum):
     """
-    Resample method
+    Resample method.
 
     Possible enumeration values are: ResampleMethod.SINC_INTERPOLATION, ResampleMethod.KAISER_WINDOW.
 
-    - ResampleMethod.SINC_INTERPOLATION: means it resample the tensor with sinc interpolation.
-    - ResampleMethod.KAISER_WINDOW: means it resample the tensor with kaiser window.
+    - ResampleMethod.SINC_INTERPOLATION: The Whittaker-Shannon interpolation or sinc interpolation formula.
+    - ResampleMethod.KAISER_WINDOW: The Kaiser window interpolation.
     """
     SINC_INTERPOLATION: str = "sinc_interpolation"
     KAISER_WINDOW: str = "kaiser_window"
@@ -185,16 +189,16 @@ class ScaleType(str, Enum):
 
 class WindowType(str, Enum):
     """
-    Window Function types,
+    Window function type.
 
     Possible enumeration values are: WindowType.BARTLETT, WindowType.BLACKMAN, WindowType.HAMMING, WindowType.HANN,
     WindowType.KAISER.
 
-    - WindowType.BARTLETT: means the type of window function is Bartlett.
-    - WindowType.BLACKMAN: means the type of window function is Blackman.
-    - WindowType.HAMMING: means the type of window function is Hamming.
-    - WindowType.HANN: means the type of window function is Hann.
-    - WindowType.KAISER: means the type of window function is Kaiser, currently not supported on macOS.
+    - WindowType.BARTLETT: Bartlett window function.
+    - WindowType.BLACKMAN: Blackman window function.
+    - WindowType.HAMMING: Hamming window function.
+    - WindowType.HANN: Hann window function.
+    - WindowType.KAISER: Kaiser window function. Currently, it is not supported on macOS.
     """
     BARTLETT: str = "bartlett"
     BLACKMAN: str = "blackman"
@@ -214,11 +218,21 @@ def create_dct(n_mfcc, n_mels, norm=NormMode.NONE):
     Args:
         n_mfcc (int): Number of mfc coefficients to retain, the value must be greater than 0.
         n_mels (int): Number of mel filterbanks, the value must be greater than 0.
-        norm (NormMode, optional): Normalization mode, can be NormMode.NONE or NormMode.ORTHO (default=NormMode.NONE).
+        norm (NormMode, optional): Normalization mode, can be NormMode.NONE or NormMode.ORTHO. Default: NormMode.NONE.
 
     Returns:
         numpy.ndarray, the transformation matrix, to be right-multiplied to row-wise data of size (n_mels, n_mfcc).
 
+    Raises:
+        TypeError: If `n_mfcc` is not of type int.
+        ValueError: If `n_mfcc` is not positive.
+        TypeError: If `n_mels` is not of type int.
+        ValueError: If `n_mels` is not positive.
+        TypeError: If `n_mels` is not of type :class:`mindspore.dataset.audio.NormMode` .
+
+    Supported Platforms:
+        ``CPU``
+
     Examples:
         >>> from mindspore.dataset.audio import create_dct, NormMode
         >>>
@@ -253,15 +267,31 @@ def linear_fbanks(n_freqs, f_min, f_max, n_filter, sample_rate):
     Creates a linear triangular filterbank.
 
     Args:
-        n_freqs (int): Number of frequency.
-        f_min (float): Minimum of frequency in Hz.
-        f_max (float): Maximum of frequency in Hz.
+        n_freqs (int): Number of frequencies to highlight/apply.
+        f_min (float): Minimum frequency in Hz.
+        f_max (float): Maximum frequency in Hz.
         n_filter (int): Number of (linear) triangular filter.
-        sample_rate (int): Sample rate.
+        sample_rate (int): Sample rate of the waveform.
 
     Returns:
         numpy.ndarray, the linear triangular filterbank.
 
+    Raises:
+        TypeError: If `n_freqs` is not of type int.
+        ValueError: If `n_freqs` is negative.
+        TypeError: If `f_min` is not of type float.
+        ValueError: If `f_min` is negative.
+        TypeError: If `f_max` is not of type float.
+        ValueError: If `f_max` is negative.
+        ValueError: If `f_min` is larger than `f_max`.
+        TypeError: If `n_filter` is not of type int.
+        ValueError: If `n_filter` is not positive.
+        TypeError: If `sample_rate` is not of type int.
+        ValueError: If `sample_rate` is not positive.
+
+    Supported Platforms:
+        ``CPU``
+
     Examples:
         >>> from mindspore.dataset.audio import linear_fbanks
         >>>
@@ -291,19 +321,37 @@ def linear_fbanks(n_freqs, f_min, f_max, n_filter, sample_rate):
 
 def melscale_fbanks(n_freqs, f_min, f_max, n_mels, sample_rate, norm=NormType.NONE, mel_type=MelType.HTK):
     """
-    Create a frequency transformation matrix with shape (n_freqs, n_mels).
+    Create a frequency transformation matrix.
 
     Args:
-        n_freqs (int): Number of frequency.
+        n_freqs (int): Number of frequencies to highlight/apply.
         f_min (float): Minimum of frequency in Hz.
         f_max (float): Maximum of frequency in Hz.
         n_mels (int): Number of mel filterbanks.
-        sample_rate (int): Sample rate.
-        norm (NormType, optional): Norm to use, can be NormType.NONE or NormType.SLANEY (Default: NormType.NONE).
-        mel_type (MelType, optional): Scale to use, can be MelType.HTK or MelType.SLANEY (Default: NormType.SLANEY).
+        sample_rate (int): Sample rate of the audio waveform.
+        norm (NormType, optional): Normalization method, can be NormType.NONE or NormType.SLANEY.
+            Default: NormType.NONE.
+        mel_type (MelType, optional): Scale to use, can be MelType.HTK or MelType.SLANEY. Default: MelType.HTK.
 
     Returns:
-        numpy.ndarray, the frequency transformation matrix.
+        numpy.ndarray, the frequency transformation matrix with shape ( `n_freqs` , `n_mels` ).
+
+    Raises:
+        TypeError: If `n_freqs` is not of type int.
+        ValueError: If `n_freqs` is a negative number.
+        TypeError: If `f_min` is not of type float.
+        ValueError: If `f_min` is greater than `f_max` .
+        TypeError: If `f_max` is not of type float.
+        ValueError: If `f_max` is a negative number.
+        TypeError: If `n_mels` is not of type int.
+        ValueError: If `n_mels` is not positive.
+        TypeError: If `sample_rate` is not of type int.
+        ValueError: If `sample_rate` is not positive.
+        TypeError: If `norm` is not of type :class:`mindspore.dataset.audio.NormType` .
+        TypeError: If `mel_type` is not of type :class:`mindspore.dataset.audio.MelType` .
+
+    Supported Platforms:
+        ``CPU``
 
     Examples:
         >>> from mindspore.dataset.audio import melscale_fbanks

mindspore/dataset/audio/validators.py

@@ -23,7 +23,7 @@ from mindspore.dataset.core.validator_helpers import check_float32, check_float3
     check_int32_not_zero, check_list_same_size, check_non_negative_float32, check_non_negative_int32, \
     check_pos_float32, check_pos_int32, check_value, INT32_MAX, parse_user_args, type_check
 from mindspore.dataset.audio.utils import BorderType, DensityFunction, FadeShape, GainType, \
-    Interpolation, MelType, Modulation, NormType, ResampleMethod, ScaleType, WindowType
+    Interpolation, MelType, Modulation, NormMode, NormType, ResampleMethod, ScaleType, WindowType
 
 
 def check_amplitude_to_db(method):
@@ -366,6 +366,35 @@ def check_inverse_mel_scale(method):
     return new_method
 
 
+def check_inverse_spectrogram(method):
+    """Wrapper method to check the parameters of InverseSpectrogram."""
+
+    @wraps(method)
+    def new_method(self, *args, **kwargs):
+        [length, n_fft, win_length, hop_length, pad, window, normalized, center, \
+         pad_mode, onesided], _ = parse_user_args(method, *args, **kwargs)
+        if length is not None:
+            check_non_negative_int32(length, "length")
+        check_pos_int32(n_fft, "n_fft")
+        type_check(window, (WindowType,), "window")
+        type_check(normalized, (bool,), "normalized")
+        type_check(center, (bool,), "center")
+        type_check(pad_mode, (BorderType,), "pad_mode")
+        type_check(onesided, (bool,), "onesided")
+        check_non_negative_int32(pad, "pad")
+        if hop_length is not None:
+            check_pos_int32(hop_length, "hop_length")
+        if win_length is not None:
+            check_pos_int32(win_length, "win_length")
+            if win_length > n_fft:
+                raise ValueError(
+                    "Input win_length should be no more than n_fft, but got win_length: {0} and n_fft: {1}.".format(
+                        win_length, n_fft))
+        return method(self, *args, **kwargs)
+
+    return new_method
+
+
 def check_lfilter(method):
     """Wrapper method to check the parameters of LFilter."""
 
@@ -925,6 +954,33 @@ def check_phase_vocoder(method):
     return new_method
 
 
+def check_pitch_shift(method):
+    """Wrapper method to check the parameters of PitchShift."""
+
+    @wraps(method)
+    def new_method(self, *args, **kwargs):
+        [sample_rate, n_steps, bins_per_octave, n_fft, win_length, hop_length, window], _ = parse_user_args(
+            method, *args, **kwargs)
+
+        check_non_negative_int32(sample_rate, "sample_rate")
+        check_int32(n_steps, "n_steps")
+        check_int32_not_zero(bins_per_octave, "bins_per_octave")
+        check_pos_int32(n_fft, "n_fft")
+        type_check(window, (WindowType,), "window")
+
+        if win_length is not None:
+            check_pos_int32(win_length, "win_length")
+            if win_length > n_fft:
+                raise ValueError(
+                    "Input win_length should be no more than n_fft, but got win_length: {0} and n_fft: {1}.".format(
+                        win_length, n_fft))
+        if hop_length is not None:
+            check_pos_int32(hop_length, "hop_length")
+        return method(self, *args, **kwargs)
+
+    return new_method
+
+
 def check_resample(method):
     """Wrapper method to check the parameters of Resample."""
 
@@ -948,3 +1004,169 @@ def check_resample(method):
         return method(self, *args, **kwargs)
 
     return new_method
+
+
+def check_lfcc(method):
+    """Wrapper method to check the parameters of LFCC."""
+
+    @wraps(method)
+    def new_method(self, *args, **kwargs):
+        [sample_rate, n_filter, n_lfcc, f_min, f_max, dct_type, norm, log_lf, speckwargs], _ = parse_user_args(
+            method, *args, **kwargs)
+        type_check(sample_rate, (int,), "sample_rate")
+        check_non_negative_int32(sample_rate, "sample_rate")
+        type_check(n_filter, (int,), "n_filter")
+        check_pos_int32(n_filter, "n_filter")
+        type_check(n_lfcc, (int,), "n_lfcc")
+        check_pos_int32(n_lfcc, "n_lfcc")
+        type_check(log_lf, (bool,), "log_lf")
+        type_check(norm, (NormMode,), "norm")
+        type_check(f_min, (int, float), "f_min")
+        check_non_negative_float32(f_min, "f_min")
+        if f_max is not None:
+            type_check(f_max, (int, float), "f_max")
+            check_non_negative_float32(f_max, "f_max")
+            if f_min > f_max:
+                raise ValueError(
+                    "f_max should be greater than or equal to f_min, but got f_min: {0} and f_max: {1}.".format(
+                        f_min, f_max))
+        else:
+            if f_min >= sample_rate // 2:
+                raise ValueError(
+                    "Input sample_rate // 2 should be greater than f_min when f_max is set to None, but got f_min: {0} "
+                    "and sample_rate: {1}.".format(f_min, sample_rate))
+        if dct_type != 2:
+            raise ValueError("Input dct_type must be 2, but got : {0}.".format(dct_type))
+        if speckwargs is not None:
+            type_check(speckwargs, (dict,), "speckwargs")
+            window = speckwargs["window"]
+            pad_mode = speckwargs["pad_mode"]
+            n_fft = speckwargs["n_fft"]
+            win_length = speckwargs["win_length"]
+            pad = speckwargs["pad"]
+            power = speckwargs["power"]
+            type_check(window, (WindowType,), "window")
+            type_check(pad_mode, (BorderType,), "pad_mode")
+            type_check(pad, (int,), "pad")
+            check_non_negative_int32(pad, "pad")
+            type_check(power, (float,), "power")
+            check_non_negative_float32(power, "power")
+            if n_fft < n_lfcc:
+                raise ValueError(
+                    "n_fft should be greater than or equal to n_lfcc, but got n_fft: {0} and n_lfcc: {1}.".format(
+                        n_fft, n_lfcc))
+            if win_length > n_fft:
+                raise ValueError(
+                    "win_length must be less than or equal to n_fft, but got win_length: {0} and n_fft: {1}.".format(
+                        win_length, n_fft))
+        return method(self, *args, **kwargs)
+
+    return new_method
+
+
+def check_mfcc(method):
+    """Wrapper method to check the parameters of MFCC."""
+
+    @wraps(method)
+    def new_method(self, *args, **kwargs):
+        [sample_rate, n_mfcc, dct_type, norm, log_mels, melkwargs], _ = parse_user_args(method, *args, **kwargs)
+        check_non_negative_int32(sample_rate, "sample_rate")
+        type_check(log_mels, (bool,), "log_mels")
+        type_check(norm, (NormMode,), "norm")
+        check_non_negative_int32(n_mfcc, "n_mfcc")
+        if dct_type != 2:
+            raise ValueError("Input dct_type must be 2, but got : {0}.".format(dct_type))
+
+        if melkwargs is not None:
+            type_check(melkwargs, (dict,), "melkwargs")
+            n_fft = melkwargs["n_fft"]
+            win_length = melkwargs["win_length"]
+            hop_length = melkwargs["hop_length"]
+            f_min = melkwargs["f_min"]
+            f_max = melkwargs["f_max"]
+            pad = melkwargs["pad"]
+            power = melkwargs["power"]
+            normalized = melkwargs["normalized"]
+            center = melkwargs["center"]
+            onesided = melkwargs["onesided"]
+            window = melkwargs["window"]
+            pad_mode = melkwargs["pad_mode"]
+            norm_mel = melkwargs["norm"]
+            mel_scale = melkwargs["mel_scale"]
+            n_mels = melkwargs["n_mels"]
+
+            check_pos_int32(n_fft, "n_fft")
+            check_mel_scale_n_mels(n_mels)
+            check_mel_scale_freq(f_min, f_max, sample_rate)
+            check_mel_scale_norm(norm_mel)
+            check_mel_scale_mel_type(mel_scale)
+            check_power(power)
+            type_check(window, (WindowType,), "window")
+            type_check(normalized, (bool,), "normalized")
+            type_check(center, (bool,), "center")
+            type_check(pad_mode, (BorderType,), "pad_mode")
+            type_check(onesided, (bool,), "onesided")
+            check_non_negative_int32(pad, "pad")
+            if hop_length is not None:
+                check_pos_int32(hop_length, "hop_length")
+            if f_max is not None:
+                check_non_negative_float32(f_max, "f_max")
+            if win_length is not None:
+                check_non_negative_int32(win_length, "win_length")
+            if n_mels < n_mfcc:
+                raise ValueError("Input n_mels should be greater than or equal to n_mfcc, but got n_mfcc: {0} and " \
+                                 "n_mels: {1}.".format(n_mfcc, n_mels))
+
+        return method(self, *args, **kwargs)
+
+    return new_method
+
+
+def check_mel_spectrogram_freq(f_min, f_max, sample_rate):
+    """Wrapper method to check the parameters of f_min and f_max."""
+    type_check(f_min, (float,), "f_min")
+
+    if f_max is not None:
+        check_non_negative_float32(f_max, "f_max")
+        if f_min > f_max:
+            raise ValueError("f_max should be greater than or equal to f_min, but got f_min: {0} and f_max: {1}."
+                             .format(f_min, f_max))
+    else:
+        if f_min >= sample_rate // 2:
+            raise ValueError(
+                "MelSpectrogram: sample_rate // 2 should be greater than f_min when f_max is set to None, "
+                "but got f_min: {0}.".format(f_min))
+
+
+def check_mel_spectrogram(method):
+    """Wrapper method to check the parameters of MelSpectrogram."""
+
+    @wraps(method)
+    def new_method(self, *args, **kwargs):
+        [sample_rate, n_fft, win_length, hop_length, f_min, f_max, pad, n_mels, window, power, normalized, center, \
+         pad_mode, onesided, norm, mel_scale], _ = parse_user_args(method, *args, **kwargs)
+        check_non_negative_int32(sample_rate, "sample_rate")
+        check_pos_int32(n_fft, "n_fft")
+        check_non_negative_int32(n_mels, "n_mels")
+        check_mel_spectrogram_freq(f_min, f_max, sample_rate)
+        check_mel_scale_norm(norm)
+        check_mel_scale_mel_type(mel_scale)
+        check_pos_float32(power, "power")
+        type_check(window, (WindowType,), "window")
+        type_check(normalized, (bool,), "normalized")
+        type_check(center, (bool,), "center")
+        type_check(pad_mode, (BorderType,), "pad_mode")
+        type_check(onesided, (bool,), "onesided")
+        check_non_negative_int32(pad, "pad")
+        if hop_length is not None:
+            check_pos_int32(hop_length, "hop_length")
+        if win_length is not None:
+            check_pos_int32(win_length, "win_length")
+            if win_length > n_fft:
+                raise ValueError(
+                    "Input win_length should be no more than n_fft, but got win_length: {0} and n_fft: {1}.".format(
+                        win_length, n_fft))
+
+        return method(self, *args, **kwargs)
+
+    return new_method

mindspore/dataset/callback/ds_callback.py

@@ -27,8 +27,8 @@ class DSCallback:
     """
     Abstract base class used to build dataset callback classes.
 
-    Users can obtain the dataset pipeline context through `ds_run_context`, including
-    `cur_epoch_num`, `cur_step_num_in_epoch` and `cur_step_num`.
+    Users can obtain the dataset pipeline context through `ds_run_context` , including
+    `cur_epoch_num` , `cur_step_num_in_epoch` and `cur_step_num` .
 
     Args:
         step_size (int, optional): The number of steps between adjacent `ds_step_begin`/`ds_step_end`
@@ -130,21 +130,23 @@ class DSCallback:
 class WaitedDSCallback(Callback, DSCallback):
     r"""
     Abstract base class used to build dataset callback classes that are synchronized with the training callback class
-    `mindspore.Callback \
-    <https://www.mindspore.cn/docs/en/r1.10/api_python/mindspore/mindspore.Callback.html#mindspore.Callback>`_.
+    `mindspore.train.Callback \
+    <https://www.mindspore.cn/docs/en/r2.0/api_python/train/
+    mindspore.train.Callback.html#mindspore.train.Callback>`_ .
 
     It can be used to execute a custom callback method before a step or an epoch, such as
-    updating the parameters of operators according to the loss of the previous training epoch in auto augmentation.
-
-    Users can obtain the network training context through `train_run_context`, such as
-    `network`, `train_network`, `epoch_num`, `batch_num`, `loss_fn`, `optimizer`, `parallel_mode`,
-    `device_number`, `list_callback`, `cur_epoch_num`, `cur_step_num`, `dataset_sink_mode`,
-    `net_outputs`, etc., see
-    `mindspore.Callback \
-    <https://www.mindspore.cn/docs/en/r1.10/api_python/mindspore/mindspore.Callback.html#mindspore.Callback>`_.
-
-    Users can obtain the dataset pipeline context through `ds_run_context`, including
-    `cur_epoch_num`, `cur_step_num_in_epoch` and `cur_step_num`.
+    updating the parameters of operations according to the loss of the previous training epoch in auto augmentation.
+
+    Users can obtain the network training context through `train_run_context` , such as
+    `network` , `train_network` , `epoch_num` , `batch_num` , `loss_fn` , `optimizer` , `parallel_mode` ,
+    `device_number` , `list_callback` , `cur_epoch_num` , `cur_step_num` , `dataset_sink_mode` ,
+    `net_outputs` , etc., see
+    `mindspore.train.Callback \
+    <https://www.mindspore.cn/docs/en/r2.0/api_python/train/
+    mindspore.train.Callback.html#mindspore.train.Callback>`_ .
+
+    Users can obtain the dataset pipeline context through `ds_run_context` , including
+    `cur_epoch_num` , `cur_step_num_in_epoch` and `cur_step_num` .
 
     Note:
         Note that the call is triggered only at the beginning of the second step or epoch.