pyworld.pyi

from typing import Optional, Tuple

import numpy as np

default_frame_period: float
default_f0_floor: float
default_f0_ceil: float

def dio(
    x: np.ndarray,
    fs: int,
    f0_floor: float,
    f0_ceil: float,
    channels_in_octave=...,
    frame_period: float = ...,
    speed: int = ...,
    allowed_range: float = ...,
) -> Tuple[np.ndarray, np.ndarray]:
    """DIO F0 extraction algorithm.

    Parameters
    ----------
    x : ndarray
        Input waveform signal.
    fs : int
        Sample rate of input signal in Hz.
    f0_floor : float
        Lower F0 limit in Hz.
        Default: 71.0
    f0_ceil : float
        Upper F0 limit in Hz.
        Default: 800.0
    channels_in_octave : float
        Resolution of multiband processing; normally shouldn't be changed.
        Default: 2.0
    frame_period : float
        Period between consecutive frames in milliseconds.
        Default: 5.0
    speed : int
        The F0 estimator may downsample the input signal using this integer factor
        (range [1;12]). The algorithm will then operate on a signal at fs/speed Hz
        to reduce computational complexity, but high values may negatively impact
        accuracy.
        Default: 1 (no downsampling)
    allowed_range : float
        Threshold for voiced/unvoiced decision. Can be any value >= 0, but 0.02 to 0.2
        is a reasonable range. Lower values will cause more frames to be considered
        unvoiced (in the extreme case of `threshold=0`, almost all frames will be unvoiced).
        Default: 0.1

    Returns
    -------
    f0 : ndarray
        Estimated F0 contour.
    temporal_positions : ndarray
        Temporal position of each frame.
    """
    pass

def harvest(
    x: np.ndarray,
    fs: int,
    f0_floor: float = ...,
    f0_ceil: float = ...,
    frame_period: float = ...,
) -> Tuple[np.ndarray, np.ndarray]:
    """Harvest F0 extraction algorithm.

    Parameters
    ----------
    x : ndarray
        Input waveform signal.
    fs : int
        Sample rate of input signal in Hz.
    f0_floor : float
        Lower F0 limit in Hz.
        Default: 71.0
    f0_ceil : float
        Upper F0 limit in Hz.
        Default: 800.0
    frame_period : float
        Period between consecutive frames in milliseconds.
        Default: 5.0

    Returns
    -------
    f0 : ndarray
        Estimated F0 contour.
    temporal_positions : ndarray
        Temporal position of each frame.
    """
    pass

def stonemask(
    x: np.ndarray, f0: np.ndarray, temporal_positions: np.ndarray, fs: int
) -> np.ndarray:
    """StoneMask F0 refinement algorithm.

    Parameters
    ----------
    x : ndarray
        Input waveform signal.
    f0 : ndarray
        Input F0 contour.
    temporal_positions : ndarray
        Temporal positions of each frame.
    fs : int
        Sample rate of input signal in Hz.

    Returns
    -------
    refined_f0 : ndarray
        Refined F0 contour.
    """
    pass

def get_cheaptrick_fft_size(fs: int, f0_floor: float = ...) -> int:
    """Calculate suitable FFT size for CheapTrick given F0 floor.

    Parameters
    ----------
    fs : int
        Sample rate of input signal in Hz.
    f0_floor : float
        Lower F0 limit in Hz. The required FFT size is a direct
        consequence of the F0 floor used.
        Default: 71.0

    Returns
    -------
    fft_size : int
        Resulting FFT size.
    """
    pass

def get_cheaptrick_f0_floor(fs: int, fft_size: int) -> float:
    """Calculates actual lower F0 limit for CheapTrick
    based on the sampling frequency and FFT size used. Whenever F0 is below
    this threshold the spectrum will be analyzed as if the frame is unvoiced
    (using kDefaultF0 defined in constantnumbers.h).

    Parameters
    ----------
    fs : int
        Sample rate of input signal in Hz.
    fft_size : int
        FFT size used for CheapTrick.

    Returns
    -------
    f0_floor : float
        Resulting lower F0 limit in Hz.
    """
    pass

def cheaptrick(
    x: np.ndarray,
    f0: np.ndarray,
    temporal_positions: np.ndarray,
    fs: int,
    q1: float = ...,
    f0_floor: float = ...,
    fft_size: Optional[int] = ...,
) -> np.ndarray:
    """CheapTrick harmonic spectral envelope estimation algorithm.

    Parameters
    ----------
    x : ndarray
        Input waveform signal.
    f0 : ndarray
        Input F0 contour.
    temporal_positions : ndarray
        Temporal positions of each frame.
    fs : int
        Sample rate of input signal in Hz.
    q1 : float
        Spectral recovery parameter.
        Default: -0.15 (this value was tuned and normally does not need adjustment)
    f0_floor : float, None
        Lower F0 limit in Hz. Not used in case `fft_size` is specified.
        Default: 71.0
    fft_size : int, None
        FFT size to be used. When `None` (default) is used, the FFT size is computed
        automatically as a function of the given input sample rate and F0 floor.
        When `fft_size` is specified, the given `f0_floor` parameter is ignored.
        Default: None

    Returns
    -------
    spectrogram : ndarray
        Spectral envelope (squared magnitude).
    """
    pass

