alvinalexander.com | career | drupal | java | mac | mysql | perl | scala | uml | unix  

Android example source code file (RecognizerIntent.java)

This example Android source code file (RecognizerIntent.java) is included in the DevDaily.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Android by Example" TM.

Java - Android tags/keywords

android, app, application, content, details_meta_data, extra_language_model, extra_max_results, extra_only_return_language_preference, extra_results_pendingintent_bundle, extra_speech_input_complete_silence_length_millis, extra_speech_input_possibly_complete_silence_length_millis, extra_supported_languages, intent, language_model_free_form, os, recognizerintent, result_no_match, result_server_error, string, util

The RecognizerIntent.java Android example source code

/*
 * Copyright (C) 2008 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.speech;

import java.util.ArrayList;

import android.app.Activity;
import android.content.ActivityNotFoundException;
import android.content.BroadcastReceiver;
import android.content.ComponentName;
import android.content.Context;
import android.content.Intent;
import android.content.pm.PackageManager;
import android.content.pm.ResolveInfo;
import android.os.Bundle;

/**
 * Constants for supporting speech recognition through starting an {@link Intent}
 */
public class RecognizerIntent {
    /**
     * The extra key used in an intent to the speech recognizer for voice search. Not
     * generally to be used by developers. The system search dialog uses this, for example,
     * to set a calling package for identification by a voice search API. If this extra
     * is set by anyone but the system process, it should be overridden by the voice search
     * implementation.
     */
    public final static String EXTRA_CALLING_PACKAGE = "calling_package";

    private RecognizerIntent() {
        // Not for instantiating.
    }

    /**
     * Starts an activity that will prompt the user for speech and sends it through a
     * speech recognizer.  The results will be returned via activity results (in
     * {@link Activity#onActivityResult}, if you start the intent using
     * {@link Activity#startActivityForResult(Intent, int)}), or forwarded via a PendingIntent
     * if one is provided.
     * 
     * <p>Starting this intent with just {@link Activity#startActivity(Intent)} is not supported.
     * You must either use {@link Activity#startActivityForResult(Intent, int)}, or provide a
     * PendingIntent, to receive recognition results.
     * 
     * <p>Required extras:
     * <ul>
     *   <li>{@link #EXTRA_LANGUAGE_MODEL}
     * </ul>
     * 
     * <p>Optional extras:
     * <ul>
     *   <li>{@link #EXTRA_PROMPT}
     *   <li>{@link #EXTRA_LANGUAGE}
     *   <li>{@link #EXTRA_MAX_RESULTS}
     *   <li>{@link #EXTRA_RESULTS_PENDINGINTENT}
     *   <li>{@link #EXTRA_RESULTS_PENDINGINTENT_BUNDLE}
     * </ul>
     * 
     * <p> Result extras (returned in the result, not to be specified in the request):
     * <ul>
     *   <li>{@link #EXTRA_RESULTS}
     * </ul>
     * 
     * <p>NOTE: There may not be any applications installed to handle this action, so you should
     * make sure to catch {@link ActivityNotFoundException}.
     */
    public static final String ACTION_RECOGNIZE_SPEECH = "android.speech.action.RECOGNIZE_SPEECH";

    /**
     * Starts an activity that will prompt the user for speech, sends it through a
     * speech recognizer, and invokes and displays a web search result.
     * 
     * <p>Required extras:
     * <ul>
     *   <li>{@link #EXTRA_LANGUAGE_MODEL}
     * </ul>
     * 
     * <p>Optional extras:
     * <ul>
     *   <li>{@link #EXTRA_PROMPT}
     *   <li>{@link #EXTRA_LANGUAGE}
     *   <li>{@link #EXTRA_MAX_RESULTS}
     *   <li>{@link #EXTRA_PARTIAL_RESULTS}
     * </ul>
     * 
     * <p> Result extras (returned in the result, not to be specified in the request):
     * <ul>
     *   <li>{@link #EXTRA_RESULTS}
     * </ul>
     * 
     * <p>NOTE: There may not be any applications installed to handle this action, so you should
     * make sure to catch {@link ActivityNotFoundException}.
     */
    public static final String ACTION_WEB_SEARCH = "android.speech.action.WEB_SEARCH";

