TURN Credential Utils

get_turn_credentials_async

async def get_turn_credentials_async(
    method: Literal["hf", "twilio", "cloudflare"] = "cloudflare",
    **kwargs
):

Asynchronously retrieves TURN credentials from the specified provider.

You can pass this function directly to the Stream class as rtc_configuration, in which case it is called for each unique WebRTC connection. When serving your own frontend, you can instead call it yourself and embed the returned credentials in your client — for example, in your index route, call it and inject the credentials into your index.html.

Acts as an async dispatcher function to call the appropriate async credential retrieval function based on the method specified.

Args:

method: Literal["hf", "twilio", "cloudflare"]
    The provider to use. 'hf' uses the deprecated Hugging Face endpoint.
    'cloudflare' uses either Cloudflare keys or the HF endpoint.
    'twilio' is not supported asynchronously by this function yet.
    Defaults to "cloudflare".
**kwargs: 
    Additional keyword arguments passed directly to the underlying
    provider-specific async function (e.g., `token`, `ttl`, `client` for 'hf';
    `turn_key_id`, `turn_key_api_token`, `hf_token`, `ttl`, `client` for
    'cloudflare').

Returns:

dict:
    A dictionary containing the TURN credentials from the chosen provider.

Raises:

ValueError:
    If an invalid method is specified.
NotImplementedError:
    If method 'twilio' is requested.
    Also raises exceptions from the underlying provider functions (see their
    docstrings).

Example

>>> from fastrtc import get_turn_credentials_async, Stream
>>> credentials = await get_turn_credentials_async()
>>> print(credentials)
>>> # Can pass directly to stream class
>>> stream = Stream(..., rtc_configuration=get_turn_credentials_async)

get_turn_credentials

def get_turn_credentials(
    method: Literal["hf", "twilio", "cloudflare"] = "cloudflare",
    **kwargs
):

Retrieves TURN credentials from the specified provider.

You can pass this function directly to the Stream class as rtc_configuration, in which case it is called for each unique WebRTC connection. When serving your own frontend, you can instead call it yourself and embed the returned credentials in your client — for example, in your index route, call it and inject the credentials into your index.html.

Acts as a dispatcher function to call the appropriate credential retrieval function based on the method specified.

Args:

method: Literal["hf", "twilio", "cloudflare"]
    The provider to use. 'hf' uses the deprecated Hugging Face endpoint.
    'cloudflare' uses either Cloudflare keys or the HF endpoint.
    'twilio' uses the Twilio API. Defaults to "cloudflare".
**kwargs: 
    Additional keyword arguments passed directly to the underlying
    provider-specific function (e.g., `token`, `ttl` for 'hf';
    `twilio_sid`, `twilio_token` for 'twilio'; `turn_key_id`,
    `turn_key_api_token`, `hf_token`, `ttl` for 'cloudflare').

Returns:

dict:
    A dictionary containing the TURN credentials from the chosen provider.

Raises:

ValueError:
    If an invalid method is specified.
    Also raises exceptions from the underlying provider functions (see their
    docstrings).

Example

>>> from fastrtc import get_turn_credentials, Stream
>>> credentials = get_turn_credentials()
>>> print(credentials)
>>> # Can pass directly to stream class
>>> stream = Stream(..., rtc_configuration=get_turn_credentials)

get_cloudflare_turn_credentials_async

async def get_cloudflare_turn_credentials_async(
    turn_key_id=None,
    turn_key_api_token=None,
    hf_token=None,
    ttl=600,
    client: httpx.AsyncClient | None = None,
):

Asynchronously retrieves TURN credentials from Cloudflare or Hugging Face.

Asynchronously fetches TURN server credentials either directly from Cloudflare using API keys or via the Hugging Face TURN endpoint using an HF token. The HF token method takes precedence if provided.

Args:

turn_key_id (str, optional):
    Cloudflare TURN key ID. Defaults to None,
    in which case the CLOUDFLARE_TURN_KEY_ID environment variable is used.
