core/java/android/hardware/soundtrigger/SoundTrigger.java - platform/frameworks/base - Gitiles

 /*
  * Copyright (C) 2014 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 package android.hardware.soundtrigger;

 import android.content.Context;
 import android.content.Intent;
 import android.os.Handler;

 import java.util.ArrayList;
 import java.util.UUID;

 /**
  * The SoundTrigger class provides access via JNI to the native service managing
  * the sound trigger HAL.
  *
  * @hide
  */
 public class SoundTrigger {

     public static final int STATUS_OK = 0;
     public static final int STATUS_ERROR = Integer.MIN_VALUE;
     public static final int STATUS_PERMISSION_DENIED = -1;
     public static final int STATUS_NO_INIT = -19;
     public static final int STATUS_BAD_VALUE = -22;
     public static final int STATUS_DEAD_OBJECT = -32;
     public static final int STATUS_INVALID_OPERATION = -38;

     /*****************************************************************************
      * A ModuleProperties describes a given sound trigger hardware module
      * managed by the native sound trigger service. Each module has a unique
      * ID used to target any API call to this paricular module. Module
      * properties are returned by listModules() method.
      ****************************************************************************/
     public static class ModuleProperties {
         /** Unique module ID provided by the native service */
         public final int id;

         /** human readable voice detection engine implementor */
         public final String implementor;

         /** human readable voice detection engine description */
         public final String description;

         /** Unique voice engine Id (changes with each version) */
         public final UUID uuid;

         /** Voice detection engine version */
         public final int version;

         /** Maximum number of active sound models */
         public final int maxSoundModels;

         /** Maximum number of key phrases */
         public final int maxKeyPhrases;

         /** Maximum number of users per key phrase */
         public final int maxUsers;

         /** Supported recognition modes (bit field, RECOGNITION_MODE_VOICE_TRIGGER ...) */
         public final int recognitionModes;

         /** Supports seamless transition to capture mode after recognition */
         public final boolean supportsCaptureTransition;

         /** Maximum buffering capacity in ms if supportsCaptureTransition() is true */
         public final int maxBufferMs;

         /** Supports capture by other use cases while detection is active */
         public final boolean supportsConcurrentCapture;

         /** Rated power consumption when detection is active with TDB silence/sound/speech ratio */
         public final int powerConsumptionMw;

         ModuleProperties(int id, String implementor, String description,
                 String uuid, int version, int maxSoundModels, int maxKeyPhrases,
                 int maxUsers, int recognitionModes, boolean supportsCaptureTransition,
                 int maxBufferMs, boolean supportsConcurrentCapture,
                 int powerConsumptionMw) {
             this.id = id;
             this.implementor = implementor;
             this.description = description;
             this.uuid = UUID.fromString(uuid);
             this.version = version;
             this.maxSoundModels = maxSoundModels;
             this.maxKeyPhrases = maxKeyPhrases;
             this.maxUsers = maxUsers;
             this.recognitionModes = recognitionModes;
             this.supportsCaptureTransition = supportsCaptureTransition;
             this.maxBufferMs = maxBufferMs;
             this.supportsConcurrentCapture = supportsConcurrentCapture;
             this.powerConsumptionMw = powerConsumptionMw;
         }
     }

     /*****************************************************************************
      * A SoundModel describes the attributes and contains the binary data used by the hardware
      * implementation to detect a particular sound pattern.
      * A specialized version {@link KeyPhraseSoundModel} is defined for key phrase
      * sound models.
      ****************************************************************************/
     public static class SoundModel {
         /** Undefined sound model type */
         public static final int TYPE_UNKNOWN = -1;

         /** Keyphrase sound model */
         public static final int TYPE_KEYPHRASE = 0;

         /** Sound model type (e.g. TYPE_KEYPHRASE); */
         public final int type;

         /** Opaque data. For use by vendor implementation and enrollment application */
         public final byte[] data;

         public SoundModel(int type, byte[] data) {
             this.type = type;
             this.data = data;
         }
     }

     /*****************************************************************************
      * A KeyPhrase describes a key phrase that can be detected by a
      * {@link KeyPhraseSoundModel}
      ****************************************************************************/
     public static class KeyPhrase {
         /** Recognition modes supported for this key phrase in the model */
         public final int recognitionModes;

         /** Locale of the keyphrase. JAVA Locale string e.g en_US */
         public final String locale;

         /** Key phrase text */
         public final String text;

         /** Number of users this key phrase has been trained for */
         public final int numUsers;

         public KeyPhrase(int recognitionModes, String locale, String text, int numUsers) {
             this.recognitionModes = recognitionModes;
             this.locale = locale;
             this.text = text;
             this.numUsers = numUsers;
         }
     }

     /*****************************************************************************
      * A KeyPhraseSoundModel is a specialized {@link SoundModel} for key phrases.
      * It contains data needed by the hardware to detect a certain number of key phrases
      * and the list of corresponding {@link KeyPhrase} descriptors.
      ****************************************************************************/
     public static class KeyPhraseSoundModel extends SoundModel {
         /** Key phrases in this sound model */
         public final KeyPhrase[] keyPhrases; // keyword phrases in model

         public KeyPhraseSoundModel(byte[] data, KeyPhrase[] keyPhrases) {
             super(TYPE_KEYPHRASE, data);
             this.keyPhrases = keyPhrases;
         }
     }

     /**
      *  Modes for key phrase recognition
      */
     /** Simple recognition of the key phrase */
     public static final int RECOGNITION_MODE_VOICE_TRIGGER = 0x1;
     /** Trigger only if one user is identified */
     public static final int RECOGNITION_MODE_USER_IDENTIFICATION = 0x2;
     /** Trigger only if one user is authenticated */
     public static final int RECOGNITION_MODE_USER_AUTHENTICATION = 0x4;

     /**
      *  Status codes for {@link RecognitionEvent}
      */
     /** Recognition success */
     public static final int RECOGNITION_STATUS_SUCCESS = 0;
     /** Recognition aborted (e.g. capture preempted by anotehr use case */
     public static final int RECOGNITION_STATUS_ABORT = 1;
     /** Recognition failure */
     public static final int RECOGNITION_STATUS_FAILURE = 2;

     /**
      *  A RecognitionEvent is provided by the
      *  {@link StatusListener#onRecognition(RecognitionEvent)}
      *  callback upon recognition success or failure.
      */
     public static class RecognitionEvent {
         /** Recognition status e.g {@link #RECOGNITION_STATUS_SUCCESS} */
         public final int status;
         /** Sound Model corresponding to this event callback */
         public final int soundModelHandle;
         /** True if it is possible to capture audio from this utterance buffered by the hardware */
         public final boolean captureAvailable;
         /** Audio session ID to be used when capturing the utterance with an AudioRecord
          * if captureAvailable() is true. */
         public final int captureSession;
         /** Delay in ms between end of model detection and start of audio available for capture.
          * A negative value is possible (e.g. if keyphrase is also available for capture) */
         public final int captureDelayMs;
         /** Opaque data for use by system applications who know about voice engine internals,
          * typically during enrollment. */
         public final byte[] data;

         RecognitionEvent(int status, int soundModelHandle, boolean captureAvailable,
                 int captureSession, int captureDelayMs, byte[] data) {
             this.status = status;
             this.soundModelHandle = soundModelHandle;
             this.captureAvailable = captureAvailable;
             this.captureSession = captureSession;
             this.captureDelayMs = captureDelayMs;
             this.data = data;
         }
     }

     /**
      *  Additional data conveyed by a {@link KeyPhraseRecognitionEvent}
      *  for a key phrase detection.
      */
     public static class KeyPhraseRecognitionExtra {
         /** Confidence level for each user defined in the key phrase in the same order as
          * users in the key phrase. The confidence level is expressed in percentage (0% -100%) */
         public final int[] confidenceLevels;

         /** Recognition modes matched for this event */
         public final int recognitionModes;

         KeyPhraseRecognitionExtra(int[] confidenceLevels, int recognitionModes) {
             this.confidenceLevels = confidenceLevels;
             this.recognitionModes = recognitionModes;
         }
     }

     /**
      *  Specialized {@link RecognitionEvent} for a key phrase detection.
      */
     public static class KeyPhraseRecognitionEvent extends RecognitionEvent {
         /** Indicates if the key phrase is present in the buffered audio available for capture */
         public final KeyPhraseRecognitionExtra[] keyPhraseExtras;

         /** Additional data available for each recognized key phrases in the model */
         public final boolean keyPhraseInCapture;

         KeyPhraseRecognitionEvent(int status, int soundModelHandle, boolean captureAvailable,
                int captureSession, int captureDelayMs, byte[] data,
                boolean keyPhraseInCapture, KeyPhraseRecognitionExtra[] keyPhraseExtras) {
             super(status, soundModelHandle, captureAvailable, captureSession, captureDelayMs, data);
             this.keyPhraseInCapture = keyPhraseInCapture;
             this.keyPhraseExtras = keyPhraseExtras;
         }
     }

     /**
      * Returns a list of descriptors for all harware modules loaded.
      * @param modules A ModuleProperties array where the list will be returned.
      * @return - {@link #STATUS_OK} in case of success
      *         - {@link #STATUS_ERROR} in case of unspecified error
      *         - {@link #STATUS_PERMISSION_DENIED} if the caller does not have system permission
      *         - {@link #STATUS_NO_INIT} if the native service cannot be reached
      *         - {@link #STATUS_BAD_VALUE} if modules is null
      *         - {@link #STATUS_DEAD_OBJECT} if the binder transaction to the native service fails
      */
     public static native int listModules(ArrayList <ModuleProperties> modules);

     /**
      * Get an interface on a hardware module to control sound models and recognition on
      * this module.
      * @param moduleId Sound module system identifier {@link ModuleProperties#id}. mandatory.
      * @param listener {@link StatusListener} interface. Mandatory.
      * @param handler the Handler that will receive the callabcks. Can be null if default handler
      *                is OK.
      * @return a valid sound module in case of success or null in case of error.
      */
     public static SoundTriggerModule attachModule(int moduleId,
                                                   StatusListener listener,
                                                   Handler handler) {
         if (listener == null) {
             return null;
         }
         SoundTriggerModule module = new SoundTriggerModule(moduleId, listener, handler);
         return module;
     }

     /**
      * Interface provided by the client application when attaching to a {@link SoundTriggerModule}
      * to received recognition and error notifications.
      */
     public static interface StatusListener {
         /**
          * Called when recognition succeeds of fails
          */
         public abstract void onRecognition(RecognitionEvent event);

         /**
          * Called when the sound trigger native service dies
          */
         public abstract void onServiceDied();
     }
 }
	/*
	* Copyright (C) 2014 The Android Open Source Project
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	package android.hardware.soundtrigger;

	import android.content.Context;
	import android.content.Intent;
	import android.os.Handler;

	import java.util.ArrayList;
	import java.util.UUID;

	/**
	* The SoundTrigger class provides access via JNI to the native service managing
	* the sound trigger HAL.
	*
	* @hide
	*/
	public class SoundTrigger {

	public static final int STATUS_OK = 0;
	public static final int STATUS_ERROR = Integer.MIN_VALUE;
	public static final int STATUS_PERMISSION_DENIED = -1;
	public static final int STATUS_NO_INIT = -19;
	public static final int STATUS_BAD_VALUE = -22;
	public static final int STATUS_DEAD_OBJECT = -32;
	public static final int STATUS_INVALID_OPERATION = -38;

	/*****************************************************************************
	* A ModuleProperties describes a given sound trigger hardware module
	* managed by the native sound trigger service. Each module has a unique
	* ID used to target any API call to this paricular module. Module
	* properties are returned by listModules() method.
	****************************************************************************/
	public static class ModuleProperties {
	/** Unique module ID provided by the native service */
	public final int id;

	/** human readable voice detection engine implementor */
	public final String implementor;

	/** human readable voice detection engine description */
	public final String description;

	/** Unique voice engine Id (changes with each version) */
	public final UUID uuid;

	/** Voice detection engine version */
	public final int version;

	/** Maximum number of active sound models */
	public final int maxSoundModels;

	/** Maximum number of key phrases */
	public final int maxKeyPhrases;

	/** Maximum number of users per key phrase */
	public final int maxUsers;

	/** Supported recognition modes (bit field, RECOGNITION_MODE_VOICE_TRIGGER ...) */
	public final int recognitionModes;

	/** Supports seamless transition to capture mode after recognition */
	public final boolean supportsCaptureTransition;

	/** Maximum buffering capacity in ms if supportsCaptureTransition() is true */
	public final int maxBufferMs;

	/** Supports capture by other use cases while detection is active */
	public final boolean supportsConcurrentCapture;

	/** Rated power consumption when detection is active with TDB silence/sound/speech ratio */
	public final int powerConsumptionMw;

	ModuleProperties(int id, String implementor, String description,
	String uuid, int version, int maxSoundModels, int maxKeyPhrases,
	int maxUsers, int recognitionModes, boolean supportsCaptureTransition,
	int maxBufferMs, boolean supportsConcurrentCapture,
	int powerConsumptionMw) {
	this.id = id;
	this.implementor = implementor;
	this.description = description;
	this.uuid = UUID.fromString(uuid);
	this.version = version;
	this.maxSoundModels = maxSoundModels;
	this.maxKeyPhrases = maxKeyPhrases;
	this.maxUsers = maxUsers;
	this.recognitionModes = recognitionModes;
	this.supportsCaptureTransition = supportsCaptureTransition;
	this.maxBufferMs = maxBufferMs;
	this.supportsConcurrentCapture = supportsConcurrentCapture;
	this.powerConsumptionMw = powerConsumptionMw;
	}
	}

	/*****************************************************************************
	* A SoundModel describes the attributes and contains the binary data used by the hardware
	* implementation to detect a particular sound pattern.
	* A specialized version {@link KeyPhraseSoundModel} is defined for key phrase
	* sound models.
	****************************************************************************/
	public static class SoundModel {
	/** Undefined sound model type */
	public static final int TYPE_UNKNOWN = -1;

	/** Keyphrase sound model */
	public static final int TYPE_KEYPHRASE = 0;

	/** Sound model type (e.g. TYPE_KEYPHRASE); */
	public final int type;

	/** Opaque data. For use by vendor implementation and enrollment application */
	public final byte[] data;

	public SoundModel(int type, byte[] data) {
	this.type = type;
	this.data = data;
	}
	}

	/*****************************************************************************
	* A KeyPhrase describes a key phrase that can be detected by a
	* {@link KeyPhraseSoundModel}
	****************************************************************************/
	public static class KeyPhrase {
	/** Recognition modes supported for this key phrase in the model */
	public final int recognitionModes;

	/** Locale of the keyphrase. JAVA Locale string e.g en_US */
	public final String locale;

	/** Key phrase text */
	public final String text;

	/** Number of users this key phrase has been trained for */
	public final int numUsers;

	public KeyPhrase(int recognitionModes, String locale, String text, int numUsers) {
	this.recognitionModes = recognitionModes;
	this.locale = locale;
	this.text = text;
	this.numUsers = numUsers;
	}
	}

	/*****************************************************************************
	* A KeyPhraseSoundModel is a specialized {@link SoundModel} for key phrases.
	* It contains data needed by the hardware to detect a certain number of key phrases
	* and the list of corresponding {@link KeyPhrase} descriptors.
	****************************************************************************/
	public static class KeyPhraseSoundModel extends SoundModel {
	/** Key phrases in this sound model */
	public final KeyPhrase[] keyPhrases; // keyword phrases in model

	public KeyPhraseSoundModel(byte[] data, KeyPhrase[] keyPhrases) {
	super(TYPE_KEYPHRASE, data);
	this.keyPhrases = keyPhrases;
	}
	}

	/**
	* Modes for key phrase recognition
	*/
	/** Simple recognition of the key phrase */
	public static final int RECOGNITION_MODE_VOICE_TRIGGER = 0x1;
	/** Trigger only if one user is identified */
	public static final int RECOGNITION_MODE_USER_IDENTIFICATION = 0x2;
	/** Trigger only if one user is authenticated */
	public static final int RECOGNITION_MODE_USER_AUTHENTICATION = 0x4;

	/**
	* Status codes for {@link RecognitionEvent}
	*/
	/** Recognition success */
	public static final int RECOGNITION_STATUS_SUCCESS = 0;
	/** Recognition aborted (e.g. capture preempted by anotehr use case */
	public static final int RECOGNITION_STATUS_ABORT = 1;
	/** Recognition failure */
	public static final int RECOGNITION_STATUS_FAILURE = 2;

	/**
	* A RecognitionEvent is provided by the
	* {@link StatusListener#onRecognition(RecognitionEvent)}
	* callback upon recognition success or failure.
	*/
	public static class RecognitionEvent {
	/** Recognition status e.g {@link #RECOGNITION_STATUS_SUCCESS} */
	public final int status;
	/** Sound Model corresponding to this event callback */
	public final int soundModelHandle;
	/** True if it is possible to capture audio from this utterance buffered by the hardware */
	public final boolean captureAvailable;
	/** Audio session ID to be used when capturing the utterance with an AudioRecord
	* if captureAvailable() is true. */
	public final int captureSession;
	/** Delay in ms between end of model detection and start of audio available for capture.
	* A negative value is possible (e.g. if keyphrase is also available for capture) */
	public final int captureDelayMs;
	/** Opaque data for use by system applications who know about voice engine internals,
	* typically during enrollment. */
	public final byte[] data;

	RecognitionEvent(int status, int soundModelHandle, boolean captureAvailable,
	int captureSession, int captureDelayMs, byte[] data) {
	this.status = status;
	this.soundModelHandle = soundModelHandle;
	this.captureAvailable = captureAvailable;
	this.captureSession = captureSession;
	this.captureDelayMs = captureDelayMs;
	this.data = data;
	}
	}

	/**
	* Additional data conveyed by a {@link KeyPhraseRecognitionEvent}
	* for a key phrase detection.
	*/
	public static class KeyPhraseRecognitionExtra {
	/** Confidence level for each user defined in the key phrase in the same order as
	* users in the key phrase. The confidence level is expressed in percentage (0% -100%) */
	public final int[] confidenceLevels;

	/** Recognition modes matched for this event */
	public final int recognitionModes;

	KeyPhraseRecognitionExtra(int[] confidenceLevels, int recognitionModes) {
	this.confidenceLevels = confidenceLevels;
	this.recognitionModes = recognitionModes;
	}
	}

	/**
	* Specialized {@link RecognitionEvent} for a key phrase detection.
	*/
	public static class KeyPhraseRecognitionEvent extends RecognitionEvent {
	/** Indicates if the key phrase is present in the buffered audio available for capture */
	public final KeyPhraseRecognitionExtra[] keyPhraseExtras;

	/** Additional data available for each recognized key phrases in the model */
	public final boolean keyPhraseInCapture;

	KeyPhraseRecognitionEvent(int status, int soundModelHandle, boolean captureAvailable,
	int captureSession, int captureDelayMs, byte[] data,
	boolean keyPhraseInCapture, KeyPhraseRecognitionExtra[] keyPhraseExtras) {
	super(status, soundModelHandle, captureAvailable, captureSession, captureDelayMs, data);
	this.keyPhraseInCapture = keyPhraseInCapture;
	this.keyPhraseExtras = keyPhraseExtras;
	}
	}

	/**
	* Returns a list of descriptors for all harware modules loaded.
	* @param modules A ModuleProperties array where the list will be returned.
	* @return - {@link #STATUS_OK} in case of success
	* - {@link #STATUS_ERROR} in case of unspecified error
	* - {@link #STATUS_PERMISSION_DENIED} if the caller does not have system permission
	* - {@link #STATUS_NO_INIT} if the native service cannot be reached
	* - {@link #STATUS_BAD_VALUE} if modules is null
	* - {@link #STATUS_DEAD_OBJECT} if the binder transaction to the native service fails
	*/
	public static native int listModules(ArrayList <ModuleProperties> modules);

	/**
	* Get an interface on a hardware module to control sound models and recognition on
	* this module.
	* @param moduleId Sound module system identifier {@link ModuleProperties#id}. mandatory.
	* @param listener {@link StatusListener} interface. Mandatory.
	* @param handler the Handler that will receive the callabcks. Can be null if default handler
	* is OK.
	* @return a valid sound module in case of success or null in case of error.
	*/
	public static SoundTriggerModule attachModule(int moduleId,
	StatusListener listener,
	Handler handler) {
	if (listener == null) {
	return null;
	}
	SoundTriggerModule module = new SoundTriggerModule(moduleId, listener, handler);
	return module;
	}

	/**
	* Interface provided by the client application when attaching to a {@link SoundTriggerModule}
	* to received recognition and error notifications.
	*/
	public static interface StatusListener {
	/**
	* Called when recognition succeeds of fails
	*/
	public abstract void onRecognition(RecognitionEvent event);

	/**
	* Called when the sound trigger native service dies
	*/
	public abstract void onServiceDied();
	}
	}