    /**
     * The minimum length of an utterance. We will not stop recording before this amount of time.
     * 
     * Note that it is extremely rare you'd want to specify this value in an intent. If you don't
     * have a very good reason to change these, you should leave them as they are. Note also that
     * certain values may cause undesired or unexpected results - use judiciously! Additionally,
     * depending on the recognizer implementation, these values may have no effect.
     */
    public static final String EXTRA_SPEECH_INPUT_MINIMUM_LENGTH_MILLIS =
            "android.speech.extras.SPEECH_INPUT_MINIMUM_LENGTH_MILLIS";

    /**
     * The amount of time that it should take after we stop hearing speech to consider the input
     * complete. 
     * 
     * Note that it is extremely rare you'd want to specify this value in an intent. If
     * you don't have a very good reason to change these, you should leave them as they are. Note
     * also that certain values may cause undesired or unexpected results - use judiciously!
     * Additionally, depending on the recognizer implementation, these values may have no effect.
     */
    public static final String EXTRA_SPEECH_INPUT_COMPLETE_SILENCE_LENGTH_MILLIS =
            "android.speech.extras.SPEECH_INPUT_COMPLETE_SILENCE_LENGTH_MILLIS";

    /**
     * The amount of time that it should take after we stop hearing speech to consider the input
     * possibly complete. This is used to prevent the endpointer cutting off during very short
     * mid-speech pauses. 
     * 
     * Note that it is extremely rare you'd want to specify this value in an intent. If
     * you don't have a very good reason to change these, you should leave them as they are. Note
     * also that certain values may cause undesired or unexpected results - use judiciously!
     * Additionally, depending on the recognizer implementation, these values may have no effect.
     */
    public static final String EXTRA_SPEECH_INPUT_POSSIBLY_COMPLETE_SILENCE_LENGTH_MILLIS =
            "android.speech.extras.SPEECH_INPUT_POSSIBLY_COMPLETE_SILENCE_LENGTH_MILLIS";

    /**
     * Informs the recognizer which speech model to prefer when performing
     * {@link #ACTION_RECOGNIZE_SPEECH}. The recognizer uses this
     * information to fine tune the results. This extra is required. Activities implementing
     * {@link #ACTION_RECOGNIZE_SPEECH} may interpret the values as they see fit.
     * 
     *  @see #LANGUAGE_MODEL_FREE_FORM
     *  @see #LANGUAGE_MODEL_WEB_SEARCH
     */
    public static final String EXTRA_LANGUAGE_MODEL = "android.speech.extra.LANGUAGE_MODEL";

    /** 
     * Use a language model based on free-form speech recognition.  This is a value to use for 
     * {@link #EXTRA_LANGUAGE_MODEL}. 
     * @see #EXTRA_LANGUAGE_MODEL
     */
    public static final String LANGUAGE_MODEL_FREE_FORM = "free_form";
    /** 
     * Use a language model based on web search terms.  This is a value to use for 
     * {@link #EXTRA_LANGUAGE_MODEL}. 
     * @see #EXTRA_LANGUAGE_MODEL
     */
    public static final String LANGUAGE_MODEL_WEB_SEARCH = "web_search";

    /** Optional text prompt to show to the user when asking them to speak. */
    public static final String EXTRA_PROMPT = "android.speech.extra.PROMPT";

    /**
     * Optional IETF language tag (as defined by BCP 47), for example "en-US". This tag informs the
     * recognizer to perform speech recognition in a language different than the one set in the
     * {@link java.util.Locale#getDefault()}.
     */
    public static final String EXTRA_LANGUAGE = "android.speech.extra.LANGUAGE";

    /** 
     * Optional limit on the maximum number of results to return. If omitted the recognizer
     * will choose how many results to return. Must be an integer.
     */
    public static final String EXTRA_MAX_RESULTS = "android.speech.extra.MAX_RESULTS";

