HLS-Proxy | Node.js server to proxy HLS video streams | Video Utils library

--tls is a flag to start HTTPS proxy, rather than HTTP. --host must be an IP address of the server on the LAN (so Chromecast can proxy requests through it). used to modify URLs in .m3u8 files.
--tls is a flag to start HTTPS proxy, rather than HTTP
--host must be an IP address of the server on the LAN (so Chromecast can proxy requests through it)
ex: 192.168.0.100
used to modify URLs in .m3u8 files
when this option is not specified:
the list of available network addresses is determined
if there are none, 'localhost' is used silently
if there is only a single address on the LAN, it is used silently
if there are multiple addresses:
they are listed
a prompt asks the user to choose (the numeric index) of one
--port is the port number that the server listens on
ex: 8080
used to modify URLs in .m3u8 files
when this option is not specified:
HTTP proxy binds to: 80
HTTPS proxy binds to: 443
--req-headers is the filepath to a JSON data Object containing key:value pairs
each key is the name of an HTTP header to send in in every outbound request
--origin is the value of the corresponding HTTP request header
--referer is the value of the corresponding HTTP request header
--useragent is the value of the corresponding HTTP request header
--header is a single name:value pair
this option can be used multiple times to include several HTTP request headers
the pair can be written:
"name: value"
"name=value"
"name = value"
--req-options is the filepath to a JSON data Object
exposes the options Object passed to low-level network request APIs:
[http.request(options)](https://nodejs.org/api/http.html#http_http_request_options_callback)
[https.request(options)](https://nodejs.org/api/https.html#https_https_request_options_callback)
advanced https request options:
context of the secure request is obtained by passing the request options Object to: [tls.createSecureContext(options)](https://nodejs.org/api/tls.html#tls_tls_createsecurecontext_options)
configuration for the context of the secure request can be merged with the request options Object
configuration keys of particular interest:
honorCipherOrder
default value: false
ciphers
default value: ["ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA256:ECDHE-RSA-AES256-SHA384:DHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA256:HIGH:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!SRP:!CAMELLIA"](https://nodejs.org/api/tls.html#tls_modifying_the_default_tls_cipher_suite)
secureProtocol
default value: ["TLS_method"](https://www.openssl.org/docs/man1.1.0/ssl/ssl.html#Dealing-with-Protocol-Methods)
ecdhCurve
default value: [tls.DEFAULT_ECDH_CURVE](https://nodejs.org/api/tls.html#tls_tls_default_ecdh_curve)
the exact value depends on the version of node
most commonly:
older versions of node: "prime256v1"
newer versions of node: "auto"
--req-insecure is a flag to override the following environment variable to disable certificate validation for secure https requests:
[NODE_TLS_REJECT_UNAUTHORIZED](https://nodejs.org/api/cli.html#cli_node_tls_reject_unauthorized_value)= 0
equivalent to:
curl --insecure
wget --no-check-certificate
--req-secure-honor-server-cipher-order is a flag to set the following key in the request options Object to configure the context for secure https requests:
{honorCipherOrder: true}
--req-secure-ciphers is the value to assign to the following key in the request options Object to configure the context for secure https requests:
{ciphers: value}
--req-secure-protocol is the value to assign to the following key in the request options Object to configure the context for secure https requests:
{secureProtocol: value}
--req-secure-curve is the value to assign to the following key in the request options Object to configure the context for secure https requests:
{ecdhCurve: value}
--hooks is the filepath to a CommonJS module that exports a single JSON Object
each key is the name of a hook function
each value is the implementation of the corresponding Function
hook function signatures:
"redirect": (url) ⇒ new_url
conditionally redirect the URLs encountered in .m3u8 files before they are modified to pass through the proxy
"prefetch": (url) ⇒ boolean
conditionally decide whether to prefetch video segments on a per-URL basis
return value must be a strict boolean type (ie: true or false)
otherwise, the default behavior supersedes to only prefetch .ts files
"prefetch_segments": (prefetch_urls, max_segments, is_vod, seg_duration_ms, perform_prefetch) ⇒ new_prefetch_urls
conditionally filter the list of video segment URLs that are pending prefetch, when more than --max-segments are contained in an HLS manifest
inputs:
prefetch_urls
array of string video segment URLs
max_segments
integer that denotes the max length of the return value
is_vod
boolean that indicates whether the HLS manifest is for video-on-demand
if true:
the video is not a live stream
the HLS manifest is complete and contains URLs for every video segment that would be needed to play the entire stream from start to finish
seg_duration_ms
integer that represents the duration (ms) of each video segment in the HLS manifest
perform_prefetch
function that accepts an array of string video segment URLs, and immediately begins to prefetch all corresponding segments
return value:
array of string video segment URLs that is a subset of prefetch_urls
can be emtpy (ex: when using perform_prefetch)
pre-conditions:
the length of prefetch_urls is > max_segments
post-conditions:
the length of the return value array is <= max_segments
--prefetch is a flag to enable the prefetch and caching of video segments
when .m3u8 files are downloaded and modified inflight, all of the URLs in the playlist are known
at this time, it is possible to prefetch the video segments (.ts files)
when the video segments (.ts files) are requested at a later time, the data is already cached (in memory) and can be returned immediately
--max-segments is the maximum number of video segments (.ts files) to hold in each cache
this option is only meaningful when --prefetch is enabled
a cache is created for each unique HLS manifest URL all of the video segments (.ts files) associated with each distinct video stream are stored in isolation
when any cache grows larger than this size, the oldest data is removed to make room to store new data
when this option is not specified:
default value: 20
--cache-timeout is the maximum number of seconds that any segment cache can remain unused before its contents are cleared (to reduce wasted space in memory)
this option is only meaningful when --prefetch is enabled
when this option is not specified:
default value: 60
--cache-key sets the type of string used to represent keys in the cache hashtable when logged
this option is only meaningful when --prefetch is enabled
scope: v0.16.0 and earlier
keys in the cache hashtable used this string representation v0.16.1 and later
keys in the cache hashtable are full URLs the data structure to cache video segments (.ts files) was updated each unique HLS manifest is associated with a distinct FIFO list that holds --max-segments when a video segment is requested
the proxy needs to search every FIFO list for a match
when keys in the cache hashtable lose fidelity, collisions can occur and the wrong video segment can be returned
full URLs are unique and guarantee correct behavior
0 (default):
sequence number of .ts file w/ .ts file extension (ex: "123.ts")
pros:
shortest type of string
makes the log output easiest to read
cons:
in the wild, I’ve encountered video servers that assign each .ts file a unique filename that always terminate with the same static sequence number
this is a strange edge case, but this option provides an easy workaround
1:
full filename of .ts file
2:
full URL of .ts file
-v sets logging verbosity level:
-1:
silent
0 (default):
show errors only
1:
show an informative amount of information
2:
show technical details
3:
show an enhanced technical trace (useful while debugging unexpected behavior)
--acl-whitelist restricts proxy server access to clients at IP addresses in whitelist
ex: "192.168.1.100,192.168.1.101,192.168.1.102"
print help<br> hlsd --help
print version<br> hlsd --version
start HTTP proxy at default host:port<br> hlsd
start HTTP proxy at default host and specific port<br> hlsd --port "8080"
start HTTP proxy at specific host:port<br> hlsd --host "192.168.0.100" --port "8080"
start HTTPS proxy at default host:port<br> hlsd --tls
start HTTPS proxy at specific host:port<br> hlsd --tls --host "192.168.0.100" --port "8081"
start HTTPS proxy at default host:port and send specific HTTP headers<br> hlsd --tls --req-headers "/path/to/request/headers.json"
start HTTPS proxy at default host:port and enable prefetch of 10 video segments<br> hlsd --tls --prefetch --max-segments 10 - - -
identical to the [command-line binary](#installation-and-usage-globally). print help<br> npm start — --help. start HTTP proxy at specific host:port<br> npm start — --host "192.168.0.100" --port "8080". start HTTPS proxy at specific host:port<br> npm start — --host "192.168.0.100" --port "8081" --tls. start HTTP proxy at default host:port with escalated privilege<br> npm run sudo — --port "80". start HTTPS proxy at default host:port with escalated privilege<br> npm run sudo — --port "443" --tls. start HTTP proxy at specific port and send custom "Referer" request header for specific video stream<br> ```bash npm start — --port "8080". URL='https://httpbin.org/headers' URL="${URL}|${h_referer}" URL=$(echo -n "$URL" | base64 --wrap=0) URL="http://127.0.0.1:8080/${URL}.json" # URL='http://127.0.0.1:8080/aHR0cHM6Ly9odHRwYmluLm9yZy9oZWFkZXJzfGh0dHA6Ly9YWFg6ODAvcGFnZS5odG1s.json' curl --silent "$URL". URL='https://127.0.0.1:8081/aHR0cHM6Ly9odHRwYmluLm9yZy9oZWFkZXJz.json' curl --silent --insecure "$URL".
identical to the [command-line binary](#installation-and-usage-globally)
print help<br> npm start — --help
start HTTP proxy at specific host:port<br> npm start — --host "192.168.0.100" --port "8080"
start HTTPS proxy at specific host:port<br> npm start — --host "192.168.0.100" --port "8081" --tls
start HTTP proxy at default host:port with escalated privilege<br> npm run sudo — --port "80"
start HTTPS proxy at default host:port with escalated privilege<br> npm run sudo — --port "443" --tls
start HTTP proxy at specific port and send custom "Referer" request header for specific video stream<br> ```bash npm start — --port "8080"
start HTTPS proxy at specific port and send custom request headers<br> ```bash headers_file="${TMPDIR}/headers.json" echo '{"Origin" : "http://XXX:80", "Referer": "http://XXX:80/page.html"}' > "$headers_file" npm start — --port "8081" --req-headers "$headers_file" --tls -v 1
- - -
when playing the proxied HLS video stream in an HTML5 player in a Chromium web browser (ex: THEOplayer)
if the page hosting the HTML5 video player is served from HTTPS:
when running only the HTTP proxy server:
the XHR requests from the player to the HTTP proxy server raise a security warning (insecure content)
the XHR requests get elevated to HTTPS, which are unanswered (since the HTTPS proxy server isn’t running)
when running only the HTTPS proxy server:
the XHR requests from the player to the HTTPS proxy server will silently fail
this is because the HTTPS proxy server is using a self-signed security certificate
this certificate needs to be (temporarily) allowed
once it is, the video stream works perfectly
to allow the certificate:
browse to a URL hosted by the proxy server ( [example](https://127.0.0.1:443/aHR0cHM6Ly9naXRodWIuY29tL3dhcnJlbi1iYW5rL0hMUy1wcm94eS9yYXcvbWFzdGVyL3BhY2thZ2UuanNvbg==.json) )
you should see the warning: NET::ERR_CERT_AUTHORITY_INVALID Your connection is not private
click: Advanced
click: Proceed to 127.0.0.1 (unsafe)
done
when playing the proxied HLS video stream on a Chromecast
the HTTP proxy server works perfectly
the HTTPS proxy server doesn’t begin playback
not sure why..
probably has something to do with the Chromecast’s browser security policies
a more respectable security certificate (ie: more expensive) would probably fix it
error:<br> ssl3_check_cert_and_algorithm:dh key too small attempted fix:<br> --req-secure-ciphers "AES128-SHA"
error:<br> SSL routines:SSL23_GET_SERVER_HELLO:sslv3 alert handshake failure attempted fix:<br> --req-secure-protocol "SSLv3_method"
result:<br> Error: SSLv3 methods disabled
issue:
[node #3695](https://github.com/nodejs/node/issues/3695) attempted fix:<br> --req-secure-curve "auto" - - -
copyright: [Warren Bank](https://github.com/warren-bank)
license: [GPL-2.0](https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt)