{"id":6982,"library":"amazon-transcribe","title":"Amazon Transcribe Streaming SDK for Python","description":"The `amazon-transcribe` library is an asynchronous Python SDK designed for direct integration with the Amazon Transcribe Streaming service, enabling real-time conversion of audio into text. As of version 0.6.4, this SDK is considered experimental, is no longer actively developed, and is not officially supported by AWS for new projects. It receives infrequent updates and has a stated lack of commitment for ongoing support.","status":"deprecated","version":"0.6.4","language":"en","source_language":"en","source_url":"https://github.com/awslabs/amazon-transcribe-streaming-sdk","tags":["aws","amazon","transcribe","streaming","speech-to-text","asynchronous","deprecated"],"install":[{"cmd":"pip install amazon-transcribe","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Core dependency for AWS Common Runtime (CRT) C libraries. May require manual compilation on non-standard operating systems if precompiled wheels are unavailable.","package":"awscrt","optional":false},{"reason":"Used in common examples for asynchronous file I/O, but not a direct dependency of the SDK itself.","package":"aiofile","optional":true}],"imports":[{"symbol":"TranscribeStreamingClient","correct":"from amazon_transcribe.client import TranscribeStreamingClient"},{"symbol":"TranscriptResultStreamHandler","correct":"from amazon_transcribe.handlers import TranscriptResultStreamHandler"},{"symbol":"TranscriptEvent","correct":"from amazon_transcribe.model import TranscriptEvent"}],"quickstart":{"code":"import asyncio\nimport os\nimport time\n\n# NOTE: aiofile is not a direct dependency but is commonly used\n# for asynchronous file reads in examples. Install with `pip install aiofile`.\n# For a minimal example, we'll simulate an audio stream.\n# import aiofile\n\nfrom amazon_transcribe.client import TranscribeStreamingClient\nfrom amazon_transcribe.handlers import TranscriptResultStreamHandler\nfrom amazon_transcribe.model import TranscriptEvent\n\n# Configure AWS credentials from environment variables for quickstart.\n# In a real application, consider using AWS CLI config or IAM roles.\n# os.environ['AWS_ACCESS_KEY_ID'] = os.environ.get('AWS_ACCESS_KEY_ID', '')\n# os.environ['AWS_SECRET_ACCESS_KEY'] = os.environ.get('AWS_SECRET_ACCESS_KEY', '')\n# os.environ['AWS_SESSION_TOKEN'] = os.environ.get('AWS_SESSION_TOKEN', '') # Optional\n\nclass MyEventHandler(TranscriptResultStreamHandler):\n    async def handle_transcript_event(self, transcript_event: TranscriptEvent):\n        results = transcript_event.transcript.results\n        for result in results:\n            if not result.is_partial:\n                for alternative in result.alternatives:\n                    print(f\"[Transcription]: {alternative.transcript}\")\n\nasync def basic_transcribe_stream(client: TranscribeStreamingClient, region: str):\n    # Simulate a stream of audio bytes (replace with actual audio source)\n    async def get_audio_stream():\n        # For a real application, read from microphone or file (e.g., using aiofile)\n        # For this example, we'll send a few empty bytes to keep the stream open briefly\n        for _ in range(5):\n            yield b'\\x00' * 1024 # Simulate 1KB of silence/empty data\n            await asyncio.sleep(0.1)\n        print(\"\\n--- Audio stream ended ---\")\n\n    stream = await client.start_stream_transcription(\n        language_code=\"en-US\",\n        media_sample_rate_hz=16000,\n        media_encoding=\"pcm\",\n    )\n\n    # Instantiate our handler and start processing events\n    handler = MyEventHandler(stream.output_stream)\n    await asyncio.gather(stream.input_stream.send_from_iterable(get_audio_stream()), handler.handle_events())\n\nasync def main():\n    # Ensure AWS_REGION is set, e.g., in your environment variables\n    aws_region = os.environ.get('AWS_REGION', 'us-east-1')\n    print(f\"Connecting to Amazon Transcribe in region: {aws_region}\")\n    client = TranscribeStreamingClient(region=aws_region)\n    await basic_transcribe_stream(client, aws_region)\n\nif __name__ == \"__main__\":\n    # Set dummy credentials if not set for local testing, replace with actual for production\n    if not os.environ.get('AWS_ACCESS_KEY_ID'):\n        os.environ['AWS_ACCESS_KEY_ID'] = 'AKIAIOSFODNN7EXAMPLE'\n        os.environ['AWS_SECRET_ACCESS_KEY'] = 'wJalrXUtnFEMI/K7MDENG/bPxRfiorexamplekey'\n        os.environ['AWS_REGION'] = 'us-east-1'\n        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.\")\n\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"fix":"For 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.","message":"This 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.","severity":"breaking","affected_versions":"0.6.x and earlier"},{"fix":"Ensure you are using the `amazon-transcribe` SDK for streaming transcription. Boto3 is suitable for batch transcription jobs.","message":"The standard AWS SDK for Python (Boto3) does NOT support Amazon Transcribe streaming. This `amazon-transcribe` SDK is specifically designed for streaming.","severity":"gotcha","affected_versions":"All"},{"fix":"Monitor CPU usage and refer to GitHub issues (e.g., #109, #84) for potential workarounds if encountered.","message":"The SDK can, in rare cases, suffer from high CPU issues.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure your operating system is supported by `awscrt` precompiled wheels, or be prepared to compile the AWS Common Runtime libraries manually.","message":"The `awscrt` dependency, built on C libraries, may require manual compilation on non-standard operating systems if precompiled wheels are not available.","severity":"gotcha","affected_versions":"All"},{"fix":"Design your application to handle a single audio stream per `start_stream_transcription` call and associated `output_stream` handler.","message":"Amazon 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Break 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`.","cause":"The audio data stream provided to Amazon Transcribe exceeds the service's size limits or contains malformed audio data.","error":"BadRequestException: Your stream is too big."},{"fix":"Review 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.","cause":"Your client has exceeded one of the Amazon Transcribe limits, typically the audio length limit for a streaming session.","error":"LimitExceededException"},{"fix":"This 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.","cause":"A problem occurred internally while Amazon Transcribe was processing the audio, leading to termination of processing.","error":"InternalFailureException"},{"fix":"Verify 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.","cause":"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.","error":"HTTP/2 stream is abnormally aborted in mid-communication with result code 2"},{"fix":"Ensure `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.","cause":"The AWS credentials (access key, secret key, session token) used by the SDK are invalid, expired, or not configured correctly.","error":"UnrecognizedClientException: The security token included in the request is invalid. (or similar credential errors)"}]}