    /**
     * Optional boolean to indicate whether partial results should be returned by the recognizer
     * as the user speaks (default is false).  The server may ignore a request for partial
     * results in some or all cases.
     */
    public static final String EXTRA_PARTIAL_RESULTS = "android.speech.extra.PARTIAL_RESULTS";

    /**
     * When the intent is {@link #ACTION_RECOGNIZE_SPEECH}, the speech input activity will
     * return results to you via the activity results mechanism.  Alternatively, if you use this
     * extra to supply a PendingIntent, the results will be added to its bundle and the 
     * PendingIntent will be sent to its target.
     */
    public static final String EXTRA_RESULTS_PENDINGINTENT = 
            "android.speech.extra.RESULTS_PENDINGINTENT";
    
    /**
     * If you use {@link #EXTRA_RESULTS_PENDINGINTENT} to supply a forwarding intent, you can
     * also use this extra to supply additional extras for the final intent.  The search results
     * will be added to this bundle, and the combined bundle will be sent to the target.
     */
    public static final String EXTRA_RESULTS_PENDINGINTENT_BUNDLE = 
            "android.speech.extra.RESULTS_PENDINGINTENT_BUNDLE";

    /** Result code returned when no matches are found for the given speech */
    public static final int RESULT_NO_MATCH = Activity.RESULT_FIRST_USER;
    /** Result code returned when there is a generic client error */
    public static final int RESULT_CLIENT_ERROR = Activity.RESULT_FIRST_USER + 1;
    /** Result code returned when the recognition server returns an error */
    public static final int RESULT_SERVER_ERROR = Activity.RESULT_FIRST_USER + 2;
    /** Result code returned when a network error was encountered */
    public static final int RESULT_NETWORK_ERROR = Activity.RESULT_FIRST_USER + 3;
    /** Result code returned when an audio error was encountered */
    public static final int RESULT_AUDIO_ERROR = Activity.RESULT_FIRST_USER + 4;

    /**
     * An ArrayList<String> of the recognition results when performing
     * {@link #ACTION_RECOGNIZE_SPEECH}. Returned in the results; not to be specified in the
     * recognition request. Only present when {@link Activity#RESULT_OK} is returned in
     * an activity result. In a PendingIntent, the lack of this extra indicates failure.
     */
    public static final String EXTRA_RESULTS = "android.speech.extra.RESULTS";
    
    /**
     * Returns the broadcast intent to fire with
     * {@link Context#sendOrderedBroadcast(Intent, String, BroadcastReceiver, android.os.Handler, int, String, Bundle)}
     * to receive details from the package that implements voice search.
     * <p>
     * This is based on the value specified by the voice search {@link Activity} in
     * {@link #DETAILS_META_DATA}, and if this is not specified, will return null. Also if there
     * is no chosen default to resolve for {@link #ACTION_WEB_SEARCH}, this will return null.
     * <p>
     * If an intent is returned and is fired, a {@link Bundle} of extras will be returned to the
     * provided result receiver, and should ideally contain values for
     * {@link #EXTRA_LANGUAGE_PREFERENCE} and {@link #EXTRA_SUPPORTED_LANGUAGES}.
     * <p>
     * (Whether these are actually provided is up to the particular implementation. It is
     * recommended that {@link Activity}s implementing {@link #ACTION_WEB_SEARCH} provide this
     * information, but it is not required.)
     * 
     * @param context a context object
     * @return the broadcast intent to fire or null if not available
     */
    public static final Intent getVoiceDetailsIntent(Context context) {
        Intent voiceSearchIntent = new Intent(ACTION_WEB_SEARCH);
        ResolveInfo ri = context.getPackageManager().resolveActivity(
                voiceSearchIntent, PackageManager.GET_META_DATA);
        if (ri == null || ri.activityInfo == null || ri.activityInfo.metaData == null) return null;
        
        String className = ri.activityInfo.metaData.getString(DETAILS_META_DATA);
        if (className == null) return null;
        
        Intent detailsIntent = new Intent(ACTION_GET_LANGUAGE_DETAILS);
        detailsIntent.setComponent(new ComponentName(ri.activityInfo.packageName, className));
        return detailsIntent;
    }
    
