Class SPXSpeechConfiguration

  • Article

Declaration

@class SPXSpeechConfiguration : NSObject;

Description

Defines configurations for speech or intent recognition.

Methods

initWithSubscription:region:error:

Initializes an instance of a speech configuration with the specified subscription key and service region.

Added in version 1.6.0.

- (instancetype _Nullable)initWithSubscription:(NSString * _Nonnull)subscriptionKey
    region:(NSString * _Nonnull)region error:(NSError * _Nullable * _Nullable)outError

Parameters

  • subscriptionKey - the subscription key to be used.
  • region - the region name (see the region page).
  • outError - error information.

Returns

a speech configuration instance.

initWithSubscription:region:

Initializes an instance of a speech configuration with the specified subscription key and service region.

- (instancetype _Nullable)initWithSubscription:(NSString * _Nonnull)subscriptionKey
    region:(NSString * _Nonnull)region

Parameters

  • subscriptionKey - the subscription key to be used.
  • region - the region name (see the region page).

Returns

a speech configuration instance.

initWithAuthorizationToken:region:

Initializes an instance of a speech configuration with specified authorization token and service region.

Note: The caller needs to ensure that the authorization token is valid. Before the authorization token expires, the caller needs to refresh it by calling this setter with a new valid token. As configuration values are copied when creating a new recognizer, the new token value will not apply to recognizers that have already been created. For recognizers that have been created before, you need to set authorization token of the corresponding recognizer to refresh the token. Otherwise, the recognizers will encounter errors during recognition.

- (instancetype _Nullable)initWithAuthorizationToken:(NSString * _Nonnull)authToken
    region:(NSString * _Nonnull)region

Parameters

  • authToken - the authorization token.
  • region - the region name (see the region page).

Returns

a speech configuration instance.

initWithAuthorizationToken:region:error:

Initializes an instance of a speech configuration with specified authorization token and service region.

Note: The caller needs to ensure that the authorization token is valid. Before the authorization token expires, the caller needs to refresh it by calling this setter with a new valid token. As configuration values are copied when creating a new recognizer, the new token value will not apply to recognizers that have already been created. For recognizers that have been created before, you need to set authorization token of the corresponding recognizer to refresh the token. Otherwise, the recognizers will encounter errors during recognition.

Added in version 1.6.0.

- (instancetype _Nullable)initWithAuthorizationToken:(NSString * _Nonnull)authToken
    region:(NSString * _Nonnull)region error:(NSError * _Nullable * _Nullable)outError

Parameters

  • authToken - the authorization token.
  • region - the region name (see the region page).
  • outError - error information.

Returns

a speech configuration instance.

initWithEndpoint:subscription:

Initializes an instance of the speech configuration with specified endpoint and subscription key. This method is intended only for users who use a non-standard service endpoint or parameters.

Note: The query parameters specified in the endpoint URI are not changed, even if they are set by any other APIs. Whether a specific query parameter is supported or not, depends on the endpoint and scenario. For example, if the recognition language is defined in the URI as query parameter "language=de-DE", and is also set to "en-US" via property speechRecognitionLanguage in SPXSpeechConfiguration, the language setting in the URI takes precedence, and the effective language is "de-DE". The example only applies when the endpoint and scenario combination supports language as a query parameter. Only the parameters that are not specified in the endpoint URI can be set by other APIs.

Note: To use an authorization token, use initWithEndpoint, and then set the authorizationToken property on the created SPXSpeechConfiguration instance.

- (instancetype _Nullable)initWithEndpoint:(NSString * _Nonnull)endpointUri
    subscription:(NSString * _Nonnull)subscriptionKey

Parameters

  • endpointUri - The service endpoint to connect to.
  • subscriptionKey - the subscription key.

Returns

A speech configuration instance.

initWithEndpoint:subscription:error:

Initializes an instance of the speech configuration with specified endpoint and subscription key. This method is intended only for users who use a non-standard service endpoint or parameters.

