Low-Latency Live Streaming
  • Platform
  • Framework / Engine
  • iOS
  • Android
  • macOS
  • Windows
  • Linux
  • Web
  • WeChat Mini Program

Beauty and Watermark

Update Time:2021-04-25 20:24

1 Introduction

There are times and occasions when the users want to look like their best self in a video conference call or a live broadcast. ZEGO Express-Video SDK provides retouching features such as skin smoothing and skin color adjustment that make users look amazing on live video.

ZEGO Express-Video SDK also provides the ability to watermark your video stream. For example, businesses and organizations can use the watermark feature to display their logo on the video.

2 Download the Sample Codes

Please refer to Sample Codes for how to download and run the sample code.

The sample code package contains many code examples of different features of the SDK. Please refer to the source file "/ZegoExpressExample/Topics/Beautify/ZGBeautifyViewController.m" for the code examples of how to use the APIs of the beauty and watermark features.

3 Prerequisites

Before implementing the beauty and watermark functions, please make sure:

  • ZEGO Express SDK has been integrated in the project to realize basic real-time audio and video functions. For details, please refer to Quick Starts.
  • A project has been created in ZEGO Admin Console and a valid AppID and AppSign have been applied. For details, please refer to Console - Project Management.

4 Implementation Steps

4.1 Using Beauty Features

Call the API enableBeautify to enable the beauty features as needed.

  • API Function Prototype:

    /// Beauty features
    typedef NS_OPTIONS(NSUInteger, ZegoBeautifyFeature) {
        /// No beauty effects.
        ZegoBeautifyFeatureNone = 0,
        /// Skin smoothing
        ZegoBeautifyFeaturePolish = 1 << 0,
        /// Entire screen color adjustment
        ZegoBeautifyFeatureWhiten = 1 << 1,
        /// Skin color adjustment
        ZegoBeautifyFeatureSkinWhiten = 1 << 2,
        /// Image sharpening
        ZegoBeautifyFeatureSharpen = 1 << 3,
    };
    
    /// Turn On/off Beauty Features.
    /// @discussion: Identify and retouch portraits in the video. It can be configured before or after the start of stream publishing.
    /// @param featureBitmask: Beauty features, in bitmask format. You can choose to enable several features in [ZegoBeautifyFeature] at the same time.
    - (void)enableBeautify:(ZegoBeautifyFeature)featureBitmask;
  • API Call Example:

    // Turn on skin smoothing and image sharpening
    [self.engine enableBeautify:ZegoBeautifyFeaturePolish | ZegoBeautifyFeatureSharpen];
    
    // Turn off all beauty features.
    [self.engine enableBeautify:ZegoBeautifyFeatureNone];

4.2 Customize the Beauty Parameters

When the beauty features are turned on, the SDK will use the default parameters of those features. You can call the API setBeautifyOption customize the beauty parameters according to actual requirements.

  • API Function Prototype:

    /// The beauty configuration object
    @interface ZegoBeautifyOption : NSObject
    
    /// The sampling step size for skin smoothing. The value range is [0,1], defaults to 0.2 
    @property (nonatomic, assign) double polishStep;
    
    /// The color adjustment parameter. The value range is [0,1], defaults to 0.5. The larger the value, the lighter the color.
    @property (nonatomic, assign) double whitenFactor;
    
    /// Image sharpening parameter. The value range is [0,1], defaults 0.1. The larger the value, the stronger the sharpening.
    @property (nonatomic, assign) double sharpenFactor;
    
    @end
    
    /// Set up the beauty parameters
    /// @param option: The beauty configuration option.
    - (void)setBeautifyOption:(ZegoBeautifyOption *)option;
  • API Call Example:

    ZegoBeautifyOption *option = [[ZegoBeautifyOption alloc] init];
    option.polishStep = 0.2;
    option.whitenFactor = 0.5;
    option.sharpenFactor = 0.1;
    
    [self.engine setBeautifyOption:option];

4.3 Using Stream Watermark

Call the API setPublishWatermark to set up the watermark before publishing the stream.

Images in "JPG" and "PNG" formats (i.e., image files with subfixes ".jpg", ".jpeg", and ".png") can be used as watermarks.

To configure the watermark, you need to create a ZegoWatermark object, which has two properties:

  • "imageURL": The access path of the watermark image.
  • "layout": The watermark's position in the video.

You can also decide whether the watermark is visible on local preview by configuring the second parameter "isPreviewVisible" accordingly when calling the API.

The "imageURL" parameter in the ZegoWatermark object supports two path formats.

  1. Accessing the Image in the Bundle via the Absolute Path

    file://[the absolute path of the image in the bundle]: If the image is stored somewhere in the Bundle, you obtain the absolute path of the image in the bundle through the "pathForResource:ofType:" method of "NSBundle". The "imageURL" should start with a prefix "file://" followed by the absolute path of the image in the bundle.

    watermark-bundle
  • API Function Prototype:

    /// Set up the stream watermark
    /// @discussion Watermark should be set up before publishing the stream. The watermark area cannot exceed the size set by the encoding resolution of the stream.
    /// @param watermark: The ZegoWaterMark object, which has two properties: imageURL (the access path of the watermark image) and layout (the watermark's position in the video). 
    /// @param isPreviewVisible: Whether the watermark is visible on the local preview.
    - (void)setPublishWatermark:(ZegoWatermark *)watermark isPreviewVisible:(BOOL)isPreviewVisible;
  • API Call Example:

    ZegoWatermark *watermark = [[ZegoWatermark alloc] init];
    
    NSString *imagePath = [[NSBundle mainBundle] pathForResource:@"ZegoLogo" ofType:@"png"];
    watermark.imageURL = [NSString stringWithFormat:@"file://%@", imagePath];
    
    watermark.layout = CGRectMake(0, 0, 200, 200);
    
    [self.engine setPublishWatermark:watermark isPreviewVisible:YES];
  1. Accessing the Image in the Assets Directory of the iOS Project

    asset://[image file name]: If the image is stored in "Assets.xcassets" of the iOS project, the "imageURL" should start with a prefix "asset://" followed by the file name of the image.

    watermark-assets
  • API Function Prototype:

    /// Set up the stream watermark
    /// @discussion Watermark should be set up before publishing the stream. The watermark area cannot exceed the size set by the encoding resolution of the stream.
    /// @param watermark: The ZegoWaterMark object, which has two properties: imageURL (the access path of the watermark image) and layout (the watermark's position in the video). 
    /// @param isPreviewVisible: Whether the watermark is visible on the local preview.
    - (void)setPublishWatermark:(ZegoWatermark *)watermark isPreviewVisible:(BOOL)isPreviewVisible;
  • API Call Example:

    ZegoWatermark *watermark = [[ZegoWatermark alloc] init];
    watermark.imageURL = @"asset://ZegoLogo";
    watermark.layout = CGRectMake(0, 0, 200, 200);
    [self.engine setPublishWatermark:watermark isPreviewVisible:YES];
  1. Set up the Position of the Watermark in the Video

The "layout" property of the "ZegoWatermark" object defines a rectangle watermark area in the video using 4 integer coordinates. The top-left corner of the video is the origin of coordinates. The watermark area cannot exceed the size set by the encoding resolution of the stream.

Please refer to setVideoConfig for more details about the encoding resolution of the stream.

5 API Reference

Method Description
enableBeautify Enables or disables the beauty features.
setBeautifyOption Sets beauty parameters.
setPublishWatermark Sets up stream watermark before stream publishing.