Eagle Speaker Recognition
Python API

API Reference for the Python Eagle SDK (PyPI).

pveagle.`available_devices()`

def available_devices(library_path: Optional[str] = None) -> Sequence[str]

Lists all available devices that Eagle can use for inference. Each entry in the list can be the device argument of create_profiler() factory method or create_recognizer constructor.

Parameters

library_path Optional[str] : Absolute path to Eagle's dynamic library. If not set it will be set to the default location.

Returns

Sequence[str]: List of all available devices that Eagle can use for inference.

Throws

EagleError

pveagle.`create_profiler()`

def create_profiler(
        access_key: str,
        model_path: Optional[str] = None,
        device: Optional[str] = None,
        min_enrollment_chunks: int = 1,
        voice_threshold: float = 0.3,
        library_path: Optional[str] = None) -> EagleProfiler:

Factory method for the profiler component of the Eagle speaker recognition engine.

Parameters

access_key str : AccessKey obtained from Picovoice Console.
model_path Optional[str] : Absolute path to the file containing model parameters.
device Optional[str] : String representation of the device (e.g., CPU or GPU) to use. If set to best, the most suitable device is selected automatically. If set to gpu, the engine uses the first available GPU device. To select a specific GPU device, set this argument to gpu:${GPU_INDEX}, where ${GPU_INDEX} is the index of the target GPU. If set tocpu, the engine will run on the CPU with the default number of threads. To specify the number of threads, set this argument to cpu:${NUM_THREADS}, where ${NUM_THREADS} is the desired number of threads.
min_enrollment_chunks int : Minimum number of chunks to be processed before enroll returns 100%. The value should be a number greater than or equal to 1. A higher number results in more accurate profiles at the cost of needing more data to create the profile.
voice_threshold float : Sensitivity threshold for detecting voice. The value should be a number within [0, 1]. A higher threshold increases detection confidence values at the cost of potentially missing frames of voice.
library_path Optional[str] : Absolute path to Eagle's dynamic library.

Returns

EagleProfiler: An instance of EagleProfiler object.

Throws

EagleError

pveagle.`create_recognizer()`

def create_recognizer(
        access_key: str,
        model_path: Optional[str] = None,
        device: Optional[str] = None,
        voice_threshold: float = 0.3,
        library_path: Optional[str] = None) -> Eagle:

Factory method for the recognizer component of the Eagle speaker recognition engine.

Parameters

access_key str : AccessKey obtained from Picovoice Console.
speaker_profiles Union[Sequence[EagleProfile], EagleProfile] : An instance of EagleProfiler or a list of EagleProfiler instances. Each profile corresponds to a speaker enrolled in the system.
model_path Optional[str] : Absolute path to the file containing model parameters.
device Optional[str] : String representation of the device (e.g., CPU or GPU) to use. If set to best, the most suitable device is selected automatically. If set to gpu, the engine uses the first available GPU device. To select a specific GPU device, set this argument to gpu:${GPU_INDEX}, where ${GPU_INDEX} is the index of the target GPU. If set tocpu, the engine will run on the CPU with the default number of threads. To specify the number of threads, set this argument to cpu:${NUM_THREADS}, where ${NUM_THREADS} is the desired number of threads.
voice_threshold float : Sensitivity threshold for detecting voice. The value should be a number within [0, 1]. A higher threshold increases detection confidence values at the cost of potentially missing frames of voice.
library_path Optional[str] : Absolute path to Eagle's dynamic library.

Returns

Eagle: An instance of Eagle object.

Throws

EagleError

pveagle.EagleProfiler

class EagleProfiler(object)

Class for the profiler component of the Eagle speaker recognition engine.

EagleProfiler can be initialized either using the module level create_profiler() function or directly using the class __init__() method. Resources should be cleaned when you are done using the delete() method.

pveagle.EagleProfiler.`init()`

def __init__(
    self,
    access_key: str,
    model_path: str,
    device: str,
    min_enrollment_chunks: int,
    voice_threshold: float,
    library_path: str) -> None:

__init__ method for the profiler component of the Eagle speaker recognition engine.

Parameters

access_key str : AccessKey obtained from Picovoice Console.
model_path str : Absolute path to the file containing model parameters.
device Optional[str] : String representation of the device (e.g., CPU or GPU) to use. If set to best, the most suitable device is selected automatically. If set to gpu, the engine uses the first available GPU device. To select a specific GPU device, set this argument to gpu:${GPU_INDEX}, where ${GPU_INDEX} is the index of the target GPU. If set tocpu, the engine will run on the CPU with the default number of threads. To specify the number of threads, set this argument to cpu:${NUM_THREADS}, where ${NUM_THREADS} is the desired number of threads.
min_enrollment_chunks int : Minimum number of chunks to be processed before enroll returns 100%. The value should be a number greater than or equal to 1. A higher number results in more accurate profiles at the cost of needing more data to create the profile.
voice_threshold float : Sensitivity threshold for detecting voice. The value should be a number within [0, 1]. A higher threshold increases detection confidence values at the cost of potentially missing frames of voice.
library_path str : Absolute path to Eagle's dynamic library.

Returns

EagleProfiler: An instance of EagleProfiler object.

Throws

EagleError

pveagle.EagleProfiler.`enroll()`

def enroll(self, pcm: Sequence[int]) -> float:

Enrolls a speaker. This function should be called multiple times with different utterances of the same speaker until the enrollment percentage reaches 100.0. Any further enrollment can be used to improve the speaker voice profile. The number of required samples can be obtained by calling .frame_length. The audio data used for enrollment should satisfy the following requirements:

only one speaker should be present in the audio
the speaker should be speaking in a normal voice
the audio should contain no speech from other speakers and no other sounds (e.g. music)
it should be captured in a quiet environment with no background noise

