SynthesisCallback.java revision a24b50bee1aca19028477b235862bcd2c37135ed 
1/*
2 * Copyright (C) 2011 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5 * use this file except in compliance with the License. You may obtain a copy of
6 * 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, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations under
14 * the License.
15 */
16package android.speech.tts;
17
18import android.annotation.IntDef;
19import android.annotation.IntRange;
20import android.media.AudioFormat;
21import android.speech.tts.TextToSpeech;
22
23import java.lang.annotation.Retention;
24import java.lang.annotation.RetentionPolicy;
25
26/**
27 * A callback to return speech data synthesized by a text to speech engine.
28 *
29 * The engine can provide streaming audio by calling
30 * {@link #start}, then {@link #audioAvailable} until all audio has been provided, then finally
31 * {@link #done}.
32 *
33 * {@link #error} can be called at any stage in the synthesis process to
34 * indicate that an error has occurred, but if the call is made after a call
35 * to {@link #done}, it might be discarded.
36 *
37 * {@link #done} must be called at the end of synthesis, regardless of errors.
38 *
39 * All methods can be only called on the synthesis thread.
40 */
41public interface SynthesisCallback {
42
43     /** @hide */
44     @Retention(RetentionPolicy.SOURCE)
45     @IntDef({AudioFormat.ENCODING_PCM_8BIT, AudioFormat.ENCODING_PCM_16BIT,
46              AudioFormat.ENCODING_PCM_FLOAT})
47     public @interface SupportedAudioFormat {};
48
49    /**
50     * @return the maximum number of bytes that the TTS engine can pass in a single call of
51     *         {@link #audioAvailable}. Calls to {@link #audioAvailable} with data lengths
52     *         larger than this value will not succeed.
53     */
54    public int getMaxBufferSize();
55
56    // TODO: Replace reference to Android N to an API level when the API level for N is decided.
57    /**
58     * The service should call this when it starts to synthesize audio for this
59     * request.
60     *
61     * This method should only be called on the synthesis thread,
62     * while in {@link TextToSpeechService#onSynthesizeText}.
63     *
64     * @param sampleRateInHz Sample rate in HZ of the generated audio.
65     * @param audioFormat Audio format of the generated audio. Must be one of
66     *         {@link android.media.AudioFormat.ENCODING_PCM_8BIT} or
67     *         {@link android.media.AudioFormat.ENCODING_PCM_16BIT}. Or
68     *         {@link android.media.AudioFormat.ENCODING_PCM_FLOAT} when targetting Android N and
69     *         above.
70     * @param channelCount The number of channels. Must be {@code 1} or {@code 2}.
71     * @return {@link TextToSpeech#SUCCESS}, {@link TextToSpeech#ERROR} or
72     *          {@link TextToSpeech#STOPPED}.
73     */
74    public int start(int sampleRateInHz, @SupportedAudioFormat int audioFormat,
75                     @IntRange(from=1,to=2) int channelCount);
76
77    /**
78     * The service should call this method when synthesized audio is ready for consumption.
79     *
80     * This method should only be called on the synthesis thread,
81     * while in {@link TextToSpeechService#onSynthesizeText}.
82     *
83     * @param buffer The generated audio data. This method will not hold on to {@code buffer},
84     *         so the caller is free to modify it after this method returns.
85     * @param offset The offset into {@code buffer} where the audio data starts.
86     * @param length The number of bytes of audio data in {@code buffer}. This must be
87     *         less than or equal to the return value of {@link #getMaxBufferSize}.
88     * @return {@link TextToSpeech#SUCCESS}, {@link TextToSpeech#ERROR} or
89     *          {@link TextToSpeech#STOPPED}.
90     */
91    public int audioAvailable(byte[] buffer, int offset, int length);
92
93    /**
94     * The service should call this method when all the synthesized audio for a request has
95     * been passed to {@link #audioAvailable}.
96     *
97     * This method should only be called on the synthesis thread,
98     * while in {@link TextToSpeechService#onSynthesizeText}.
99     *
100     * This method has to be called if {@link #start} and/or {@link #error} was called.
101     *
102     * @return {@link TextToSpeech#SUCCESS}, {@link TextToSpeech#ERROR} or
103     *          {@link TextToSpeech#STOPPED}.
104     */
105    public int done();
106
107    /**
108     * The service should call this method if the speech synthesis fails.
109     *
110     * This method should only be called on the synthesis thread,
111     * while in {@link TextToSpeechService#onSynthesizeText}.
112     */
113    public void error();
114
115
116    /**
117     * The service should call this method if the speech synthesis fails.
118     *
119     * This method should only be called on the synthesis thread,
120     * while in {@link TextToSpeechService#onSynthesizeText}.
121     *
122     * @param errorCode Error code to pass to the client. One of the ERROR_ values from
123     *      {@link TextToSpeech}
124     */
125    public void error(@TextToSpeech.Error int errorCode);
126
127    /**
128     * Check if {@link #start} was called or not.
129     *
130     * This method should only be called on the synthesis thread,
131     * while in {@link TextToSpeechService#onSynthesizeText}.
132     *
133     * Useful for checking if a fallback from network request is possible.
134     */
135    public boolean hasStarted();
136
137    /**
138     * Check if {@link #done} was called or not.
139     *
140     * This method should only be called on the synthesis thread,
141     * while in {@link TextToSpeechService#onSynthesizeText}.
142     *
143     * Useful for checking if a fallback from network request is possible.
144     */
145    public boolean hasFinished();
146}
147