    /**
     * Meta-data name under which an {@link Activity} implementing {@link #ACTION_WEB_SEARCH} can
     * use to expose the class name of a {@link BroadcastReceiver} which can respond to request for
     * more information, from any of the broadcast intents specified in this class.
     * <p>
     * Broadcast intents can be directed to the class name specified in the meta-data by creating
     * an {@link Intent}, setting the component with
     * {@link Intent#setComponent(android.content.ComponentName)}, and using
     * {@link Context#sendOrderedBroadcast(Intent, String, BroadcastReceiver, android.os.Handler, int, String, android.os.Bundle)}
     * with another {@link BroadcastReceiver} which can receive the results.
     * <p>
     * The {@link #getVoiceDetailsIntent(Context)} method is provided as a convenience to create
     * a broadcast intent based on the value of this meta-data, if available.
     * <p>
     * This is optional and not all {@link Activity}s which implement {@link #ACTION_WEB_SEARCH}
     * are required to implement this. Thus retrieving this meta-data may be null.
     */
    public static final String DETAILS_META_DATA = "android.speech.DETAILS";
    
    /**
     * A broadcast intent which can be fired to the {@link BroadcastReceiver} component specified
     * in the meta-data defined in the {@link #DETAILS_META_DATA} meta-data of an
     * {@link Activity} satisfying {@link #ACTION_WEB_SEARCH}.
     * <p>
     * When fired with
     * {@link Context#sendOrderedBroadcast(Intent, String, BroadcastReceiver, android.os.Handler, int, String, android.os.Bundle)},
     * a {@link Bundle} of extras will be returned to the provided result receiver, and should
     * ideally contain values for {@link #EXTRA_LANGUAGE_PREFERENCE} and
     * {@link #EXTRA_SUPPORTED_LANGUAGES}.
     * <p>
     * (Whether these are actually provided is up to the particular implementation. It is
     * recommended that {@link Activity}s implementing {@link #ACTION_WEB_SEARCH} provide this
     * information, but it is not required.)
     */
    public static final String ACTION_GET_LANGUAGE_DETAILS =
            "android.speech.action.GET_LANGUAGE_DETAILS";
    
    /**
     * Specify this boolean extra in a broadcast of {@link #ACTION_GET_LANGUAGE_DETAILS} to
     * indicate that only the current language preference is needed in the response. This
     * avoids any additional computation if all you need is {@link #EXTRA_LANGUAGE_PREFERENCE}
     * in the response.
     */
    public static final String EXTRA_ONLY_RETURN_LANGUAGE_PREFERENCE =
            "android.speech.extra.ONLY_RETURN_LANGUAGE_PREFERENCE";
    
    /**
     * The key to the extra in the {@link Bundle} returned by {@link #ACTION_GET_LANGUAGE_DETAILS}
     * which is a {@link String} that represents the current language preference this user has
     * specified - a locale string like "en-US".
     */
    public static final String EXTRA_LANGUAGE_PREFERENCE =
            "android.speech.extra.LANGUAGE_PREFERENCE";
    
    /**
     * The key to the extra in the {@link Bundle} returned by {@link #ACTION_GET_LANGUAGE_DETAILS}
     * which is an {@link ArrayList} of {@link String}s that represents the languages supported by
     * this implementation of voice recognition - a list of strings like "en-US", "cmn-Hans-CN",
     * etc.
     */
    public static final String EXTRA_SUPPORTED_LANGUAGES =
            "android.speech.extra.SUPPORTED_LANGUAGES";
}

Other Android examples (source code examples)

Here is a short list of links related to this Android RecognizerIntent.java source code file:

... this post is sponsored by my books ...

#1 New Release!

FP Best Seller

 

new blog posts

 

Copyright 1998-2021 Alvin Alexander, alvinalexander.com
All Rights Reserved.

A percentage of advertising revenue from
pages under the /java/jwarehouse URI on this website is
paid back to open source projects.