Note: The query parameters specified in the endpoint URI are not changed, even if they are set by any other APIs. For example, if the recognition language is defined in the URI as query parameter "language=de-DE", and is also set to "en-US" via property speechRecognitionLanguage in SPXSpeechConfiguration, the language setting in the URI takes precedence, and the effective language is "de-DE". Only the parameters that are not specified in the endpoint URI can be set by other APIs.

Note: To use an authorization token, use initWithEndpoint, and then set the authorizationToken property on the created SPXSpeechConfiguration instance.

Added in version 1.5.0.

- (instancetype _Nullable)initWithEndpoint:(NSString * _Nonnull)endpointUri
    subscription:(NSString * _Nonnull)subscriptionKey
    error:(NSError * _Nullable * _Nullable)outError

Parameters

  • endpointUri - The service endpoint to connect to.
  • subscriptionKey - the subscription key.
  • outError - error information.

Returns

A speech configuration instance.

initWithEndpoint:

Initializes an instance of the speech configuration with specified endpoint. This method is intended only for users who use a non-standard service endpoint or parameters.

Note: The query parameters specified in the endpoint URI are not changed, even if they are set by any other APIs. For example, if the recognition language is defined in the uri as query parameter "language=de-DE", and is also set to "en-US" via property speechRecognitionLanguage in SpeechConfiguration, the language setting in the uri takes precedence, and the effective language is "de-DE". Only the parameters that are not specified in the endpoint URL can be set by other APIs.

Note: if the endpoint requires a subscription key for authentication, please use initWithEndpoint:subscription: to pass the subscription key as parameter. To use an authorization token, use this method to create a SpeechConfig instance, and then set the authorizationToken property on the created SPXSpeechConfiguration instance.

Added in version 1.6.0.

- (instancetype _Nullable)initWithEndpoint:(NSString * _Nonnull)endpointUri

Parameters

  • endpointUri - The service endpoint to connect to.

Returns

A speech configuration instance.

initWithEndpoint:error:

Initializes an instance of the speech configuration with specified endpoint. This method is intended only for users who use a non-standard service endpoint or parameters.

Note: The query parameters specified in the endpoint URI are not changed, even if they are set by any other APIs. For example, if the recognition language is defined in the uri as query parameter "language=de-DE", and is also set to "en-US" via property speechRecognitionLanguage in SpeechConfiguration, the language setting in the uri takes precedence, and the effective language is "de-DE". Only the parameters that are not specified in the endpoint URL can be set by other APIs.

Note: if the endpoint requires a subscription key for authentication, please use initWithEndpoint:subscription: to pass the subscription key as parameter. To use an authorization token, use this method to create a SpeechConfig instance, and then set the authorizationToken property on the created SPXSpeechConfiguration instance.

Added in version 1.6.0.

- (instancetype _Nullable)initWithEndpoint:(NSString * _Nonnull)endpointUri
    error:(NSError * _Nullable * _Nullable)outError

Parameters

  • endpointUri - The service endpoint to connect to.
  • outError - error information.

Returns

A speech configuration instance.

initWithHost:subscription:

Initializes an instance of the speech configuration with specified host and subscription key. This method is intended only for users who use a non-default service host. Standard resource path will be assumed. For services with a non-standard resource path or no path at all, use initWithEndpoint instead.

Note: Query parameters are not allowed in the host URI and must be set by other APIs.

Note: To use an authorization token, use initWithHost, and then set the authorizationToken property on the created SPXSpeechConfiguration instance.

Added in version 1.8.0.

- (instancetype _Nullable)initWithHost:(NSString * _Nonnull)hostUri
    subscription:(NSString * _Nonnull)subscriptionKey

Parameters

  • hostUri - The service host to connect to. Format is "protocol://host:port" where ":port" is optional.
  • subscriptionKey - The subscription key.

Returns

A speech configuration instance.

initWithHost:subscription:error:

Initializes an instance of the speech configuration with specified host and subscription key. This method is intended only for users who use a non-default service host. Standard resource path will be assumed. For services with a non-standard resource path or no path at all, use initWithEndpoint instead.

Note: Query parameters are not allowed in the host URI and must be set by other APIs.

Note: To use an authorization token, use initWithHost, and then set the authorizationToken property on the created SPXSpeechConfiguration instance.

