REST queries and response states

Name

Description

Example

uri

Transcoder URL

transcoder://tcode1

localStreamNameTranscoder output stream name

testT

remoteStreamNameStream name to transcode

test

localMediaSessionIdTranscoder media session Id42a92132-bcd1-4436-a96f

REST query

Request example

Response example

Response states

Description

/transcoder/startup

Code Block

language	js
theme	RDark

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

language	js
theme	RDark

{
 "remoteStreamName": "test"
}

Code Block

language	js
theme	RDark

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

language	js
theme	RDark

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

language	js
theme	RDark

{
"uri":"transcoder://tcode1"
}

200 - Transcoders is terminated

404 - Transcoder not found

Stop transcoder and its output stream

Parameters

/transcoder/set_watermark

Code Block

language	js
theme	RDark

{
 "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
localStreamName	Transcoder output stream name	testT
remoteStreamName	Stream name to transcode	test
localMediaSessionId	Transcoder media session Id	42a92132-bcd1-4436-a96f-3fec36b32b37
status	Transcoder state	PROCESSED_LOCAL
hasAudio	Output stream has audio	true
hasVideo	Output stream has video	true
record	Output stream is recorded	false
Encoder parameters
width	Picture width	640
height	Picture height	480
keyFrameInterval	Key frame generation interval (GOP)	30
fps	Frames per second	30
bitrate	Bitrate, in kbps	500
type	Codec	OPENH264
watermark	Watermark file	Test.png

...

REST queries and response states

REST query

Request example

Response example

Response states

Description

/transcoder2/startup

Code Block

language	js
theme	RDark

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

}

Name

Description

Example

uri

Transcoder URL

transcoder2://tcode2

localStreamNameTranscoder output stream name

testT

remoteStreamNameStream name to transcode

test

localMediaSessionIdTranscoder

  "audioBitrate": 64000
 }
}

200 - OK

400 - Bad request

409 - Conflict

500 - Internal error

Create transcoder with defined parameters for certain stream

/transcoder2/find

Code Block

language	js
theme	RDark

{
 "remoteStreamName": "test"
}

Code Block

language	js
theme	RDark

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

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

language	js
theme	RDark

{
 "uri":"transcoder2://tcode2"
}

200 – OK

404 – Not found

Stop transcoder and its output stream

Parameters

/transcoder2/set_watermark

Code Block

language	js
theme	RDark

{
 "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
localStreamName	Transcoder output stream name	testT
remoteStreamName	Stream name to transcode	test
localMediaSessionId	Transcoder media session Id	82ad5545-e11e-4f0f-801a-49e69d8c38f2
status	Transcoder state	PROCESSED_LOCAL
hasAudio	Output stream has audio	true
hasVideo	Output stream has video	true
record	Output stream is recorded	false
Encoder parameters
width	Picture width	320
height	Picture height	240
audioCodec	Audio codec	mpeg4-generic
audioRate	Audio sample rate, Hz	44100
audioChannels	Audio channels	2
audioBitrate	Audio bitrate, bps	64000
videoCodec	Video codec	H264
keyFrameInterval	Key frame generation interval (GOP)	30
fps	Frames per second	30
bitrate	Video bitrate, in kbps	500
type	Encoder type	OPENH264
watermark	Watermark file	Test.png
videoRate	Video sample rate, Hz	90000

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

...

Code Block

language	bash
theme	RDark

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

Multithreaded encoding

...

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

language	js
theme	RDark

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

language	js
theme	RDark

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

theme	RDark

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

theme	RDark

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

theme	RDark

video_encoder_second_thread_threshold=408950

H264 profile-level-id detection

Since build 5.2.1644 a command line tool is available to detect H264 encoder profile-level-id according to encoding parameters:

Code Block

language	bash
theme	RDark

sudo bash /usr/local/FlashphonerWebCallServer/tools/h264_profile_tool.sh --config=codec,resolution,profile,level[,preset]

Where

codec - encoder name: OPENH264 or FF
resolution - resolution
profile - encoding profile
level - encoding level
preset - encoding preset

For example, with the following encoding parameters

Code Block

language	bash
theme	RDark

sudo bash /usr/local/FlashphonerWebCallServer/tools/h264_profile_tool.sh --config="OPENH264,1280x720,66,31,ultrafast"

the tool will display the following profile-level-id

Code Block

language	bash
theme	RDark

42c01f <= "OPENH264,66,31,ultrafast,1280x720"

The tool also may generate a full supported profiles list for all encoders

Code Block

language	bash
theme	RDark

sudo bash /usr/local/FlashphonerWebCallServer/tools/h264_profile_tool.sh --catalog --output=catalog.csv

or for certain encoder

Code Block

language	bash
theme	RDark

sudo bash /usr/local/FlashphonerWebCallServer/tools/h264_profile_tool.sh --catalog --encoders=OPENH264 --output=openH264.csv

The list is generated as CSV file in the form

Code Block

theme	RDark

codec,profile,level,preset,resolution,profile-level-id

for example

Code Block

theme	RDark

FF,0,0,fast,320x180,42c01e
...

If there is no encoder library in the server distribution, the tool will display the following error while requesting a profile-level-id

Code Block

theme	RDark

Unable to create instance of encoder: FF

and the following error will be displayed while requesting a full supported profiles list

Code Block

theme	RDark

video_encoder_max_threads=2

By default, streams will be encoded in 2 threads.

...

Unsupported encoder: FF

and CSV file of zero length will be created.

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

theme	RDark

video_encoder_second_thread_threshold=777000

...

constraints.video.quality=5

does not differ from

Code Block

theme	RDark

constraints.video.quality=20

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

Code Block

theme	RDark

video_encoder_second_thread_threshold=408950priority=FF

Space shortcuts

Page tree

Versions Compared

Old Version 10

New Version 15

Key

REST queries and response states

Parameters

Parameters

REST queries and response states

Parameters

Parameters

Known limits

Multithreaded encoding

Adding and changing stream watermark dynamically

Multithreaded encoding

H264 profile-level-id detection

Known issues

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 10

New Version 15

Key

REST queries and response states

Parameters

Parameters

REST queries and response states

Parameters

Parameters

Known limits

Multithreaded encoding

Adding and changing stream watermark dynamically

Multithreaded encoding

H264 profile-level-id detection

Known issues