def d4c(
    x: np.ndarray,
    f0: np.ndarray,
    temporal_positions: np.ndarray,
    fs: int,
    threshold: float = ...,
    fft_size: Optional[int] = ...,
) -> np.ndarray:
    """D4C aperiodicity estimation algorithm.

    Parameters
    ----------
    x : ndarray
        Input waveform signal.
    f0 : ndarray
        Input F0 contour.
    temporal_positions : ndarray
        Temporal positions of each frame.
    fs : int
        Sample rate of input signal in Hz.
    q1 : float
        Spectral recovery parameter.
        Default: -0.15 (this value was tuned and normally does not need adjustment)
    threshold : float
        Threshold for aperiodicity-based voiced/unvoiced decision, in range 0 to 1.
        If a value of 0 is used, voiced frames will be kept voiced. If a value > 0 is
        used some voiced frames can be considered unvoiced by setting their aperiodicity
        to 1 (thus synthesizing them with white noise). Using `threshold=0` will result
        in the behavior of older versions of D4C. The current default of 0.85 is meant
        to be used in combination with the Harvest F0 estimator, which was designed to have
        a high voiced/unvoiced threshold (i.e. most frames will be considered voiced).
        Default: 0.85
    fft_size : int, None
        FFT size to be used. When `None` (default) is used, the FFT size is computed
        automatically as a function of the given input sample rate and the default F0 floor.
        When `fft_size` is specified, it should match the FFT size used to compute
        the spectral envelope (i.e. `fft_size=2*(sp.shape[1] - 1)`) in order to get the
        desired results when resynthesizing.
        Default: None

    Returns
    -------
    aperiodicity : ndarray
        Aperiodicity (envelope, linear magnitude relative to spectral envelope).
    """
    pass

def synthesize(
    f0: np.ndarray,
    spectrogram: np.ndarray,
    aperiodicity: np.ndarray,
    fs: int,
    frame_period: float = ...,
) -> np.ndarray:
    """WORLD synthesis from parametric representation.

    Parameters
    ----------
    f0 : ndarray
        Input F0 contour.
    spectrogram : ndarray
        Spectral envelope.
    aperiodicity : ndarray
        Aperodicity envelope.
    fs : int
        Sample rate of input signal in Hz.
    frame_period : float
        Period between consecutive frames in milliseconds.
        Default: 5.0

    Returns
    -------
    y : ndarray
        Output waveform signal.
    """
    pass

def get_num_aperiodicities(fs: int) -> int:
    """Calculate the required dimensionality to code D4C aperiodicity.

    Parameters
    ----------
    fs : int
        Sample rate of input signal in Hz.

    Returns
    -------
    n_aper : int
        Required number of coefficients.
    """
    pass

def code_aperiodicity(aperiodicity: np.ndarray, fs: int) -> np.ndarray:
    """Reduce dimensionality of D4C aperiodicity.

    Parameters
    ----------
    aperiodicity : ndarray
        Aperodicity envelope.
    fs : int
        Sample rate of input signal in Hz.

    Returns
    -------
    coded_aperiodicity : ndarray
        Coded aperiodicity envelope.
    """
    pass

def decode_aperiodicity(
    coded_aperiodicity: np.ndarray, fs: int, fft_size: int
) -> np.ndarray:
    """Restore full dimensionality of coded D4C aperiodicity.

    Parameters
    ----------
    coded_aperiodicity : ndarray
        Coded aperodicity envelope.
    fs : int
        Sample rate of input signal in Hz.
    fft_size : int
        FFT size corresponding to the full dimensional aperiodicity.

    Returns
    -------
    aperiodicity : ndarray
        Aperiodicity envelope.
    """
    pass

def code_spectral_envelope(
    spectrogram: np.ndarray, fs: int, number_of_dimensions: int
) -> np.ndarray:
    """Reduce dimensionality of spectral envelope.

    Parameters
    ----------
    spectrogram : ndarray
        Spectral envelope.
    fs : int
        Sample rate of input signal in Hz.
    number_of_dimensions : int
        Number of dimentions of coded spectral envelope

    Returns
    -------
    coded_spectral_envelope : ndarray
        Coded spectral envelope.
    """
    pass

def decode_spectral_envelope(
    coded_spectral_envelope: np.ndarray, fs: int, fft_size: int
) -> np.ndarray:
    """Restore full dimensionality of coded spectral envelope.

    Parameters
    ----------
    coded_spectral_envelope : ndarray
        Coded spectral envelope.
    fs : int
        Sample rate of input signal in Hz.
    fft_size : int
        FFT size corresponding to the full dimensional spectral envelope.

    Returns
    -------
    spectrogram : ndarray
        Spectral envelope.
    """
    pass

def wav2world(
    x: np.ndarray, fs: int, fft_size: Optional[int] = ..., frame_period: float = ...
) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
    """Convenience function to do all WORLD analysis steps in a single call.

    In this case only `frame_period` can be configured and other parameters
    are fixed to their defaults. Likewise, F0 estimation is fixed to
    DIO plus StoneMask refinement.

    Parameters
    ----------
    x : ndarray
        Input waveform signal.
    fs : int
        Sample rate of input signal in Hz.
    fft_size : int
        Length of Fast Fourier Transform (in number of samples)
        The resulting dimension of `ap` adn `sp` will be `fft_size` // 2 + 1
    frame_period : float
        Period between consecutive frames in milliseconds.
        Default: 5.0

    Returns
    -------
    f0 : ndarray
        F0 contour.
    sp : ndarray
        Spectral envelope.
    ap : ndarray
        Aperiodicity.
    """
    pass