mexca.audio.extraction ====================== .. py:module:: mexca.audio.extraction .. autoapi-nested-parse:: Extract voice features from an audio file. Construct a dictionary with keys as feature names and values as feature objects. The dictionary can be used to extract the specified features with the :class:`VoiceExtractor`. Feature objects require lower-level voice signal properties, which are defined in the :func:`requires` method of feach feature class. The :class:`VoiceExtractor` class computes the properties and supplies them to the feature objects. Classes ------- .. autoapisummary:: mexca.audio.extraction.BaseFeature mexca.audio.extraction.FeaturePitchF0 mexca.audio.extraction.FeatureJitter mexca.audio.extraction.FeatureShimmer mexca.audio.extraction.FeatureHnr mexca.audio.extraction.FeatureFormantFreq mexca.audio.extraction.FeatureFormantBandwidth mexca.audio.extraction.FeatureFormantAmplitude mexca.audio.extraction.FeatureAlphaRatio mexca.audio.extraction.FeatureHammarIndex mexca.audio.extraction.FeatureSpectralSlope mexca.audio.extraction.FeatureHarmonicDifference mexca.audio.extraction.FeatureMfcc mexca.audio.extraction.FeatureSpectralFlux mexca.audio.extraction.FeatureRmsEnergy mexca.audio.extraction.VoiceExtractor Functions --------- .. autoapisummary:: mexca.audio.extraction.cli Module Contents --------------- .. py:class:: BaseFeature Abstract base class for features. Can be used to create custom voice feature extraction classes. .. py:property:: requires :type: Optional[Dict[str, type]] :abstractmethod: Specify objects required for feature extraction. This abstract method must be overwritten to return a dictionary with keys as the names of objects required for computing features and values the types of these objects. The :class:`VoiceExtractor` object will look for objects with the specified types and add them as attributes to the feature class with the names of the dictionary keys. :returns: Dictionary where keys are the names and values the types of required objects. :rtype: dict .. py:method:: apply(time: numpy.ndarray) -> numpy.ndarray :abstractmethod: Extract features at time points by linear interpolation. :param time: Time points. :type time: numpy.ndarray :returns: Feature values interpolated at time points. :rtype: numpy.ndarray .. py:class:: FeaturePitchF0 Extract voice pitch as the fundamental frequency F0 in Hz. .. py:property:: requires :type: Optional[Dict[str, emvoice.pitch.PitchFrames]] Specify objects required for feature extraction. :returns: Dictionary with key `pitch_frames`. :rtype: dict .. py:method:: apply(time: numpy.ndarray) -> numpy.ndarray Extract features at time points by linear interpolation. :param time: Time points. :type time: numpy.ndarray :returns: Feature values interpolated at time points. :rtype: numpy.ndarray .. py:class:: FeatureJitter Extract local jitter relative to the fundamental frequency. .. py:property:: requires :type: Optional[Dict[str, emvoice.pitch.JitterFrames]] Specify objects required for feature extraction. :returns: Dictionary with key `jitter_frames`. :rtype: dict .. py:method:: apply(time: numpy.ndarray) -> numpy.ndarray Extract features at time points by linear interpolation. :param time: Time points. :type time: numpy.ndarray :returns: Feature values interpolated at time points. :rtype: numpy.ndarray .. py:class:: FeatureShimmer Extract local shimmer relative to the fundamental frequency. .. py:property:: requires :type: Optional[Dict[str, emvoice.pitch.ShimmerFrames]] Specify objects required for feature extraction. :returns: Dictionary with key `shimmer_frames`. :rtype: dict .. py:method:: apply(time: numpy.ndarray) -> numpy.ndarray Extract features at time points by linear interpolation. :param time: Time points. :type time: numpy.ndarray :returns: Feature values interpolated at time points. :rtype: numpy.ndarray .. py:class:: FeatureHnr Extract the harmonicity-to-noise ratio in dB. .. py:property:: requires :type: Optional[Dict[str, emvoice.energy.HnrFrames]] Specify objects required for feature extraction. :returns: Dictionary with key `hnr_frames`. :rtype: dict .. py:method:: apply(time: numpy.ndarray) -> numpy.ndarray Extract features at time points by linear interpolation. :param time: Time points. :type time: numpy.ndarray :returns: Feature values interpolated at time points. :rtype: numpy.ndarray .. py:class:: FeatureFormantFreq(n_formant: int) Extract formant central frequency in Hz. :param n_formant: Index of the formant (starting at 0). :type n_formant: int .. py:property:: requires :type: Optional[Dict[str, emvoice.formants.FormantFrames]] Specify objects required for feature extraction. :returns: Dictionary with key `formant_frames`. :rtype: dict .. py:method:: apply(time: numpy.ndarray) -> Optional[numpy.ndarray] Extract features at time points by linear interpolation. :param time: Time points. :type time: numpy.ndarray :returns: Feature values interpolated at time points. :rtype: numpy.ndarray .. py:class:: FeatureFormantBandwidth(n_formant: int) Extract formant frequency bandwidth in Hz. :param n_formant: Index of the formant (starting at 0). :type n_formant: int .. py:method:: apply(time: numpy.ndarray) -> Optional[numpy.ndarray] Extract features at time points by linear interpolation. :param time: Time points. :type time: numpy.ndarray :returns: Feature values interpolated at time points. :rtype: numpy.ndarray .. py:class:: FeatureFormantAmplitude(n_formant: int) Extract formant amplitude relative to F0 harmonic amplitude. :param n_formant: Index of the formant (starting at 0). :type n_formant: int .. py:property:: requires :type: Optional[Dict[str, emvoice.formants.FormantAmplitudeFrames]] Specify objects required for feature extraction. :returns: Dictionary with key `formant_amp_frames`. :rtype: dict .. py:method:: apply(time: numpy.ndarray) -> Optional[numpy.ndarray] Extract features at time points by linear interpolation. :param time: Time points. :type time: numpy.ndarray :returns: Feature values interpolated at time points. :rtype: numpy.ndarray .. py:class:: FeatureAlphaRatio Extract the alpha ratio in dB. .. py:property:: requires :type: Optional[Dict[str, emvoice.spectral.AlphaRatioFrames]] Specify objects required for feature extraction. :returns: Dictionary with key `alpha_ratio_frames`. :rtype: dict .. py:method:: apply(time: numpy.ndarray) -> numpy.ndarray Extract features at time points by linear interpolation. :param time: Time points. :type time: numpy.ndarray :returns: Feature values interpolated at time points. :rtype: numpy.ndarray .. py:class:: FeatureHammarIndex Extract the Hammarberg index in dB. .. py:property:: requires :type: Optional[Dict[str, emvoice.spectral.HammarIndexFrames]] Specify objects required for feature extraction. :returns: Dictionary with key `hammar_index_frames`. :rtype: dict .. py:method:: apply(time: numpy.ndarray) -> numpy.ndarray Extract features at time points by linear interpolation. :param time: Time points. :type time: numpy.ndarray :returns: Feature values interpolated at time points. :rtype: numpy.ndarray .. py:class:: FeatureSpectralSlope(lower: float, upper: float) Extract spectral slopes for frequency bands. :param lower: Lower and upper boundary of the frequency band for which to extract the spectral slope. A band with these boundaries must exist in the required `spectral_slope_frames` object. :type lower: float :param upper: Lower and upper boundary of the frequency band for which to extract the spectral slope. A band with these boundaries must exist in the required `spectral_slope_frames` object. :type upper: float .. py:property:: requires :type: Optional[Dict[str, type]] Specify objects required for feature extraction. :returns: Dictionary with key `spectral_slope_frames`. :rtype: dict .. py:method:: apply(time: numpy.ndarray) -> numpy.ndarray Extract features at time points by linear interpolation. :param time: Time points. :type time: numpy.ndarray :returns: Feature values interpolated at time points. :rtype: numpy.ndarray .. py:class:: FeatureHarmonicDifference(x_idx: int = 0, x_type: str = 'h', y_idx: int = 1, y_type: str = 'h') Extract the difference between pitch harmonic and/or formant amplitudes in dB. :param x_idx: Index of the first/second amplitude. :type x_idx: int, default=0 :param y_idx: Index of the first/second amplitude. :type y_idx: int, default=0 :param x_type: Type of the first/second amplitude. Must be either `'h'` for pitch harmonic or `'f'` for formant. :type x_type: str, default='h' :param y_type: Type of the first/second amplitude. Must be either `'h'` for pitch harmonic or `'f'` for formant. :type y_type: str, default='h' :raises ValueError: If `x_type` or `y_type` is not `'h'` or `'f'`. .. py:property:: requires :type: Optional[Dict[str, Union[emvoice.formants.FormantAmplitudeFrames, emvoice.pitch.PitchHarmonicsFrames]]] Specify objects required for feature extraction. :returns: Dictionary with keys `formant_amp_frames` and `pitch_harmonics_frames`. :rtype: dict .. py:method:: apply(time: numpy.ndarray) -> numpy.ndarray Extract features at time points by linear interpolation. :param time: Time points. :type time: numpy.ndarray :returns: Feature values interpolated at time points. :rtype: numpy.ndarray .. py:class:: FeatureMfcc(n_mfcc: int = 0) Extract Mel frequency cepstral coefficients (MFCCs). :param n_mfcc: Index of the MFCC to be extracted. :type n_mfcc: int, default=0 .. py:property:: requires :type: Optional[Dict[str, emvoice.spectral.MfccFrames]] Specify objects required for feature extraction. :returns: Dictionary with key `mfcc_frames`. :rtype: dict .. py:method:: apply(time: numpy.ndarray) -> numpy.ndarray Extract features at time points by linear interpolation. :param time: Time points. :type time: numpy.ndarray :returns: Feature values interpolated at time points. :rtype: numpy.ndarray .. py:class:: FeatureSpectralFlux Extract spectral flux. .. py:property:: requires :type: Optional[Dict[str, emvoice.spectral.SpectralFluxFrames]] Specify objects required for feature extraction. :returns: Dictionary with key `spectral_flux_frames`. :rtype: dict .. py:method:: apply(time: numpy.ndarray) -> numpy.ndarray Extract features at time points by linear interpolation. :param time: Time points. :type time: numpy.ndarray :returns: Feature values interpolated at time points. :rtype: numpy.ndarray .. py:class:: FeatureRmsEnergy Extract the root mean squared energy in dB. .. py:property:: requires :type: Optional[Dict[str, type]] Specify objects required for feature extraction. :returns: Dictionary with key `rms_frames`. :rtype: dict .. py:method:: apply(time: numpy.ndarray) -> numpy.ndarray Extract features at time points by linear interpolation. :param time: Time points. :type time: numpy.ndarray :returns: Feature values interpolated at time points. :rtype: numpy.ndarray .. py:class:: VoiceExtractor(features: Optional[Dict[str, BaseFeature]] = None, config: Optional[mexca.data.VoiceFeaturesConfig] = None) Extract voice features from an audio file. For default features, see the :ref:`Output ` section. :param features: Dictionary with keys as feature names and values as feature extraction objects. If `None`, default features are extracted. :type features: dict, optional, default=None :param config: Voice feature extraction configuration object. If `None`, uses :class:`VoiceFeaturesConfig`'s default configuration. :type config: VoiceFeaturesConfig, optional, default=None .. py:method:: apply(filepath: str, time_step: float, skip_frames: int = 1) -> mexca.data.VoiceFeatures Extract voice features from an audio file. :param filepath: Path to the audio file. :type filepath: str :param time_step: The interval between time points at which features are extracted. :type time_step: float :param skip_frames: Only process every nth frame, starting at 0. :type skip_frames: int :returns: A data class object containing the extracted voice features. :rtype: VoiceFeatures .. py:function:: cli() Command line interface for extracting voice features. See `extract-voice -h` for details.