SynthesisRequest.java revision 71e0b4807797c602e7fc787d00d27c4f9c92a507
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 request for speech synthesis given to a TTS engine for processing. 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 * Alternatively, the engine can provide all the audio at once, by using 26 * {@link #completeAudioAvailable}. 27 * 28 * @hide Pending approval 29 */ 30public abstract class SynthesisRequest { 31 32 private final String mText; 33 private String mLanguage; 34 private String mCountry; 35 private String mVariant; 36 private int mSpeechRate; 37 private int mPitch; 38 39 public SynthesisRequest(String text) { 40 mText = text; 41 } 42 43 /** 44 * Sets the locale for the request. 45 */ 46 void setLanguage(String language, String country, String variant) { 47 mLanguage = language; 48 mCountry = country; 49 mVariant = variant; 50 } 51 52 /** 53 * Sets the speech rate. 54 */ 55 void setSpeechRate(int speechRate) { 56 mSpeechRate = speechRate; 57 } 58 59 /** 60 * Sets the pitch. 61 */ 62 void setPitch(int pitch) { 63 mPitch = pitch; 64 } 65 66 /** 67 * Gets the text which should be synthesized. 68 */ 69 public String getText() { 70 return mText; 71 } 72 73 /** 74 * Gets the ISO 3-letter language code for the language to use. 75 */ 76 public String getLanguage() { 77 return mLanguage; 78 } 79 80 /** 81 * Gets the ISO 3-letter country code for the language to use. 82 */ 83 public String getCountry() { 84 return mCountry; 85 } 86 87 /** 88 * Gets the language variant to use. 89 */ 90 public String getVariant() { 91 return mVariant; 92 } 93 94 /** 95 * Gets the speech rate to use. {@link TextToSpeech.Engine#DEFAULT_RATE} (100) 96 * is the normal rate. 97 */ 98 public int getSpeechRate() { 99 return mSpeechRate; 100 } 101 102 /** 103 * Gets the pitch to use. {@link TextToSpeech.Engine#DEFAULT_PITCH} (100) 104 * is the normal pitch. 105 */ 106 public int getPitch() { 107 return mPitch; 108 } 109 110 /** 111 * Gets the maximum number of bytes that the TTS engine can pass in a single call of 112 * {@link #audioAvailable}. This does not apply to {@link #completeAudioAvailable}. 113 */ 114 public abstract int getMaxBufferSize(); 115 116 /** 117 * Aborts the speech request. 118 * 119 * Can be called from multiple threads. 120 */ 121 abstract void stop(); 122 123 /** 124 * The service should call this when it starts to synthesize audio for this 125 * request. 126 * 127 * This method should only be called on the synthesis thread, 128 * while in {@link TextToSpeechService#onSynthesizeText}. 129 * 130 * @param sampleRateInHz Sample rate in HZ of the generated audio. 131 * @param audioFormat Audio format of the generated audio. Must be one of 132 * the ENCODING_ constants defined in {@link android.media.AudioFormat}. 133 * @param channelCount The number of channels. Must be {@code 1} or {@code 2}. 134 * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}. 135 */ 136 public abstract int start(int sampleRateInHz, int audioFormat, int channelCount); 137 138 /** 139 * The service should call this method when synthesized audio is ready for consumption. 140 * 141 * This method should only be called on the synthesis thread, 142 * while in {@link TextToSpeechService#onSynthesizeText}. 143 * 144 * @param buffer The generated audio data. This method will not hold on to {@code buffer}, 145 * so the caller is free to modify it after this method returns. 146 * @param offset The offset into {@code buffer} where the audio data starts. 147 * @param length The number of bytes of audio data in {@code buffer}. This must be 148 * less than or equal to the return value of {@link #getMaxBufferSize}. 149 * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}. 150 */ 151 public abstract int audioAvailable(byte[] buffer, int offset, int length); 152 153 /** 154 * The service should call this method when all the synthesized audio for a request has 155 * been passed to {@link #audioAvailable}. 156 * 157 * This method should only be called on the synthesis thread, 158 * while in {@link TextToSpeechService#onSynthesizeText}. 159 * 160 * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}. 161 */ 162 public abstract int done(); 163 164 /** 165 * The service can call this method instead of using {@link #start}, {@link #audioAvailable} 166 * and {@link #done} if all the audio data is available in a single buffer. 167 * 168 * @param sampleRateInHz Sample rate in HZ of the generated audio. 169 * @param audioFormat Audio format of the generated audio. Must be one of 170 * the ENCODING_ constants defined in {@link android.media.AudioFormat}. 171 * @param channelCount The number of channels. Must be {@code 1} or {@code 2}. 172 * @param buffer The generated audio data. This method will not hold on to {@code buffer}, 173 * so the caller is free to modify it after this method returns. 174 * @param offset The offset into {@code buffer} where the audio data starts. 175 * @param length The number of bytes of audio data in {@code buffer}. 176 * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}. 177 */ 178 public abstract int completeAudioAvailable(int sampleRateInHz, int audioFormat, 179 int channelCount, byte[] buffer, int offset, int length); 180}