...

...

The settings above should be applied to Transcoder nodes.

Transcoding profile management using REST API

The specific REST API is used to manage transcoding profiles on the fly, without server restart

REST query should be HTTP/HTTPS POST request as follows:

• HTTP: http://test.flashphoner.com:8081/rest-api/cdn/profile/print
• HTTPS: https://test.flashphoner.com:8444/rest-api/cdn/profile/print

Where:

• test.flashphoner.com - WCS server address
• 8081 - standard REST / HTTP port of WCS server
• 8444 - standard HTTPS port
• rest-api - URL mandatory part
• /cdn/profile/print - REST query used

REST queries should be sent to Edge server. Any profile changes are stored in memory and applied immediately, also they are written to cdn_profiles.yml file to use after server restart.

REST queries and response states

...

REST query

...

REST query body example

...

Response body example

...

Response states

...

Description

...

/cdn/profile/add

{
"name": "-profile1",
"profile": {
        "audio": {
            "type": "audio",
            "bitrate": 0, 
            "codec": "opus", 
            "rate": 48000 
        }, 
        "video": {
            "type": "video", 
            "bitrate": 0, 
            "codec": "h264", 
            "codecImpl": "FF", 
            "fps": 30, 
            "gop": 90, 
            "height": 360, 
            "quality": 0, 
            "width": 640
        }
}
}

...

200 – OK

400 - Bad Request

409 - Conflict

500 – Internal Server Error

...

Add transcoding profile

...

Multi channels audio support

Since build 5.2.773, audio transcoding by profile with certain number of channels (1 - mono, 2 - stereo) is supported

profiles:
 -240p:
  audio:
    codec : mpeg4-generic
    rate : 48000
    channels: 1
  video:
    height : 240
    bitrate : 300
    gop : 50
    codec : h264

A channels number in a profile should be equal to channels number in original audio track for subscriber on Edge server to play stereo sound when stream with stereo sound is published, i.e.

profiles:
 -240p:
  audio:
    codec : mpeg4-generic
    rate : 48000
    channels: 2

If profile codec, samplerate and channels number are equal to original audio track parameters, the track will be passed to Edge server without transcoding

Transcoding profile management using REST API

The specific REST API is used to manage transcoding profiles on the fly, without server restart

REST query should be HTTP/HTTPS POST request as follows:

• HTTP: http://test.flashphoner.com:8081/rest-api/cdn/profile/print
• HTTPS: https://test.flashphoner.com:8444/rest-api/cdn/profile/print

Where:

• test.flashphoner.com - WCS server address
• 8081 - standard REST / HTTP port of WCS server
• 8444 - standard HTTPS port
• rest-api - URL mandatory part
• /cdn/profile/print - REST query used

REST queries should be sent to Edge server. Any profile changes are stored in memory and applied immediately, also they are written to cdn_profiles.yml file to use after server restart.

REST queries and response states

{
"name": "-profile1",
"profile": {
        "

audio": {
            "

type": 

"audio",

            "

bitrate": 0, 

    "

codec": 

"opus", 
            "

rate": 

48000 
        }, 
        "

video": 

{
            "

type": 

"video", 
            "

bitrate": 

0, 
            "

codec": 

"h264", 
            "

codecImpl": "

FF", 
        

"fps": 

30, 
            "

gop": 

90, 
            "

height": 

360, 
            "

quality": 

0, 
            "

width": 

640
        

}
}
}

{
"name": "-profile1",
"profile": {
        "heightvideo": 240, {
            "presetbitrate": "veryfast"400, 
            "quality": 0, 25
            "type": "video", 
            "width": 0
        }
    }, 
}
}
}

    "-480p240p": {
        "audio": {
            "bitrate": 0, 
            "channels": 0, 
            "codec": "opus", 
            "rate": 48000, 
            "type": "audio"
        }, 
        "video": {
            "bitrate": 0, 
            "codec": "h264", 
            "codecImpl": "FF", 
            "fps": 25, 
            "gop": 50, 
            "height": 480240, 
            "preset": "veryfast", 
            "quality": 0, 
            "type": "video", 
            "width": 0
        }
    }

