Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Transcoding management with REST API

Obsolete REST API version (server builds before 5.2.898)

REST query should be HTTP/HTTPS POST request as:

...

  • test.flashphoner.com is WCS server address
  • 8081 is a standard REST / HTTP port of  WCS server
  • 8444 is a standard HTTPS port
  • rest-api is mandatory URL prefix
  • /transcoder/startup is REST query

REST queries and response states

REST query

Request example

Response example

Response states

Description

/transcoder/startup

Code Block
languagejs
themeRDark
{
 "uri": "transcoder://tcode1",
 "remoteStreamName": "test",
 "localStreamName": "testT",
 "encoder": {
  "width": 640,
  "height": 480,
  "keyFrameInterval": 30,
  "fps": 30,
  "watermark": "Test.png"
 }
}

400 - Bad request

409 - Conflict

500 - Internal error


Create transcoder with defined parameters for certain stream


/transcoder/find
Code Block
languagejs
themeRDark
{
 "remoteStreamName": "test"
}
Code Block
languagejs
themeRDark
[
    {
        "localMediaSessionId": "42a92132-bcd1-4436-a96f-3fec36b32b37",
        "localStreamName": "testT",
        "remoteStreamName": "test",
        "uri": "transcoder://tcode1",
        "status": "PROCESSED_LOCAL",
        "hasAudio": true,
        "hasVideo": true,
        "record": false,
        "encoder": {
            "width": 640,
            "height": 480,
            "keyFrameInterval": 30,
            "fps": 30,
            "watermark": "Test.png"
        }
    }
]

200 – Transcoders found

404 – Transcoders not found

Find the transcoder by certain criteria

/transcoder/find_all


Code Block
languagejs
themeRDark
[
    {
        "localMediaSessionId": "42a92132-bcd1-4436-a96f-3fec36b32b37",
        "localStreamName": "testT",
        "remoteStreamName": "test",
        "uri": "transcoder://tcode1",
        "status": "PROCESSED_LOCAL",
        "hasAudio": true,
        "hasVideo": true,
        "record": false,
        "encoder": {
            "width": 640,
            "height": 480,
            "keyFrameInterval": 30,
            "fps": 30
        }
    }
]

200 – Transcoders found

404 – Transcoders not found


Find all transcoders

/transcoder/terminate

Code Block
languagejs
themeRDark
{
"uri":"transcoder://tcode1"
}

200 - Transcoders is terminated

404 - Transcoder not found

Stop transcoder and its output stream

Parameters

...

Name

...

Description

...

Example

...

uri

...

Transcoder URL

...

transcoder://tcode1

...

testT

...

test

...

42a92132-bcd1-4436-a96f-3fec36b32b37

...

status

...

Transcoder state

...

PROCESSED_LOCAL

...

true

...

true

...

false

...

640

...

480

...

30

...

30

...

500

...

OPENH264

...

Known limits

...

/transcoder/set_watermark
Code Block
languagejs
themeRDark
{
 "uri":"transcoder://tcode1",
 "watermark":"/opt/media/logo.png",
 "x":10,
 "y":10,
 "marginTop":5,
 "marginLeft":5,
 "marginBottom":5,
 "marginRight":5
}

200 - OK

400 - Bad request

404 - Not found

Add watermark to transcoder output stream

Parameters

Name

Description

Example

uri

Transcoder URL

transcoder://tcode1
localStreamNameTranscoder output stream name
testT
remoteStreamNameStream name to transcode
test
localMediaSessionIdTranscoder media session Id
42a92132-bcd1-4436-a96f-3fec36b32b37

status

Transcoder state

PROCESSED_LOCAL
hasAudioOutput stream has audio
true
hasVideoOutput stream has video
true
recordOutput stream is recorded
false
Encoder parameters
widthPicture width
640
heightPicture height
480
keyFrameIntervalKey frame generation interval (GOP)
30
fpsFrames per second
30
bitrateBitrate, in kbps
500
typeCodec
OPENH264
watermarkWatermark fileTest.png

Known limits

