...

		location ~* ^.+.(ts)$ {
		    proxy_pass https://localhost:8445;
		    proxy_http_version  1.1;
		    proxy_set_header    Host $server_name:$server_port;
		    proxy_set_header    X-Forwarded-Host $http_host;
		    proxy_set_header    X-Forwarded-Proto $scheme;
		    proxy_set_header    X-Forwarded-For $remote_addr;
		    proxy_set_header    Upgrade $http_upgrade;
		    proxy_set_header    Connection "upgrade";
            proxy_cache proxy_cache;
            proxy_cache_key $host$uri$is_args$args;
            proxy_cache_valid 200 2m;
       	}

		location ~* ^.+.(m3u8)$ {
		    proxy_pass https://localhost:8445;
		    proxy_http_version  1.1;
		    proxy_set_header    Host $server_name:$server_port;
		    proxy_set_header    X-Forwarded-Host $http_host;
		    proxy_set_header    X-Forwarded-Proto $scheme;
		    proxy_set_header    X-Forwarded-For $remote_addr;
		    proxy_set_header    Upgrade $http_upgrade;
		    proxy_set_header    Connection "upgrade";
            proxy_cache off;
            expires -1;
       	}

Returning of static HTML pages on HLS port

Another way to workaround cross domain requests restrictions in browser is to return a static content, player page for example, on the same port that returns HLS content. To enable this feature, the following parameter should be set in flashphoner.properties file

hls_static_enabled=true

...

Passing a custom parameters when requesting a playlist

A custom parameters should be passed when requesting a playlist if reverse proxy authentication is set up:

hls_static_dir=client2/examples/demo/streaming/hls_static

...

https://wcs:8445/test/test.m3u8?key1=value1&key2=value2

The feature is supported since build 5.2.1959. The parameters passed will be returned in every playlist for every segment, this allows to authorize a viewer correctly on proxy server.

There will be an additional parameter sessionId in playlists, for example

hlsav_statictest_dir=/var/www/html/hls_static

If static content returning is enabled, browser will display the HLS player page by URL https://host:8445/hls-player.html. If this feature is disabled, server will return 404 Not found error by such URL.

Preloader for HLS stream playback

...

o/av_test_o.m3u8?sessionId=11&key1=value1&key2=value2

This is the internal WCS parameter to identify the subscriber for statistical purposes.

Returning of static HTML pages on HLS port

Another way to workaround cross domain requests restrictions in browser is to return a static content, player page for example, on the same port that returns HLS content. To enable this feature, the following parameter should be set in flashphoner.properties file

hls_static_enabled=true

The player page should be in directory defined by the following parameter

hls_static_dir=client2/examples/demo/streaming/hls_static

In this case (by default) the path to the player page files is set relative to WCS installation directory. A full path may also be set, for example

hls_static_dir=/var/www/html/hls_static

If static content returning is enabled, browser will display the HLS player page by URL https://host:8445/hls-player.html. If this feature is disabled, server will return 404 Not found error by such URL.

Preloader for HLS stream playback

When first HLS subscribes connects to a stream on WCS server, especilally to CDN stream, it may take a time to split a stream to HLS segmets and to form a playlist. As a result, Safari browser on iOS devices may not be able to play HLS stream on the first attempt. To successfully play HLS stream in this case, the HLS preloader was added since build 5.2.371. The default preloader looks like this:

...

{
  "name":"test"
}

{
  "offset":0,
  "size":10
}

[{
    "id": "test",
    "streamName": "test",
    "status": "ACTIVE",
    "waitingSize": 0,
    "profiles": [
      "a_test",
      "v_test"
    ],
    "subscribers": 1,
    "playlist": "...",
    "createdDate": 1697605114475,
    "logs": []
}]

{
  "name":"test"
}

{
  "hlsId":"test",
  "profileName":"v_test" }