{
"name": "-profile1"
}

Parameters

-profile1

, 
    "-480p": {
        "audio": {

            "bitrate": 0, 

            "channels": 0, 

            "codec": "opus",

 
            "rate": 48000, 

            "type": 

"

audio"
        }, 
        "video"

: {
            "bitrate": 0,

 
            "codec": "h264", 

            "codecImpl": "FF", 

            "fps": 

25, 
            "gop": 

50, 
            "height":

 480, 
            "preset": "veryfast", 
            "quality": 0,

cdn_group_origin_to_transcoder_relation=true

Profile parameters should contain audio or video sections.

The mandatory profile parameters are:

• audio:
  • bitrate
  • codec
  • rate
• video:
  • bitrate
  • codec
  • width
  • height
  • quality

If some of those parameters are omitted in profile creation query, they will be added to profile with 0 value for digital parameters and "" for string parameters, in this case default values will be applied.

The remaining parameters are optional and may be omitted in the profile:

• video:
  • codecImpl
  • fps
  • gop
  • level
  • preset
  • profile

When modifying a profile, only parameters passed in REST query will be changed. To drop some of mandatory parameters to default value, or to remove optional parameter from profile, -1 should be passed, fro example:

{
"name": "-profile1",
"profile": {
        "video": {
            "bitrate": -1, 
            "codecImpl": -1
        }
}
}

Used profiles modification

If stream is played by the profile, this profile can be modified after stream playback finishes and publishing agent stops, i.e. near 1 minute after last stream subscriber disconnects.

When stream is transcoded on Edge server

Stream will be transcoded on Edge in the following cases:

1. If there is no audio codec or sample rate from profile in subscriber's SDP, audio track will be transcoded to one of formats supported by subscriber.

2. If constraints are set for the subscriber: e.g., if video height or bitrate are specified. Therefore, when transcoding by profile, desired constraints should be specified in the profile and not set for subscribers.

Profile applied for a subscriber should correspond to the technology used by the subscriber for playing the stream. For example, for a subscriber using WSPlayer, apply profile with codecs ulaw and mpv, and for RTMP - mpeg4-generic and h264.

Picture aspect ratio preserving while stream transcoding by profile

If picture aspect ratio preserving is enabled for all CDN nodes (by default), then stream aspect ratio as published to Origin node will be preserved while transcoding the stream on Transcoder node. For example, if the following profile (16:9) is applied  to 640x480 (4:3) stream

 profile1:
  audio:
    codec : opus
    rate : 48000
  video:
    width : 320
    height : 180
    gop : 90
    fps : 30
    codec : h264

the stream will be transcoded to 320x240 (4:3).

In this case, picture width may be omitted in transcoding profile, because width will be chosen according to picture aspect ratio. For example, the following profile is allowed

...

 
            "type": "video", 
            "width": 0
        }
    }

{
"name": "-profile1"
}

Parameters

-profile1

