streamlink-serverless

Streamlink as a Serverless Service | Getting started | Usage | FAQ

Getting started

Streamlink Serverless is a CDK construct to run Streamlink as a serverless Lambda Function on AWS.

Requirements

• AWS CDK
• Docker (to bundle the Streamlink Serverless Lambda Function)

Installation

Add Streamlink Serverless to a new or existing AWS CDK app in the language of your choice:

Node.js

# npm
npm install streamlink-serverless
# Yarn
yarn add streamlink-serverless
# pnpm
pnpm add streamlink-serverless

Other languages

# Python
pip install streamlink-serverless

# Dotnet
dotnet add package StreamlinkServerless

Full example

This example creates a Stack with a Streamlink Serverless backend and publishes the service behind a Function URL. Finally an output returns the service URL for immediate use.

app = cdk.App()
stack = cdk.Stack(app, "Streamlink")

streamlink = Streamlink(stack, "Backend")

endpoint = lambda_.FunctionUrl(stack, "Endpoint",
    function=streamlink.function,
    auth_type=lambda_.FunctionUrlAuthType.NONE
)

cdk.CfnOutput(stack, "EndpointUrl",
    value=endpoint.url
)

app.synth()

Usage

Once deployed, you can use your Streamlink Serverless service like this: https://example.com/live/youtube.com/@NASA/best.m3u8

URL formats

https://<endpoint>/live/<url>
Simply put the stream URL behind your endpoint.

• <endpoint>
  The endpoint URL of the Streamlink Serverless deployment.
• <url>
  A URL to attempt to extract streams from. Usually, the protocol of http(s) URLs can be omitted.

https://<endpoint>/live/<url>/<stream>.<type>
This format allows selecting a specific stream quality and format.

• <stream>
  Stream to play. Use best or worst for selecting the highest or lowest available quality. Optional.
• <type>
  Type of the returned stream. Needed by some players for correct playback. Use m3u8 for HLS streams or mpd for Dash streams.

FAQ

Feel free to open an issue for any unaddressed questions.

🌍 Does it work with geo-blocking?

Make sure to deploy Streamlink Serverless into the region you intend to watch streams from. Most services are already geo-blocked when trying to retrieve the stream URL. E.g. if you are based in London, United Kingdom deploy to eu-west-2.

See this blog post for detailed instructions.

💰 How much does it cost to run?

The pricing model for AWS Lambda is based on number of request and duration of the execution. It also offers a generous "always free" allocation via AWS Free Tier.

While cost predications are incredible difficult to make, it seems possible to run Streamlink Serverless for personal use only within the bounds of AWS Free Tier.

Always set up billing alarms to avoid unexpected costs.

🔐 Why does it have no authentication or password protection?

Adding appropriate authentication is your responsibility. Putting any unprotected URL online makes you susceptible to occurring unexpected cost.

Streamlink Serverless does not offer built-in password protection, because the pricing model for AWS Lambda charges for number of requests and duration of the execution. This means that you would still be charged for any unauthenticated requests if password protection were to be handled inside the Lambda Function. While there might be some savings from shorter execution times and the deterrent of an unusable service, it is much safer to deploy a proper authentication mechanism.

The simplest way would be to enable AWS_IAM auth on the Lambda Function URL (see docs). However IAM authentication is likely not compatible with the intended use case of using Streamlink Serverless URLs as IPTV playlists, as it involves signing requests.

A more advanced approach would be to deploy Streamlink Serverless as part of an API Gateway HTTP API and configure an authorizer according to your needs.