{
  "name": "v_test",
  "stream": {
    "appKey": "defaultApp",
    "sessionId": "test-HLS",
    "mediaSessionId": "81b8b278-612e-4b72-9153-454be9df0a34-test-HLS",
    "name": "test",
    "published": false,
    "hasVideo": false,
    "hasAudio": true,
    "status": "PLAYING",
    "sdp": "...",
    "videoCodec": "H264",
    "record": false,
    "width": 1280,
    "height": 720,
    "bitrate": 0,
    "minBitrate": 0,
    "maxBitrate": 0,
    "quality": 0,
    "parentMediaSessionId": "f3401d2e-7e9a-4e18-a353-d323c947ac94",
    "history": false,
    "gop": 0,
    "fps": 0,
    "audioBitrate": 0,
    "codecImpl": "",
    "transport": "UDP",
    "cvoExtension": true,
    "createDate": 1697605114875,
    "mediaType": "play",
    "audioState": {
      "muted": false
    },
    "videoState": {
      "muted": false
    },
    "mediaProvider": "HLS"
  },
  "keyFrameReceived": true,
  "videoProfile": {
    "type": "video",
    "width": 1280,
    "height": 720,
    "fps": 29,
    "bitrate": 1720,
    "codec": "",
    "quality": 0,
    "audioGroupId": "audio"
  },
  "metrics": {
    "minFPS": 29.962547,
    "avgFPS": 30.000088,
    "maxFPS": 30.04292,
    "countGaps": 0,
    "resolutionChanges": 0,
    "queueSize": 10,
    "startPts": 375400,
    "currentPts": 375400
  },
  "subscribers": 1
}

{
  "hlsId":"test"
}

[
  {
    "id": "192.168.0.83-59000-Mozilla/5.0 (X11; Linux x86_64) Chrome/118.0.0.0",
    "ip": "192.168.0.83",
    "port": 59000,
    "userAgent": "Mozilla/5.0 (X11; Linux x86_64) Chrome/118.0.0.0",
    "active": true,
    "metrics": {
      "profileTime": {
        "test": 71,
        "v_test": 541353
      },
      "requestsNumber": 5930,
      "requestsStatuses": {
        "200 OK": 5930
      },
      "profileSwitches": 1,
      "maxResponseTime": 29,
      "minResponseTime": 0,
      "avgResponseTime": 0.4436762225969646
    }
  }
]

{
  "idsoffset":0,
  "size":10
}

[
  {
   "test "ip": "192.168.0.83",
    "test-HLS-ABR-STREAM"
  ]
}port": 51708,
    "userAgent": "Chrome/125.0.0.0 Safari/537.36"
  }
]

{
  "ids": [
    "test",
    "test-HLS-ABR-STREAM"
  ]
}

{
  "ids": [
    "test",
    "test-HLS-ABR-STREAM"
  ]
}

...

[
  {
    "id": "192.168.0.83-59000-Mozilla/5.0 (X11; Linux x86_64) Chrome/118.0.0.0",
    "ip": "192.168.0.83",
    "port": 59000,
    "userAgent": "Mozilla/5.0 (X11; Linux x86_64) Chrome/118.0.0.0",
    "active": true,
    "metrics": {
      "profileTime": {
        "test": 71,
        "v_test": 541353
      },
      "requestsNumber": 5930,
      "requestsStatuses": {
        "200 OK": 5930
      },
      "profileSwitches": 1,
      "maxResponseTime": 29,
      "minResponseTime": 0,
      "avgResponseTime": 0.4436762225969646
    }
  }
]

Where:

• id - subscriber identifier
• ip - subscriber IP address
• port -  subscriber source port
• userAgent - User-Agent header sent by subscriber
• active - subscriber is active
• metrics - current subscriber metrics:
  • profileTime - the time the subscriber requested the profile shown by profile
  • requestsNumber - subscribers requests number
  • requestStatuses - response status codes count sent to the subscriber shown by response status code
  • profileSwitches - HLS ABR profile switches count for the subscriber
  • maxResponseTime - maximum response time
  • minResponseTime - minimum response time
  • avgResponseTime - average response time

HLS subscribers and connections displaying issues

In the response to the /hls/find_all, /hls/profiles, /hls/subscribers  queries a current HLS subscribers count and information are returned as per browser tabs. But HLS network connections count displaying at WCS statistics page

curl -s http://localhost:8081/?action=stat&params=connections_hls

may differ from HLS subscribers count. In the most cases, HLS subscribers use HTTP 2 protocol to connect and download a segments, then all the browser tabs receiving HLS streams from the same WCS server will use the same network connection.

In this case connections count displayed by connections_hls parameter is usually equal to HLS port connections count displayed by netstat command:

sudo netstat -np | grep ESTABLISHED | grep java | grep 8445

Where 8445 is HTTPS HLS port of WCS server

Displaying a list of HLS clients connected to the server

Since build 5.2.1968 it is possible to display a list of HLS clients connected to the server. The list is returned in response to the /hls/connections query:

[
  {
      "200 OKip": 5930
      },
      "profileSwitches": 1"192.168.0.83",
      "maxResponseTimeport": 2951708,
      "minResponseTimeuserAgent": "Mozilla/5.0,
 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML,  "avgResponseTime": 0.4436762225969646
    }like Gecko) Chrome/125.0.0.0 Safari/537.36"
  }
]

Where:

• id - subscriber identifier
• ip - subscriber IP address
• port -  subscriber source port
• userAgent - User-Agent header sent by subscriber
• active - subscriber is active
• metrics - current subscriber metrics:
  • profileTime - the time the subscriber requested the profile shown by profile
  • requestsNumber - subscribers requests number
  • requestStatuses - response status codes count sent to the subscriber shown by response status code
  • profileSwitches - HLS ABR profile switches count for the subscriber
  • maxResponseTime - maximum response time
  • minResponseTime - minimum response time
  • avgResponseTime - average response time

HLS subscribers and connections displaying issues

In the response to the /hls/find_all, /hls/profiles, /hls/subscribers  queries a current HLS subscribers count and information are returned as per browser tabs. But HLS network connections count displaying at WCS statistics page:

• ip - client address
• port - client source port
• userAgent - User-Agent header sent by the client

For HTTPS clients all the tabs of the same browser window on the same PC will be displayed at one position because HTTP/2 uses the same TCP connection for all HTTPS connections.

A clients count in the list will be the same as the statistics page value

curl -s 'http://localhostwcs:8081/?action=stat&params=connections_hls

may differ from HLS subscribers count. In the most cases, HLS subscribers use HTTP 2 protocol to connect and download a segments, then all the browser tabs receiving HLS streams from the same WCS server will use the same network connection.

In this case connections count displayed by connections_hls parameter is usually equal to HLS port connections count displayed by netstat command:

sudo netstat -np | grep ESTABLISHED | grep java | grep 8445

...

connections_hls'

HLS stream segments recording to disk for debugging purposes

...

...

Since build 5.2.1920 it is possible to control HLS provider shutdown when a source stream publishing on the server is stopped. By default, the HLS provider is stopped with a delay

hls_delayed_shutdown=true

The delay depends on playlist size

hls_list_size=8

Thus, a subscribers playing the HLS stream may play a rest of playlist if the source stream is stopped.

The delayed shutdown may be disabled if needed

hls_delayed_shutdown=false

In this case HLS provider is stopped with a delaywill be stopped right after the source stream is stopped.

HLS segments size control

By default HLS segments will be cut either by key frame receiving or by reaching the size set by the following parameter (2000 ms by default)

hls_delayedtime_shutdownmin=true

...

2000

Since build 5.2.1974 it is possible to enable HLS segments cutting by key frame receiving only

hls_list_size=8

Thus, a subscribers playing the HLS stream may play a rest of playlist if the source stream is stopped.

...

always_start_segment_with_key_frame=true

In this case a segment size may exceed hls_time_min value, bur a minimal segment size may be less. The following parameter is used to strictly limit the minimal segments size

hls_delayed_shutdown=falsekeep_min_segment_duration=true

In this case HLS provider a segment size will be stopped right after the source stream is stoppednot be less than hls_time_min.

Known issues

1. Non-recoverable freeze of HLS stream played in iOS Safari through a CDN

...