{
"audio": {
"type": "audio"
"bitrate": 0, 
"channels": 0, 
"codec": "opus", 
"rate": 48000, 
}, 
"video": {
"type": "video", 
"bitrate": 0, 
"codec": "h264", 
"codecImpl": "FF", 
"fps": 30, 
"gop": 90, 
"height": 360, 
"quality": 0, 
"width": 640
}

cdn_group_origin_to_transcoder_relation=true

Profile parameters should contain audio or video sections.

The mandatory profile parameters are:

• audio:
  • bitrate
  • codec
  • rate
• video:
  • bitrate
  • codec
  • width
  • height
  • quality

If some of those parameters are omitted in profile creation query, they will be added to profile with 0 value for digital parameters and "" for string parameters, in this case default values will be applied.

The remaining parameters are optional and may be omitted in the profile:

• video:
  • codecImpl
  • fps
  • gop
  • level
  • preset
  • profile

When modifying a profile, only parameters passed in REST query will be changed. To drop some of mandatory parameters to default value, or to remove optional parameter from profile, -1 should be passed, fro example:

{
"name": "-profile1",
"profile": {
        "video": {
            "bitrate": -1, 
            "codecImpl": -1
        }
}
}

Used profiles modification

If stream is played by the profile, this profile can be modified after stream playback finishes and publishing agent stops, i.e. near 1 minute after last stream subscriber disconnects.

When stream is transcoded on Edge server

Stream will be transcoded on Edge in the following cases:

1. If there is no audio codec or sample rate from profile in subscriber's SDP, audio track will be transcoded to one of formats supported by subscriber.

2. If constraints are set for the subscriber: e.g., if video height or bitrate are specified. Therefore, when transcoding by profile, desired constraints should be specified in the profile and not set for subscribers.

Profile applied for a subscriber should correspond to the technology used by the subscriber for playing the stream. For example, for a subscriber using WSPlayer, apply profile with codecs ulaw and mpv, and for RTMP - mpeg4-generic and h264.

Picture aspect ratio preserving while stream transcoding by profile

If picture aspect ratio preserving is enabled for all CDN nodes (by default), then stream aspect ratio as published to Origin node will be preserved while transcoding the stream on Transcoder node. For example, if the following profile (16:9) is applied  to 640x480 (4:3) stream

 profile3profile1:
  audio:
    codec : opus
    rate : 48000
  video:
    width : 320
    height : 180

...

    gop : 90
    fps : 30
    codec : h264

the stream will be transcoded to 320x240 (4:3).

In this case, picture width may be omitted in transcoding profile, because width will be chosen according to picture aspect ratio. For example, the following profile is allowed

 profile3:
  audio:
    codec : opus
    rate : 48000
  video:
    height : 180

Transcoder node tuning to work under high load

The server CPU load increases while a large number of streams are transcoded. If the server CPU does not manage to process all the streams frames, frame encoding queues take a much of server RAM (not JVM heap!). As a result, memory leak may occur and, therefore, server can stop working depending on memory allocation libraries used by server operating system.

...

REST queries should be sent to Edge server.

Stream transcoding by two or more profiles with the same video parameters

...

In this case, if the stream is transcoded at the same Transcoder node by those two profiles, only one video encoder and two audio encoders will be used.

Choosing a route for stream playback

CDN routes are based on the following periodic data sendings between CDN nodes:

• Origin sends published streams data to Transcoder and Edge;
• Transcoder sends pulled streams data to Edge in the same group;
• Edge sends nothing and is always an end point of a route.

A route for stream playback on Edge server is chosen as follows:

Image Removed

1. If transcoding profile is set on Edge server:

...

Transcoding to higher resolutions prevention

Since build 5.2.607, stream transcoding to higher resolutions can be escaped. The feature can be enabled with the following parameter

cdn_strict_transcoding_boundaries=true

In this case, if a stream is published to Origin with resolution 640x480, and Edge server tries to request playback by 720p profile, Edge will receive an original stream directly from Origin without transcoding. Resolutions are compared by height.

Stream requesting by higher resolution profiles can be strictly forbidden with the following parameter

cdn_strict_transcoding_throws_exception=true

When, if a stream is published to Origin with resolution 640x480, and Edge server tries to request playback by 720p profile, Edge can not choose stream playback route and will return error to a client.

These parameters should be set on Edge server.

Known limits

1. If stream transcoding to higher resolutions is disabled, a stream height must be set for every profile.

Choosing a route for stream playback

CDN routes are based on the following periodic data sendings between CDN nodes:

• Origin sends published streams data to Transcoder and Edge;
• Transcoder sends pulled streams data to Edge in the same group;
• Edge sends nothing and is always an end point of a route.

A route for stream playback on Edge server is chosen as follows:

Image Added

1. If transcoding profile is set on Edge server:

1.1. If there is the stream with such name on Transcoder node in the same group with Edge:

...

    "3-PROXY-192.168.1.219": [
        "AUDIO{bitrate=0, codec='opus', rate=48000, channels=2}",
        "VIDEO{width=0, height=0, gop=null, fps=null, bitrate=0, codec='H264', codecImpl='', quality=null}"
    ]

CDN stream advertising by keyframe receiving

By default, all the streams published on Origin nodes are advertised to CDN and become available to select route and play right after publishing. In this case, a video stream picture resolution and aspect ratio are unknown until a publisher sends the first keyframe.

...

='', quality=null}"
    ]

