AWSTranscribeStreaming

Objective-C

@interface AWSTranscribeStreaming

Swift

class AWSTranscribeStreaming

Operations and objects for transcribing streaming speech to text.

For backend setup and instructions on configuring policies, please see https://docs.aws.amazon.com/transcribe/latest/dg/streaming.html

This SDK currently only supports streaming via WebSockets, which is described here https://docs.aws.amazon.com/transcribe/latest/dg/websocket.html

How to Use

See the AWSTranscribeStreamingSwiftTests.testStreamingExample() integration test for an example of the “happy path” usage of this SDK. The general steps for usage are:

Configure the AWSServiceConfiguration, including setting a credentials provider for signing WebSocket requests
Create a TranscribeStreaming client with +[AWSTranscribeStreaming registerTranscribeStreamingWithConfiguration:forKey:], or use the default
Create a AWSTranscribeStreamingStartStreamTranscriptionRequest and set its properties to allow transcription of your audio stream
Set up an AWSTranscribeStreamingClientDelegate to receive callbacks for connection status changes and transcription events
Call AWSTranscribeStreaming.setDelegate(:callbackQueue:) to register your delegate with the client. NOTE We do not recommend using the main queue as your callback queue, since doing so could impact your app’s UI performance.
Call AWSTranscribeStreaming.startTranscriptionWSS() with the configured request
Wait for your delegate’s connectionStatusCallback to be invoked with a status of .connected. At this point, the transcribe client is ready to receive audio data
Chunk your audio data and send it to AWS Transcribe using the AWSTranscribeStreaming.send() method
As you send data, your delegate will be receiving transcription events in the receiveEventCallback, which you can decode and use in your app.
When you reach the end of your audio data, call AWSTranscribeStreaming.sendEndFrame() to signal the end of processing. NOTE: We recommend waiting 2-3 seconds past the end of your last detected audio data before sending the end frame.
Wait for your final transcription events to be received, as indicated by a transcription event with the isPartial flag set to 0.
Call AWSTranscribeStreaming.endTranscription() to close the web socket and gracefully shut down the connection to the service.

configuration
The service configuration used to instantiate this service client.

Warning
Once the client is instantiated, do not modify the configuration object. It may cause unspecified behaviors.
Declaration
Objective-C

@property (nonatomic, strong, readonly) AWSServiceConfiguration *configuration


                    
                    
                    +defaultTranscribeStreaming

Returns the singleton service client. If the singleton object does not exist, the SDK instantiates the default service client with defaultServiceConfiguration from [AWSServiceManager defaultServiceManager]. The reference to this object is maintained by the SDK, and you do not need to retain it manually.

For example, set the default service configuration in - application:didFinishLaunchingWithOptions:

Swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
   let credentialProvider = AWSCognitoCredentialsProvider(regionType: .USEast1, identityPoolId: "YourIdentityPoolId")
   let configuration = AWSServiceConfiguration(region: .USEast1, credentialsProvider: credentialProvider)
   AWSServiceManager.default().defaultServiceConfiguration = configuration

   return true

}

Objective-C

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
     AWSCognitoCredentialsProvider *credentialsProvider = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1
                                                                                                     identityPoolId:@"YourIdentityPoolId"];
     AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSEast1
                                                                          credentialsProvider:credentialsProvider];
     [AWSServiceManager defaultServiceManager].defaultServiceConfiguration = configuration;

     return YES;
 }

Then call the following to get the default service client:

Swift

let TranscribeStreaming = AWSTranscribeStreaming.default()

Objective-C

AWSTranscribeStreaming *TranscribeStreaming = [AWSTranscribeStreaming defaultTranscribeStreaming];

Declaration

Objective-C

+ (nonnull instancetype)defaultTranscribeStreaming;

Swift

class func `default`() -> Self

Return Value

The default service client.


                    
                    
                    +registerTranscribeStreamingWithConfiguration:forKey:

Creates a service client with the given service configuration and registers it for the key.

For example, set the default service configuration in - application:didFinishLaunchingWithOptions:

Swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
   let credentialProvider = AWSCognitoCredentialsProvider(regionType: .USEast1, identityPoolId: "YourIdentityPoolId")
   let configuration = AWSServiceConfiguration(region: .USWest2, credentialsProvider: credentialProvider)
   AWSTranscribeStreaming.register(with: configuration!, forKey: "USWest2TranscribeStreaming")

   return true

}