turn_key_api_token (str, optional):
    Cloudflare TURN key API token.
    Defaults to None, in which case the CLOUDFLARE_TURN_KEY_API_TOKEN
    environment variable is used.
hf_token (str, optional):
    Hugging Face API token. If provided, this method
    is used instead of Cloudflare keys.
    Defaults to None, in which case the HF_TOKEN environment variable is used.
ttl (int, optional): Time-to-live for the credentials in seconds.
    Defaults to 600.
client (httpx.AsyncClient | None, optional): An existing httpx async client
    to use for the request. If None, a new client is created per request.
    Defaults to None.

Returns:

dict: A dictionary containing the TURN credentials (ICE servers).

Raises:

ValueError: If neither HF token nor Cloudflare keys (either as arguments
    or environment variables) are provided.
Exception: If the request to the credential server fails.

Example

>>> from fastrtc import get_cloudflare_turn_credentials_async, Stream
>>> credentials = await get_cloudflare_turn_credentials_async()
>>> print(credentials)
>>> # Can pass directly to stream class
>>> stream = Stream(..., rtc_configuration=get_cloudflare_turn_credentials_async)

get_cloudflare_turn_credentials

def get_cloudflare_turn_credentials(
    turn_key_id=None,
    turn_key_api_token=None,
    hf_token=None,
    ttl=600,
    client: httpx.AsyncClient | None = None,
):

Retrieves TURN credentials from Cloudflare or Hugging Face.

Fetches TURN server credentials either directly from Cloudflare using API keys or via the Hugging Face TURN endpoint using an HF token. The HF token method takes precedence if provided.

Args:

turn_key_id (str, optional):
    Cloudflare TURN key ID. Defaults to None,
    in which case the CLOUDFLARE_TURN_KEY_ID environment variable is used.
turn_key_api_token (str, optional):
    Cloudflare TURN key API token.
    Defaults to None, in which case the CLOUDFLARE_TURN_KEY_API_TOKEN
    environment variable is used.
hf_token (str, optional):
    Hugging Face API token. If provided, this method
    is used instead of Cloudflare keys.
    Defaults to None, in which case the HF_TOKEN environment variable is used.
ttl (int, optional): Time-to-live for the credentials in seconds.
    Defaults to 600.
client (httpx.AsyncClient | None, optional): An existing httpx async client
    to use for the request. If None, a new client is created per request.
    Defaults to None.

Returns:

dict: A dictionary containing the TURN credentials (ICE servers).

Raises:

ValueError: If neither HF token nor Cloudflare keys (either as arguments
    or environment variables) are provided.
Exception: If the request to the credential server fails.

Example

>>> from fastrtc import get_cloudflare_turn_credentials, Stream
>>> credentials = get_cloudflare_turn_credentials()
>>> print(credentials)
>>> # Can pass directly to stream class
>>> stream = Stream(..., rtc_configuration=get_cloudflare_turn_credentials)

get_twilio_turn_credentials

def get_twilio_turn_credentials(
    twilio_sid=None,
    twilio_token=None):

Retrieves TURN credentials from Twilio.

Uses the Twilio REST API to generate temporary TURN credentials. Requires the twilio package to be installed.

Args:

twilio_sid (str, optional):
    Twilio Account SID. Defaults to None, in which
    case the TWILIO_ACCOUNT_SID environment variable is used.
twilio_token (str, optional): 
    Twilio Auth Token. Defaults to None, in which
    case the TWILIO_AUTH_TOKEN environment variable is used.

Returns:

dict:
    A dictionary containing the TURN credentials formatted for WebRTC,
    including 'iceServers' and 'iceTransportPolicy'.

Raises:

ImportError: If the `twilio` package is not installed.
ValueError: If Twilio credentials (SID and token) are not provided either
    as arguments or environment variables.
TwilioRestException: If the Twilio API request fails.