KIOSTextAligner Class Reference

Aligns recognized speech against a reference text using DP edit distance. More...

#include <KIOSTextAligner.h>

Instance Methods
(nullable instancetype)	- initWithReference:langCode:
	Designated initializer. Constructs an aligner bound to the given reference text and language code.
(nullable instancetype)	- initWithReference:recognizer:
	Convenience initializer that sources the language code from a recognizer instance.
(instancetype)	- NS_UNAVAILABLE
(KIOSAlignmentResult *)	- align:
	Align recognized text against the reference using default configuration.
(KIOSAlignmentResult *)	- align:config:
	Align recognized text against the reference with custom configuration.
(KIOSAlignmentResult *)	- incrementalAlign:
	Align recognized text incrementally, reusing DP state from the previous call.
(KIOSAlignmentResult *)	- incrementalAlign:config:
	Incremental align with custom configuration.
(void)	- reset
	Drop cached DP state. Call between utterances when using incremental alignment.

Class Methods
(instancetype)	+ NS_UNAVAILABLE

Properties
NSArray< NSString * > *	referenceTokens
	Normalized reference tokens, in order. Indices in alignment results refer to positions in this array.
NSString *	langCode
	Language code this aligner was constructed with.

Detailed Description

Aligns recognized speech against a reference text using DP edit distance.

Typical use is oral-reading scoring: a user reads a known passage, the ASR produces a hypothesis, and the aligner reports which reference words were read correctly, which were skipped, and how far the reader got. The same primitive supports word-error-rate reporting for batch ASR evaluation.

The reference text is normalized and tokenized once at construction and cached. Subsequent calls to - align: (KIOSTextAligner) and - incrementalAlign: (KIOSTextAligner) normalize their inputs using the same rules, so reference and recognized sides share a canonical form.

The language code passed at construction must match the ASR bundle that produced (or will produce) the recognized text — normalization differs subtly between languages (accent handling, & expansion, etc.) and a mismatch silently degrades accuracy.

Stateless vs. incremental

• - align: (KIOSTextAligner) recomputes alignment from scratch each call. Safe to call concurrently from multiple threads.
• - incrementalAlign: (KIOSTextAligner) caches DP rows from the previous call and reuses them up to the longest common prefix of consecutive recognized inputs, amortizing cost across a stream of partial ASR results. Not thread-safe. Call -- reset (KIOSTextAligner) between utterances.

Ownership

The receiver owns its native counterpart and releases it on dealloc.

Method Documentation

align:

- (KIOSAlignmentResult *) align:

(NSString *)

recognized

Align recognized text against the reference using default configuration.

Equivalent to calling - align:config: with a default-constructed KIOSAlignmentConfig. Stateless — safe to call concurrently with itself.

Parameters

recognized

Recognized text from the ASR engine.

Returns

Alignment result. Never nil.

align:config:

- (KIOSAlignmentResult *) align:		(NSString *)	recognized
config:		(nullable KIOSAlignmentConfig *)	config

Align recognized text against the reference with custom configuration.

Stateless — safe to call concurrently with itself.

Parameters

recognized	Recognized text from the ASR engine.
config	Alignment configuration. Pass nil to use defaults.

Returns

Alignment result. Never nil.

incrementalAlign:

- (KIOSAlignmentResult *) incrementalAlign:

(NSString *)

recognized

Align recognized text incrementally, reusing DP state from the previous call.

Intended for use in partial-result callbacks where the recognized text grows or changes slightly between calls. The aligner detects the longest common prefix between successive inputs and recomputes only the divergent tail.

Call -- reset when starting a new utterance to clear the cache.

Not thread-safe. Do not call concurrently from multiple threads, and do not interleave with -- align: if you depend on the cache surviving.

Parameters

recognized

Recognized text from the ASR engine.

Returns

Alignment result. Never nil.

incrementalAlign:config:

- (KIOSAlignmentResult *) incrementalAlign:		(NSString *)	recognized
config:		(nullable KIOSAlignmentConfig *)	config

Incremental align with custom configuration.

Changing cost values between successive calls invalidates the cache and forces a full recompute on the next call.

Parameters

recognized	Recognized text from the ASR engine.
config	Alignment configuration. Pass nil to use defaults.

Returns

Alignment result. Never nil.

initWithReference:langCode:

- (nullable instancetype) initWithReference:		(NSString *)	reference
langCode:		(NSString *)	NS_DESIGNATED_INITIALIZER

Designated initializer. Constructs an aligner bound to the given reference text and language code.

The reference is normalized and tokenized at construction; the cached token vector is available via referenceTokens.

Parameters

reference	Reference text to align against. Required.
langCode	ASR bundle language code, e.g. "en-us", "fr-fr", "de-de", "es-es". Required.

Returns

An initialized aligner, or nil if construction failed.

initWithReference:recognizer:

- (nullable instancetype) initWithReference:		(NSString *)	reference
recognizer:		(KIOSRecognizer *)	recognizer

Convenience initializer that sources the language code from a recognizer instance.

Equivalent to calling - initWithReference:langCode: with [recognizer asrBundleLang].

Parameters

reference	Reference text to align against. Required.
recognizer	Initialized recognizer whose ASR bundle defines the language code. Required.

Returns

An initialized aligner, or nil if construction failed.

---

The documentation for this class was generated from the following file:

• KeenASR/KIOSTextAligner.h