Agora Objective-C API Reference for iOS/macOS

AgoraVideoEncoderConfiguration Class Reference

Inherits from NSObject
Declared in AgoraObjects.h

Overview

Properties of the video encoder configuration.

  dimensions

The video frame dimension used to specify the video quality in the total number of pixels along a frame’s width and height.

@property (assign, nonatomic) CGSize dimensions

Discussion

You can customize the dimension, or select from the following list:

  • AgoraVideoDimension120x120
  • AgoraVideoDimension160x120
  • AgoraVideoDimension180x180
  • AgoraVideoDimension240x180
  • AgoraVideoDimension320x180
  • AgoraVideoDimension240x240
  • AgoraVideoDimension320x240
  • AgoraVideoDimension424x240
  • AgoraVideoDimension360x360
  • AgoraVideoDimension480x360
  • AgoraVideoDimension640x360
  • AgoraVideoDimension480x480
  • AgoraVideoDimension640x480
  • AgoraVideoDimension840x480
  • AgoraVideoDimension960x720
  • AgoraVideoDimension1280x720
  • AgoraVideoDimension1920x1080 (macOS only)
  • AgoraVideoDimension2540x1440 (macOS only)
  • AgoraVideoDimension3840x2160 (macOS only)

Note:

  • The dimension does not specify the orientation mode of the output ratio. For how to set the video orientation, see AgoraVideoOutputOrientationMode.
  • Whether 720p can be supported depends on the device. If the device cannot support 720p, the frame rate will be lower than the one listed in the table. Agora optimizes the video in lower-end devices.
  • iPhones do not support video frame dimensions above 720p.

Declared In

AgoraObjects.h

  frameRate

The frame rate of the video (fps).

@property (assign, nonatomic) NSInteger frameRate

Discussion

You can either set the frame rate manually or choose from the following options. We do not recommend setting this to a value greater than 30.

  • AgoraVideoFrameRateFps1(1): 1 fps
  • AgoraVideoFrameRateFps7(7): 7 fps
  • AgoraVideoFrameRateFps10(10): 10 fps
  • AgoraVideoFrameRateFps15(15): 15 fps
  • AgoraVideoFrameRateFps24(24): 24 fps
  • AgoraVideoFrameRateFps30(30): 30 fps
  • AgoraVideoFrameRateFps60(30): 60 fps (macOS only)

Declared In

AgoraObjects.h

  minFrameRate

The minimum video encoder frame rate (fps).

@property (assign, nonatomic) NSInteger minFrameRate

Discussion

The default value is DEFAULT_MIN_BITRATE(-1) (the SDK uses the lowest encoder frame rate). For information on scenarios and considerations, see Set the Video Profile (iOS) or Set the Video Profile (macOS).

Declared In

AgoraObjects.h

  bitrate

The bitrate of the video.

@property (assign, nonatomic) NSInteger bitrate

Discussion

Sets the video bitrate (Kbps). Refer to the table below and set your bitrate. If you set a bitrate beyond the proper range, the SDK automatically adjusts it to a value within the range. You can also choose from the following options:

  • AgoraVideoBitrateStandard: (recommended) the standard bitrate mode. In this mode, the bitrates differ between the Live-broadcast and Communication profiles:

    • Communication profile: the video bitrate is the same as the base bitrate.
    • Live-broadcast profile: the video bitrate is twice the base bitrate.
  • AgoraVideoBitrateCompatible: the compatible bitrate mode. In this mode, the bitrate stays the same regardless of the profile. In the Live-broadcast profile, if you choose this mode, the video frame rate may be lower than the set value.

Agora uses different video codecs for different profiles to optimize the user experience. For example, the Communication profile prioritizes the smoothness while the Live-broadcast profile prioritizes the video quality (a higher bitrate). Therefore, Agora recommends setting this parameter as AgoraVideoBitrateStandard.

Video Bitrate Table

Resolution Frame Rate (fps) Base Bitrate (Kbps, for Communication) Live Bitrate (Kbps, for Live Broadcast)
160 × 120 15 65 130
120 × 120 15 50 100
320 × 180 15 140 280
180 × 180 15 100 200
240 × 180 15 120 240
320 × 240 15 200 400
240 × 240 15 140 280
424 × 240 15 220 440
640 × 360 15 400 800
360 × 360 15 260 520
640 × 360 30 600 1200
360 × 360 30 400 800
480 × 360 15 320 640
480 × 360 30 490 980
640 × 480 15 500 1000
480 × 480 15 400 800
640 × 480 30 750 1500
480 × 480 30 600 1200
848 × 480 15 610 1220
848 × 480 30 930 1860
640 × 480 10 400 800
1280 × 720 15 1130 2260
1280 × 720 30 1710 3420
960 × 720 15 910 1820
960 × 720 30 1380 2760
1920 × 1080 15 2080 4160
1920 × 1080 30 3150 6300
1920 × 1080 60 4780 6500
2560 × 1440 30 4850 6500
2560 × 1440 60 6500 6500
3840 × 2160 30 6500 6500
3840 × 2160 60 6500 6500