1. Transcoder cannot be created by REST API for audio only stream. In response to /transcoder/startup query for such stream, server returns 400 Bad request with message "Can't start transcoder for audio only stream"

...

4, If only width is specified, the quey return 400 Bad request with message "Height is not specified"

Quick manual for testing

1. For test we use

  • WCS server;
  • Two Way Streaming web application to publish a stream;
  • Player web application to play an output stream;
  • Chrome browser with REST client to send REST queries to server

2. Open Two Way Streaming application and publish stream named test

Image Removed

3. Open REST client and send REST query /transcoder/startup

Image Removed

4. Open Player application, set testT to Stream field and click Start

Image Removed

5. Open REST client adn send REST query /transcoder/terminate

Image Removed

6. Playback will be stopped due to transcoder stop

Image Removed

Picture aspect ratio preserving

By default, if the stream is published with one picture resolution and is requested to play with another resolution, WCS tries to preserve picture aspect ratio. For example, if stream is published on server with resolution 640x360, aspect ratio 16:9, and subscriber requests to play it with resolution 320x240 (4:3), the stream will be transcoded to resolution 320x180 (16:9). If subscriber requests picture height only without setting width, aspect ratio will also be preserved.

To disable picture aspect ratio preserving, the following parameter sho;ud be set in flashphoner.properties file

Code Block
themeRDark
video_transcoder_preserve_aspect_ratio=false

In this case stream will be transcoded to picture width and height that are requested by subscriber. If subscriber does not set picture height, it wiil be set to 120. If subscriber does not set picture width, it wiil be set to 160.

Transcoder output stream audio and video synchronization

By default transcoder does not synchronize output stream audio and video, leaving sinchronization value as is. This can lead to out of audio and video sync in stream transcoded. To prevent this, the pacer buffer is added in build 5.2.543 which can be enabled with the following parameter

Code Block
themeRDark
av_paced_sender=true

Pacer buffer maximum size is set in frames by the following parameter

Code Block
themeRDark
av_paced_sender_max_buffer_size=5000

By default pacer buffer size is 5000 frames.

The statistics information received by the following query is uused to control pacer buffer usage

Code Block
languagebash
themeRDark
curl -s 'http://localhost:8081/?action=stat&format=json&groups=buffer_stats'

A certain stream watermarking

Since build 5.2.693 it is possible to add watermark to transcoded stream when creating transcoder using REST API, for example

...

languagejs
themeRDark

...

REST API version 2 (server builds since 5.2.898)

REST query should be HTTP/HTTPS POST request as:

  • HTTP: http://test.flashphoner.com:8081/rest-api/transcoder2/startup
  • HTTPS: https://test.flashphoner.com:8444/rest-api/transcoder2/startup

Where:

  • test.flashphoner.com is WCS server address
  • 8081 is a standard REST / HTTP port of  WCS server
  • 8444 is a standard HTTPS port
  • rest-api is mandatory URL prefix
  • /transcoder2/startup is REST query

REST queries and response states

REST query

Request example

Response example

Response states

Description

/transcoder2/startup

Code Block
languagejs
themeRDark
{
 "uri": "transcoder2://tcode2",
 "remoteStreamName": "test",
 "localStreamName": "testT",
 "encoder": {
  "videoCodec": "H264",
  "audioCodec": "mpeg4-generic",
  "width": 320,
  "height": 240,
  "keyFrameInterval": 60,
  "fps": 30,
  "audioRate": 44100,
  "audioBitrate": 64000
 }
}

200 - OK

400 - Bad request

409 - Conflict

500 - Internal error


Create transcoder with defined parameters for certain stream


/transcoder2/find
Code Block
languagejs
themeRDark
{
 "remoteStreamName": "test"
}
Code Block
languagejs
themeRDark
[
  {
    "localMediaSessionId": "82ad5545-e11e-4f0f-801a-49e69d8c38f2",
    "localStreamName": "testT",
    "remoteStreamName": "test",
    "uri": "transcoder2://tcode2",
    "status": "PROCESSED_LOCAL",
    "hasAudio": true,
    "hasVideo": true,
    "record": false,
    "encoder": {
      "width": 320,
      "height": 240,
      "keyFrameInterval": 60,
      "fps": 30,
      "

...

audioRate": 

...

44100,
      "audioCodec": "mpeg4-generic",
      "videoCodec": "H264",
      "videoRate": 90000
    }
  }
]

