1/*
2 * Copyright (C) 2010 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16package android.speech;
17
18import android.content.Intent;
19import android.os.Bundle;
20
21/**
22 * Used for receiving notifications from the SpeechRecognizer when the
23 * recognition related events occur. All the callbacks are executed on the
24 * Application main thread.
25 */
26public interface RecognitionListener {
27    /**
28     * Called when the endpointer is ready for the user to start speaking.
29     *
30     * @param params parameters set by the recognition service. Reserved for future use.
31     */
32    void onReadyForSpeech(Bundle params);
33
34    /**
35     * The user has started to speak.
36     */
37    void onBeginningOfSpeech();
38
39    /**
40     * The sound level in the audio stream has changed. There is no guarantee that this method will
41     * be called.
42     *
43     * @param rmsdB the new RMS dB value
44     */
45    void onRmsChanged(float rmsdB);
46
47    /**
48     * More sound has been received. The purpose of this function is to allow giving feedback to the
49     * user regarding the captured audio. There is no guarantee that this method will be called.
50     *
51     * @param buffer a buffer containing a sequence of big-endian 16-bit integers representing a
52     *        single channel audio stream. The sample rate is implementation dependent.
53     */
54    void onBufferReceived(byte[] buffer);
55
56    /**
57     * Called after the user stops speaking.
58     */
59    void onEndOfSpeech();
60
61    /**
62     * A network or recognition error occurred.
63     *
64     * @param error code is defined in {@link SpeechRecognizer}
65     */
66    void onError(int error);
67
68    /**
69     * Called when recognition results are ready.
70     *
71     * @param results the recognition results. To retrieve the results in {@code
72     *        ArrayList<String>} format use {@link Bundle#getStringArrayList(String)} with
73     *        {@link SpeechRecognizer#RESULTS_RECOGNITION} as a parameter. A float array of
74     *        confidence values might also be given in {@link SpeechRecognizer#CONFIDENCE_SCORES}.
75     */
76    void onResults(Bundle results);
77
78    /**
79     * Called when partial recognition results are available. The callback might be called at any
80     * time between {@link #onBeginningOfSpeech()} and {@link #onResults(Bundle)} when partial
81     * results are ready. This method may be called zero, one or multiple times for each call to
82     * {@link SpeechRecognizer#startListening(Intent)}, depending on the speech recognition
83     * service implementation.  To request partial results, use
84     * {@link RecognizerIntent#EXTRA_PARTIAL_RESULTS}
85     *
86     * @param partialResults the returned results. To retrieve the results in
87     *        ArrayList<String> format use {@link Bundle#getStringArrayList(String)} with
88     *        {@link SpeechRecognizer#RESULTS_RECOGNITION} as a parameter
89     */
90    void onPartialResults(Bundle partialResults);
91
92    /**
93     * Reserved for adding future events.
94     *
95     * @param eventType the type of the occurred event
96     * @param params a Bundle containing the passed parameters
97     */
98    void onEvent(int eventType, Bundle params);
99}
100