StartMedicalScribeStream
Starts a bidirectional HTTP/2 stream, where audio is streamed to AWS HealthScribe and the transcription results are streamed to your application.
When you start a stream, you first specify the stream configuration in a MedicalScribeConfigurationEvent
.
This event includes channel definitions, encryption settings, and post-stream analytics settings, such as the output configuration for aggregated transcript and clinical note generation. These are additional
streaming session configurations beyond those provided in your initial start request headers. Whether you are starting a new session or resuming an existing session,
your first event must be a MedicalScribeConfigurationEvent
.
After you send a MedicalScribeConfigurationEvent
, you start AudioEvents
and AWS HealthScribe
responds with real-time transcription results. When you are finished, to start processing the results with the post-stream analytics, send a MedicalScribeSessionControlEvent
with a Type
of
END_OF_SESSION
and AWS HealthScribe starts the analytics.
You can pause or resume streaming.
To pause streaming, complete the input stream without sending the
MedicalScribeSessionControlEvent
.
To resume streaming, call the StartMedicalScribeStream
and specify the same SessionId you used to start the stream.
The following parameters are required:
-
language-code
-
media-encoding
-
media-sample-rate-hertz
For more information on streaming with AWS HealthScribe, see AWS HealthScribe.
Request Syntax
POST /medical-scribe-stream HTTP/1.1
x-amzn-transcribe-session-id: SessionId
x-amzn-transcribe-language-code: LanguageCode
x-amzn-transcribe-sample-rate: MediaSampleRateHertz
x-amzn-transcribe-media-encoding: MediaEncoding
Content-type: application/json
{
"AudioEvent": {
"AudioChunk": blob
},
"ConfigurationEvent": {
"ChannelDefinitions": [
{
"ChannelId": number
,
"ParticipantRole": "string
"
}
],
"EncryptionSettings": {
"KmsEncryptionContext": {
"string
" : "string
"
},
"KmsKeyId": "string
"
},
"PostStreamAnalyticsSettings": {
"ClinicalNoteGenerationSettings": {
"NoteTemplate": "string
",
"OutputBucketName": "string
"
}
},
"ResourceAccessRoleArn": "string
",
"VocabularyFilterMethod": "string
",
"VocabularyFilterName": "string
",
"VocabularyName": "string
"
},
"SessionControlEvent": {
"Type": "string
"
}
}
URI Request Parameters
The request uses the following URI parameters.
- LanguageCode
-
Specify the language code for your HealthScribe streaming session.
Valid Values:
en-US
Required: Yes
- MediaEncoding
-
Specify the encoding used for the input audio.
Supported formats are:
-
FLAC
-
OPUS-encoded audio in an Ogg container
-
PCM (only signed 16-bit little-endian audio formats, which does not include WAV)
For more information, see Media formats.
Valid Values:
pcm | ogg-opus | flac
Required: Yes
-
- MediaSampleRateHertz
-
Specify the sample rate of the input audio (in hertz). AWS HealthScribe supports a range from 16,000 Hz to 48,000 Hz. The sample rate you specify must match that of your audio.
Valid Range: Minimum value of 16000. Maximum value of 48000.
Required: Yes
- SessionId
-
Specify an identifier for your streaming session (in UUID format). If you don't include a SessionId in your request, AWS HealthScribe generates an ID and returns it in the response.
Length Constraints: Fixed length of 36.
Pattern:
[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}
Request Body
The request accepts the following data in JSON format.
- AudioEvent
-
A wrapper for your audio chunks
For more information, see Event stream encoding.
Type: MedicalScribeAudioEvent object
Required: No
- ConfigurationEvent
-
Specify additional streaming session configurations beyond those provided in your initial start request headers. For example, specify channel definitions, encryption settings, and post-stream analytics settings.
Whether you are starting a new session or resuming an existing session, your first event must be a
MedicalScribeConfigurationEvent
.Type: MedicalScribeConfigurationEvent object
Required: No
- SessionControlEvent
-
Specify the lifecycle of your streaming session, such as ending the session.
Type: MedicalScribeSessionControlEvent object
Required: No
Response Syntax
HTTP/1.1 200
x-amzn-transcribe-session-id: SessionId
x-amzn-request-id: RequestId
x-amzn-transcribe-language-code: LanguageCode
x-amzn-transcribe-sample-rate: MediaSampleRateHertz
x-amzn-transcribe-media-encoding: MediaEncoding
Content-type: application/json
{
"BadRequestException": {
},
"ConflictException": {
},
"InternalFailureException": {
},
"LimitExceededException": {
},
"ServiceUnavailableException": {
},
"TranscriptEvent": {
"TranscriptSegment": {
"BeginAudioTime": number,
"ChannelId": "string",
"Content": "string",
"EndAudioTime": number,
"IsPartial": boolean,
"Items": [
{
"BeginAudioTime": number,
"Confidence": number,
"Content": "string",
"EndAudioTime": number,
"Type": "string",
"VocabularyFilterMatch": boolean
}
],
"SegmentId": "string"
}
}
}
Response Elements
If the action is successful, the service sends back an HTTP 200 response.
The response returns the following HTTP headers.
- LanguageCode
-
The Language Code that you specified in your request. Same as provided in the
StartMedicalScribeStreamRequest
.Valid Values:
en-US
- MediaEncoding
-
The Media Encoding you specified in your request. Same as provided in the
StartMedicalScribeStreamRequest
Valid Values:
pcm | ogg-opus | flac
- MediaSampleRateHertz
-
The sample rate (in hertz) that you specified in your request. Same as provided in the
StartMedicalScribeStreamRequest
Valid Range: Minimum value of 16000. Maximum value of 48000.
- RequestId
-
The unique identifier for your streaming request.
- SessionId
-
The identifier (in UUID format) for your streaming session.
If you already started streaming, this is same ID as the one you specified in your initial
StartMedicalScribeStreamRequest
.Length Constraints: Fixed length of 36.
Pattern:
[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}
The following data is returned in JSON format by the service.
- BadRequestException
-
One or more arguments to the
StartStreamTranscription
,StartMedicalStreamTranscription
, orStartCallAnalyticsStreamTranscription
operation was not valid. For example,MediaEncoding
orLanguageCode
used unsupported values. Check the specified parameters and try your request again.Type: Exception
HTTP Status Code: 400 - ConflictException
-
A new stream started with the same session ID. The current stream has been terminated.
Type: Exception
HTTP Status Code: 409 - InternalFailureException
-
A problem occurred while processing the audio. Amazon Transcribe terminated processing.
Type: Exception
HTTP Status Code: 500 - LimitExceededException
-
Your client has exceeded one of the Amazon Transcribe limits. This is typically the audio length limit. Break your audio stream into smaller chunks and try your request again.
Type: Exception
HTTP Status Code: 429 -
The service is currently unavailable. Try your request later.
Type: Exception
HTTP Status Code: 503 - TranscriptEvent
-
The transcript event that contains real-time transcription results.
Type: MedicalScribeTranscriptEvent object
Errors
For information about the errors that are common to all actions, see Common Errors.
- BadRequestException
-
One or more arguments to the
StartStreamTranscription
,StartMedicalStreamTranscription
, orStartCallAnalyticsStreamTranscription
operation was not valid. For example,MediaEncoding
orLanguageCode
used unsupported values. Check the specified parameters and try your request again.HTTP Status Code: 400
- ConflictException
-
A new stream started with the same session ID. The current stream has been terminated.
HTTP Status Code: 409
- InternalFailureException
-
A problem occurred while processing the audio. Amazon Transcribe terminated processing.
HTTP Status Code: 500
- LimitExceededException
-
Your client has exceeded one of the Amazon Transcribe limits. This is typically the audio length limit. Break your audio stream into smaller chunks and try your request again.
HTTP Status Code: 429
- ServiceUnavailableException
-
The service is currently unavailable. Try your request later.
HTTP Status Code: 503
See Also
For more information about using this API in one of the language-specific AWS SDKs, see the following: