KIOSDecodingGraph Class Reference
| Inherits from | NSObject |
|---|---|
| Declared in | KIOSDecodingGraph.h |
Overview
KIOSDecodingGraph class manages decoding graphs in the filesystem.
You can use various KIOSDecodingGraph class methods to create decoding graphs, which will be saved in the filesystem on the device. Typically, you will provide a list of phrases to createDecodingGraphFromPhrases:forRecognizer:andSaveWithName: method, which will then create a decoding graph in the filesystem. Later on, you can refer to the decoding graph by its name.
Contextual graphs are a composition of multiple decoding graphs in a single graph. If your application needs to create multiple decoding graphs often it may be more efficient to create a single contextual decoding graph instead and then switch the contexts as needed. A good example would be a digital book; each page presented to the user would be a single context and you would switch contexts as the app (or user) changes the pages. The trade-offs with contextual graphs is that creating one with N contexts will be much faster than creation of a single graph N times; the downside is that there will be a small penalty (delay of 100ms or so) when switching between different contexts.
Note: When dynamically creating decoding graphs, any words that do not have
phonetic representation in the lexicon (ASRBUNDLE/lang/lexicon.txt) will be
assigned one algorithmically. For English langauge algorithmic representation is
imperfect, thus you should aim to use KIOSAlternative prounciations to augment the lexicon with
words that are likely to be encountered in your app. For example, if your app is dealing with ASR of names
you would augment the lexicon with additional names and their proper pronunciation before releasing your app.
Note: For the large number of phrases (e.g. several thousands), creating of decoding graph can take several seconds on older devices.
Note: Decoding graphs can also be created ahead of time and packaged with the application.
Regular Decoding Graphs
+ createDecodingGraphFromPhrases:forRecognizer:usingAlternativePronunciations:andTask:andSaveWithName:
Create decoding graph from an array of phrases and save it in the filesystem for later use. Decoding graphs can be referenced by their name by various methods in the framework.
+ (BOOL)createDecodingGraphFromPhrases:(nonnull NSArray *)phrases forRecognizer:(nonnull KIOSRecognizer *)recognizer usingAlternativePronunciations:(nullable NSArray<KIOSAlternativePronunciation*> *)alternativePronunciations andTask:(KIOSSpeakingTask)task andSaveWithName:(nonnull NSString *)decodingGraphNameParameters
phrases |
an NSArray of NSString objects that specify phrases recognizer should listen for. These phrases are used to create a language model, from which decoding graph is created. Text in phrases should be normalized (e.g. numbers and dates should be represented by words, so ‘two hundred dollars’ not $200). |
|---|---|
recognizer |
KIOSRecognizer object that will be used to perform recognition with this decoding graph. Note that decoding graph is persisted in the filesystem and can be resued at the later time with a different KIOSRecognizer object as long as such recognizer uses the same ASR bundle as the KIOSRecognizer object used to create the decoding graph. |
alternativePronunciations |
an NSArray of AlternativePronunciations specifying alternative pronunciations that should be used when building this decoding graph. |
task |
KIOSSpeakingTask specyfing the type of task this decoding graph corresponds to. Calling this method with KIOSSpeakingTaskDefault is equivalent to calling createDecodingGraphFromSentences:forRecognizer:andSaveWithName method. |
decodingGraphName |
a name of the custom decoding graph. All graph resources will be stored in a directy named DECODING_GRAPH_NAME-ASR_BUNDLE_NAME in Library/Application Support/KaldiIOS-decoding-graphs/ |
Return Value
TRUE on success, FALSE otherwise
Declared In
KIOSDecodingGraph.h
+ createDecodingGraphFromPhrases:forRecognizer:usingAlternativePronunciations:andTask:withSpokenNoiseProbability:andSaveWithName:
Create decoding graph from an array of phrases and save it in the filesystem for later use. Decoding graphs can be referenced by their name by various methods in the framework.
+ (BOOL)createDecodingGraphFromPhrases:(nonnull NSArray *)phrases forRecognizer:(nonnull KIOSRecognizer *)recognizer usingAlternativePronunciations:(nullable NSArray<KIOSAlternativePronunciation*> *)alternativePronunciations andTask:(KIOSSpeakingTask)task withSpokenNoiseProbability:(float)spokenNoiseProbability andSaveWithName:(nonnull NSString *)decodingGraphNameParameters
phrases |
an NSArray of NSString objects that specify phrases recognizer should listen for. These phrases are used to create a language model, from which decoding graph is created. Text in phrases should be normalized (e.g. numbers and dates should be represented by words, so ‘two hundred dollars’ not $200). |
|---|---|
recognizer |
KIOSRecognizer object that will be used to perform recognition with this decoding graph. Note that decoding graph is persisted in the filesystem and can be resued at the later time with a different KIOSRecognizer object as long as such recognizer uses the same ASR bundle as the KIOSRecognizer object used to create the decoding graph. |
alternativePronunciations |
an NSArray of AlternativePronunciations specifying alternative pronunciations that should be used when building this decoding graph. |
task |
KIOSSpeakingTask specyfing the type of task this decoding graph corresponds to. Calling this method with KIOSSpeakingTaskDefault is equivalent to calling createDecodingGraphFromSentences:forRecognizer:andSaveWithName method. |
spokenNoiseProbability |
a float value in the range 0.0 - 1.0. Default value is 0.5. Lower values will make <SPOKEN_NOISE> occur less frequently in the result, whereas higher values will make it more likely to occur in the result. |
decodingGraphName |
a name of the custom decoding graph. All graph resources will be stored in a directy named DECODING_GRAPH_NAME-ASR_BUNDLE_NAME in Library/Application Support/KaldiIOS-decoding-graphs/ |
Return Value
TRUE on success, FALSE otherwise
Declared In
KIOSDecodingGraph.h
Contextual Decoding Graphs
+ createContextualDecodingGraphFromPhrases:forRecognizer:usingAlternativePronunciations:andTask:andSaveWithName:
Create custom decoding graph from an array of arrays of phrases and save it in the filesystem for later use. Each top-level array represents a context, which you can then set using prepareForListening before calling startListening.
+ (BOOL)createContextualDecodingGraphFromPhrases:(nonnull NSArray<NSArray*> *)contextualPhrases forRecognizer:(nonnull KIOSRecognizer *)recognizer usingAlternativePronunciations:(nullable NSArray<KIOSAlternativePronunciation*> *)alternativePronunciations andTask:(KIOSSpeakingTask)task andSaveWithName:(nonnull NSString *)decodingGraphNameParameters
contextualPhrases |
an NSArray of NSArrays with NSString objects that specify phrases grouped by specific context. These phrases are used to create a language model, from which decoding graph is created. Text in phrases should be normalized (e.g. numbers and dates should be represented by words, so ‘two hundred dollars’ not $200) |
|---|---|
recognizer |
KIOSRecognizer object that will be used to perform recognition with this decoding graph. Note that decoding graph is persisted in the filesystem and can be resued at the later time with a different KIOSRecognizer object as long as such recognizer uses the same ASR bundle as the KIOSRecognizer object used to create the decoding graph. |
alternativePronunciations |
an optional NSArray of AlternativePronunciations specifying alternative pronunciations that should be used when building this decoding graph. |
task |
KIOSSpeakingTask specyfing the type of task this decoding graph corresponds to. Calling this method with KIOSSpeakingTaskDefault is equivalent to calling createDecodingGraphFromPhrases:forRecognizer:andSaveWithName method. |
decodingGraphName |
a name of the custom decoding graph. All graph resources will be stored in a directy named DECODING_GRAPH_NAME-ASR_BUNDLE_NAME in Library/Application Support/KaldiIOS-decoding-graphs/ |
Return Value
TRUE on success, FALSE otherwise
Discussion
For example, you could build a decoding graph with the following contextualPhrases parameter: @[ @[ // contextId 0 @“This is a first phrase.”, @“This first phrase belongs to the first contextual group ], @[ // contextId 1 @"This is another phrase.”, @“This phrase belongs to the second contextual group ] ];
Custom decoding graphs can be referenced by their name by various methods in the framework.
Decoding graphs created with this method require call to prepareForListeningWithContextId
Declared In
KIOSDecodingGraph.h
+ createContextualDecodingGraphFromPhrases:forRecognizer:usingAlternativePronunciations:andTask:withSpokenNoiseProbability:andSaveWithName:
Create custom decoding graph from an array of arrays of phrases and save it in the filesystem for later use. Each top-level array represents a context, which you can then set using prepareForListening before calling startListening.
+ (BOOL)createContextualDecodingGraphFromPhrases:(nonnull NSArray<NSArray*> *)contextualPhrases forRecognizer:(nonnull KIOSRecognizer *)recognizer usingAlternativePronunciations:(nullable NSArray<KIOSAlternativePronunciation*> *)alternativePronunciations andTask:(KIOSSpeakingTask)task withSpokenNoiseProbability:(float)spokenNoiseProbability andSaveWithName:(nonnull NSString *)decodingGraphNameParameters
contextualPhrases |
an NSArray of NSArrays with NSString objects that specify phrases grouped by specific context. These phrases are used to create a language model, from which decoding graph is created. Text in phrases should be normalized (e.g. numbers and dates should be represented by words, so ‘two hundred dollars’ not $200) |
|---|---|
recognizer |
KIOSRecognizer object that will be used to perform recognition with this decoding graph. Note that decoding graph is persisted in the filesystem and can be resued at the later time with a different KIOSRecognizer object as long as such recognizer uses the same ASR bundle as the KIOSRecognizer object used to create the decoding graph. |
alternativePronunciations |
an optional NSArray of AlternativePronunciations specifying alternative pronunciations that should be used when building this decoding graph. |
task |
KIOSSpeakingTask specyfing the type of task this decoding graph corresponds to. Calling this method with KIOSSpeakingTaskDefault is equivalent to calling createDecodingGraphFromPhrases:forRecognizer:andSaveWithName method. |
spokenNoiseProbability |
a float value in the range 0.0 - 1.0. Default value is 0.5. Lower values will make <SPOKEN_NOISE> occur less frequently in the result, whereas higher values will make it more likely to occur in the result. |
decodingGraphName |
a name of the custom decoding graph. All graph resources will be stored in a directy named DECODING_GRAPH_NAME-ASR_BUNDLE_NAME in Library/Application Support/KaldiIOS-decoding-graphs/ |
Return Value
TRUE on success, FALSE otherwise
Discussion
For example, you could build a decoding graph with the following contextualPhrases parameter: @[ @[ // contextId 0 @“This is a first phrase.”, @“This first phrase belongs to the first contextual group ], @[ // contextId 1 @"This is another phrase.”, @“This phrase belongs to the second contextual group ] ];
Custom decoding graphs can be referenced by their name by various methods in the framework.
Decoding graphs created with this method require call to prepareForListeningWithContextId
Declared In
KIOSDecodingGraph.h
+ createDecodingGraphFromPhrases:withTriggerPhrase:forRecognizer:andSaveWithName:
Create decoding graph setup for trigger phrase, using an array of phrases and save it in the filesystem for later use. Decoding graphs can be referenced by their name by various methods in the framework.
+ (BOOL)createDecodingGraphFromPhrases:(nonnull NSArray *)phrases withTriggerPhrase:(nonnull NSString *)triggerPhrase forRecognizer:(nonnull KIOSRecognizer *)recognizer andSaveWithName:(nonnull NSString *)decodingGraphNameParameters
phrases |
an NSArray of NSString objects that specify phrases recognizer should listen for. These phrases are used to create a language model, from which decoding graph is created. Text in phrases should be normalized (e.g. numbers and dates should be represented by words, so ‘two hundred dollars’ not $200). |
|---|---|
triggerPhrase |
NSString object that defines trigger phrase which will be used when building this decoding graphs. When using graphs built with trigger phrase support, recognizer will not report any results until it recognizes the trigger phrase. If you are using trigger phrase graphs, you can also setup a [KIOSRecognizer |
recognizer |
KIOSRecognizer object that will be used to perform recognition with this decoding graph. Note that decoding graph is persisted in the filesystem and can be resued at the later time with a different KIOSRecognizer object as long as such recognizer uses the same ASR bundle as the KIOSRecognizer object used to create the decoding graph. |
decodingGraphName |
a name of the custom decoding graph. All graph resources will be stored in a directy named DECODING_GRAPH_NAME-ASR_BUNDLE_NAME in Library/Application Support/KaldiIOS-decoding-graphs/ |
Return Value
TRUE on success, FALSE otherwise
Declared In
KIOSDecodingGraph.h
Helper methods
+ validatePronunciation:forRecognizer:
Verify if pronunciation speciifed in the input string is composed of valid phones that are supported for the given recognizer. Returns TRUE if pronunciation is valid, FALSE otherwise.
+ (BOOL)validatePronunciation:(nonnull NSString *)pronunciation forRecognizer:(nonnull KIOSRecognizer *)recognizerParameters
pronunciation |
string that represents pronunciation of a word. For example @“k ae t” |
|---|---|
recognizer |
KIOSRecognizer object equivalent to the KIOSRecognizer object that was used to create the decoding graph. |
Return Value
Returns TRUE if pronunciation is valid, false otherwise
Declared In
KIOSDecodingGraph.h
+ decodingGraphWithNameExists:forRecognizer:
Returns TRUE if valid custom decoding graph with the given name exists in the filesystem.
+ (BOOL)decodingGraphWithNameExists:(nonnull NSString *)decodingGraphName forRecognizer:(nonnull KIOSRecognizer *)recognizerParameters
decodingGraphName |
name of the custom decoding graph |
|---|---|
recognizer |
KIOSRecognizer object equivalent to the KIOSRecognizer object that was used to create the decoding graph. |
Return Value
TRUE if decoding graph with such name exists, FALSE otherwise. This method will also check for existance of all the necessary files in the decoding graph directory.
Declared In
KIOSDecodingGraph.h
+ decodingGraphAtPathExists:
Returns TRUE if a valid decoding graph exists at the given absolute filepath.
+ (BOOL)decodingGraphAtPathExists:(nonnull NSString *)absolutePathToDecodingGraphDirectoryParameters
absolutePathToDecodingGraphDirectory |
absolute path to the decoding graph directory. |
|---|
Return Value
TRUE if decoding graph with such name exists, FALSE otherwise. This method will also check for existance of all the necessary files in the decoding graph directory.
Declared In
KIOSDecodingGraph.h
+ decodingGraphExistsAtPath:
Returns TRUE if a valid decoding graph exists at the given absolute filepath.
+ (BOOL)decodingGraphExistsAtPath:(nonnull NSString *)absolutePathToDecodingGraphDirectoryParameters
absolutePathToDecodingGraphDirectory |
absolute path to the decoding graph directory. |
|---|
Return Value
TRUE if decoding graph with such name exists, FALSE otherwise. This method will also check for existance of all the necessary files in the decoding graph directory.
Declared In
KIOSDecodingGraph.h
+ decodingGraphCreationDate:forRecognizer:
Returns date when custom decoding graph was created.
+ (nullable NSDate *)decodingGraphCreationDate:(nonnull NSString *)decodingGraphName forRecognizer:(nonnull KIOSRecognizer *)recognizerParameters
decodingGraphName |
name of the decoding graph |
|---|---|
recognizer |
KIOSRecognizer object equivalent to the KIOSRecognizer object that was used to create the decoding graph. |
Return Value
date when decoding graph was created and saved in the filesystem. nil if not available.
Declared In
KIOSDecodingGraph.h
+ getDecodingGraphDirURL:forRecognizer:
Returns NSURL object that specifies directory where decoding graph is stored.
+ (nullable NSURL *)getDecodingGraphDirURL:(nonnull NSString *)decodingGraphName forRecognizer:(nonnull KIOSRecognizer *)recognizerParameters
decodingGraphName |
name of the decoding graph |
|---|---|
recognizer |
KIOSRecognizer object equivalent to the KIOSRecognizer object that was used to create the decoding graph. |
Return Value
NSURL object where the decoding graph was or should have been stored.
Declared In
KIOSDecodingGraph.h