Note:

The base bitrate in this table applies to the Communication profile. The Live-broadcast profile generally requires a higher bitrate for better video quality. Agora recommends setting the bitrate mode as AgoraVideoBitrateStandard. You can also set the bitrate as twice the base bitrate.

Declared In

AgoraObjects.h

  minBitrate

The minimum encoding bitrate.

@property (assign, nonatomic) NSInteger minBitrate

Discussion

Sets the minimum encoding bitrate (Kbps).

The Agora SDK automatically adjusts the encoding bitrate to adapt to network conditions. Using a value greater than the default value forces the video encoder to output high-quality images but may cause more packet loss and hence sacrifice the smoothness of the video transmission. Unless you have special requirements for image quality, Agora does not recommend changing this value.

Note:

This parameter applies only to the Live-broadcast profile.

Declared In

AgoraObjects.h

  orientationMode

The video orientation mode of the video: AgoraVideoOutputOrientationMode.

@property (assign, nonatomic) AgoraVideoOutputOrientationMode orientationMode

Discussion

  • AgoraVideoOutputOrientationModeAdaptative(0): (Default) The output video always follows the orientation of the captured video, because the receiver takes the rotational information passed on from the video encoder.
    • If the captured video is in landscape mode, the output video is in landscape mode.
    • If the captured video is in portrait mode, the output video is in portrait mode.
  • AgoraVideoOutputOrientationModeFixedLandscape(1): The output video is always in landscape mode. If the captured video is in portrait mode, the video encoder crops it to fit the output. This applies to situations where the receiver cannot process the rotational information. For example, CDN live streaming.
  • AgoraVideoOutputOrientationModeFixedPortrait(2): The output video is always in portrait mode. If the captured video is in landscape mode, the video encoder crops it to fit the output. This applies to situations where the receiver cannot process the rotational information. For example, CDN live streaming.

For scenarios with video rotation, Agora provides Basic: Video Rotation Guide to guide users on how to set this parameter to get the preferred video orientation.

Declared In

AgoraObjects.h

  degradationPreference

The video encoding degradation preference under limited bandwidth.

@property (assign, nonatomic) AgoraDegradationPreference degradationPreference

Discussion

AgoraDegradationPreference:

  • AgoraDegradationMaintainQuality(0): (Default) Degrades the frame rate to guarantee the video quality.
  • AgoraDegradationMaintainFramerate(1): Degrades the video quality to guarantee the frame rate.

Declared In

AgoraObjects.h

– initWithSize:frameRate:bitrate:orientationMode:

Initializes and returns a newly allocated AgoraVideoEncoderConfiguration object with the specified video resolution.

- (instancetype _Nonnull)initWithSize:(CGSize)size frameRate:(AgoraVideoFrameRate)frameRate bitrate:(NSInteger)bitrate orientationMode:(AgoraVideoOutputOrientationMode)orientationMode

Parameters

size

Video resolution.

frameRate

Video frame rate.

bitrate

Video bitrate.

orientationMode

AgoraVideoOutputOrientationMode.

Return Value

An initialized AgoraVideoEncoderConfiguration object.

Declared In

AgoraObjects.h

– initWithWidth:height:frameRate:bitrate:orientationMode:

Initializes and returns a newly allocated AgoraVideoEncoderConfiguration object with the specified video width and height.

- (instancetype _Nonnull)initWithWidth:(NSInteger)width height:(NSInteger)height frameRate:(AgoraVideoFrameRate)frameRate bitrate:(NSInteger)bitrate orientationMode:(AgoraVideoOutputOrientationMode)orientationMode

Parameters

width

Width of the video.

height

Height of the video.

frameRate

Video frame rate.

bitrate

Video bitrate.

orientationMode

AgoraVideoOutputOrientationMode.

Return Value

An initialized AgoraVideoEncoderConfiguration object.

Declared In

AgoraObjects.h

Is this page helpful?