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
18/**
19 * A callback to return speech data synthesized by a text to speech engine.
20 *
21 * The engine can provide streaming audio by calling
22 * {@link #start}, then {@link #audioAvailable} until all audio has been provided, then finally
23 * {@link #done}.
24 *
25 *
26 * {@link #error} can be called at any stage in the synthesis process to
27 * indicate that an error has occurred, but if the call is made after a call
28 * to {@link #done}, it might be discarded.
29 */
30public interface SynthesisCallback {
31    /**
32     * @return the maximum number of bytes that the TTS engine can pass in a single call of
33     *         {@link #audioAvailable}. Calls to {@link #audioAvailable} with data lengths
34     *         larger than this value will not succeed.
35     */
36    public int getMaxBufferSize();
37
38    /**
39     * The service should call this when it starts to synthesize audio for this
40     * request.
41     *
42     * This method should only be called on the synthesis thread,
43     * while in {@link TextToSpeechService#onSynthesizeText}.
44     *
45     * @param sampleRateInHz Sample rate in HZ of the generated audio.
46     * @param audioFormat Audio format of the generated audio. Must be one of
47     *         the ENCODING_ constants defined in {@link android.media.AudioFormat}.
48     * @param channelCount The number of channels. Must be {@code 1} or {@code 2}.
49     * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}.
50     */
51    public int start(int sampleRateInHz, int audioFormat, int channelCount);
52
53    /**
54     * The service should call this method when synthesized audio is ready for consumption.
55     *
56     * This method should only be called on the synthesis thread,
57     * while in {@link TextToSpeechService#onSynthesizeText}.
58     *
59     * @param buffer The generated audio data. This method will not hold on to {@code buffer},
60     *         so the caller is free to modify it after this method returns.
61     * @param offset The offset into {@code buffer} where the audio data starts.
62     * @param length The number of bytes of audio data in {@code buffer}. This must be
63     *         less than or equal to the return value of {@link #getMaxBufferSize}.
64     * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}.
65     */
66    public int audioAvailable(byte[] buffer, int offset, int length);
67
68    /**
69     * The service should call this method when all the synthesized audio for a request has
70     * been passed to {@link #audioAvailable}.
71     *
72     * This method should only be called on the synthesis thread,
73     * while in {@link TextToSpeechService#onSynthesizeText}.
74     *
75     * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}.
76     */
77    public int done();
78
79    /**
80     * The service should call this method if the speech synthesis fails.
81     *
82     * This method should only be called on the synthesis thread,
83     * while in {@link TextToSpeechService#onSynthesizeText}.
84     */
85    public void error();
86
87}