CDN stream advertising by keyframe receiving

By default, all the streams published on Origin nodes are advertised to CDN and become available to select route and play right after publishing. In this case, a video stream picture resolution and aspect ratio are unknown until a publisher sends the first keyframe.

In some cases, it is necessary to know the stream picture resolution and aspect ratio on Edge server when the stream becomes available in CDN. To do this, Origin server can advertise streams after keyframe receiving since build 5.2.404. This behaviour can be enabled using the following parameter

cdn_advertise_streams_by_kframe=true

Note that audio only streams (without video track) will not be available in CDN with this setting, because they contain no keyframes.

Transcoder node load balancing

Node load detection by CPU load

If there are some Transcoder nodes with the same profiles in CDN, those nodes load can be balanced  by CPU load. Maximum allowed load for certain Transcoder can be defined with the following parameter

cdn_node_load_average_threshold=1.0

This value sets average CPU load (JVM SystemLoadAverage parameter) to CPU cores avalable ratio, including hyperthreading cores. When this value is exceeded, the Transcoder node is excluded from route elections for new stteams and profiles. In this case the Transcoder node is displayed in the stream route PROFILE section for profiles the stream is already transcoded by.

Node current state (if node participates in new stream route elections) can be checked with REST API. A node in NEW_STREAMS_ALLOWED state can pull new streams to transcode, a node in GROUP_CONNECTION_ALLOWED state can only push the streams already transcoded.

This parameter should be set on Transcoder nodes. Also this parameter can be set on Origin nodes, in this case their load can be checked via REST API, and if the Origin node become GROUP_CONNECTION_ALLOWED then new streams can be published to another Origin server.

Transcoder node video encoders limiting

If necessary, maximum video encoders simultaneously used amount can be lemited for Transcoder nodes with the following parameter

cdn_transcoder_video_encoders_threshold=10000

When this amount is reached, the Transcoder node becomes GROUP_CONNECTION_ALLOWED. All the video encoders on server are included, for example, if one stream is transcoding by two profiles, 3 video encoders are used, including PNG encoder.

This parameter should be set on Transcoder nodes.

Decoders load limiting

Since build 5.2.594, an integral decoders load value can be limited. For example, to allow no more then 20 streams 1080p with 30 fps to be decoded, the following parameter should be set

cdn_advertisetranscoder_video_streamsdecoders_byload_kframe=true

Note that audio only streams (without video track) will not be available in CDN with this setting, because they contain no keyframes.

Transcoder node load balancing

Node load detection by CPU load

If there are some Transcoder nodes with the same profiles in CDN, those nodes load can be balanced  by CPU load. Maximum allowed load for certain Transcoder can be defined with the following parameter

cdn_node_load_average_threshold=1.0

This value sets average CPU load (JVM SystemLoadAverage parameter) to CPU cores avalable ratio, including hyperthreading cores. When this value is exceeded, the Transcoder node is excluded from route elections for new stteams and profiles. In this case the Transcoder node is displayed in the stream route PROFILE section for profiles the stream is already transcoded by.

...

threshold=1244160000

which is the result of multiplication

1920 * 1080 * 30 * 20

When this value is reached, the Transcoder node becomes GROUP_CONNECTION_ALLOWED.

This parameter should be set on Transcoder nodes.

Encoders load limiting

Since build 5.2.594, an integral decoders load value can be limited. For example, to allow no more then 20 streams to be encoded to 720p, 480p and 240p with 25 fps, the following parameter should be set

cdn_transcoder_video_encoders_load_threshold=716400000

which is the result of summation

1280 * 720 * 25 * 20 + 852 * 480 * 25 * 20 + 426 * 240 * 25 * 20

