Video playback. VoD/OTT

Unique player name

Accepts an object with specified input parameters.

Depending on the input type, different parameters are passed:

1. When input is SRT Servers module from the Callaba Engine:

{ input_type: "INPUT_TYPE_SRT_SOFTWARE", input_server_id: Objectid, input_stream_id: "publisher/srt-server-name/srt-stream-01" }

Note:

Use INPUT_TYPE_SRT_HARDWARE, if you plan to get your stream from a hardware encoder. This will perform additional optimization
inside Callaba Engine. If your senders are mobile devices or computers, use INPUT_TYPE_SRT_SOFTWARE

2. When input is RTMP Servers module from Callaba Engine:

{ input_type: "INPUT_TYPE_RTMP_SOFTWARE" input_server_id: Objectid, input_stream_id: "publisher/srt-server-name/srt-stream-01" }

In this case, you pass in the ID of your RTMP server and the key of the stream you want to convert.

Note

Use INPUT_TYPE_RTMP_HARDWARE, if you plan get your stream from a hardware encoder. This will perform additional optimization inside Callaba Engine. If your senders are mobile devices or computers, use INPUT_TYPE_RTMP_SOFTWARE

In this case, you are passing in the id of your SRT server and the publisher's id of the stream you want to convert.

3. When input is received via port listening, without using other modules.

Possible input_type values:

INPUT_TYPE_SRT_LISTEN: listen on SRT port
INPUT_TYPE_RTMP_LISTEN: listen on RTMP port
INPUT_TYPE_RTSP_LISTEN: listen on RSTP port
INPUT_TYPE_UDP_LISTEN: listen on UDP port
INPUT_TYPE_HTTP_LISTEN: - listen on HTTP port


Example of the SRT listen request on port 2035 :

{ input_type: "INPUT_TYPE_SRT_URL" , input_stream_listen_port: { port: 2035, transport: "UDP" } }

For this type of input, you must explicitly specify the port you are listening and the type of transport you are using.
Optionally, you can also pass module_name and module_type for more flexible organization of your application.

For example, if you use the method for receiving all the inputs, you'd be able to see which of the processes you've made earlier occupies the server port.

This type of input accepts the following transport values :

For SRT, WEBRTC, RTP the transport value is UDP.
For all of the rest transport value is TCP.

4. When input is a URL, from where the stream is picked up for further conversion.

Possible input_type values:

INPUT_TYPE_SRT_URL: listen SRT address
INPUT_TYPE_RTMP_URL: listen RTMP address
INPUT_TYPE_RTSP_URL: listen RTSP address
INPUT_TYPE_UDP_URL: listen UDP address
INPUT_TYPE_HTTP_URL: listen HTTP address
INPUT_TYPE_OTHER: listen any address
INPUT_TYPE_HLS_URL: listen HLS address
INPUT_TYPE_MPEG_DASH_URL: listen MPEG-DASH address

For this type of input, specify the address where you want to receive video.

{ input_type: "INPUT_TYPE_SRT_URL", input_stream_url : "srt://1.2.3.4:8000" }

Additionally, you can control the protocol by adjusting its parameters.

For example:

{ input_stream_url : "srt://1.2.3.4:8000?rcvbuf=12036704" }

Controlling parameters is available for all protocols.

5. When you don't have video but need a test stream of video and audio

{ input_type: "INPUT_TYPE_GENERATE_TEST_VIDEO" } 

It generates a default test stream (1920 by 1080, 24, 6000Kbit/s) with a duration of 1 hour and 216 Hz sine wave audio.

If necessary, you can control the settings of the test video by passing parameters to the input object:

• encoding_rate. Default value is 24 
• sound_hz. Default value is 216
• resolution_width. Default value is 1920
• resolution_height. Default value is 1080
• video_duration_sec. Default value is 3600
• test_video_bitrate. Default value is 6000

Example:

{ input_type: "INPUT_TYPE_GENERATE_TEST_VIDEO", test_video_bitrate: 2500 } 

Acceptable values are from 1 to 65535.

Since HLS or MPEG-DASH uses TCP as a transport, after creating a player on the specified port, the corresponding TCP port will be used.

To find out if a port is free, use the /api/ports/getAll method from the /api/ports section

