...

		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
}

[
  {
    "testip": "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"
  ]
}

...

Where 8445 is HTTPS HLS port of WCS server

...

Displaying a list of HLS clients connected to the server

Since build 5.2.19131968 it is possible to record a segments and a playlists for a certain HLS stream played by subscribers for debugging purposes. Segments will be recorded to the folder set by the following parameter

hls_debug_dir=hls-debug

Segments recording for a certain stream may be started with REST API query /hls/enableRecording display a list of HLS clients connected to the server. The list is returned in response to the /hls/connections query:

POST /rest-api/hls/enableRecording HTTP/1.1
Host: localhost:8081
Content-Type: application/json

[
  {
    "idsip": [
    "192.168.0.83",
    "testport": 51708,
    "userAgent": "Mozilla/5.0 (X11;  "test-HLS-ABR-STREAM"
    ] 
}

...

Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36"
  }
]

Where:

• 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

POSTcurl /rest-api/hls/disableRecording-s 'http://wcs:8081/?action=stat&params=connections_hls'

HLS stream segments recording to disk for debugging purposes

Since build 5.2.1913 it is possible to record a segments and a playlists for a certain HLS stream played by subscribers for debugging purposes. Segments will be recorded to the folder set by the following parameter

hls_debug_dir=hls-debug

Segments recording for a certain stream may be started with REST API query /hls/enableRecording 

POST /rest-api/hls/enableRecording HTTP/1.1
Host: localhost:8081
Content-Type: application/json

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

Use a various media parsing and the REST API query /hls/disableRecording to stop the recording

POST /rest-api/hls/disableRecording HTTP/1.1
Host: localhost:8081
Content-Type: application/json

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

Use a various media parsing and playing tools like ffmpeg, ffprobe etc to work with a segments recorded. Also, the debud stream recording may be played from the server using the URL with -DEBUG suffix

...

The following parameters are applied to LL HLS only and not applied to non-LL HLS only and not applied to non-LL HLS

...

ll_hls_part_hold_back_count

...

ll_hls_partial_time_max

...

m4s container support

Since build 5.2.1626 m4s container is supported for HLS segments cut, and since build 5.2.1632 the container is enabled by default for HLS ABR too

ll_hls_fragmented_mp4=true

Since build 5.2.1724, m4s container is supported for HLS ABR in CDN.

You can switch back to the ts container if necessary

ll_hls_fragmented_mp4=false

Using a common network stack for HLS and Low Latency HLS

Since build 5.2.1749 the parameter allowing an unified network stack usage both for HLS and Low latency HLS is added. The parameter is enabled by default:

use_new_hls=true

In this case:

• m4s container is used by default to record an HLS segments
• parameters with hls prefix are applied both to HLS and LL HLS
• parameters with ll_hls prefox are applied to LL HLS and to m4s container

Manifest URL setup

Since build 5.2.1852, an URL templates to request a stream main playlist (manifest) may be customized. By default, the following templates are used:HLS

m4s container support

Since build 5.2.1626 m4s container is supported for HLS segments cut, and since build 5.2.1632 the container is enabled by default for HLS ABR too

ll_hls_fragmented_mp4=true

Since build 5.2.1724, m4s container is supported for HLS ABR in CDN.

You can switch back to the ts container if necessary

ll_hls_fragmented_mp4=false

Using a common network stack for HLS and Low Latency HLS

Since build 5.2.1749 the parameter allowing an unified network stack usage both for HLS and Low latency HLS is added. The parameter is enabled by default:

use_new_hls=true

In this case:

• m4s container is used by default to record an HLS segments
• parameters with hls prefix are applied both to HLS and LL HLS
• parameters with ll_hls prefox are applied to LL HLS and to m4s container

Manifest URL setup

Since build 5.2.1852, an URL templates to request a stream main playlist (manifest) may be customized. By default, the following templates are used:

hls_path_template={streamName}/{streamName}.m3u8
hls_abr_path_template={streamName}{abrSuffix}/{streamName}{abrSuffix}.m3u8

Where:

• streamName - stream published name
• abrSuffix - HLS ABR stream suffix set by hls_abr_stream_name_suffix parameter

In this case, the following URLs should be used to get HLS manifest

https://wcs:8445/stream/stream.m3u8

and to get HLS ABR manifest

https://wcs:8445/stream-HLS-ABR-STREAM/stream-HLS-ABR-STREAM.m3u8

For example, if a fixed manifest name different for HLS ABR and non-ABR streams is preferred to use, then the following templates should be set

hls_path_template={streamName}/playlist.m3u8
hls_abr_path_template={streamName}/playlist{abrSuffix}.m3u8

In this case, the following URLs should be used to get HLS manifest

https://wcs:8445/stream/playlist.m3u8

and to get HLS ABR manifest

https://wcs:8445/stream/playlist-HLS-ABR-STREAM.m3u8

HLS provider shutdown when source stream is stopped

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_pathdelayed_template={streamName}/{streamName}.m3u8
hls_abr_path_template={streamName}{abrSuffix}/{streamName}{abrSuffix}.m3u8

Where:

• streamName - stream published name
• abrSuffix - HLS ABR stream suffix set by hls_abr_stream_name_suffix parameter

...

shutdown=false

In this case HLS provider will 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)

https://wcs:8445/stream/stream.m3u8

...

hls_time_min=2000

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

https://wcs:8445/stream-HLS-ABR-STREAM/stream-HLS-ABR-STREAM.m3u8

...

hls_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_path_template={streamName}/playlist.m3u8
hls_abr_path_template={streamName}/playlist{abrSuffix}.m3u8

In this case, the following URLs should be used to get HLS manifest

https://wcs:8445/stream/playlist.m3u8

and to get HLS ABR manifest

https://wcs:8445/stream/playlist-HLS-ABR-STREAM.m3u8keep_min_segment_duration=true

In this case a segment size will not be less than hls_time_min.

Known issues

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

...