200 – OK

404 – Not found

Find the transcoder by certain criteria

/transcoder/find_all


Code Block
language

...

js
themeRDark
[
  {

...

    "localMediaSessionId": "

...

82ad5545-e11e-4f0f-801a-49e69d8c38f2",
    "

...

localStreamName": "

...

testT",
    "

...

remoteStreamName": "

...

test",
 

...

 

...

  "

...

uri": 

...

"transcoder2://tcode2",
    "

...

status": 

...

"PROCESSED_LOCAL",
    "

...

hasAudio": 

...

true,
    "

...

hasVideo": 

...

true,
    "

...

record": 

...

false,
    "encoder": {
      "width": 320,
      "height": 240,
      "keyFrameInterval": 60,
      "fps": 30,
      "audioRate": 44100,
      "audioCodec": "mpeg4-generic",
      "videoCodec": "H264",
      "videoRate": 90000
    }
  }
]

200 – OK

404 – Not found

Find all transcoders

/transcoder/terminate

Code Block
languagejs
themeRDark
{
 "uri":"transcoder2://tcode2"
}

200 – OK

404 – Not found

Stop transcoder and its output stream

/transcoder2/set_watermark
Code Block
languagejs
themeRDark
{
 "uri":"transcoder2://tcode1",
 "watermark":"/opt/media/logo.png",
 "x":10,
 "y":10,
 "marginTop":5,
 "marginLeft":5,
 "marginBottom":5,
 "marginRight":5
}

200 - OK

400 - Bad request

404 - Not found

Add watermark to transcoder output stream

Parameters

Name

Description

Example

uri

Transcoder URL

transcoder2://tcode2
localStreamNameTranscoder output stream name
testT
remoteStreamNameStream name to transcode
test
localMediaSessionIdTranscoder media session Id
82ad5545-e11e-4f0f-801a-49e69d8c38f2

status

Transcoder state

PROCESSED_LOCAL
hasAudioOutput stream has audio
true
hasVideoOutput stream has video
true
recordOutput stream is recorded
false
Encoder parameters
widthPicture width
320
heightPicture height
240
audioCodecAudio codecmpeg4-generic
audioRateAudio sample rate, Hz 44100
audioChannelsAudio channels2
audioBitrateAudio bitrate, bps64000
videoCodecVideo codecH264
keyFrameIntervalKey frame generation interval (GOP)
30
fpsFrames per second
30
bitrateVideo bitrate, in kbps
500
typeEncoder type
OPENH264
watermarkWatermark fileTest.png
videoRateVideo sample rate, Hz90000

Known limits

1. If video transcoding parameters are passed for audio only stream, or audio transcoding parameters are passed for video only stream, 400 Bad request will return

Quick manual for testing

1. For test we use

  • WCS server;
  • Two Way Streaming web application to publish a stream;
  • Player web application to play an output stream;
  • Chrome browser with REST client to send REST queries to server

2. Open Two Way Streaming application and publish stream named test

Image Added

3. Open REST client and send REST query /transcoder/startup

Image Added

4. Open Player application, set testT to Stream field and click Start

Image Added

5. Open REST client adn send REST query /transcoder/terminate

Image Added

6. Playback will be stopped due to transcoder stop

Image Added

Picture aspect ratio preserving

By default, if the stream is published with one picture resolution and is requested to play with another resolution, WCS tries to preserve picture aspect ratio. For example, if stream is published on server with resolution 640x360, aspect ratio 16:9, and subscriber requests to play it with resolution 320x240 (4:3), the stream will be transcoded to resolution 320x180 (16:9). If subscriber requests picture height only without setting width, aspect ratio will also be preserved.