Objective-C

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    AWSCognitoCredentialsProvider *credentialsProvider = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1
                                                                                                    identityPoolId:@"YourIdentityPoolId"];
    AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSWest2
                                                                         credentialsProvider:credentialsProvider];

    [AWSTranscribeStreaming registerTranscribeStreamingWithConfiguration:configuration forKey:@"USWest2TranscribeStreaming"];

    return YES;
}

Then call the following to get the service client:

Swift

let TranscribeStreaming = AWSTranscribeStreaming(forKey: "USWest2TranscribeStreaming")

Objective-C

AWSTranscribeStreaming *TranscribeStreaming = [AWSTranscribeStreaming TranscribeStreamingForKey:@"USWest2TranscribeStreaming"];

Warning

After calling this method, do not modify the configuration object. It may cause unspecified behaviors.

Declaration

Objective-C

+ (void)registerTranscribeStreamingWithConfiguration:(id)configuration
                                              forKey:(nonnull NSString *)key;

Swift

class func register(withConfiguration configuration: Any!, forKey key: String)

Parameters

`configuration`	A service configuration object.
`key`	A string to identify the service client.


                    
                    
                    +registerTranscribeStreamingWithConfiguration:forKey:webSocketProvider:

Creates a service client with the given service configuration and registers it for the key.

For example, set the default service configuration in - application:didFinishLaunchingWithOptions:

Swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
   let credentialProvider = AWSCognitoCredentialsProvider(regionType: .USEast1, identityPoolId: "YourIdentityPoolId")
   let configuration = AWSServiceConfiguration(region: .USWest2, credentialsProvider: credentialProvider)
   let webSocketProvider = MyCustomNativeWebSocketProvider()
   AWSTranscribeStreaming.register(with: configuration!, forKey: "USWest2TranscribeStreaming", webSocketProvider: webSocketProvider)

   return true

}

Objective-C

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    AWSCognitoCredentialsProvider *credentialsProvider = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1
                                                                                                    identityPoolId:@"YourIdentityPoolId"];
    AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSWest2
                                                                         credentialsProvider:credentialsProvider];
    MyCustomNativeWebSocketProvider *webSocketProvider =  [[MyCustomNativeWebSocketProvider alloc] init;

    [AWSTranscribeStreaming registerTranscribeStreamingWithConfiguration:configuration forKey:@"USWest2TranscribeStreaming" webSocketProvider:webSocketProvider];

    return YES;
}

Then call the following to get the service client:

Swift

let TranscribeStreaming = AWSTranscribeStreaming(forKey: "USWest2TranscribeStreaming")

Objective-C

AWSTranscribeStreaming *TranscribeStreaming = [AWSTranscribeStreaming TranscribeStreamingForKey:@"USWest2TranscribeStreaming"];

Warning

After calling this method, do not modify the configuration object. It may cause unspecified behaviors.

Declaration

Objective-C

+ (void)
    registerTranscribeStreamingWithConfiguration:(id)configuration
                                          forKey:(nonnull NSString *)key
                               webSocketProvider:
                                   (nonnull id<
                                       AWSTranscribeStreamingWebSocketProvider>)
                                       webSocketProvider;

Swift

class func register(withConfiguration configuration: Any!, forKey key: String, webSocketProvider: AWSTranscribeStreamingWebSocketProvider)

Parameters

`configuration`	A service configuration object.
`key`	A string to identify the service client.
`webSocketProvider`	the web socket provider you would like to use


                    
                    
                    +TranscribeStreamingForKey:

Retrieves the service client associated with the key. You need to call + registerTranscribeStreamingWithConfiguration:forKey: before invoking this method.

For example, set the default service configuration in - application:didFinishLaunchingWithOptions:

Swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
   let credentialProvider = AWSCognitoCredentialsProvider(regionType: .USEast1, identityPoolId: "YourIdentityPoolId")
   let configuration = AWSServiceConfiguration(region: .USWest2, credentialsProvider: credentialProvider)
   AWSTranscribeStreaming.register(with: configuration!, forKey: "USWest2TranscribeStreaming")

   return true

}