When this value is reached, the Transcoder node becomes GROUP_CONNECTION_ALLOWED.

This parameter should be set on Transcoder nodes. Also this parameter can be set on Origin nodes, in this case their load can be checked via REST API, and if the Origin node become GROUP_CONNECTION_ALLOWED then new streams can be published to another Origin server.

Transcoder node video encoders limiting

If necessary, maximum video encoders simultaneously used amount can be lemited for Transcoder nodes with the following parameter

Degraded streams percent limiting

Since build 5.2.594, a degrading streams percent can be limited. For example, to stop new streams transcoding when 10% of streams is degraded, the following parameter should be set

cdn_transcoder_videodegraded_encodersstreams_threshold=1000010

When this amount value is reached, the Transcoder node becomes GROUP_CONNECTION_ALLOWED. All the video encoders on server are included, for example, if one stream is transcoding by two profiles, 3 video encoders are used, including PNG encoderNote that streams usually start to degrade due to lack of decoder or encoder perfomance, and decoder/encoder picture queues are grown to maximum values to the moment of degradation, that leads to RAM waste. Therefore, this parameter must be used in addition to encoder/decoder load thresholds only.

This parameter should be set on Transcoder nodes.

...

ACTIVE

192.168.1.64

NEW_STREAMS_ALLOWED

ORIGIN

...

Current CDN node state is defined as follows in priority order:
1. If there is a value enforced by /cdn/enforce_state REST query, state will be set to this value.
2. If CPU load threshold is reached, state will be set to GROUP_CONNECTIONS_ALLOWED.
3. If video encoders threshold is reached, state will be set to GROUP_CONNECTIONS_ALLOWED.
4. If no limits are reached, state will be set to NEW_STREAMS_ALLOWED.CDN node broadcasts its state to another nodes periodically, using the interval set in milliseconds with the folowing parameterenforce_state REST query, state will be set to this value.
2. If CPU load threshold is reached, state will be set to GROUP_CONNECTIONS_ALLOWED.
3. If video encoders threshold is reached, state will be set to GROUP_CONNECTIONS_ALLOWED.
4. If no limits are reached, state will be set to NEW_STREAMS_ALLOWED.

CDN node broadcasts its state to another nodes periodically, using the interval set in milliseconds with the folowing parameter

cdn_nodes_state_refresh_interval=60000

By default, this interval is 60 seconds. It is recommended to reduce this parameter to 1 second for Transcoder nodes to distribute the streams to another nodes.

Transcoder threshold reached state setup

Since build 5.2.640 Transcoder node threshold reached state can be set with the following parameter, GROUP_CONNECTIONS_ALLOWED by default

cdn_transcoder_threshold_state=GROUP_CONNECTIONS_ALLOWED

To prevent stream spreading over CDN, Transcoder node can be switched to CONNECTIONS_ALLOWED state if necessary

cdn_transcoder_nodesthreshold_state_refresh_interval=60000

...

=CONNECTIONS_ALLOWED

In this state, Transcoder node allows to pull streams which are already decoded on, including new encoding profiles. For example, if some Transcoder node decodes test stream by 360p profile, and som of Edge servers requests test240p stream, playback route will be built via the same Transcoder node.

This parameter should be set on Transcoder nodes.

CDN nodes authentication

...

In these cases transcoding works according to codecs and SDP setup as defined for CDN 2.0.

Known limits

1. It is strongly not recommended to publish streams with same name to two Origin servers in the same CDN.

...

profiles:
 -240p:
  audio:
    codec : opus
    rate : 48000
  video:
    height : 240
    bitrate : 400
    gop : 50
    fps : 25
    codec : h264
    codecImpl : OPENH264

2. Encoding quality settings cannot be applied if OpenH264 is used

Symptoms: picture quality is not changing when using different quality values in transcoding profile

Solution: do not use OpenH264 encoder because it does not support CRF

profiles:
 -240p:
  audio:
    ...
  video:
    ...
    quality: 10
    codecImpl : FF