...

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

theme	RDark

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

theme	RDark

hls_abr_auto_start=true

HLS playback authentication using REST hook

...

REST query

Body example

Response example

Response state

Desctiption

/hls/startup

Code Block

language	js
theme	RDark

{
  "name":"test"
}

200 - OK

404 - Stream not found

500 - Internal error

Start HLS agent for the stream

/hls/find_all

Code Block

language	js
theme	RDark

{
  "testoffset": {0,
    "handler": "com.flashphoner.server.client.handler.wcs4.WCS4Handler@74dbf27b",
    "statesize":10
}

Code Block

language	js
theme	RDark

[{
    "id": "ACTIVEtest",
    "writerstreamName": "HLS-test",
    "streamStatusstatus": "PLAYINGACTIVE",
    "writerStartedwaitingSize": "true"0,
      "logsprofiles": [
      "2023-07-18T10:22:52.457 WARNING: Playback speed changed to 0.779, segment 49, media type: video"a_test",
      "v_test"
    ],
      "2023-07-18T10:22:56.614 WARNING: Gap{from=112000, to=114000, duration=2000}, media type: video"subscribers": 1,
    "playlist": "...",
      "2023-07-18T10:22:56.615 WARNING: Fps changed from 30 to 27, segment 50 , media type: video",
      "2023-07-18T10:22:56.624 WARNING: Segment 51.1 have no data, pts 112400, duration 400, media type: video",
      ...
    ]
  }
}"createdDate": 1697605114475,
    "logs": []
}]

200 – OK

404 – Not found

Find all streams having HLS agents

/hls/terminate

Code Block

language	js
theme	RDark

{
  "name":"test"
}

200 – OK

404 – Not found

Stop or restart HLS agent for the stream

Parameters

...

Description

...

Example

...

name

...

Stream published name

...

test

...

Issues

1. If HLS agent for the stream is started by REST query /hls/startup, and there are no active HLS subscribers, agent will stop after the following timeout in seconds

Code Block

theme	RDark

hls_manager_provider_timeout=300

By default, the timeout is 5 minutes. Also it concerns HLS agents which are started automatically for streams published using the following parameter

Code Block

theme	RDark

hls_auto_start=true

2. If HLS agent for the stream is stopped by REST query /hls/terminate, and there are active HLS subscribers, this agent will be restarted. In this case, active HLS subscribers must reconnect to the stream.

LL HLS stream issues displaying

Since build 5.2.1709 LL HLS stream issues are displaying in response on /hls/find_all REST API query:

...

language	js
theme	RDark

...

/hls/profiles

Code Block

language	js
theme	RDark

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

Code Block

language	js
theme	RDark

{
  "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

...

},

...

By default, up to 50 last issues are displayed for every stream. This value may be changed with the following parameter

Code Block

theme	RDark

hls_metrics_log_size=50

The following issues are detected:

Fps changed from x to y - stream FPS leap over 10 %
Segment x does not start with keyframe - stream keyframe interval is more than one segment duration
Playback speed changed to x - stream playback speed has changed
Segment interval is too big - an interval in milliseconds between a subsequent segments is too big
Video resolution changed from x to y - stream resolution has changed
Gap{from=x, to=y, duration=z} - stream gap detected, EXT-X-GAP tag is added to the playlist

...

"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
}

200 – OK

400 – Bad request

404 – Not found

Get HLS profile statistics

/hls/subscribers

Code Block

language	js
theme	RDark

{
  "hlsId":"test"
}

Code Block

language	js
theme	RDark

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

200 – OK

400 – Bad request

404 – Not found

Get HLS subscribers statistics

Parameters

Parameter name	Description	Example
name	Stream published name	test
logs	Messages about stream issues	[]

Issues

1. If HLS agent for the stream is started by REST query /hls/startup, and there are no active HLS subscribers, agent will stop after the following timeout in seconds

Code Block

theme	RDark

hls_manager_provider_timeout=300

By default, the timeout is 5 minutes. Also it concerns HLS agents which are started automatically for streams published using the following parameter

Code Block

theme	RDark

hls_auto_start=true

2. If HLS agent for the stream is stopped by REST query /hls/terminate, and there are active HLS subscribers, this agent will be restarted. In this case, active HLS subscribers must reconnect to the stream.

LL HLS stream issues displaying

Since build 5.2.1709 LL HLS stream issues are displaying in response on /hls/find_all REST API query:

Code Block

language	js
theme	RDark

{
   "test": {
    "handler": "com.flashphoner.server.client.handler.wcs4.WCS4Handler@74dbf27b",
    "state": "ACTIVE",
    "writer": "HLS-test",
    "streamStatus": "PLAYING",
    "writerStarted": "true",
    "logs": [
      "2023-07-18T10:22:52.457 WARNING: Playback speed changed to 0.779, segment 49, media type: video",
      "2023-07-18T10:22:56.614 WARNING: Gap{from=112000, to=114000, duration=2000}, media type: video",
      "2023-07-18T10:22:56.615 WARNING: Fps changed from 30 to 27, segment 50 , media type: video",
      "2023-07-18T10:22:56.624 WARNING: Segment 51.1 have no data, pts 112400, duration 400, media type: video",
      ...
    ]
  }
}

By default, up to 50 last issues are displayed for every stream. This value may be changed with the following parameter

Code Block

theme	RDark

hls_metrics_log_size=50

The following issues are detected:

Fps changed from x to y - stream FPS leap over 10 %
Segment x does not start with keyframe - stream keyframe interval is more than one segment duration
Playback speed changed to x - stream playback speed has changed
Segment interval is too big - an interval in milliseconds between a subsequent segments is too big
Video resolution changed from x to y - stream resolution has changed
Gap{from=x, to=y, duration=z} - stream gap detected, EXT-X-GAP tag is added to the playlist

Any of those issues means a source stream publishing quality degradation and may lead to freezes, out of audio and video sync and even HLS playback stopping in some browsers. In this case, a possible packets loss or bandwidth issues should be resolved, or pablishing technology shuld be changed from WebRTC to a more noise-resistant, RTMP or SRT for example.

HLS statistics displaying

Since build 5.2.1777 it is possible to get HLS statistics via REST API

HLS common data

In the response to the /hls/find_all query HLS agents list is returned containing a common HLS data:

Code Block

language	js
theme	RDark

[{
    "id": "test",
    "streamName": "test",
    "status": "ACTIVE",
    "waitingSize": 0,
    "profiles": [
      "a_test",
      "v_test"
    ],
    "subscribers": 1,
    "playlist": "#EXTM3U\n#EXT-X-VERSION:9\n#EXT-X-INDEPENDENT-SEGMENTS\n#EXT-X-MEDIA:TYPE=AUDIO,URI=\"a_test/a_test.m3u8\",GROUP-ID=\"audio\",NAME=\"none\",DEFAULT=YES,AUTOSELECT=YES,CHANNELS=\"2\"\n#EXT-X-STREAM-INF:BANDWIDTH=1761281,CODECS=\"avc1.640028,mp4a.40.2\",RESOLUTION=1280x720,FRAME-RATE=29.0,AUDIO=\"audio\"\nv_test/v_test.m3u8\n",
    "createdDate": 1697605114475,
    "logs": []
}]

Where

id - HLS stream identifier
streamName - a source stream name which is cut to a segments
waitingSize - HTTP requests count waiting for response
profiles - audio and video profiles list
subscribers - HLS subscribers count
playlist - HLS manifest content
createdDate - HLS agent creation date as integer
logs - HLS stream issues log

if there are a much HLS streams on the server, the list may be limited by the following parameters

Code Block

language	js
theme	RDark

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

Where

offset - from which item the list should be dispalyed, 0 by default
size - a maximum list items to display, 10 by default

Audio and video profiles data

In the response to the /hls/profiles query an audio or video HLS profile statistics is returned:

Code Block

language	js
theme	RDark

{
  "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": "v=0\r\no=- 1988962254 1988962254 IN IP4 0.0.0.0\r\nc=IN IP4 0.0.0.0\r\nt=0 0\r\na=sdplang:en\r\nm=video 0 RTP/AVP 112\r\na=rtpmap:112 H264/90000\r\na=fmtp:112 packetization-mode=1; profile-level-id=42001f\r\na=recvonly\r\n",
    "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
}

Where:

name - profile name
stream - profile stream data in /stream/find like form
keyFrameReceived - is there any key frame received
audioProfile, videoProfile - audio or video profile settings
- type - profile type: video or audio
- width - profile picture width as defined
- height - profile picture width as defined
- fps - profile video frame rate as defined
- bitrate - profile bitrate as defined
- codec - profile codec as defined
- quality - profile quality as defined
- audioGroupId - audio profile id used in video profile
- rate - audio profile samplerate
- channels - audio profile channels number
- groupId - audio profile id to bind to video profile
metrics - current profile metrics:
- minFPS - minimal FPS
- avgFPS - average FPS
- maxFPS - maximum FPS
- countGaps - gaps count inserted to the stream
- resolutionChanges - video resolution changes count
- queueSize - stream frame queue size
- startPts - start MPEG timestamp
- currentPts - current MPEG timestamp
subscribers - HLS subscribers to the profile count

HLS subscribers count

In the response to the /hls/subscribers query an HLS stream subscribers list is returned:

Code Block

language	js
theme	RDark

[
  {
    "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

Code Block

language	bash
theme	RDark

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:

Code Block

language	bash
theme	RDark

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

Where 8445 is HTTPS HLS port of WCS server

HLS ABR support

For a streams with video track (video only or audio+video) WCS supports HLS ABR in CDN (a qualities are encoded on a dedicated Transcoder node) and on a single node.

...

If there is a profile without both width and height parameters, the stream will be transcoded to its original resolution with GOP and FPS defined in the profile, and this variant will always be included to manifest:

...

theme	RDark

...

will always be included to manifest:

Code Block

theme	RDark

profiles:
  original:
    video:
      codec : h264
      codecImpl : OPENH264
      gop : 60
      fps : 30

Qualities order in HLS ABR manifest

Before build 5.2.1606, HLS ABR manifest qualities are sorted in profile names alphabetical order, for example, such cdn_profiles.yml or hls_abr_profiles.yml

Code Block

language	yml
theme	RDark

profiles:
  360:
    video:
      height : 360
      bitrate : 1000
      codec : h264
      codecImpl : OPENH264
      gop : 60
      fps : 30

  720:
    video:
      height : 720
      bitrate : 2000
      codec : h264
      codecImpl : OPENH264
      gop : 60
      fps : 30

Qualities order in HLS ABR manifest

Before build 5.2.1606, HLS ABR manifest qualities are sorted in profile names alphabetical order, for example, such cdn_profiles.yml or hls_abr_profiles.yml

Code Block

language	yml
theme	RDark

profiles:

  3601080:
    video:
      height : 3601080
      bitrate : 10002500
      codec : h264
      codecImpl : OPENH264
      gop : 60
      fps : 30

  720:
    video:
      height : 720
      bitrate : 2000
      codec : h264
      codecImpl : OPENH264
      gop : 60
      fps : 30

  1080:
    video:
      height : 1080
      bitrate : 2500
      codec : h264
      codecImpl : OPENH264
      gop : 60
      fps : 30

...

      fps : 30

give the following manifest

Code Block

theme	RDark

#EXTM3U
#EXT-X-STREAM-INF:BANDWIDTH=2500000,RESOLUTION=1920x1080,CODECS="avc1.42e01f,mp4a.40.2"
1080/1080.m3u8
#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

Since build 5.2.1606, manifest qualities order equals to profiles order in cdn_profiles.yml or hls_abr_profiles.yml

Code Block

theme	RDark

#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
#EXT-X-STREAM-INF:BANDWIDTH=2500000,RESOLUTION=1920x1080,CODECS="avc1.42e01f,mp4a.40.2"
1080/1080.m3u8

If there are two profiles with the same name in the setup, server will use only the last profile with the same name.

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

theme	RDark

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

theme	RDark

frame_cnt_to_determine_their_type=10

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

theme	RDark

#EXTM3U
#EXT-X-STREAM-INF:BANDWIDTH=25000001000000,RESOLUTION=1920x1080640x360,CODECS="avc1.42e01f,mp4a.40.2"
1080360/1080360.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=10000002000000,RESOLUTION=640x3601280x720,CODECS="avc1.42e01f,mp4a.40.2"
360720/360720.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=20000002500000,RESOLUTION=1280x7201920x1080,CODECS="avc1.42e01f,mp4a.40.2"
7201080/7201080.m3u8

Since build 5.2.1606, manifest qualities order equals to profiles order in cdn_profiles.yml or hls_abr_profiles.ymlIf there are no B-frames in the stream, the maximum ABR quality will not be transcoded

Code Block

theme	RDark

#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
#EXT-X-STREAM-INF:BANDWIDTH=2500000,RESOLUTION=1920x1080,CODECS="avc1.42e01f,mp4a.40.2"
1080/1080.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

theme	RDark

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

...

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 HLSthe 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

theme	RDark

hls_preloader_enabled=true

LL HLS preloader files are placed by default to the folder

Code Block

theme	RDark

ll_hls_preloader_dir=/usr/local/FlashphonerWebCallServer/ll-hls/.preloader

The folder can be changed, for example

Code Block

theme	RDark

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

theme	RDark

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

theme	RDark

hls_preloader_enabled=truefalse

Custom LL HLS preloader setup

A custom LL HLS preloader files are placed by default to the folder

Code Block

theme	RDark

ll_hls_preloader_dir=/usr/local/FlashphonerWebCallServer/ll-hls/.preloader

The folder can be changed, for example

Code Block

theme	RDark

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

theme	RDark

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

theme	RDark

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

language	bash
theme	RDark

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

theme	RDark

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

theme	RDark

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

theme	RDark

use_new_hls=true

In this case:

...

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

language	bash
theme	RDark

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

theme	RDark

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

theme	RDark

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

theme	RDark

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

theme	RDark

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

theme	RDark

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

and to get HLS ABR manifest

Code Block

theme	RDark

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

theme	RDark

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

theme	RDark

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

and to get HLS ABR manifest

Code Block

theme	RDark

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

...

Symptoms: no video for the first subscriber when playing a stream as HLS in Safari on iOS 12.4, however video is played normally if there are other HLS-subscribers to the streamSolution: set the minimum HLS playlist segments count not less than 2the stream

Solution: set the minimum HLS playlist segments count not less than 2

Code Block

theme	RDark

hls_min_list_size=2

4. No video for any subscriber when playing RTMP stream as HLS in Safari on iOS 12.4 if the following parameter is set to

Code Block

theme	RDark

hls_auto_start=true

Symptoms: no video for any subscriber when playing RTMP stream as HLS in Safari on iOS 12.4

Soluition: use mono sound when a file with stereo sound track is published, for example, set the followint command line options for ffmpeg

Code Block

theme	RDark

hls_min_list_size=2

...

-acodec aac -ac 1

5. If stream transcoded by CDN is played as HLS, and if stream aspect ratio is changed during transcoding, HLS preloader is shown by original stream aspect ratio

Symptoms: when stream transcoded is requested by setting profile name, test-640x480p for example, 16x9 preloader is shown if original stream is 1280x720

Solution: turn on aspect ratio preserving on Transcoder CDN nodes

Code Block

theme	RDark

hls_auto_start=true

Symptoms: no video for any subscriber when playing RTMP stream as HLS in Safari on iOS 12.4

Soluition: use mono sound when a file with stereo sound track is published, for example, set the followint command line options for ffmpeg

Code Block

theme	RDark

-acodec aac -ac 1

5. If stream transcoded by CDN is played as HLS, and if stream aspect ratio is changed during transcoding, HLS preloader is shown by original stream aspect ratio

Symptoms: when stream transcoded is requested by setting profile name, test-640x480p for example, 16x9 preloader is shown if original stream is 1280x720

Solution: turn on aspect ratio preserving on Transcoder CDN nodes

Code Block

theme	RDark

video_transcoder_preserve_aspect_ratio=true

6. If the source stream contains B-fames, the picture can twitch in some players

...

video_transcoder_preserve_aspect_ratio=true

6. If the source stream contains B-fames, the picture can twitch in some players

Symptoms: a strong picture twitching while playing a stream via HLS, this may lokk like low FPS

Solution: update WCS to build 5.2.863, where the problem is solved

7. Audio may be missed on the first connection to the stream when playing native LL HLS in Safari browser

Symptoms: stream is playing as LL HLS but there is no sound

Solution: update WCS to build 5.2.1345 or newer where the issue is solved

8. Chrome browser on Ubuntu 22.04 may raise CORS error while downloading HLS playlists via HTTPS

Symptoms: Chrome browser on Ubuntu 22.04 plays HLS via HTTPS normally, then CORS error occurs while downloading another playlist

Solution: do not send HTTP requests from Chrome to the same site HLS via HTTPS is playing from

9. LL HLS ABR stream may be played with a big delay in iOS Safari 16.

Symptoms: all the subscribers using iOS Safari 16, play LL HLS ABR stream with a big delay (more than 20 seconds) from published stream

Solution: update WCS to build 5.2.863, where the problem is solved

7. Audio may be missed on the first connection to the stream when playing native LL HLS in Safari browser

Symptoms: stream is playing as LL HLS but there is no sound1677 to use m4s container by default for LL HLS and wait for a posssible fix in iOS Safari 17

10. HLS ABR may not be played if m4s container is used

Symptoms: HLS ABR segments are not cut with server log message

Code Block

theme	RDark

02:18:01,957 ERROR HlsAbrStreamProvider - HLS-HTTPS-pool-5-thread-1 Failed to check stream null
java.lang.NullPointerException

Solution: update WCS to build 5.2.1345 or newer 1677 where the issue is solvedresolved

8. Chrome browser on Ubuntu 22.04 may raise CORS error while downloading HLS playlists via HTTPS

Symptoms: Chrome browser on Ubuntu 22.04 plays HLS via HTTPS normally, then CORS error occurs while downloading another playlist

Solution: do not send HTTP requests from Chrome to the same site HLS via HTTPS is playing from

9. LL HLS ABR stream may be played with a big delay in iOS Safari 16.

Symptoms: all the subscribers using iOS Safari 16, play LL HLS ABR stream with a big delay (more than 20 seconds) from published stream11. VLC requires LL HLS manifest to include at least 4-6 segments for the first subscriber

Symptoms: audio and video are out of sync when VLC plays LL HLS in m4s container, or playback is freezing while switching a quality in LL HLS ABR

Solution: update WCS to build 5.2.1677 to use m4s container by default for LL HLS and wait for a posssible fix in iOS Safari 17

10. HLS ABR may not be played if m4s container is used

Symptoms: HLS ABR segments are not cut with server log message

Code Block

theme	RDark

02:18:01,957 ERROR HlsAbrStreamProvider - HLS-HTTPS-pool-5-thread-1 Failed to check stream null
java.lang.NullPointerException

Solution: update WCS to build 5.2.1677 where the issue is resolved

11. VLC requires LL HLS manifest to include at least 4-6 segments for the first subscriber

Symptoms: audio and video are out of sync when VLC plays LL HLS in m4s container, or playback is freezing while switching a quality in LL HLS ABR and increase a minimal manifest size

Code Block

theme	RDark

hls_min_list_size=6

12. Audio only HLS stream in ts container is playing with a notable clicks in Safari browser

Symptoms: Audio only HLS stream clicks while playing in native HTML5 player in Safari browser

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

theme	RDark

streams_hls=0
...
native_resources.video_encoders=5

Solution: update WCS to build 5.2.1677 and increase a minimal manifest size1947 and set the following parameter

Code Block

theme	RDark

hlshandler_minasync_list_size=6

12. Audio only HLS stream in ts container is playing with a notable clicks in Safari browser

Symptoms: Audio only HLS stream clicks while playing in native HTML5 player in Safari browser

...

disconnect=false

Space shortcuts

Page tree

Versions Compared

Old Version 57

New Version Current

Key

HLS playback authentication using REST hook

Parameters

Issues

LL HLS stream issues displaying

Parameters

Issues

LL HLS stream issues displaying

HLS statistics displaying

HLS common data

Audio and video profiles data

HLS subscribers count

HLS subscribers and connections displaying issues

HLS ABR support

Qualities order in HLS ABR manifest

Qualities order in HLS ABR manifest

Force transcoding of a maximum ABR quality only if there are B-frames in a source stream

Maximum playlist size

LL HLS preloader

LL HLS preloader

Custom LL HLS preloader setup

Custom LL HLS preloader setup

m4s container support

Using a common network stack for HLS and Low Latency HLS

m4s container support

Using a common network stack for HLS and Low Latency HLS

Manifest URL setup

Known issues

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 57

New Version Current

Key

HLS playback authentication using REST hook

Parameters

Issues

LL HLS stream issues displaying

Parameters

Issues

LL HLS stream issues displaying

HLS statistics displaying

HLS common data

Audio and video profiles data

HLS subscribers count

HLS subscribers and connections displaying issues

HLS ABR support

Qualities order in HLS ABR manifest

Qualities order in HLS ABR manifest

Force transcoding of a maximum ABR quality only if there are B-frames in a source stream

Maximum playlist size

LL HLS preloader

LL HLS preloader

Custom LL HLS preloader setup

Custom LL HLS preloader setup

m4s container support

Using a common network stack for HLS and Low Latency HLS

m4s container support

Using a common network stack for HLS and Low Latency HLS

Manifest URL setup

Known issues