ToneGenerator.java revision 843ef36f7b96cc19ea7d2996b7c8661b41ec3452
1/* 2 * Copyright (C) 2008 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 */ 16 17package android.media; 18 19 20 21/** 22 * This class provides methods to play DTMF tones (ITU-T Recommendation Q.23), 23 * call supervisory tones (3GPP TS 22.001, CEPT) and proprietary tones (3GPP TS 31.111). 24 * Depending on call state and routing options, tones are mixed to the downlink audio 25 * or output to the speaker phone or headset. 26 * This API is not for generating tones over the uplink audio path. 27 */ 28public class ToneGenerator 29{ 30 31 /* Values for toneType parameter of ToneGenerator() constructor */ 32 /* 33 * List of all available tones: These constants must be kept consistant with 34 * the enum in ToneGenerator C++ class. */ 35 36 /** 37 * DTMF tone for key 0: 1336Hz, 941Hz, continuous</p> 38 * 39 * @see #ToneGenerator(int, int) 40 */ 41 public static final int TONE_DTMF_0 = 0; 42 /** 43 * DTMF tone for key 1: 1209Hz, 697Hz, continuous 44 * 45 * @see #ToneGenerator(int, int) 46 */ 47 public static final int TONE_DTMF_1 = 1; 48 /** 49 * DTMF tone for key 2: 1336Hz, 697Hz, continuous 50 * 51 * @see #ToneGenerator(int, int) 52 */ 53 public static final int TONE_DTMF_2 = 2; 54 /** 55 * DTMF tone for key 3: 1477Hz, 697Hz, continuous 56 * 57 * @see #ToneGenerator(int, int) 58 */ 59 public static final int TONE_DTMF_3 = 3; 60 /** 61 * DTMF tone for key 4: 1209Hz, 770Hz, continuous 62 * 63 * @see #ToneGenerator(int, int) 64 */ 65 public static final int TONE_DTMF_4 = 4; 66 /** 67 * DTMF tone for key 5: 1336Hz, 770Hz, continuous 68 * 69 * @see #ToneGenerator(int, int) 70 */ 71 public static final int TONE_DTMF_5 = 5; 72 /** 73 * DTMF tone for key 6: 1477Hz, 770Hz, continuous 74 * 75 * @see #ToneGenerator(int, int) 76 */ 77 public static final int TONE_DTMF_6 = 6; 78 /** 79 * DTMF tone for key 7: 1209Hz, 852Hz, continuous 80 * 81 * @see #ToneGenerator(int, int) 82 */ 83 public static final int TONE_DTMF_7 = 7; 84 /** 85 * DTMF tone for key 8: 1336Hz, 852Hz, continuous 86 * 87 * @see #ToneGenerator(int, int) 88 */ 89 public static final int TONE_DTMF_8 = 8; 90 /** 91 * DTMF tone for key 9: 1477Hz, 852Hz, continuous 92 * 93 * @see #ToneGenerator(int, int) 94 */ 95 public static final int TONE_DTMF_9 = 9; 96 /** 97 * DTMF tone for key *: 1209Hz, 941Hz, continuous 98 * 99 * @see #ToneGenerator(int, int) 100 */ 101 public static final int TONE_DTMF_S = 10; 102 /** 103 * DTMF tone for key #: 1477Hz, 941Hz, continuous 104 * 105 * @see #ToneGenerator(int, int) 106 */ 107 public static final int TONE_DTMF_P = 11; 108 /** 109 * DTMF tone for key A: 1633Hz, 697Hz, continuous 110 * 111 * @see #ToneGenerator(int, int) 112 */ 113 public static final int TONE_DTMF_A = 12; 114 /** 115 * DTMF tone for key B: 1633Hz, 770Hz, continuous 116 * 117 * @see #ToneGenerator(int, int) 118 */ 119 public static final int TONE_DTMF_B = 13; 120 /** 121 * DTMF tone for key C: 1633Hz, 852Hz, continuous 122 * 123 * @see #ToneGenerator(int, int) 124 */ 125 public static final int TONE_DTMF_C = 14; 126 /** 127 * DTMF tone for key D: 1633Hz, 941Hz, continuous 128 * 129 * @see #ToneGenerator(int, int) 130 */ 131 public static final int TONE_DTMF_D = 15; 132 /** 133 * Call supervisory tone, Dial tone: 134 * CEPT: 425Hz, continuous 135 * ANSI (IS-95): 350Hz+440Hz, continuous 136 * JAPAN: 400Hz, continuous 137 * 138 * @see #ToneGenerator(int, int) 139 */ 140 public static final int TONE_SUP_DIAL = 16; 141 /** 142 * Call supervisory tone, Busy: 143 * CEPT: 425Hz, 500ms ON, 500ms OFF... 144 * ANSI (IS-95): 480Hz+620Hz, 500ms ON, 500ms OFF... 145 * JAPAN: 400Hz, 500ms ON, 500ms OFF... 146 * 147 * @see #ToneGenerator(int, int) 148 */ 149 public static final int TONE_SUP_BUSY = 17; 150 /** 151 * Call supervisory tone, Congestion: 152 * CEPT, JAPAN: 425Hz, 200ms ON, 200ms OFF... 153 * ANSI (IS-95): 480Hz+620Hz, 250ms ON, 250ms OFF... 154 * 155 * @see #ToneGenerator(int, int) 156 */ 157 public static final int TONE_SUP_CONGESTION = 18; 158 /** 159 * Call supervisory tone, Radio path acknowlegment : 160 * CEPT, ANSI: 425Hz, 200ms ON 161 * JAPAN: 400Hz, 1s ON, 2s OFF... 162 * 163 * @see #ToneGenerator(int, int) 164 */ 165 public static final int TONE_SUP_RADIO_ACK = 19; 166 /** 167 * Call supervisory tone, Radio path not available: 425Hz, 200ms ON, 200 OFF 3 bursts 168 * 169 * @see #ToneGenerator(int, int) 170 */ 171 public static final int TONE_SUP_RADIO_NOTAVAIL = 20; 172 /** 173 * Call supervisory tone, Error/Special info: 950Hz+1400Hz+1800Hz, 330ms ON, 1s OFF... 174 * 175 * @see #ToneGenerator(int, int) 176 */ 177 public static final int TONE_SUP_ERROR = 21; 178 /** 179 * Call supervisory tone, Call Waiting: 180 * CEPT, JAPAN: 425Hz, 200ms ON, 600ms OFF, 200ms ON, 3s OFF... 181 * ANSI (IS-95): 440 Hz, 300 ms ON, 9.7 s OFF, (100 ms ON, 100 ms OFF, 100 ms ON, 9.7s OFF ...) 182 * 183 * @see #ToneGenerator(int, int) 184 */ 185 public static final int TONE_SUP_CALL_WAITING = 22; 186 /** 187 * Call supervisory tone, Ring Tone: 188 * CEPT, JAPAN: 425Hz, 1s ON, 4s OFF... 189 * ANSI (IS-95): 440Hz + 480Hz, 2s ON, 4s OFF... 190 * 191 * @see #ToneGenerator(int, int) 192 */ 193 public static final int TONE_SUP_RINGTONE = 23; 194 /** 195 * Proprietary tone, general beep: 400Hz+1200Hz, 35ms ON 196 * 197 * @see #ToneGenerator(int, int) 198 */ 199 public static final int TONE_PROP_BEEP = 24; 200 /** 201 * Proprietary tone, positive acknowlegement: 1200Hz, 100ms ON, 100ms OFF 2 bursts 202 * 203 * @see #ToneGenerator(int, int) 204 */ 205 public static final int TONE_PROP_ACK = 25; 206 /** 207 * Proprietary tone, negative acknowlegement: 300Hz+400Hz+500Hz, 400ms ON 208 * 209 * @see #ToneGenerator(int, int) 210 */ 211 public static final int TONE_PROP_NACK = 26; 212 /** 213 * Proprietary tone, prompt tone: 400Hz+1200Hz, 200ms ON 214 * 215 * @see #ToneGenerator(int, int) 216 */ 217 public static final int TONE_PROP_PROMPT = 27; 218 /** 219 * Proprietary tone, general double beep: twice 400Hz+1200Hz, 35ms ON, 200ms OFF, 35ms ON 220 * 221 * @see #ToneGenerator(int, int) 222 */ 223 public static final int TONE_PROP_BEEP2 = 28; 224 /** 225 * Call supervisory tone (IS-95), intercept tone: alternating 440 Hz and 620 Hz tones, each on for 250 ms 226 * 227 * @see #ToneGenerator(int, int) 228 */ 229 public static final int TONE_SUP_INTERCEPT = 29; 230 /** 231 * Call supervisory tone (IS-95), abbreviated intercept: intercept tone limited to 4 seconds 232 * 233 * @see #ToneGenerator(int, int) 234 */ 235 public static final int TONE_SUP_INTERCEPT_ABBREV = 30; 236 /** 237 * Call supervisory tone (IS-95), abbreviated congestion: congestion tone limited to 4 seconds 238 * 239 * @see #ToneGenerator(int, int) 240 */ 241 public static final int TONE_SUP_CONGESTION_ABBREV = 31; 242 /** 243 * Call supervisory tone (IS-95), confirm tone: a 350 Hz tone added to a 440 Hz tone repeated 3 times in a 100 ms on, 100 ms off cycle 244 * 245 * @see #ToneGenerator(int, int) 246 */ 247 public static final int TONE_SUP_CONFIRM = 32; 248 /** 249 * Call supervisory tone (IS-95), pip tone: four bursts of 480 Hz tone (0.1 s on, 0.1 s off). 250 * 251 * @see #ToneGenerator(int, int) 252 */ 253 public static final int TONE_SUP_PIP = 33; 254 255 256 /** Maximum volume, for use with {@link #ToneGenerator(int,int)} */ 257 public static final int MAX_VOLUME = AudioSystem.MAX_VOLUME; 258 /** Minimum volume setting, for use with {@link #ToneGenerator(int,int)} */ 259 public static final int MIN_VOLUME = AudioSystem.MIN_VOLUME; 260 261 262 /** 263 * ToneGenerator class contructor specifying output stream type and volume. 264 * 265 * @param streamType The streame type used for tone playback (e.g. STREAM_MUSIC). 266 * @param volume The volume of the tone, given in percentage of maximum volume (from 0-100). 267 * 268 */ 269 public ToneGenerator(int streamType, int volume) { 270 native_setup(streamType, volume); 271 } 272 273 /** 274 * This method starts the playback of a tone of the specified type. 275 * only one tone can play at a time: if a tone is playing while this method is called, 276 * this tone is stopped and replaced by the one requested. 277 * @param toneType The type of tone generate chosen from the following list: 278 * <ul> 279 * <li>{@link #TONE_DTMF_0} 280 * <li>{@link #TONE_DTMF_1} 281 * <li>{@link #TONE_DTMF_2} 282 * <li>{@link #TONE_DTMF_3} 283 * <li>{@link #TONE_DTMF_4} 284 * <li>{@link #TONE_DTMF_5} 285 * <li>{@link #TONE_DTMF_6} 286 * <li>{@link #TONE_DTMF_7} 287 * <li>{@link #TONE_DTMF_8} 288 * <li>{@link #TONE_DTMF_9} 289 * <li>{@link #TONE_DTMF_A} 290 * <li>{@link #TONE_DTMF_B} 291 * <li>{@link #TONE_DTMF_C} 292 * <li>{@link #TONE_DTMF_D} 293 * <li>{@link #TONE_SUP_DIAL} 294 * <li>{@link #TONE_SUP_BUSY} 295 * <li>{@link #TONE_SUP_CONGESTION} 296 * <li>{@link #TONE_SUP_RADIO_ACK} 297 * <li>{@link #TONE_SUP_RADIO_NOTAVAIL} 298 * <li>{@link #TONE_SUP_ERROR} 299 * <li>{@link #TONE_SUP_CALL_WAITING} 300 * <li>{@link #TONE_SUP_RINGTONE} 301 * <li>{@link #TONE_PROP_BEEP} 302 * <li>{@link #TONE_PROP_ACK} 303 * <li>{@link #TONE_PROP_NACK} 304 * <li>{@link #TONE_PROP_PROMPT} 305 * <li>{@link #TONE_PROP_BEEP2} 306 * <li>{@link #TONE_SUP_INTERCEPT} 307 * <li>{@link #TONE_SUP_INTERCEPT_ABBREV} 308 * <li>{@link #TONE_SUP_CONGESTION_ABBREV} 309 * <li>{@link #TONE_SUP_CONFIRM} 310 * <li>{@link #TONE_SUP_PIP} 311 * </ul> 312 * @see #ToneGenerator(int, int) 313 */ 314 public native boolean startTone(int toneType); 315 316 /** 317 * This method stops the tone currently playing playback. 318 * @see #ToneGenerator(int, int) 319 */ 320 public native void stopTone(); 321 322 /** 323 * Releases resources associated with this ToneGenerator object. It is good 324 * practice to call this method when you're done using the ToneGenerator. 325 */ 326 public native void release(); 327 328 private native final void native_setup(int streamType, int volume); 329 330 private native final void native_finalize(); 331 protected void finalize() { native_finalize(); } 332 333 private int mNativeContext; // accessed by native methods 334 335 336} 337