...
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
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:
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
hls_static_enabled=true |
The player page should be in directory defined by the following parameter
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
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:
...
REST query | Body example | Response example | Response state | Desctiption | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
/hls/startup |
| 200 - OK 404 - Stream not found 500 - Internal error | Start HLS agent for the stream | |||||||||||||||
/hls/find_all |
|
| 200 – OK 404 – Not found | Find all streams having HLS agents | ||||||||||||||
/hls/terminate |
| 200 – OK 404 – Not found | Stop or restart HLS agent for the stream | |||||||||||||||
/hls/profiles |
|
| 200 – OK 400 – Bad request 404 – Not found | Get HLS profile statistics | ||||||||||||||
/hls/subscribers |
|
| 200 – OK 400 – Bad request 404 – Not found | Get HLS subscribers statistics | ||||||||||||||
/hls/enableRecordingconnections |
|
| 200 – OK 400 – Bad request 404 – Not found 500 - Internal server error | Get a list of HLS clients connected to the server | ||||||||||||||
/hls/enableRecording |
| 200 – OK 400 – Bad request 404 – Not found 409 - Conflict 500 - Internal server error | Enable HLS stream debug segments recording | |||||||||||||||
/hls/disableRecording |
| 200 – OK 400 – Bad request 404 – Not found | Disable HLS stream debug segments recording |
...
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
Code Block | ||
---|---|---|
| ||
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:
Code Block | ||||
---|---|---|---|---|
| ||||
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
Code Block | ||||
---|---|---|---|---|
| ||||
POSTcurl /rest-api/hls/disableRecording-s 'http://wcs:8081/?action=stat¶ms=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
Code Block | ||
---|---|---|
| ||
hls_debug_dir=hls-debug |
Segments recording for a certain stream may be started with REST API query /hls/enableRecording
Code Block | ||||
---|---|---|---|---|
| ||||
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
Code Block | ||||
---|---|---|---|---|
| ||||
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
...
Code Block | ||
---|---|---|
| ||
hls_ll_enabled=true hls_auto_start=true hls_preloader_enabled=false hls_player_width=848 hls_player_height=480 video_filter_enable_fps=true video_filter_fps=30 video_encoder_h264_gop=60 |
Using HTTP/2 and HTTP/1
According to specification, LL HLS must be Since build 5.2.1965, the following parameter is enough to play LL HLS, a defaults may be used for other settings
Code Block | ||
---|---|---|
| ||
hls_ll_enabled=true |
Using HTTP/2 and HTTP/1
According to specification, LL HLS must be played using HTTP/2, i.e. via secure connection
...
To restore default preloader it is enough to remove custom preloader files and restart WCS.
...
A settings applied both for LL and non-LL HLS
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
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
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:
Code Block | ||
---|---|---|
| ||
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
Warning |
---|
Since build 5.2.1793, the parameter is removed. The unified network stack is always used to deliver both HLS and LL HLS segments. |
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:1965 all the settings with hls_
prefix are applied both to LL and non-LL HLS.
The following parameters are applied to LL HLS only and not applied to non-LL HLS
Parameter | Description | Default value |
---|---|---|
ll_hls_max_number_of_parent_segments_containing_partials | A maximum partial segments number per one parent segment | 5 |
ll_hls_part_hold_back_count | PART-HOLD-BACK attribute value in playlist | 6 |
ll_hls_partial_time_max | A maximum partial segment size in milliseconds | 400 |
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
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
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:
Code Block | ||
---|---|---|
| ||
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
Warning |
---|
Since build 5.2.1793, the parameter is removed. The unified network stack is always used to deliver both HLS and LL HLS segments. |
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:
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
https://wcs:8445/stream/stream.m3u8 |
and to get HLS ABR manifest
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
https://wcs:8445/stream/playlist.m3u8 |
and to get HLS ABR manifest
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
hls_delayed_shutdown=true |
The delay depends on playlist size
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
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)
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
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
Code Block | ||
---|---|---|
| ||
https://wcs:8445/stream/playlist.m3u8 |
and to get HLS ABR manifest
Code Block | ||
---|---|---|
| ||
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
...