...
Any of streams published via WebRTC, RTMP, MPEG-TS or captured from RTSP or RTMP source using REST API may be cut automatically to HLS segments. This feature may be enabled with the following parameter
Code Block |
---|
|
hls_auto_start=true |
Since build 5.2.1895 it is possible to start HLS ABR stream automatically if HLS ABR on a single node is used. This feature may be enabled with the following parameter
Code Block |
---|
|
hls_abr_auto_start=true |
HLS playback authentication using REST hook
...
If there are two profiles with the same name in the setup, server will use only the last profile with the same name.
Maximum playlist size
Maximum playlist size in segments is defined by the following parameter
Code Block |
---|
|
hls_list_size=8 |
By default, HLS playlist size is 8 segments. Note that HLS cut is just started, a segments quantity in the first playlists will be less than value set.
HLS segments storage
Using disk
...
Force transcoding of a maximum ABR quality only if there are B-frames in a source stream
To reduce a server load while video encoding, since WCS build 5.2.1840 it is possible to transcode a maximum ABR quality (which is usually the original stream resolution and bitrate) only if there are B-frames in a source stream. The feature may be enabled by the following parameter
Code Block |
---|
|
hls_dir=/usr/local/FlashphonerWebCallServer/hls |
(Preloader folder is configured separately with parameter hls_preloader_dir.)
...
h264_b_frames_force_transcoding=true |
In this case the server will detect B-frames in a stream analizing a certain frames count (10 by default)
Code Block |
---|
|
hlsframe_cnt_holdto_segmentsdetermine_beforetheir_deletetype=true |
By default, 5 last segments will be stored
Code Block |
---|
|
hls_hold_segments_size=5 |
For example, if playlist contains 3 segments
If there are B-frames in the stream, the maximum ABR quality will be transcoded and will be available for playback in the HLS manifest
Code Block |
---|
|
#EXTM3U
#EXT-X-STREAM-VERSION:8
#EXT-X-TARGETDURATION:11INF:BANDWIDTH=1000000,RESOLUTION=640x360,CODECS="avc1.42e01f,mp4a.40.2"
360/360.m3u8
#EXT-X-MEDIASTREAM-SEQUENCE:15INF:BANDWIDTH=2000000,RESOLUTION=1280x720,CODECS="avc1.42e01f,mp4a.40.2"
720/720.m3u8
#EXT-X-DISCONTINUITYSTREAM-SEQUENCE:1
#EXTINF:3.415,
test_017.ts
#EXTINF:10.417,
test_018.ts
#EXTINF:9.084,
test_019.ts |
...
INF:BANDWIDTH=2500000,RESOLUTION=1920x1080,CODECS="avc1.42e01f,mp4a.40.2"
1080/1080.m3u8 |
If there are no B-frames in the stream, the maximum ABR quality will not be transcoded
Code Block |
---|
|
test_012.ts
test_013.ts
test_014.ts
test_015.ts
test_016.ts
test_017.ts
test_018.ts
test_019.ts |
Using memory
...
#EXTM3U
#EXT-X-STREAM-INF:BANDWIDTH=1000000,RESOLUTION=640x360,CODECS="avc1.42e01f,mp4a.40.2"
360/360.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=2000000,RESOLUTION=1280x720,CODECS="avc1.42e01f,mp4a.40.2"
720/720.m3u8 |
The original quality should be requested separately from a playing client.
Since build 5.2.1916, the feature is available for HLS ABR in CDN. To activate it, all the CDN servers should be updated to build 5.2.1916 or newer, and the following parameters should be set on Edge server
Code Block |
---|
|
hls_store_segment_in_memory=true |
Segments will be read from memory to send them to subscribers. Note this will require more Java heap memory.
Since build 5.2.1713 HLS segments are stored in memory by default.
Debug logs for HLS session
For an error report, debug logging can be enabled for HLS sessions using CLI
Code Block |
---|
|
update node-setting --value true hls_enable_session_debug |
Note that config flashphoner.properties will be overwritten after the command.
Low Latency HLS support
...
cdn_strict_transcoding_boundaries=true
h264_b_frames_force_transcoding=true |
Maximum playlist size
Maximum playlist size in segments is defined by the following parameter
Code Block |
---|
|
hls_list_size=8 |
By default, HLS playlist size is 8 segments. Note that HLS cut is just started, a segments quantity in the first playlists will be less than value set.
HLS segments storage
Using disk
In builds before 5.2.1713HLS segments are written to server hard drive to the /usr/local/FlashphonerWebCallServer/hls
folder by default. Starting from build 5.2.687, the folder for saving segments can be changed using the following parameter
Code Block |
---|
|
hls_ll_enabled=true
hls_new_http_stack=true |
In this case, players supporting LL HLS (HLS.JS for example) will play additional HLS segments reducing playback latency comparing with players which do not play those segments (VideoJS for example).
It is necessary to provide a stable FPS and keyframe interval for a published stream to play it as LL HLS correctly. Therefore, it is recommended to publish the source strem as RTMP with the following example parameters
Image Removed
Image Removed
Recommended settings for LL HLS playback
...
dir=/usr/local/FlashphonerWebCallServer/hls |
(Preloader folder is configured separately with parameter hls_preloader_dir.)
The number of stored segments corresponds to the specified playlist size. The less segments number, the less playback latency. However subscribers with poor channel could request HLS segments which are already gone from playlist and disk if playlist is short. To fix it, since build 5.2.581 the certain number of segments can be stored on disk after they gone from playlist. This feature can be enabled by the following parameter
Code Block |
---|
|
hls_hold_segments_before_delete=true |
By default, 5 last segments will be stored
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
...
For example, if playlist contains 3 segments
Code Block |
---|
|
https://wsc:8445/test/test.m3u8 |
...
#EXTM3U
#EXT-X-VERSION:8
#EXT-X-TARGETDURATION:11
#EXT-X-MEDIA-SEQUENCE:15
#EXT-X-DISCONTINUITY-SEQUENCE:1
#EXTINF:3.415,
test_017.ts
#EXTINF:10.417,
test_018.ts
#EXTINF:9.084,
test_019.ts |
3 current segments and 5 previous segments will be stored on disk
Code Block |
---|
|
http://wsc:8082/test/test.m3u8 |
Note that LL HLS via HTTP/1 works in main browsers except Safari, and this feature is not recommended to use in production.
LL HLS segments folder
...
test_012.ts
test_013.ts
test_014.ts
test_015.ts
test_016.ts
test_017.ts
test_018.ts
test_019.ts |
Using memory
Under high load, for example on HLS streaming dedicated server, segments reading from hard drive to send them to subscribers can increase the latency. In this case, HLS segments storing in memory should be enabled
Code Block |
---|
|
ll_hls_dir=/usr/local/FlashphonerWebCallServer/ll-hls |
If folder has changed
Code Block |
---|
|
ll_hls_dir=/opt/ll-hls |
...
hls_store_segment_in_memory=true |
Segments will be read from memory to send them to subscribers. Note this will require more Java heap memory.
Since build 5.2.1713 HLS segments are stored in memory by default.
Debug logs for HLS session
For an error report, debug logging can be enabled for HLS sessions using CLI
Code Block |
---|
|
/usr/local/FlashphonerWebCallServer/bin/webcallserver set-permissions |
and restart WCS to apply the changes.
Maximum LL HLS playlist size
...
update node-setting --value true hls_enable_session_debug |
Note that config flashphoner.properties will be overwritten after the command.
Low Latency HLS support
Since WCS build 5.2.1181, Low Latency HLS (LL HLS) is supported. The feature may be enabled with the following parameters
Code Block |
---|
|
hls_ll_enabled=true
hls_listnew_http_sizestack=12 |
By default, LL HLS playlist size is 12 full segments. Note that LL HLS cut is just started, a full segments quantity in the first playlists will be less than value set.
LL HLS preloader
...
In this case, players supporting LL HLS (HLS.JS for example) will play additional HLS segments reducing playback latency comparing with players which do not play those segments (VideoJS for example).
It is necessary to provide a stable FPS and keyframe interval for a published stream to play it as LL HLS correctly. Therefore, it is recommended to publish the source strem as RTMP with the following example parameters
Image Added
Image Added
Recommended settings for LL HLS playback
Since build 5.2.1345, the recommended settings to play Low latency HLS are follow:
Code Block |
---|
|
hls_preloaderll_enabled=true |
LL HLS preloader files are placed by default to the folder
Code Block |
---|
|
ll_
hls_auto_start=true
hls_preloader_dir=/usr/local/FlashphonerWebCallServer/ll-hls/.preloader |
The folder can be changed, for example
Code Block |
---|
|
ll_hls_preloader_dir=/opt/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 played using HTTP/2, i.e. via secure connection
Code Block |
---|
|
16x9.mp4
2x1.mp4
4x3.mp4 |
...
https://wsc:8445/test/test.m3u8 |
It is also possible to use HTTP/1 via unsecure connection with WCS
Code Block |
---|
|
http://wsc:8082/test/test.m3u8 |
Note that LL HLS via HTTP/1 works in main browsers except Safari, and this feature is not recommended to use in production.
LL HLS segments folder
By default, LL HLS segments are written to streams subdolder to the folder
Code Block |
---|
|
hls_preloader_enabled=false |
Custom LL HLS preloader setup
A custom LL HLS preloader can be set up if necessary. The media files in three standard aspects 16:9, 4:3 и 2:1 should be prepared according to the following requirements:
- MP4 container, video codec H264, audio codec AAC
- the files should allow instant playback (MP4
moov
atom must precede mdat
one) - the files should not containt B frames
- the file duration should be near 1 minute
- the file should have a smooth FPS
- keyframe interval should be near 2 seconds
Suppose a source files are prepared in a proper aspects in OBS Studio or in a video editor. Use the following command example to convert a preloader files to conform the requirements above:
Code Block |
---|
|
ffmpeg -i 16x9-source.mp4 -bf 0 -acodec aac -vcodec h264 -preset ultrafast -g 60 -strict -2 -r 30 -ar 48000 -movflags faststart -ss 00:00:00 -t 00:01:00 16x9.mp4 |
Then the default preloader files should be replaced by custom preloader files, and WCS should be restarted.
To restore default preloader it is enough to remove custom preloader files and restart WCS.
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.ll_hls_dir=/usr/local/FlashphonerWebCallServer/ll-hls |
If folder has changed
Code Block |
---|
|
ll_hls_dir=/opt/ll-hls |
it is necessary to set file access permissions using the command
Code Block |
---|
|
/usr/local/FlashphonerWebCallServer/bin/webcallserver set-permissions |
and restart WCS to apply the changes.
Maximum LL HLS playlist size
Maximum LL HLS playlist size in segments is defined by the following parameter
Code Block |
---|
|
ll_hls_list_size=12 |
By default, LL HLS playlist size is 12 full segments. Note that LL HLS cut is just started, a full segments quantity in the first playlists will be less than value set.
LL HLS preloader
Since build 5.2.1729, a special preloader can be used for LL HLS as like as usual HLS
Code Block |
---|
|
hls_preloader_enabled=true |
LL HLS preloader files are placed by default to the folder
Code Block |
---|
|
ll_hls_preloader_dir=/usr/local/FlashphonerWebCallServer/ll-hls/.preloader |
The folder can be changed, for example
Code Block |
---|
|
ll_hls_preloader_dir=/opt/preloader |
Default LL HLS preloader consists of the following files, one per each standard video streams aspect ratio
Code Block |
---|
|
16x9.mp4
2x1.mp4
4x3.mp4 |
If stream aspect ration is unknown, 16:9 preloader file will be used. If there are no preloader files at all, LL HLS stream cut will start without a preloader like
Code Block |
---|
|
hls_preloader_enabled=false |
Custom LL HLS preloader setup
A custom LL HLS preloader can be set up if necessary. The media files in three standard aspects 16:9, 4:3 и 2:1 should be prepared according to the following requirements:
- MP4 container, video codec H264, audio codec AAC
- the files should allow instant playback (MP4
moov
atom must precede mdat
one) - the files should not containt B frames
- the file duration should be near 1 minute
- the file should have a smooth FPS
- keyframe interval should be near 2 seconds
Suppose a source files are prepared in a proper aspects in OBS Studio or in a video editor. Use the following command example to convert a preloader files to conform the requirements above:
Code Block |
---|
|
ffmpeg -i 16x9-source.mp4 -bf 0 -acodec aac -vcodec h264 -preset ultrafast -g 60 -strict -2 -r 30 -ar 48000 -movflags faststart -ss 00:00:00 -t 00:01:00 16x9.mp4 |
Then the default preloader files should be replaced by custom preloader files, and WCS should be restarted.
To restore default preloader it is enough to remove custom preloader files and restart WCS.
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 |
Known issues
1. Non-recoverable freeze of HLS stream played in iOS Safari through a CDN
...
Solution: since build 5.2.1690, use m4s container for audio only streams
13. Encoder resources leak may appear under a high load when using HLS ABR
Symptoms: when HLS ABR is used and server CPU load is high (for instance, an encoding profiles number for all the streams published exceeds CPU capabilities), encoding resources may not be freed after publishing is stopped, and this may be visible on server statistics page, for example
Code Block |
---|
|
streams_hls=0
...
native_resources.video_encoders=5 |
Solution: update WCS to build 5.2.1947 and set the following parameter
Code Block |
---|
|
handler_async_disconnect=false |