Added in version 1.8.0.

- (instancetype _Nullable)initWithHost:(NSString * _Nonnull)hostUri
    subscription:(NSString * _Nonnull)subscriptionKey
    error:(NSError * _Nullable * _Nullable)outError

Parameters

  • hostUri - The service host to connect to. Format is "protocol://host:port" where ":port" is optional.
  • subscriptionKey - The subscription key.
  • outError - Error information.

Returns

A speech configuration instance.

initWithHost:

Initializes an instance of the speech configuration with specified host. This method is intended only for users who use a non-default service host. Standard resource path will be assumed. For services with a non-standard resource path or no path at all, use initWithEndpoint instead.

Note: Query parameters are not allowed in the host URI and must be set by other APIs.

Note: If the host requires a subscription key for authentication, use initWithHost:subscription: to pass the subscription key as parameter. To use an authorization token, use this method to create a SpeechConfig instance, and then set the authorizationToken property on the created SPXSpeechConfiguration instance.

Added in version 1.8.0.

- (instancetype _Nullable)initWithHost:(NSString * _Nonnull)hostUri

Parameters

  • hostUri - The service host to connect to. Format is "protocol://host:port" where ":port" is optional.

Returns

A speech configuration instance.

initWithHost:error:

Initializes an instance of the speech configuration with specified host. This method is intended only for users who use a non-default service host. Standard resource path will be assumed. For services with a non-standard resource path or no path at all, use initWithEndpoint instead.

Note: Query parameters are not allowed in the host URI and must be set by other APIs.

Note: If the host requires a subscription key for authentication, use initWithHost:subscription: to pass the subscription key as parameter. To use an authorization token, use this method to create a SpeechConfig instance, and then set the authorizationToken property on the created SPXSpeechConfiguration instance.

Added in version 1.8.0.

- (instancetype _Nullable)initWithHost:(NSString * _Nonnull)hostUri
    error:(NSError * _Nullable * _Nullable)outError

Parameters

  • hostUri - The service host to connect to. Format is "protocol://host:port" where ":port" is optional.
  • outError - Error information.

Returns

A speech configuration instance.

setProxyUsingHost:Port:UserName:Password:

Sets proxy configuration

Added in version 1.1.0

Note: Proxy functionality is not available on iOS and macOS. This function will have no effect on these platforms.

- (void)setProxyUsingHost:(NSString * _Nonnull)proxyHostName Port:(uint32_t)proxyPort
    UserName:(NSString * _Nullable)proxyUserName Password:(NSString * _Nullable)proxyPassword