Parameters

pcm Sequence[int] : Audio data. The audio needs to have a sample rate equal to .sample_rate and be 16-bit linearly-encoded. EagleProfiler operates on single-channel audio.

Returns

float : The percentage of enrollment completed.

Throws

EagleError

pveagle.EagleProfiler.`flush()`

def flush(self) -> float:

Marks the end of the audio stream, flushes internal state of the object, and returns the percentage of enrollment completed.

Returns

float : The percentage of enrollment completed.

Throws

EagleError

pveagle.EagleProfiler.`export()`

def export(self) -> EagleProfile:

Exports the speaker profile of the current session. Will raise an exception if the profile is not ready.

Returns

EagleProfile: An immutable EagleProfile object representing the enrolled speaker.

Throws

EagleError

pveagle.EagleProfiler.`reset()`

def reset(self) -> None:

Resets the internal state of EagleProfiler. It should be called before starting a new enrollment session.

Throws

EagleError

pveagle.EagleProfiler.`delete()`

def delete(self) -> None:

Releases resources acquired by EagleProfiler.

pveagle.EagleProfiler.`frame_length`

self.frame_length: int

Number of audio samples per frame expected by EagleProfiler, i.e. length of the array passed into .enroll().

pveagle.EagleProfiler.`sample_rate`

self.sample_rate: int

Audio sample rate accepted by .enroll().

pveagle.EagleProfiler.`version`

self.version: str

The version string of the Eagle library.

pveagle.EagleProfile

class EagleProfile(object)

Python representation of an Eagle speaker profile.

pveagle.EagleProfile.`from_bytes()`

def from_bytes(cls, profile: bytes) -> 'EagleProfile'

Creates an instance of EagleProfile from a bytes object.

Parameters

profile bytes : A bytes object containing the profile.

Returns

EagleProfile: An instance of EagleProfile object.

pveagle.EagleProfile.`to_bytes()`

def to_bytes(self) -> bytes

Converts the profile to a bytes object.

Returns

bytes : The profile as a bytes object.

pveagle.EagleProfile.`size`

self.size: int

The size of the profile in bytes.

pveagle.Eagle

class Eagle(object)

Class for the recognizer component of the Eagle speaker recognition engine.

Eagle can be initialized either using the module level create_recognizer() function or directly using the class __init__() method. Resources should be cleaned when you are done using the delete() method.

pveagle.Eagle.`init()`

def __init__(
    self,
    access_key: str,
    model_path: str,
    device: str,
    voice_threshold: float,
    library_path: str) -> None:

__init__ method for the recognizer component of the Eagle speaker recognition engine.

Parameters

access_key str : AccessKey obtained from Picovoice Console.
model_path str : Absolute path to the file containing model parameters.
device Optional[str] : String representation of the device (e.g., CPU or GPU) to use. If set to best, the most suitable device is selected automatically. If set to gpu, the engine uses the first available GPU device. To select a specific GPU device, set this argument to gpu:${GPU_INDEX}, where ${GPU_INDEX} is the index of the target GPU. If set tocpu, the engine will run on the CPU with the default number of threads. To specify the number of threads, set this argument to cpu:${NUM_THREADS}, where ${NUM_THREADS} is the desired number of threads.
voice_threshold float : Sensitivity threshold for detecting voice. The value should be a number within [0, 1]. A higher threshold increases detection confidence values at the cost of potentially missing frames of voice.
library_path str : Absolute path to Eagle's dynamic library.

Returns

Eagle: An instance of Eagle object.

Throws

EagleError

pveagle.Eagle.`process()`

def process(self, pcm: Sequence[int], speaker_profiles: Sequence[EagleProfile]) -> Optional[Sequence[float]]:

Processes a frame of audio and returns a list of similarity scores for each speaker profile.

Parameters

pcm Sequence[int] : A frame of audio samples. The minimum number of samples per frame can be attained by calling .frame_length. The incoming audio needs to have a sample rate equal to .sample_rate and be 16-bit linearly-encoded. Eagle operates on single-channel audio.
speaker_profiles Sequence[EagleProfile] : A list of EagleProfile objects. This can be constructed using EagleProfiler.

Returns

Optional[Sequence[float]] : A list of similarity scores for each speaker profile or None. A higher score indicates that the voice belongs to the corresponding speaker. The range is [0, 1] with 1 representing a perfect match. A result of None indicates that there was not enough voice in the audio to recognize any speakers.

Throws

EagleError

pveagle.Eagle.`delete()`

def delete(self) -> None:

Releases resources acquired by Eagle.

Throws

EagleError

pveagle.Eagle.`sample_rate`

self.sample_rate: int

Audio sample rate accepted by Eagle.

pveagle.Eagle.`min_process_samples`

self.min_process_samples: int

The minimum length of the input pcm required by .process().

pveagle.Eagle.`version`

self.version: str

The version string of the Eagle library.

pveagle.EagleError

class EagleError(Exception)

Error thrown if an error occurs within Eagle Speaker Recognition Engine.

Exceptions

class EagleActivationError(EagleError)
class EagleActivationLimitError(EagleError)
class EagleActivationRefusedError(EagleError)
class EagleActivationThrottledError(EagleError)
class EagleIOError(EagleError)
class EagleInvalidArgumentError(EagleError)
class EagleInvalidStateError(EagleError)
class EagleKeyError(EagleError)
class EagleMemoryError(EagleError)
class EagleRuntimeError(EagleError)
class EagleStopIterationError(EagleError)

Was this doc helpful?

Issue with this doc?

Eagle Speaker Recognition Python API

Eagle Speaker Recognition
Python API