|
| 1 | +// |
| 2 | +// SKRecognizer.h |
| 3 | +// SpeechKit |
| 4 | +// |
| 5 | +// Copyright 2010, Nuance Communications Inc. All rights reserved. |
| 6 | +// |
| 7 | +// Nuance Communications, Inc. provides this document without representation |
| 8 | +// or warranty of any kind. The information in this document is subject to |
| 9 | +// change without notice and does not represent a commitment by Nuance |
| 10 | +// Communications, Inc. The software and/or databases described in this |
| 11 | +// document are furnished under a license agreement and may be used or |
| 12 | +// copied only in accordance with the terms of such license agreement. |
| 13 | +// Without limiting the rights under copyright reserved herein, and except |
| 14 | +// as permitted by such license agreement, no part of this document may be |
| 15 | +// reproduced or transmitted in any form or by any means, including, without |
| 16 | +// limitation, electronic, mechanical, photocopying, recording, or otherwise, |
| 17 | +// or transferred to information storage and retrieval systems, without the |
| 18 | +// prior written permission of Nuance Communications, Inc. |
| 19 | +// |
| 20 | +// Nuance, the Nuance logo, Nuance Recognizer, and Nuance Vocalizer are |
| 21 | +// trademarks or registered trademarks of Nuance Communications, Inc. or its |
| 22 | +// affiliates in the United States and/or other countries. All other |
| 23 | +// trademarks referenced herein are the property of their respective owners. |
| 24 | +// |
| 25 | + |
| 26 | +#import <Foundation/Foundation.h> |
| 27 | +#import <SpeechKit/SKRecognition.h> |
| 28 | + |
| 29 | + |
| 30 | +/* |
| 31 | + Recognition Types |
| 32 | + These strings are some of the possible values for the type parameter of |
| 33 | + initWithType:detection:language:delegate:. |
| 34 | +*/ |
| 35 | + |
| 36 | +/*! |
| 37 | + @abstract Search optimized recognition. |
| 38 | + */ |
| 39 | +extern NSString * const SKSearchRecognizerType; |
| 40 | + |
| 41 | +/*! |
| 42 | + @abstract Dictation optimized recognition. |
| 43 | + */ |
| 44 | +extern NSString * const SKDictationRecognizerType; |
| 45 | + |
| 46 | +/*! |
| 47 | + @abstract Type for recognizer end-of-speech detection model. |
| 48 | + */ |
| 49 | +typedef NSUInteger SKEndOfSpeechDetection; |
| 50 | + |
| 51 | +/*! |
| 52 | + @enum End-of-Speech Detection Models |
| 53 | + @abstract These constants define the various end-of-speech detection models |
| 54 | + for the detection parameter of initWithType:detection:language:delegate:. |
| 55 | + @constant SKNoEndOfSpeechDetection Do not detect the end of speech. |
| 56 | + @constant SKShortEndOfSpeechDetection Detect the end of a short phrase with |
| 57 | + no pauses. Because this model does not tolerate much silence once speech |
| 58 | + has started, it detects the end of speech more quickly. |
| 59 | + @constant SKLongEndOfSpeechDetection Detect the end of a longer phrase, |
| 60 | + sentence or sentences that may have brief pauses. Because this model |
| 61 | + tolerates longer (but still brief) intervals of silence in the middle of |
| 62 | + speech, it is less likely to wrongly detect the end of speech prematurely but |
| 63 | + also takes longer to detect the end of speech when the speaker is actually |
| 64 | + finished. |
| 65 | + */ |
| 66 | +enum { |
| 67 | + SKNoEndOfSpeechDetection = 1, |
| 68 | + SKShortEndOfSpeechDetection = 2, |
| 69 | + SKLongEndOfSpeechDetection = 3, |
| 70 | +}; |
| 71 | + |
| 72 | + |
| 73 | +@protocol SKRecognizerDelegate; |
| 74 | + |
| 75 | + |
| 76 | +/*! |
| 77 | + @discussion The SKRecognizer class manages the entire recognition process |
| 78 | + including audio recording and server communication. SKRecognizer is designed |
| 79 | + to carry out a single recognition so after receiving the response the class |
| 80 | + should be released. Subsequent recognitions should each be generated by |
| 81 | + instantiating a new SKRecognizer instance. |
| 82 | + */ |
| 83 | +@interface SKRecognizer : NSObject |
| 84 | + |
| 85 | +/*! |
| 86 | + @abstract The average power of the most recent audio during recording. |
| 87 | + */ |
| 88 | +@property(nonatomic,readonly) float audioLevel; |
| 89 | + |
| 90 | +/*! |
| 91 | + @abstract Returns an initialized recognizer and begins the recognition process. |
| 92 | + |
| 93 | + @param type The recognition type. This allows the server to better anticipate |
| 94 | + the type of phrases the user is likely to say as well as selecting an |
| 95 | + appropriate vocabulary of words that the user might say and therefor has an |
| 96 | + impact on recognition accuracy. This type is an NSString and should be specified |
| 97 | + using one of the predefined constants as described in "Recognition Types" unless |
| 98 | + otherwise specified. |
| 99 | + @param detection The end of speech detection model used to automatically |
| 100 | + determine that speech has stopped. Choose this value from |
| 101 | + "End-Of-Speech Detection Models" to reflect the amount of allowable silence |
| 102 | + within an utterance. This detector is a second way that recording may be stopped, |
| 103 | + in addition to calling stopRecording on this object in response to a user action. |
| 104 | + @param language This is language spoken by the user and is expressed as an ISO 639 |
| 105 | + language code, followed by an underscore "_", followed by the ISO 3166-1 country |
| 106 | + code. For example, an English speaker from the United States would be |
| 107 | + expressed as "en_US". A complete list of supported language tags can be found |
| 108 | + at http://dragonmobile.nuancemobiledeveloper.com/public/index.php?task=faq . |
| 109 | + @param delegate The receiver for recognition responses. The delegate must |
| 110 | + implement the SKRecognizerDelegate protocol and will receive a message when the |
| 111 | + recognition process has completed. |
| 112 | + @result A recognizer object corresponding to the recognition request. |
| 113 | + */ |
| 114 | +- (id)initWithType:(NSString *)type detection:(SKEndOfSpeechDetection)detection language:(NSString *)language delegate:(id <SKRecognizerDelegate>)delegate; |
| 115 | + |
| 116 | +/*! |
| 117 | + @abstract Stops recording and streaming audio to the speech server. |
| 118 | + |
| 119 | + @discussion This method is used to stop recording audio and continue with the |
| 120 | + recognition process. This method must be used when the end of speech detection |
| 121 | + is disabled and may be used with a end-of-speech detection model in order to |
| 122 | + allow a user to manually end a recording before the end-of-speech detctor has |
| 123 | + activated. |
| 124 | + */ |
| 125 | +- (void)stopRecording; |
| 126 | + |
| 127 | +/*! |
| 128 | + @abstract Cancels the recognition request. |
| 129 | + |
| 130 | + @discussion This method will terminate the recognition request, stopping any |
| 131 | + ongoing recording and terminating the recognition process. This will result |
| 132 | + in the delegate receiving an error message via the |
| 133 | + recognizer:didFinishWithError:suggestion method unless a recognition result |
| 134 | + has been or is already being sent to the delegate. |
| 135 | + */ |
| 136 | +- (void)cancel; |
| 137 | + |
| 138 | +@end |
| 139 | + |
| 140 | + |
| 141 | +/*! |
| 142 | + @discussion The SKRecognizerDelegate protocol defines the messages sent to a |
| 143 | + delegate of the SKRecognizer class. These delegate methods indicate the flow |
| 144 | + of the recognition process. The receiver will be notified when the recording |
| 145 | + has ended and when the recognition process is finished. |
| 146 | + */ |
| 147 | +@protocol SKRecognizerDelegate <NSObject> |
| 148 | + |
| 149 | +@optional |
| 150 | +/*! |
| 151 | + @abstract Sent when the recognizer starts recording audio. |
| 152 | + |
| 153 | + @param recognizer The recognizer sending the message. |
| 154 | + */ |
| 155 | +- (void)recognizerDidBeginRecording:(SKRecognizer *)recognizer; |
| 156 | + |
| 157 | +/*! |
| 158 | + @abstract Sent when the recognizer stops recording audio. |
| 159 | + |
| 160 | + @param recognizer The recognizer sending the message. |
| 161 | + */ |
| 162 | +- (void)recognizerDidFinishRecording:(SKRecognizer *)recognizer; |
| 163 | + |
| 164 | +@required |
| 165 | +/*! |
| 166 | + @abstract Sent when the recognition process completes successfully. |
| 167 | + |
| 168 | + @param recognizer The recognizer sending the message. |
| 169 | + @param results The SKRecognition object containing the recognition results. |
| 170 | + |
| 171 | + @discussion This method is only called when the recognition process completes |
| 172 | + successfully. The results object contains an array of possible results, with |
| 173 | + the best result at index 0 or an empty array if no error occurred but no |
| 174 | + speech was detected. |
| 175 | + */ |
| 176 | +- (void)recognizer:(SKRecognizer *)recognizer didFinishWithResults:(SKRecognition *)results; |
| 177 | + |
| 178 | +/*! |
| 179 | + @abstract Sent when the recognition process completes with an error. |
| 180 | + |
| 181 | + @param recognizer The recognizer sending the message. |
| 182 | + @param error The recognition error. Possible numeric values for the |
| 183 | + SKSpeechErrorDomain are listed in SpeechKitError.h and a text description is |
| 184 | + available via the localizedDescription method. |
| 185 | + @param suggestion This is a suggestion to the user about how he or she can |
| 186 | + improve recognition performance and is based on the audio received. Examples |
| 187 | + include moving to a less noisy location if the environment is extremely noisy, or |
| 188 | + waiting a bit longer to start speaking if the beeginning of the recording seems |
| 189 | + truncated. Results are often still present and may still be of useful quality. |
| 190 | + |
| 191 | + @discussion This method is called when the recognition process results in an |
| 192 | + error due to any number of circumstances. The audio system may fail to |
| 193 | + initialize, the server connection may be disrupted or a parameter specified |
| 194 | + during initialization, such as language or authentication information was invalid. |
| 195 | + */ |
| 196 | +- (void)recognizer:(SKRecognizer *)recognizer didFinishWithError:(NSError *)error suggestion:(NSString *)suggestion; |
| 197 | + |
| 198 | +@end |
0 commit comments