Parameters

  • proxyHostName - the host name of the proxy server, without the protocol scheme (http://)
  • proxyPort - the port number of the proxy server.
  • proxyUserName - the user name of the proxy server. Use empty string if no user name is needed.
  • proxyPassword - the password of the proxy server. Use empty string if no user password is needed.

setProxyUsingHost:Port:UserName:Password:error:

Sets proxy configuration

Note: Proxy functionality is not available on iOS and macOS. This function will have no effect on these platforms.

Added in version 1.6.0

- (BOOL)setProxyUsingHost:(NSString * _Nonnull)proxyHostName Port:(uint32_t)proxyPort
    UserName:(NSString * _Nullable)proxyUserName Password:(NSString * _Nullable)proxyPassword
    error:(NSError * _Nullable * _Nullable)outError

Parameters

  • proxyHostName - the host name of the proxy server, without the protocol scheme (http://)
  • proxyPort - the port number of the proxy server.
  • proxyUserName - the user name of the proxy server. Use empty string if no user name is needed.
  • proxyPassword - the password of the proxy server. Use empty string if no user password is needed.
  • outError - error information.

getPropertyByName:

Returns the property value. If the name is not available, it returns an empty string.

- (NSString * _Nullable)getPropertyByName:(NSString * _Nonnull)name

Parameters

  • name - property name.

Returns

value of the property.

setPropertyTo:byName:

Sets the property value by name.

- (void)setPropertyTo:(NSString * _Nonnull)value byName:(NSString * _Nonnull)name

Parameters

  • name - property name.
  • value - value of the property.

getPropertyById:

Returns the property value. If the specified id is not available, it returns an empty string.

- (NSString * _Nullable)getPropertyById:(SPXPropertyId)propertyId

Parameters

  • propertyId - property id.

Returns

value of the property.

setPropertyTo:byId:

Sets the property value by property id.

- (void)setPropertyTo:(NSString * _Nonnull)value byId:(SPXPropertyId)propertyId

Parameters

  • propertyId - property id.
  • value - value of the property.

setServicePropertyTo:byName:usingChannel:

Sets a property value that will be passed to service using the specified channel.

Added in version 1.5.0.

- (void)setServicePropertyTo:(NSString * _Nonnull)value byName:(NSString * _Nonnull)name
    usingChannel:(SPXServicePropertyChannel)channel

Parameters

  • name - the property name.
  • value - the property value.
  • channel - the channel used to pass the specified property to service.

setProfanityOptionTo:

Sets profanity option.

Added in version 1.5.0.

- (void)setProfanityOptionTo:(SPXSpeechConfigProfanityOption)profanity

Parameters

  • profanity - Profanity option value.

setSpeechSynthesisOutputFormat:

Set the speech synthesis audio output format (e.g. Riff16Khz16BitMonoPcm).

Added in version 1.7.0

- (void)setSpeechSynthesisOutputFormat:(SPXSpeechSynthesisOutputFormat)formatId

Parameters

  • formatId - output format id.

enableAudioLogging

Enables audio logging in service. Audio and content logs are stored either in Microsoft-owned storage, or in your own storage account linked to your Cognitive Services subscription (Bring Your Own Storage (BYOS) enabled Speech resource). Added in version 1.5.0.

- (void)enableAudioLogging

requestWordLevelTimestamps

Includes word-level timestamps in response result.

Added in version 1.5.0.

- (void)requestWordLevelTimestamps

enableDictation

Enables dictation mode. Only supported in speech continuous recognition.

Added in version 1.5.0.

- (void)enableDictation

Properties

speechRecognitionLanguage

@property (readwrite, copy, nonatomic) NSString * _Nullable speechRecognitionLanguage;

Tag of speech recognition language, using BCP-47 format.

endpointId

@property (readwrite, copy, nonatomic) NSString * _Nullable endpointId;

Endpoint ID of a customized speech model that is used for speech recognition, or a custom voice model for speech synthesis.

outputFormat

@property (assign, readwrite, nonatomic, unsafe_unretained) SPXOutputFormat outputFormat;

The output format of the speech recognition result.

Note: This output format is for speech recognition result, use SPXSpeechConfiguration.speechSynthesisOutputFormat and SPXSpeechConfiguration.setSpeechSynthesisOutputFormat to get/set the systhesized audio output format.

authorizationToken

@property (readwrite, copy, nonatomic) NSString * _Nullable authorizationToken;

Authorization token.

Note: The caller needs to ensure that the authorization token is valid. Before the authorization token expires, the caller needs to refresh it by calling this setter with a new valid token. As configuration values are copied when creating a new recognizer, the new token value will not apply to recognizers that have already been created. For recognizers that have been created before, you need to set authorization token of the corresponding recognizer to refresh the token. Otherwise, the recognizers will encounter errors during recognition.

subscriptionKey

@property (readonly, copy, nonatomic) NSString * _Nullable subscriptionKey;

Subscription key.

region

@property (readonly, copy, nonatomic) NSString * _Nullable region;

Region name (see the region page).

speechSynthesisLanguage

@property (readwrite, copy, nonatomic) NSString * _Nullable speechSynthesisLanguage;

Speech synthesis language.

Added in version 1.7.0

speechSynthesisVoiceName

@property (readwrite, copy, nonatomic) NSString * _Nullable speechSynthesisVoiceName;

Speech synthesis voice.

Added in version 1.7.0

speechSynthesisOutputFormat

@property (readonly, copy, nonatomic) NSString * _Nullable speechSynthesisOutputFormat;

Speech synthesis optput format.

Added in version 1.7.0