mexca.audio.identification
==========================

.. py:module:: mexca.audio.identification

.. autoapi-nested-parse::

   Speech segment and speaker identification.



Exceptions
----------

.. autoapisummary::

   mexca.audio.identification.AuthenticationError


Classes
-------

.. autoapisummary::

   mexca.audio.identification.SpeakerIdentifier


Functions
---------

.. autoapisummary::

   mexca.audio.identification.cli


Module Contents
---------------

.. py:exception:: AuthenticationError(msg: str)



   Failed authentication to HuggingFace Hub.

   :param msg: Error message.
   :type msg: str


.. py:class:: SpeakerIdentifier(num_speakers: Optional[int] = None, device: torch.device = torch.device(type='cpu'), use_auth_token: Union[bool, str] = True)

   Identify speech segments and cluster speakers using speaker diarization.

   Wrapper class for ``pyannote.audio.SpeakerDiarization``.
   Uses pretrained speaker diarization model `pyannote/speaker-diarization-3.1` from HuggingFace.

   :param num_speakers: Number of speakers to which speech segments will be assigned during the clustering
                        (oracle speakers). If `None`, the number of speakers is estimated from the audio signal.
   :type num_speakers: int, optional
   :param device: The device on which the speaker diarization model is run.
   :type device: torch.device, default=torch.device("cpu")
   :param use_auth_token: Whether to use the HuggingFace authentication token stored on the machine (if bool) or
                          a HuggingFace authentication token with access to the models ``pyannote/speaker-diarization``
                          and ``pyannote/segmentation`` (if str).
   :type use_auth_token: bool or str, default=True

   .. rubric:: Notes

   This class requires pretrained models for speaker diarization and segmentation from HuggingFace.
   To download the models accept the user conditions on `<hf.co/pyannote/speaker-diarization>`_ and
   `<hf.co/pyannote/segmentation>`_. Then generate an authentication token on `<hf.co/settings/tokens>`_.


   .. py:property:: pipeline
      :type: pyannote.audio.Pipeline


      The pretrained speaker diarization pipeline.
      See `pyannote.audio.SpeakerDiarization <https://github.com/pyannote/pyannote-audio/blob/develop/pyannote/audio/pipelines/speaker_diarization.py#L56>`_ for details.


   .. py:method:: apply(filepath: str, show_progress: bool = True) -> mexca.data.SpeakerAnnotation

      Identify speech segments and speakers.

      :param filepath: Path to the audio file.
      :type filepath: str
      :param show_progress: Enables the display of a progress bar.
      :type show_progress: bool, default=True

      :returns: A data class object that contains detected speech segments and speakers.
      :rtype: SpeakerAnnotation



.. py:function:: cli()

   Command line interface for identifying speech segments and speakers.
   See `identify-speakers -h` for details.