This parameter specifies how many HLS fragments must be loaded before playing. For good HLS experience we recommend loading 3 fragments.

Edge of live delay.  If set to 3, playback will start from fragment N-3, N being the last fragment of the live playlist. Decreasing this value is likely to cause playback stalls. For good HLS experience we recommend using 4 fragments

HLS fragment size. For good HLS experience we recommend using 3 seconds fragments.

Please make sure you have key frames at least every 2 seconds in your input video stream (or a close value) in your HLS fragment settings.

Use the transcoding to change GOP value if you cannot change this parameter in your input video stream

HLS fragments playlist length. For good HLS experience we recommend using 60 seconds.

DASH fragment size. For good DASH experience we recommend using 3 seconds fragments.

Please make sure you have key frames at least every 2 seconds in your input video stream or value near your DASH fragment settings.

Use the transcoding to change GOP value if you cannot change this parameter in your input video stream

DASH fragments playlist length. For good DASH experience we recommend using 60 seconds.

Takes an object with transform settings:

Example:

{ video_transcoding: "libx265", output_video_bitrate: 4000 } 

Properties:

video_transcoding - controls output codec type. Possible values:

• libx264 - convert to H.264 via CPU
• libx265 - convert to H.265 via CPU
• mpsoc_vcu_h264 - convert to H.264 via graphics accelerator card on Amazon Web Services (VT1 instances)
• mpsoc_vcu_hevc - convert to HEVC via graphics accelerator card on Amazon Web Services (VT1 instances)

output_video_bitrate - controls output bitrate. The value is specified in kilobits.

force_key_frames - use this parameter if you need to cut your stream into smaller HLS fragments. For good the streaming experience we recommend inserting a key frame every 2 seconds

gop - Set this to 2x frame rate for a 2 second GOP

Frame width  - For example, 1920

Frame height  - For example, 1080

preset - controls codec preset settings. Possible values: Disabled, ultrafast, superfast, very fast, faster, fast, medium, slow, slower, veryslow

tune - controls the fine tuning of the codec, possible values: Disabled, film, animation, grain, stillimage, fastdecode, zerolatency.

crf - sets the constant video quality to be controlled. Possible values are from 0 to 51 where 0 is lossless and 51 is the worst possible.

pix_fmt - video pixel format. Possible values: Disable, yuv420p, yuvj420p, yuv422p, yuvj422p, yuv444p, yuvj444p, nv12, nv16, nv21, yuv420p10le, yuv444p10le, nv20le

filter_fps - allows you to change the number of frames per second, through a filter
after transcoding and before output.

audio_trancoding - allows to convert audio. Possible values: aac, mp3

output_audio_bitrate - sets the output bitrate, in kilobits, for example 320

sample_rate - sets the resampling rate, in hertz. For example 44100. We recommend using AAC, because some browsers still don't work well with MP3s

Additional settings for the graphics accelerator card:

• slices. Valid values: 0 to 68 Slices are a fundamental part of the stream format. You can operate on slices in parallel to increase speed at which a stream is processed. However, operating on multiple “slices” of video at once will have a negative impact on video quality. This option must be used when encoding 4k streams to H.264 in order to sustain real-time performance. The maximum practical value for this option is 4 since there are 4 encoder cores in a device.
• cores. Valid values: 0 to 4 The encoder plugin automatically determines how many encoder cores are needed to sustain real-time performance (e.g. 1 for 1080p60, 4 for 4K60). The -cores option can be used to manually specify how many encoder cores are to be used for a given job. When encoding file-based clips with a resolution of 1080p60 or lower, leveraging additional cores may increase performance. This option will provide diminishing returns when multiple streams are processed on the same device. This option has no impact on live streaming use-cases as a video stream cannot be processed faster than it is received.

Controls the state of the process. Possible values are true or false. The default value is true.

A unique identifier of the playback process. Is an object and looks similar to the hashed string. 

Returns the creation date of the playback process

id - identifier of the playback process to be changed.

A unique identifier of the process

Returns the date the process was last modified

Success result. Possible value: true or false.

Returns an array of the playback processes

id - identifier of the playback process

Returns an object of the playback process

Success result. Possible value: true or false.

Success result. Possible value: true or false.

Current bitrate (kilobits)

Success result. Possible value: true or false.