Eagle Speaker Recognition
Android API

API Reference for the Android Eagle SDK (eagle-android)

package: ai.picovoice.eagle

Eagle

public class Eagle { }

Class for the Eagle speaker recognition engine.

Eagle must be initialized using the Eagle.Builder Class. Resources should be cleaned when you are done using the delete() function.

Eagle.delete()

public void delete()

Releases resources acquired by Eagle.

Eagle.getFrameLength()

public int getFrameLength()

Getter for number of audio samples per frame.

Returns

• int: Number of audio samples per frame.

Eagle.getSampleRate()

public void getSampleRate()

Getter for required audio sample rate for PCM data.

Returns

• int: Required audio sample rate for PCM data.

Eagle.getVersion()

public String getVersion()

Getter for version.

Returns

• String: Current Eagle version.

Eagle.process()

public float[] process(short[] pcm) throws EagleException

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

Parameters

• pcm short[] : A frame of audio samples. The number of samples per frame can be attained by calling .getFrameLength(). The incoming audio needs to have a sample rate equal to .getSmapleRate and be 16-bit linearly-encoded. Eagle operates on single-channel audio.

Returns

• float[]: An array of similarity scores for each speaker profile. A higher score indicates that the voice belongs to the corresponding speaker. The range is [0, 1] with 1.0 representing a perfect match.

Throws

• EagleException: If there is an error while processing the audio frame.

Eagle.reset()

public void reset() throws EagleException

Resets the internal state of the engine. It is best to call before processing a new sequence of audio (e.g. a new voice interaction). This ensures that the accuracy of the engine is not affected by a change in audio context.

Throws

• EagleException: If there is an error while resetting eagle.

Eagle.Builder

public static class Builder { }

Builder for creating an instance of Eagle with a mixture of default arguments.

Eagle.Builder.build()

public Eagle build(Context context) throws EagleException

Creates an instance of Eagle speaker recognition engine.

Parameters

• context Context : The Android app context.

Returns

• Eagle: An instance of Eagle speaker recognition engine.

Throws

• EagleException: If an error occurs while creating an instance of Eagle speaker recognition engine.

Eagle.Builder.setAccessKey()

public Eagle.Builder setAccessKey(String accessKey)

Sets the AccessKey of the builder.

Parameters

• accessKey String : AccessKey obtained from Picovoice Console.

Returns

• Eagle.Builder: Modified Eagle.Builder object.

Eagle.Builder.setModelPath()

public Eagle.Builder setModelPath(String modelPath)

Sets the model path of the builder.

Parameters

• modelPath String : Path to the file containing model parameters (.pv). Can be either a path that is relative to the project's assets folder or an absolute path to the file on device.

Returns

• Eagle.Builder: Modified Eagle.Builder object.

Eagle.Builder.setSpeakerProfiles()

public Eagle.Builder setSpeakerProfiles(EagleProfile[] speakerProfiles)

Sets the speaker profiles of the builder. This overwrites any speaker profiles assigned previously.

Parameters

• speakerProfiles EagleProfile[] : Array of speaker profiles created with EagleProfiler.

Returns

• Eagle.Builder: Modified Eagle.Builder object.

Eagle.Builder.setSpeakerProfile()

public Eagle.Builder setSpeakerProfile(EagleProfile speakerProfile)

Sets a single speaker profile of the builder. This overwrites any speaker profiles assigned previously.

Parameters

• speakerProfile EagleProfile : A speaker profiles created with EagleProfiler.

Returns

• Eagle.Builder: Modified Eagle.Builder object.

EagleException

public class EagleException extends Exception { }

Exception thrown if an error occurs within Eagle speaker recognition engine.

Exceptions:

public class EagleActivationException           extends EagleException { }
public class EagleActivationLimitException      extends EagleException { }
public class EagleActivationRefusedException    extends EagleException { }
public class EagleActivationThrottledException  extends EagleException { }
public class EagleIOException                   extends EagleException { }
public class EagleInvalidArgumentException      extends EagleException { }
public class EagleInvalidStateException         extends EagleException { }
public class EagleKeyException                  extends EagleException { }
public class EagleMemoryException               extends EagleException { }
public class EagleRuntimeException              extends EagleException { }
public class EagleStopIterationException        extends EagleException { }

EagleProfile

public class EagleProfile {
    public EagleProfile(byte[] profileBytes) { }
}

Type which represents a speaker profile. The object can be serialized (via .getBytes()) and deserialized (via constructor) for reuse. Resources must explicitly be released by calling .delete().

Parameters

• metadataBytes byte[] : A byte array previously obtained via .getBytes().

EagleProfile.getBytes()

public byte[] getBytes()

Gets the metadata in the form of a byte array.

Returns

• byte[]: The metadata in the form of a byte array.

EagleProfile.delete()

public void delete()

Releases resources acquired by EagleProfile.

EagleProfiler

public class EagleProfiler { }

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

EagleProfiler.delete()

public void delete()

Releases resources acquired by EagleProfiler.

EagleProfiler.getSampleRate()

public void getSampleRate()

Getter for required audio sample rate for PCM data.

Returns

• int: Required audio sample rate for PCM data.

EagleProfiler.getVersion()

public String getVersion()

Getter for version.

Returns

• String: Current Eagle version.

EagleProfiler.getMinEnrollSamples()

public int getMinEnrollSamples()

Getter for minimum length of the input pcm required by .enroll().

Returns

• int: minimum length of the input pcm.

EagleProfiler.enroll()

public EagleProfilerEnrollResult enroll(short[] pcm) throws EagleException

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 minimum number of required samples can be obtained by calling .getMinEnrollSamples(). 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 .getSampleRate() and be 16-bit linearly-encoded. EagleProfiler operates on single-channel audio.

Returns

• EagleProfilerEnrollResult : The percentage of completeness of the speaker enrollment process along with the feedback code corresponding to the last enrollment attempt.

Throws

• EagleException: If an error occurs while enrolling speaker.

EagleProfiler.export()

public EagleProfile export() throws EagleException

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

• EagleException: If an error occurs while exporting speaker.

EagleProfiler.reset()

public void reset() throws EagleException

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

Throws

• EagleException: If an error occurs while resetting speaker.

EagleProfilerEnrollResult

public class EagleProfilerEnrollResult {
    public EagleProfilerEnrollResult(float percentage, int feedbackIdx) { }
}

Representation of the feedback returned by EagleProfiler.enroll().

Parameters

• percentage float : The current percentage enrolled.
• feedbackIdx int : Feedback index based on EagleProfilerEnrollFeedback enum.

EagleProfilerEnrollResult.getPercentage()

public float getPercentage()

Getter for enrolled percentage.

Returns

• float: Enrolled percentage.

EagleProfilerEnrollResult.getFeedback()

public EagleProfilerFeedback getFeedback()

Getter for the enroll feedback enum.

Returns

• EagleProfilerEnrollFeedback: Enroll feedback.

EagleProfilerEnrollFeedback

public enum EagleProfilerEnrollFeedback {
    AUDIO_OK,
    AUDIO_TOO_SHORT,
    UNKNOWN_SPEAKER,
    NO_VOICE_FOUND,
    QUALITY_ISSUE;
}

Enumeration of possible enrollment feedback codes:

• AUDIO_OK: The audio is good for enrollment.
• AUDIO_TOO_SHORT: Audio length is insufficient for enrollment, i.e. it is shorter than EagleProfiler.getMinEnrollSamples().
• UNKNOWN_SPEAKER: There is another speaker in the audio that is different from the speaker being enrolled. Too much background noise may cause this error as well.
• NO_VOICE_FOUND: The audio does not contain any voice, i.e. it is silent or has a low signal-to-noise ratio.
• QUALITY_ISSUE: The audio quality is too low for enrollment due to a bad microphone or recording environment.