Release: Amazon Transcribe Streaming Client

[jonathan343]

This PR adds a new client for the Amazon Transcribe Streaming Service.

Summary

Add support for the Amazon Transcribe Streaming service by adding the latest Smithy model and code-generating a new client package (aws-sdk-transcribe-streaming).

Changes

• Add Smithy model: Added transcribe-streaming.json model definition to codegen/aws-models/
• Generate client package: Install the latest code generator from https://github.com/smithy-lang/smithy-python

Testing

• Change into the transcribe directory: cd clients/aws-sdk-transcribe-streaming
• Create a virtual environment:uv venv -p 3.14
• Activate the virtual environment: source .venv/bin/activate
• Install the transcribe client and sounddevice: uv pip install . sounddevice
• Copy AWS creds to my environment (I'm using the EnvironmentCredentialsResolver)
• Run the following example:

import asyncio
import sounddevice

from smithy_aws_core.identity import EnvironmentCredentialsResolver
from smithy_core.aio.interfaces.eventstream import EventPublisher, EventReceiver
from aws_sdk_transcribe_streaming.client import (
    TranscribeStreamingClient,
    StartStreamTranscriptionInput,
)
from aws_sdk_transcribe_streaming.models import (
    AudioStreamAudioEvent,
    AudioEvent,
    TranscriptEvent,
    AudioStream,
    TranscriptResultStream,
)
from aws_sdk_transcribe_streaming.config import Config

AWS_REGION = "us-west-2"
ENDPOINT_URI = f"https://transcribestreaming.{AWS_REGION}.amazonaws.com"


async def mic_stream():
    # This function wraps the raw input stream from the microphone forwarding
    # the blocks to an asyncio.Queue.
    loop = asyncio.get_event_loop()
    input_queue = asyncio.Queue()

    def callback(indata, frame_count, time_info, status):
        loop.call_soon_threadsafe(input_queue.put_nowait, (bytes(indata), status))

    # Be sure to use the correct parameters for the audio stream that matches
    # the audio formats described for the source language you'll be using:
    # https://docs.aws.amazon.com/transcribe/latest/dg/streaming.html
    stream = sounddevice.RawInputStream(
        channels=1,
        samplerate=16000,
        callback=callback,
        blocksize=1024 * 2,
        dtype="int16",
    )
    # Initiate the audio stream and asynchronously yield the audio chunks
    # as they become available.
    with stream:
        while True:
            indata, status = await input_queue.get()
            yield indata, status


class TranscriptResultStreamHandler:
    def __init__(self, stream: EventReceiver[TranscriptResultStream]):
        self.stream = stream

    async def handle_events(self):
        """Process generic incoming events from Amazon Transcribe
        and delegate to appropriate sub-handlers.
        """
        async for event in self.stream:
            if isinstance(event.value, TranscriptEvent):
                await self.handle_transcript_event(event.value)

    async def handle_transcript_event(self, event: TranscriptEvent):
        # This handler can be implemented to handle transcriptions as needed.
        # Here's an example to get started.
        results = event.transcript.results
        for result in results:
            for alt in result.alternatives:
                print(alt.transcript)


async def write_chunks(audio_stream: EventPublisher[AudioStream]):
    # This connects the raw audio chunks generator coming from the microphone
    # and passes them along to the transcription stream.
    async for chunk, _ in mic_stream():
        await audio_stream.send(
            AudioStreamAudioEvent(value=AudioEvent(audio_chunk=chunk))
        )


async def main():
    client = TranscribeStreamingClient(
        config=Config(
            endpoint_uri=ENDPOINT_URI,
            region=AWS_REGION,
            aws_credentials_identity_resolver=EnvironmentCredentialsResolver(),
        )
    )

    stream = await client.start_stream_transcription(
        input=StartStreamTranscriptionInput(
            language_code="en-US", media_sample_rate_hertz=16000, media_encoding="pcm"
        )
    )
    _, output_stream = await stream.await_output()

    handler = TranscriptResultStreamHandler(output_stream)
    print("Start talking to see transcription!")
    print("===================================")
    await asyncio.gather(write_chunks(stream.input_stream), handler.handle_events())
    await stream.close()


if __name__ == "__main__":
    asyncio.run(main())

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[nateprewitt]

Was this intentional? I wouldn't expect this to be a package.

[jonathan343]

This is a bug in the code generator. Will be addressed in a seperate PR! I'll update this PR to remove all __init__.py file under the docs directory once the fix is up.

[nateprewitt]

Refer to for details.

Refer to what? Is this a source docs issue or are we missing something in the generator?

[jonathan343]

This isn't an issue with the code generator. The issue is in the service model documentation:

https://github.com/aws/api-models-aws/blob/main/models/transcribe-streaming/service/2017-10-26/transcribe-streaming-2017-10-26.json#L3717

[nateprewitt]

Refer to [here] for details.

Hmm, this isn't great either. It looks like this is an issue in the upstream docs. We should make sure the service team is aware.

[jonathan343]

Yea, same as I mentioned above. I'll reach out to them. Thanks for catching this!

[nateprewitt]

This looks like an issue in the docstring generator for operations? We're getting an unnecessary newline here but not in the top level class docstring.

[jonathan343]

I'll check to see if these doc issue go away after https://github.com/smithy-lang/smithy-python/pull/592/files

[nateprewitt]

This newline also seems potentially wrong?

[nateprewitt]

What'd we use to generate this? It's strange we've named the client correctly (TranscribeStreamingClient) but this is Transcribe which would be a different client. It seems like we potentially have a mismatch or Transcribe themselves may not be making the distinction we expect. Is this the signing name?

[jonathan343]

Yea, this is using the name of the service type in the smithy model. The bedrock Config object also has a weird docstring.

I just put up a PR to fix this. The description has the before/after docstrings for bedrock runtime and transcribe streaming.
smithy-lang/smithy-python#595

[nateprewitt]

Did we generate this? If not, we should be using the fixtures from @alexgromero's PR.

[alexgromero]

Yeah this is generated. I asked Jordon about this file and whether it was intentional to generate this in codegen/protocol-test and in the generated clients. He mentioned "It's intentional in that any service can have protocol tests. But the actual file could be omitted if there’s no trait"