Automatic Encoder Configuration API

Updated: Oct 19, 2020

Copy for LLM

The Automatic Encoder Configuration API allows you to automatically configure encoding settings before going Live on Facebook. The API is designed to be stateless and lightweight so user authentication or tokens are not required.

Configure an Encoder

To automatically configure encoder settings, send a GET request to the video_encoder_settings endpoint.

curl -i -X GET \
    "https://graph.facebook.com/{graph-api-version}/video_encoder_settings
        ?video_type=live
        &input_video_width=1920
        &input_video_height=1080
        &input_video_framerate=30
        &input_video_bitrate=6000
        &input_audio_channels=2
        &input_audio_samplerate=48000
        &cap_streaming_protocols=rtmps
        &cap_video_codecs=h264
        &cap_audio_codecs=aac"

On success, your app will receive the following response:

{
   "streaming_protocol":"rtmps",
   "rtmps_settings": {
       "video_codec":"h264",
       "video_codec_settings": {
           "video_bitrate":6000,
           "video_width":1920,
           "video_height":1080,
           "video_framerate":30,
           "video_h264_profile":"high",
           "video_h264_level":"4.1",
           "video_gop_size":60,
           "video_gop_type": "fixed",
           "video_gop_closed": true,
           "video_gop_num_b_frames":3,
           "video_gop_num_ref_frames":3,
           "video_scan_mode": "progressive",
           "rate_control_mode": "cbr",
           "buffer_size": 12000
       },
       "audio_codec":"aac",
       "audio_codec_settings": {
           "audio_bitrate":256,
           "audio_channels":2,
           "audio_samplerate":48000
       }
   }
}

Reference

Input Fields

The following fields are required for all GET video_endcoder_settings endpoint requests.

video_encoder_settings Fields	Description
`cap_audio_codecs` array<enum{aac}>	A comma separated list of audio codecs you are capable of sending to Facebook.
`cap_streaming_protocols` array<enum{rtmps, https_dash, webrtc}>	A comma separated list of streaming protocols, in order of preference.
`cap_video_codecs` array<enum{h264}>	A comma separated list of video codecs you are capable of sending to Facebook.
`input_audio_channels` integer	The number of audio channels in the audio input, for example, `2`.
`input_audio_samplerate`integer	The audio sample rate, for example, `48000`.
`input_video_bitrate` integer	The video bitrate, in kbps, for example, `6000`.
`input_video_framerate` float	The video frame rate for example, `30`, `29.97`, `59.97`.
`input_video_height` integer	The height of the video, for example, `1080`.
`input_video_width` integer	The width of your video, for example, `1920`.
`video_type`enum{live,vod}	The type of video, `live` or `vod`.

Response Fields

The response returned contains recommendations for your encoder such as the streaming protocol, and audio and video codecs and settings for each.

Response Fields	Description
`streaming_protocol` enum{rtmps, https_dash, webrtc}	The recommended streaming protocol.
`{streaming-protocol}_settings`	`audio_codec` — The recommended audio codec. `audio_codec_settings` — The recommended audio codec settings. `video_codec` — The recommended video codec. `video_codec_settings`— The recommended video codec settings.

Recommendations for Common Audio Codec Settings

A audio_codec_settings object contains the audio encoding settings for the recommended audio codec. Different codecs will have different values, but they share some common settings.

Common Audio Codec Settings	Recommendation
`audio_bitrate` integer	Audio bitrate in kbps.
`audio_channels` integer	Number of audio channels.
`audio_samplerate` integer	Recommended audio sample rate, for example, `48000`.

Recommendations for Common Video Codec Settings

A video_codec_settings object contains the video encoding settings for the recommended video codec. Different codecs will have different values, but they all share some common settings.

Common Video Codec Setting	Description
`buffer_size` integer	The recommended size of buffer in kb, for example, `5000`.
`pixel_aspect_ratio` float	The recommended pixel aspect ratio as a decimal value, for example, `1.0` would be used for 1:1/square.
`rate_control_mode` enum{cbr}	The recommended rate control mode.
`video_bitrate`integer	The recommended video max bit rate, in kbps.
`video_framerate`float	The recommended video frame rate, in frames per second.
`video_gop_closed` boolean	The recommendation for a closed GOPs, `true`, or not, `false`.
`video_gop_num_b_frames` integer	The recommended number of B frames in a GOP, for example, `3`.
`video_gop_num_ref_frames` integer	The recommended number of reference frames in a GOP, for example, `3`.
`video_gop_size` integer	Recommended GOP size, in frames.
`video_gop_type` enum{fixed}	The recommended GOP type.
`video_h264_level` enum{4.1}	The recommended `h264` level.
`video_h264_profile` enum{high}	The recommended h264 profile.
`video_height`integer	The recommended video height, in pixels.
`video_scan_mode` enum{progressive}	The recommended scan mode.
`video_width`integer	The recommended video width, in pixels.