Skip to end of metadata
Go to start of metadata

The cases when transcoding is enabled

Video stream transcoding will be enabled automatically in one of the following cases:

1. Streamer and player codecs do not match by name.
For example, streamer publishes H.264 stream and player tries to play VP8.

2. H.264 codecs are differ by packetization-mode parameter
For example, streamer publishes stream with packetization-mode=1 (default value) and player explicitly sets packetization-mode=0. The situation is quite rare, because almost all  players support packetization-mode=1

3. Player resolution is explicitly set.
Example:

session.createStream({name:"stream1", constraints:{audio:true, video:{width:640,height:480}}}).play();

If the player explicitly sets the resolution desired, transcoding will be enabled even when the player resolution exactly matches the publisher one. This is done because WebRTC browser can change video resolution while publishing stream. To adapt the stream to the resolution that is specified by player, the stream should be transcoded.

4. Player bitrate is explicitly set.

Example

session.createStream({name:"stream1", constraints:{audio:true, video:{bitrate:300}}}).play();

In this case transcoder will be enabled to encode the stream to the bitrate specified.

Besides, transcoding can be forcibly enabled on server using this parameter in flashphoner.properties file

disable_streaming_proxy=true

Transcoding dramatically increases the server resources consumption (CPU cores). Therefore, use it carefully!

Force transcoding disabling

Transcoding may be fully disabled on server using this parameter in flashphoner.properties file

transcoding_disabled=true

If trascoding is forcefully disabled, in all four cases described above the TRANSCODING_REQUIRED_BUT_DISABLED error will be returned to client.

Transcoding disabling does not affects stream mixer, transcoding will be enabled automatically when mixer is used.

Transcoding management with REST API


REST query should be HTTP/HTTPS POST request as:

  • HTTP: http://test.flashphoner.com:8081/rest-api/transcoder/startup
  • HTTPS: https://test.flashphoner.com:8444/rest-api/transcoder/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
  • /transcoder/startup is REST query


REST queries and response states


REST query

Request example

Response example

Response states

Description

/transcoder/startup

{
 "uri": "transcoder://tcode1",
 "remoteStreamName": "test",
 "localStreamName": "testT",
 "encoder": {
  "width": 640,
  "height": 480,
  "keyFrameInterval": 30,
  "fps": 30
 }
}

409 - Conflict

500 - Internal error


Create transcoder with defined parameters for certain stream


/transcoder/find
{
 "remoteStreamName": "test"
}
[
    {
        "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 the transcoder by certain criteria

/transcoder/find_all


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

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

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

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

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

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

6. Playback will be stopped due to transcoder stop

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

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.