Objective-C

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    AWSCognitoCredentialsProvider *credentialsProvider = [[AWSCognitoCredentialsProvider alloc] initWithRegionType:AWSRegionUSEast1
                                                                                                    identityPoolId:@"YourIdentityPoolId"];
    AWSServiceConfiguration *configuration = [[AWSServiceConfiguration alloc] initWithRegion:AWSRegionUSWest2
                                                                         credentialsProvider:credentialsProvider];

    [AWSTranscribeStreaming registerTranscribeStreamingWithConfiguration:configuration forKey:@"USWest2TranscribeStreaming"];

    return YES;
}

Then call the following to get the service client:

Swift

let TranscribeStreaming = AWSTranscribeStreaming(forKey: "USWest2TranscribeStreaming")

Objective-C

AWSTranscribeStreaming *TranscribeStreaming = [AWSTranscribeStreaming TranscribeStreamingForKey:@"USWest2TranscribeStreaming"];

Declaration

Objective-C

+ (nonnull instancetype)TranscribeStreamingForKey:(nonnull NSString *)key;

Swift

convenience init(forKey key: String)

Parameters

key

A string to identify the service client.

Return Value

An instance of the service client.


                    
                    
                    +removeTranscribeStreamingForKey:

Removes the service client associated with the key and release it.

Warning

Before calling this method, make sure no method is running on this client.

Declaration

Objective-C

+ (void)removeTranscribeStreamingForKey:(nonnull NSString *)key;

Swift

class func remove(forKey key: String)

Parameters

key

A string to identify the service client.

TranscribeStreaming WSS support


                    
                    
                    -startTranscriptionWSS:

Prepares a websocket to handle the transcription job described by request. This method prepares the websocket and initiates opening the socket, but the web socket will not be ready for handling audio data until the delegate receives a AWSTranscribeStreamingClientConnectionStatusConnected status on the -[AWSTranscribeStreamingClientDelegate connectionStatusDidChange:withError:] callback.

Apps should set a delegate before calling this method so that they may be notified when the web socket is open and ready to begin receiving data.

The process of opening a socket involves crafting a presigned URL according to the rules at https://docs.aws.amazon.com/transcribe/latest/dg/websocket.html. The presigned URL requires credentials, which eventually makes a call to the configured credentialsProvider. The credentials provider may make a network call to refresh the credentials, or fail with a message indicating the

Declaration

Objective-C

- (void)startTranscriptionWSS:
    (nonnull AWSTranscribeStreamingStartStreamTranscriptionRequest *)request;

Swift

func startTranscriptionWSS(_ request: AWSTranscribeStreamingStartStreamTranscriptionRequest)

Parameters


                                request

the request containing the stream details

-endTranscription
Ends the transcription session cleanly by closing the web socket. Failure to invoke this will likely result in a “BadRequest” exception after 15 seconds of inactivity.
Declaration
Objective-C

- (void)endTranscription;
Swift

func endTranscription()


                    
                    
                    -sendData:headers:

Sends a chunk of data to AWSTranscribeStreaming. Internally, this method encodes the data and headers and sends it on the underlying web socket.

Declaration

Objective-C

- (void)sendData:(nonnull NSData *)data headers:(nonnull NSDictionary *)headers;

Swift

func send(_ data: Data, headers: [AnyHashable : Any])

Parameters

`data`	the data to send
`headers`	headers describing the chunk of data

-sendEndFrame
Sends an “end” frame to the TranscribeService, and immediately closes the web socket. After sending the end frame, it is a fatal error to attempt to send any more data.
Declaration
Objective-C

- (void)sendEndFrame;
Swift

func sendEndFrame()


                    
                    
                    -setDelegate:callbackQueue:

Sets the AWSTranscribeStreamingClient’s delegate, which will receive connection state change messages and notifications of events. Callback methods will be invoked on the specified queue, regardless of the queue on which the web socket data is processed.

Declaration

Objective-C

- (void)setDelegate:(nonnull id<AWSTranscribeStreamingClientDelegate>)delegate
      callbackQueue:(nonnull dispatch_queue_t)callbackQueue;

Swift

func setDelegate(_ delegate: AWSTranscribeStreamingClientDelegate, callbackQueue: dispatch_queue_t)

Parameters

`delegate`	the delegate to assign. The delegate is weakly retained.
`callbackQueue`	the queue on which to invoke delegate callback methods. The queue is strongly retained.