Graph API Version

Live Encoder

Reading

An EntLiveEncoder is for the live encoders that can be associated with video broadcasts. This is part of the reference live encoder API

Example

Graph API Explorer
GET /v5.0/{live-encoder-id} HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{live-encoder-id}',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/{live-encoder-id}",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{live-encoder-id}",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{live-encoder-id}"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];
If you want to learn how to use the Graph API, read our Using Graph API guide.

Parameters

This endpoint doesn't have any parameters.

Fields

FieldDescription
id
numeric string

The id of the object

brand
string

The live encoder brand (eg: Wowza)

creation_time
datetime

Creation time

current_broadcast

The broadcast that is currently handled by the live encoder

current_input_stream

The ingest stream this encoder is currently streaming to

device_id
string

The live encoder unique device ID used for the registration process

last_heartbeat_time
datetime

Last time we received an heartbeat from the live encoder

model
string

The live encoder model (eg: Wowza Streaming Engine)

name
string

The live encoder name set by the manufacturer or the user to differentiate between multiple encoder from the same manufacturer

status
enum

The current status of this live encoder (eg: ready, register, preview, live...)

version
string

The live encoder version (eg: 4.0.1)

Validation Rules

ErrorDescription
100Invalid parameter

Creating

You can make a POST request to telemetry edge from the following paths:
When posting to this edge, a LiveEncoder will be created.

Parameters

ParameterDescription
bitrate
int64

Stream bitrate in kbps

broadcast_id
numeric string or integer

The live video id.

cpu_load_15m
float

CPU load over 15m

cpu_load_1m
float

CPU load over 1m

cpu_load_5m
float

CPU load over 5m

cpu_temperature
int64

the CPU temperature in degree Celcius

cpu_usage
float

The percentage of CPU usage

framerate
float

Frames per second

frames_dropped
float

The number of dropped frame per second

gpu_temperature
int64

the GPU temperature in degree Celcius

gpu_usage
float

the percentage of GPU usage

last_audio_timecode
int64

timestamp of the last audio frame received

last_video_keyframe_timecode
int64

last video keyframe timecode

last_video_timecode
int64

timestamp of the last video frame received

memory_usage
float

The percentage of encoder memory usage

network_latency
float

milliseconds between encoder and facebook ingestion server

network_rx_bandwidth
int64

The rx bandwidth in kilobits per seconds

network_rx_packets_dropped
float

The number of packets dropped per second

network_rx_packets_errors
float

The number of errors per second

network_tx_bandwidth
int64

The tx bandwidth in kilobits per seconds

network_tx_packets_dropped
float

The number of packets dropped per second

network_tx_packets_errors
float

The number of errors per second

process_uptime
int64

uptime of the main process

status
enum {NONE, READY, REGISTER, CAPTURE, PREVIEW, LIVE}

The status of live encoder

Required
timestamp
int64

The timestamp of this measure

total_audio_frames_sent
int64

total number of audio frames sent

total_video_frames_sent
int64

total number of video frames sent

total_video_keyframes_sent
int64

total number of video keyframes sent

uptime
int64

The uptime of the live encoder

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
100Invalid parameter
You can make a POST request to live_encoders edge from the following paths:
When posting to this edge, a LiveEncoder will be created.

Parameters

ParameterDescription
brand
string

Brand

Required
device_id
string

Device ID

Required
model
string

Model

Required
name
string

Name

Required
version
string

Version

Required

Return Type

Struct {
id: numeric string,
}

Validation Rules

ErrorDescription
200Permissions error
You can make a POST request to live_encoders edge from the following paths:
When posting to this edge, a LiveEncoder will be created.

Parameters

ParameterDescription
brand
string

Brand

Required
device_id
string

Device ID

Required
model
string

Model

Required
name
string

Name

Required
version
string

Version

Required

Return Type

Struct {
id: numeric string,
}

Validation Rules

ErrorDescription
100Invalid parameter
200Permissions error

Updating

You can update a LiveEncoder by making a POST request to /{live_encoder_id}.

Parameters

ParameterDescription
cap_audio_codecs
array<enum {AAC}>

List of supported audio codecs (eg: aac)

cap_streaming_protocols
array<enum {RTMPS, HTTPS_DASH, WEBRTC}>

List of supported streaming protocols (eg: rtmp)

cap_video_codecs
array<enum {H264}>

List of supported video codecs (eg: h264)

input_audio_channels
int64

Number of audio channels in audio input

input_audio_samplerate
int64

Input audio samplerate (eg: 48000)

input_video_framerate
string

Input video framerate (eg: 30000/1001)

input_video_gop_num_b_frames
int64

Input video number of B frames in a GOP (eg: 2)

input_video_gop_size
int64

Input video GOP size in frames (eg: 60)

input_video_height
int64

Input video height (eg: 1080)

input_video_interlace_mode
string

Input video interlaced mode (eg: progressive)

input_video_width
int64

Input video width (eg: 1920)

name
string

Live Encoder name

status
enum {NONE, READY, REGISTER, CAPTURE, PREVIEW, LIVE}

Current Live Encoder status

Required
target_token
string

A target token recently returned by the speed test API

version
string

Live Encoder Version

Return Type

This endpoint supports read-after-write and will read the node represented by id in the return type.
Struct {
action: string,
polling_interval: int32,
error_code: int32,
error_msg: string,
broadcast_id: numeric string,
streaming_url: string,
streaming_protocol: string,
video_bitrate: int32,
video_codec: string,
video_width: int32,
video_height: int32,
video_framerate: string,
video_gop_size: int32,
video_gop_num_b_frames: int32,
video_gop_num_ref_frames: int32,
video_interlace_mode: string,
video_h264_profile: string,
video_h264_level: string,
audio_bitrate: int32,
audio_channels: int32,
audio_codec: string,
audio_samplerate: int32,
}

Validation Rules

ErrorDescription
200Permissions error
100Invalid parameter

Deleting

You can delete a LiveEncoder by making a DELETE request to /{live_encoder_id}.

Parameters

This endpoint doesn't have any parameters.

Return Type

Struct {
success: bool,
}

Validation Rules

ErrorDescription
200Permissions error