Metadata-Version: 2.4
Name: amazon-polly-streaming
Version: 1.1.0
Summary: Amazon Polly bidirectional streaming over HTTP/2 with SigV4 (the API boto3 does not yet expose)
Author-email: Alessandra Bilardi <alessandra.bilardi@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/bilardi/amazon-polly-streaming
Project-URL: Documentation, https://amazon-polly-streaming.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/bilardi/amazon-polly-streaming
Project-URL: Issues, https://github.com/bilardi/amazon-polly-streaming/issues
Keywords: aws,polly,tts,streaming,http2,sigv4,bidirectional
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.13
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: NOTICE
Requires-Dist: awscrt
Requires-Dist: botocore
Dynamic: license-file

amazon-polly-streaming
======================

Amazon Polly bidirectional streaming over HTTP/2 with SigV4: implements `StartSpeechSynthesisStream <https://docs.aws.amazon.com/polly/latest/dg/API_StartSpeechSynthesisStream.html>`_, the Polly API that boto3 does not yet expose (only the AWS Java SDK has it).

* **Async generator** interface: ``async for chunk in client.start_speech_synthesis_stream(...)`` yields audio bytes as they arrive from Polly, with no need to wait for the full audio to be generated server-side.
* **Real bidirectional**: events sent to Polly and audio events received are framed in AWS event-stream over HTTP/2, with rolling chunk-signatures (the same scheme ``amazon-transcribe-streaming-sdk`` uses for Transcribe streaming).
* **Typed**: PEP 561 ``py.typed`` marker; full pyright-strict surface for downstream consumers.

Full documentation on `readthedocs <https://amazon-polly-streaming.readthedocs.io/en/latest/>`_.

Installation
############

.. code-block:: bash

    pip install amazon-polly-streaming

Quick start
###########

.. code-block:: python

    import asyncio
    from amazon_polly_streaming import PollyStreamingClient

    async def main() -> None:
        client = PollyStreamingClient(region="eu-central-1")
        audio = b""
        async for chunk in client.start_speech_synthesis_stream(
            text="hello world, how are you today",
            voice_id="Matthew",
            engine="generative",
            language_code="en-US",
            output_format="mp3",
            sample_rate="24000",
        ):
            audio += chunk
        with open("hello.mp3", "wb") as fh:
            fh.write(audio)

    asyncio.run(main())

The ``voice_id`` must be a generative voice supporting bidirectional streaming. See the `Amazon Polly Generative voices <https://docs.aws.amazon.com/polly/latest/dg/generative-voices.html>`_ page for the current list and supported regions.

Requirements
############

* Python 3.13+
* AWS credentials in the default chain (env vars, profile, or IAM role) with ``polly:StartSpeechSynthesisStream`` permission
* A region supporting Polly bidirectional streaming (``us-east-1``, ``us-west-2``, ``eu-central-1``, ``eu-west-2``, ``ap-southeast-1``, ``ca-central-1`` as of 2026-05)

License
#######

This package is released under the Apache License 2.0. See ``LICENSE`` and ``NOTICE`` for details.
