Install & Compatibility
Where this runs
tested against v0.6.4 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.265s · 44.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.5s · import 0.229s · 44MB
42MB installed
● package 42MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TranscribeStreamingClient
✓ from amazon_transcribe.client import TranscribeStreamingClient
TranscriptResultStreamHandler
✓ from amazon_transcribe.handlers import TranscriptResultStreamHandler
TranscriptEvent
✓ from amazon_transcribe.model import TranscriptEvent
This quickstart demonstrates how to establish an asynchronous connection to Amazon Transcribe Streaming, send a simulated audio stream, and process the real-time transcription results. It defines a custom event handler to print the final transcription segments. Remember to set your AWS credentials and region via environment variables or AWS CLI configuration for actual use.
import asyncio
import os
import time
# NOTE: aiofile is not a direct dependency but is commonly used
# for asynchronous file reads in examples. Install with `pip install aiofile`.
# For a minimal example, we'll simulate an audio stream.
# import aiofile
from amazon_transcribe.client import TranscribeStreamingClient
from amazon_transcribe.handlers import TranscriptResultStreamHandler
from amazon_transcribe.model import TranscriptEvent
# Configure AWS credentials from environment variables for quickstart.
# In a real application, consider using AWS CLI config or IAM roles.
# os.environ['AWS_ACCESS_KEY_ID'] = os.environ.get('AWS_ACCESS_KEY_ID', '')
# os.environ['AWS_SECRET_ACCESS_KEY'] = os.environ.get('AWS_SECRET_ACCESS_KEY', '')
# os.environ['AWS_SESSION_TOKEN'] = os.environ.get('AWS_SESSION_TOKEN', '') # Optional
class MyEventHandler(TranscriptResultStreamHandler):
async def handle_transcript_event(self, transcript_event: TranscriptEvent):
results = transcript_event.transcript.results
for result in results:
if not result.is_partial:
for alternative in result.alternatives:
print(f"[Transcription]: {alternative.transcript}")
async def basic_transcribe_stream(client: TranscribeStreamingClient, region: str):
# Simulate a stream of audio bytes (replace with actual audio source)
async def get_audio_stream():
# For a real application, read from microphone or file (e.g., using aiofile)
# For this example, we'll send a few empty bytes to keep the stream open briefly
for _ in range(5):
yield b'\x00' * 1024 # Simulate 1KB of silence/empty data
await asyncio.sleep(0.1)
print("\n--- Audio stream ended ---")
stream = await client.start_stream_transcription(
language_code="en-US",
media_sample_rate_hz=16000,
media_encoding="pcm",
)
# Instantiate our handler and start processing events
handler = MyEventHandler(stream.output_stream)
await asyncio.gather(stream.input_stream.send_from_iterable(get_audio_stream()), handler.handle_events())
async def main():
# Ensure AWS_REGION is set, e.g., in your environment variables
aws_region = os.environ.get('AWS_REGION', 'us-east-1')
print(f"Connecting to Amazon Transcribe in region: {aws_region}")
client = TranscribeStreamingClient(region=aws_region)
await basic_transcribe_stream(client, aws_region)
if __name__ == "__main__":
# Set dummy credentials if not set for local testing, replace with actual for production
if not os.environ.get('AWS_ACCESS_KEY_ID'):
os.environ['AWS_ACCESS_KEY_ID'] = 'AKIAIOSFODNN7EXAMPLE'
os.environ['AWS_SECRET_ACCESS_KEY'] = 'wJalrXUtnFEMI/K7MDENG/bPxRfiorexamplekey'
os.environ['AWS_REGION'] = 'us-east-1'
print("Warning: Using dummy AWS credentials and region. Set environment variables AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION for actual use.")
asyncio.run(main())
Debug
Known issues
breakingThis SDK is experimental, no longer actively developed, and is not recommended for new projects. It is provided as-is without a support commitment and is being replaced by other AWS solutions.fixFor new projects, consider using the official AWS SDKs (e.g., Boto3 for batch transcription or other language-specific streaming SDKs/approaches) as recommended by AWS documentation. For existing projects, proceed with caution and pin strict dependencies.
affects: 0.6.x and earlier
gotchaThe standard AWS SDK for Python (Boto3) does NOT support Amazon Transcribe streaming. This `amazon-transcribe` SDK is specifically designed for streaming.fixEnsure you are using the `amazon-transcribe` SDK for streaming transcription. Boto3 is suitable for batch transcription jobs.
affects: All
gotchaThe SDK can, in rare cases, suffer from high CPU issues.fixMonitor CPU usage and refer to GitHub issues (e.g., #109, #84) for potential workarounds if encountered.
affects: All
gotchaThe `awscrt` dependency, built on C libraries, may require manual compilation on non-standard operating systems if precompiled wheels are not available.fixEnsure your operating system is supported by `awscrt` precompiled wheels, or be prepared to compile the AWS Common Runtime libraries manually.
affects: All
gotchaAmazon Transcribe only supports one audio stream per WebSocket session. Attempting to use multiple streams simultaneously within a single session will cause the transcription request to fail.fixDesign your application to handle a single audio stream per `start_stream_transcription` call and associated `output_stream` handler.
affects: All
Errors
Common errors & fixes
BadRequestException: Your stream is too big.
The audio data stream provided to Amazon Transcribe exceeds the service's size limits or contains malformed audio data.
fixBreak your audio stream into smaller, appropriately sized chunks. Ensure your audio format (PCM, 16-bit) and sample rate (e.g., 16000 Hz) match the parameters specified in `start_stream_transcription`.
LimitExceededException
Your client has exceeded one of the Amazon Transcribe limits, typically the audio length limit for a streaming session.
fixReview Amazon Transcribe service quotas. If applicable, break your audio input into smaller, separate streaming sessions, or reduce the frequency of requests if rate limits are hit. The AWS SDKs typically include automatic retry mechanisms for rate limit exceptions.
InternalFailureException
A problem occurred internally while Amazon Transcribe was processing the audio, leading to termination of processing.
fixThis often indicates a transient server-side issue. Implement robust retry logic with exponential backoff. If the problem persists, gather detailed logs and contact AWS Support.
HTTP/2 stream is abnormally aborted in mid-communication with result code 2
This error can stem from various issues including incorrect audio format, mismatched sample rate, an unusually small chunk size, or underlying network connectivity problems between your client and Amazon Transcribe.
fixVerify that your PCM audio is 16-bit, and the `media_sample_rate_hz` parameter matches your audio source. Try increasing the audio chunk size (e.g., to 32 KB per chunk). Check your network connection stability. Ensure proper error handling, especially for initial audio chunks.
UnrecognizedClientException: The security token included in the request is invalid. (or similar credential errors)
The AWS credentials (access key, secret key, session token) used by the SDK are invalid, expired, or not configured correctly.
fixEnsure `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION` environment variables are correctly set, or that your AWS CLI configured profile (`~/.aws/credentials`) is valid and accessible. If using temporary credentials, ensure they haven't expired.
Upgrade
Version history
0.6.4latest on PyPI · released May 5, 2025
Audit
Dependencies
awscrtrequiredCore dependency for AWS Common Runtime (CRT) C libraries. May require manual compilation on non-standard operating systems if precompiled wheels are unavailable.
aiofileoptionalUsed in common examples for asynchronous file I/O, but not a direct dependency of the SDK itself.