_Node.js HLS Proxy_ : HTTP Live Streaming Proxy for the _Node JS_ Runtime

Basic Functionality:

• proxy .m3u8 files, and the video segments (.ts files) they internally reference
• to all proxied files:

• to .m3u8:

Advanced Features:

• inject custom HTTP headers in all outbound proxied requests
• prefetch video segments (.ts files)
• use a hook function to conditionally decide which video segments to prefetch
• use a hook function to conditionally redirect URLs in the playlist (_before_ and/or _after_ they're modified to pass through the proxy)
• use a hook function to conditionally rewrite URLs after they're received by the proxy

Benefits:

• any video player (on the LAN) can access the proxied video stream

• prefetch and caching of video segments ahead-of-time makes playback of the video stream very stable

• the proxy can easily be configured to bypass many of the security measures used by video servers to restrict access:

• - - -

URL Format:

• [example Javascript]: construction of URL to _HLS Proxy_ for video stream

{
      const proxy_url      = 'http://127.0.0.1:8080'
      const video_url      = 'https://example.com/video/master.m3u8'
      const file_extension = '.m3u8'
const hls_proxy_url  = ${proxy_url}/${ btoa(video_url) }${file_extension}
    }

• [example Javascript]: construction of URL to _HLS Proxy_ for video stream w/ "Referer" request header

{
      const proxy_url      = 'http://127.0.0.1:8080'
      const video_url      = 'https://example.com/video/master.m3u8'
      const referer_url    = 'https://example.com/videos.html'
      const file_extension = '.m3u8'

const hls_proxy_url  = ${proxy_url}/${ btoa(${video_url}|${referer_url}) }${file_extension}
    }

• [example Javascript]: construction of URL to _HLS Proxy_ for video stream w/ "Referer" and additional request headers

{
      const proxy_url      = 'http://127.0.0.1:8080'
      const video_url      = 'https://example.com/video/master.m3u8'
      const referer_url    = 'https://example.com/videos.html'
      const file_extension = '.m3u8'
      const headers        = {"Cookie": "foo=bar"}

const querystring    = ?headers=${ encodeURIComponent( btoa( JSON.stringify(headers) ) ) }
      const hls_proxy_url  = ${proxy_url}/${ btoa(${video_url}|${referer_url}) }${file_extension}${querystring}
    }

• [example Bash]: construction of URL to _HLS Proxy_ for video stream

proxy_url='http://127.0.0.1:8080'
    video_url='https://example.com/video/master.m3u8'
    file_extension='.m3u8'

hls_proxy_url="${proxy_url}/"$(echo -n "$video_url" | base64 --wrap=0)"$file_extension"

• [example Bash]: construction of URL to _HLS Proxy_ for video stream w/ "Referer" request header

proxy_url='http://127.0.0.1:8080'
    video_url='https://example.com/video/master.m3u8'
    referer_url='https://example.com/videos.html'
    file_extension='.m3u8'

hls_proxy_url="${proxy_url}/"$(echo -n "${video_url}|${referer_url}" | base64 --wrap=0)"$file_extension"

• [example Bash]: construction of URL to _HLS Proxy_ for video stream w/ "Referer" and additional request headers

proxy_url='http://127.0.0.1:8080'
    video_url='https://example.com/video/master.m3u8'
    referer_url='https://example.com/videos.html'
    file_extension='.m3u8'
    headers_json='{"Cookie": "foo=bar"}'

querystring='?headers='$(echo -n "$headers_json" | base64 --wrap=0)
    hls_proxy_url="${proxy_url}/"$(echo -n "${video_url}|${referer_url}" | base64 --wrap=0)"${file_extension}${querystring}"

##### notes:

• adding a file extension to the base64 encoded video URL is highly recommended

##### high-level tools that automate this task:

• refer to the section: Other Projects

• - - -

Installation and Usage: Globally

How to: Install:

npm install --global "@warren-bank/hls-proxy"

How to: Run the server(s):

hlsd <options>
options:
========
--help
--version
--tls
--host <host>
--port <number>
--copy-req-headers
--req-headers <filepath>
--origin <header>
--referer <header>
--useragent <header>
--header <name=value>
--req-options <filepath>
--req-insecure
--req-secure-honor-server-cipher-order
--req-secure-ciphers <string>
--req-secure-protocol <string>
--req-secure-curve <string>
--hooks <filepath>
--prefetch
--max-segments <number>
--cache-timeout <number>
--cache-key <number>
--cache-storage <adapter>
--cache-storage-fs-dirpath <dirpath>
-v <number>
--acl-ip <ip_address_list>
--acl-pass <password_list>
--block-req-hostname <hostname_list>
--http-proxy <http[s]://[user:pass@]hostname:port>
--tls-cert <filepath>
--tls-key <filepath>
--tls-pass <filepath>
--manifest-extension <ext>
--segment-extension <ext>

Options:

• _--tls_ is a flag to start HTTPS proxy, rather than HTTP

• _--host_ is an IP or hostname with an optional port number that can be resolved and is reachable by clients

• _--port_ is the port number that the server listens on

• _--copy-req-headers_ is a flag to enable the duplication of all HTTP request headers sent to the proxy → to the request made by the proxy to the video server
• _--req-headers_ is the filepath to a JSON data _Object_ containing key:value pairs

• _--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

• _--req-options_ is the filepath to a JSON data _Object_

• _--req-insecure_ is a flag to override the following environment variable to disable certificate validation for secure __https__ requests:

• _--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:

• _--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:

• _--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:

• _--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:

• _--hooks_ is the filepath to a CommonJS module that exports a single JSON _Object_

module.exports = {
            request_intervals: (add_request_interval) => {
add_request_interval(
                0, // run timer once at startup to initialize cookies
                (request) => {
                  request('https://example.com/login', {username: 'me', password: '12345'})
                }
              )
add_request_interval(
                (1000  60  5), // run timer at 5 minute intervals to refresh cookies
                (request, timer_id) => {
                  request('https://example.com/heart-beat')
if (globalThis.someCondition)
                    clearInterval(timer_id)
                },
                (1000  60  60 * 1) // automatically stop after a max duration of 1 hour
              )
}
          }

• _--prefetch_ is a flag to enable the prefetch and caching of video segments

• _--max-segments_ is the maximum number of video segments (.ts files) to hold in each cache

• _--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)