To disable picture aspect ratio preserving, the following parameter sho;ud be set in flashphoner.properties file

Code Block
themeRDark
video_transcoder_preserve_aspect_ratio=false

In this case stream will be transcoded to picture width and height that are requested by subscriber. If subscriber does not set picture height, it wiil be set to 120. If subscriber does not set picture width, it wiil be set to 160.

Transcoder output stream audio and video synchronization

By default transcoder does not synchronize output stream audio and video, leaving sinchronization value as is. This can lead to out of audio and video sync in stream transcoded. To prevent this, the pacer buffer is added in build 5.2.543 which can be enabled with the following parameter

Code Block
themeRDark
av_paced_sender=true

Pacer buffer maximum size is set in frames by the following parameter

Code Block
themeRDark
av_paced_sender_max_buffer_size=5000

By default pacer buffer size is 5000 frames.

The statistics information received by the following query is uused to control pacer buffer usage

Code Block
languagebash
themeRDark
curl -s 'http://localhost:8081/?action=stat&format=json&groups=buffer_stats'

A certain stream watermarking

Since build 5.2.693 it is possible to add watermark to transcoded stream when creating transcoder using REST API, for example

Code Block
languagejs
themeRDark
{
 "uri": "transcoder://tcode1",
 "remoteStreamName": "test",
 "localStreamName": "testT",
 "encoder": {
  "width": 640,
  "height": 480,
  "keyFrameInterval": 30,
  "fps": 30,
  "watermark": "Test.png"
 }
}

By default, if file name only is passed, watermark picture file should be placed to /usr/local/FlashphonerWebCallServer/conf folder. The full path to the file can also be passed, for example

Code Block
languagebash
themeRDark
{
 "uri": "transcoder://tcode1",
 "remoteStreamName": "test",
 "localStreamName": "testT",
 "encoder": {
  "width": 640,
  "height": 480,
  "keyFrameInterval": 30,
  "fps": 30,
  "watermark": "/opt/media/Test.png"
 }
}

Adding and changing stream watermark dynamically

Since build 5.2.1349 in is possible to dynamically add or change stream watermark without stopping the transcoder. A watermark can be added, changed or moved to another picture location according to coordinates defined using REST API query /transcoder2/set_watermark 

Code Block
languagejs
themeRDark
{
 "uri":"transcoder2://tcode1",
 "watermark":"/opt/media/logo.png",
 "x":10,
 "y":10,
 "marginTop":5,
 "marginLeft":5,
 "marginBottom":5,
 "marginRight":5
}

Where

  • watermark - watermark file name
  • x, y - top left watermark corner coordinates on the stream picture
  • marginTop, marginLeft, marginBottom, marginRignt - watermark margins from stream picture borders

If watermark coordinates are out of stream picture bounds, the watermark will be scaled to the bounds using margins.

To move watermark to another location on the stream picture, send the query with the same file name and a new coordinates. To remove watermark from the stream picture, send the query with empty watermark field

Code Block
languagejs
themeRDark
{
 "uri":"transcoder2://tcode1",
 "watermark":""
}

Multithreaded encoding

Since build 5.2.816 multithreaded strems encoding is supported using OpenH264 encoder. Encoder threads count can be set with the following parameter

Code Block
themeRDark
video_encoder_max_threads=2

By default, streams will be encoded in 2 threads.

Multi threaded encoding is enabled depending on transcoder output stream resolution. The threshold can be set with the following parameter

Code Block
themeRDark
video_encoder_second_thread_threshold=777000

The threshold value is the product of the picture width multiplication to the height. Therefore, 720p and higher resolutions wiil be encoded in multiple threads. This threshold can be lowered if necessary. For example, to encode 480p pictures in multiple threads, set the following value

Code Block
themeRDark
video_encoder_second_thread_threshold=408950

Known issues

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

СSymptoms: picture quality is not changing when using different constraints.video.quality values, for example

Code Block
themeRDark
constraints.video.quality=5

does not differ from 

Code Block
themeRDark
constraints.video.quality=20

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

Code Block
themeRDark
encoder_priority=FF