...

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

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

Code Block

language	js
theme	RDark

[{
    "id": "test",
    "streamName": "test",
    "status": "ACTIVE",
    "waitingSize": 0,
    "profiles": [
      "a_test",
      "v_test"
    ],
    "subscribers": 1,
    "playlist": "...",
    "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

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

...

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/enableRecording

Code Block

language	js
theme	RDark

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

200 – OK

400 – Bad request

404 – Not found

409 - Conflict

500 - Internal server error

Enable HLS stream debug segments recording

/hls/disableRecording

Code Block

language	js
theme	RDark

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

200 – OK

400 – Bad request

404 – Not found

Disable HLS stream debug segments recording

Parameters

Parameter name	Description	Example
name	Stream published name	test
hlsId	Stream published name	test
profileName	Quality profile name to get a statistics	v_test
offset	Offset from HLS streams statistics list start	0
size	Maximum HLS streams statistics list size	10
ids	HLS streams list to enable/disable debug segment recording	[ "test", "test-HLS-ABR-STREAM" ]
state	Статус HLS нарезки	ACTIVE
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",
      ...
    ]
  }
}

...

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

...

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

theme	RDark

hls_debug_dir=hls-debug

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

Code Block

language	js
theme	RDark

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

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

Use the REST API query /hls/disableRecording to stop the recording

Code Block

language	js
theme	RDark

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

theme	RDark

https://wcs:8445/test-DEBUG/test-DEBUG.m3u8

If the stream with a certain name was recorded, and then a new stream was published with the same name, a new recording will overwrite the previous one.

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.

...

Space shortcuts

Page tree

Versions Compared

Old Version 67

New Version 68

Key

Parameters

Issues

LL HLS stream issues displaying

Parameters

Issues

LL HLS stream issues displaying

HLS subscribers and connections displaying issues

HLS subscribers and connections displaying issues

HLS stream segments recording to disk for debugging purposes

HLS ABR support

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 67

New Version 68

Key

Parameters

Issues

LL HLS stream issues displaying

Parameters

Issues

LL HLS stream issues displaying

HLS subscribers and connections displaying issues

HLS subscribers and connections displaying issues

HLS stream segments recording to disk for debugging purposes

HLS ABR support