• _--cache-key_ sets the type of string used to represent keys in the cache hashtable when logged

• _--cache-storage_ selects a storage adapter that is used to hold the cache of prefetched video segments

• _--cache-storage-fs-dirpath_ specifies the directory in which to save video segments when using a filesystem-based cache storage adapter

• _-v_ sets logging verbosity level:

• _--acl-ip_ restricts proxy server access to clients at IP addresses in whitelist

• _--acl-pass_ restricts proxy server access to requests that include a password querystring parameter having a value in whitelist

• _--block-req-hostname_ blocks proxy server requests to hostnames in blacklist

• --http-proxy enables all outbound HTTP and HTTPS requests from HLS-Proxy to be tunnelled through an additional external web proxy server

• _--tls-cert_ is the filepath to a security certificate to use for HTTPS
• _--tls-key_ is the filepath to the private key for the _--tls-cert_ security certificate
• _--tls-pass_ is the filepath to a text file containing the security passphrase for the _--tls-key_ private key

• _--manifest-extension_ is the file extension associated with HLS manifests

• _--segment-extension_ is the file extension associated with media segments

Examples:

1. print help
   

1. print version
   

1. start HTTP proxy at default host:port
   

1. start HTTP proxy at default host and specific port
   

1. start HTTP proxy at specific host:port
   

1. start HTTPS proxy at default host:port
   

1. start HTTPS proxy at specific host:port
   

1. start HTTPS proxy at default host:port and send specific HTTP headers
   

1. start HTTPS proxy at default host:port and enable prefetch of 10 video segments
   

1. start HTTPS proxy using a non-generic security certificate
   

• - - -

Installation and Usage: Working with a Local git Repo

How to: Install:

git clone "https://github.com/warren-bank/node-HLS-Proxy.git"
cd "HLS-Proxy"
npm install

How to: Run the server(s):

# ----------------------------------------------------------------------
If using a port number >= 1024 on Linux, or
If using Windows:
----------------------------------------------------------------------
npm start [-- <options>]
----------------------------------------------------------------------
https://www.w3.org/Daemon/User/Installation/PrivilegedPorts.html
#
Linux considers port numbers < 1024 to be privileged.
Use "sudo":
----------------------------------------------------------------------
npm run sudo [-- <options>]

Options:

• identical to the command-line binary

Examples:

1. print help
   

1. start HTTP proxy at specific host:port
   

1. start HTTPS proxy at specific host:port
   

1. start HTTP proxy at default host:port with escalated privilege
   

1. start HTTPS proxy at default host:port with escalated privilege
   

1. start HTTP proxy at specific port and send custom "Referer" request header for specific video stream
   

npm start -- --port "8080"
h_referer='http://XXX:80/page.html'
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"

1. start HTTP proxy at specific port and send custom request headers
   

headers_file="${TMPDIR}/headers.json"
echo '{"Origin" : "http://XXX:80", "Referer": "http://XXX:80/page.html"}' > "$headers_file"
npm start -- --port "8080" --req-headers "$headers_file"
URL='https://httpbin.org/headers'
URL=$(echo -n "$URL" | base64 --wrap=0)
URL="http://127.0.0.1:8080/${URL}.json"
URL='http://127.0.0.1:8080/aHR0cHM6Ly9odHRwYmluLm9yZy9oZWFkZXJz.json'
curl --silent "$URL"

1. start HTTPS proxy at specific port and send custom request headers
   

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
URL='https://127.0.0.1:8081/aHR0cHM6Ly9odHRwYmluLm9yZy9oZWFkZXJz.json'
curl --silent --insecure "$URL"

1. start HTTPS proxy at specific port and send custom request headers
   

h_origin='http://XXX:80'
h_referer='http://XXX:80/page.html'
h_useragent='Chromium'
h_custom_1='X-Foo: 123'
h_custom_2='X-Bar: baz'
npm start -- --port "8081" --origin "$h_origin" --referer "$h_referer" --useragent "$h_useragent" --header "$h_custom_1" --header "$h_custom_2" --tls -v 1
URL='https://127.0.0.1:8081/aHR0cHM6Ly9odHRwYmluLm9yZy9oZWFkZXJz.json'
curl --silent --insecure "$URL"

• - - -

Observations:

• when playing the proxied HLS video stream in an HTML5 player in a Chromium web browser (ex: THEOplayer)

• when playing the proxied HLS video stream on a Chromecast

Summary of (Rarely) Observed OpenSSL Connection Errors:

• error:
  

• error:
  

• - - -

Other Projects:

• Webcast-Reloaded

• - - -

Other Projects:

• Streamlink

• - - -

Major Versions:

• v1.x

• v2.x

• v3.x

• - - -

Legal:

• copyright: Warren Bank
• license: GPL-2.0