DEV Community: kouwei qing

Mastering the HarmonyOS Next Signature Verification Mechanism

kouwei qing — Mon, 30 Jun 2025 14:50:04 +0000

Mastering the HarmonyOS Next Signature Verification Mechanism

Background Introduction

Android app signing requires only one signature file. In the development environment, we use a debug signature by default. The debug signature alias is androiddebugkey, with the password android. The debug certificate is stored in the .android folder under the user directory, typically named debug.keystore, and doesn’t require special configuration in build.gradle.

HarmonyOS Next adopts a signing mechanism similar to iOS. Signing configuration information for the project is stored in the project-level build-profile.json5. When using automatic signing, the locally generated signing configuration path is automatically updated in build-profile.json5. This creates an issue: since each person’s signing path differs, build-profile.json5 cannot be configured to be ignored by Git nor maintained consistently in multi-person collaboration.

Before Develop Beta6, we could create a sign folder in the project, use my account to generate signing files automatically, copy them to the sign folder, and allow others to use my signature for development and debugging. However, starting from Develop Beta6, sharing automatically generated signatures causes real-device installation failures:

09/06 18:10:04:702: $ hdc shell bm install -p data/local/tmp/140f0b9059b04d8286941346c79d8f7b  in 304 ms
Install Failed: error: failed to install bundle.
code:9568322
error: signature verification failed due to not trusted app source.
View detailed instructions.
09/06 18:10:04:791: $ hdc shell rm -rf data/local/tmp/140f0b9059b04d8286941346c79d8f7b
09/06 18:10:04:792: Launch com.qingkouwei.demo failed, starting handle failure progress
Error while Deploy Hap

As the HarmonyOS system stabilizes through iterations, system security has been strengthened. During installation, the system now verifies whether the UDID in the signature matches the device UDID. This necessitates continuing with automatic signing and finding a thorough solution.

HarmonyOS Signing Mechanism

To solve this problem, we must understand the signing principles. Let’s first look at the files generated by automatic signing:

.p12: Key file. The P12 certificate (PKCS#12, Public-Key Cryptography Standards #12) is an encryption standard for exchanging digital certificates. It describes personal identity information, includes public and private keys for asymmetric encryption, and is stored in a keystore file. The key pair is used for digital signatures and verification.
.csr: Certificate Signing Request file, containing the public key in the key pair, public name, organization name, organizational unit, etc., used to apply for a digital certificate from AppGallery Connect.
.cer: Digital certificate issued by Huawei AppGallery Connect.
.p7b: Profile file, containing the package name of the HarmonyOS app/service, digital certificate information, a list of certificate permissions the app/service is allowed to apply for, and a list of devices allowed for debugging (if the app/service type is Release, the device list is empty). Each app/service package must include a Profile file.
material folder: Stores signing scheme-related materials, such as passwords and certificates.

The P12 and CSR files are generated locally and used to upload to the AppGallery Connect platform to apply for certificates and P7B files. The role of the material folder is introduced later.

Role of the Key

The P12 file contains public and private keys for asymmetric encryption (RSA), where encryption and decryption keys differ. Typical uses include:

Confidentiality: Encrypt plaintext with the recipient’s public key and transmit it. The ciphertext can only be decrypted with the recipient’s private key, ensuring transmission confidentiality even if intercepted.
Identity Verification and Tamper Prevention (Signing): Encrypt a message with the sender’s private key to sign it. The signed message can only be decrypted with the sender’s public key, ensuring authenticity (the message indeed belongs to the sender). If the ciphertext is intercepted, modified, and resent, it cannot be decrypted, ensuring message integrity. Thus, signing ensures message authenticity and integrity.

Role of the Digital Certificate

Asymmetric encryption algorithms are time-consuming for encrypting long plaintexts. In practice, the message is first hashed using a digest algorithm (e.g., MD5, SHA), the digest is encrypted, and the plaintext, encrypted digest, and public key are sent together. The recipient decrypts the digest ciphertext, hashes the plaintext, and compares the digests to verify integrity. This is a digital signature.

What is a certificate? Consider a communication fraud scenario: A intends to deceive B by sending a forged message pretending to be from C. A encrypts the file with their private key, sends it with their public key, and claims the public key belongs to C. How does B verify the public key’s ownership? This is where certificates play a role—like a network ID card proving the holder’s identity.

A digital certificate is issued by a CA (Certificate Authority) and contains the holder’s information and public key. Like a notarized document, it gains validity through CA authentication. B can verify the message sender by querying the CA with the digital certificate, confirming whether the public key belongs to A or C—similar to checking an ID card.

Using AppGallery Connect Platform Debug Certificates

The AppGallery Connect platform provides debug certificates. We can generate local keys, create debug certificates on the platform, place them in the app project’s sign folder, configure a unified signing file, and add other developers’ device IDs to the debug Profile. Here’s how to generate debug certificates:

Generating a P12 Key

DevEco Studio provides a tool to generate P12 keys. In the main menu, click Build > Generate Key and CSR:

Key generation configuration:

For "Key store file," select the path and filename for the key file (ending with .p12):

Next, select the CSR file path:

Upon completion, you will obtain:

qingkouwei.csr
qingkouwei.p12
material folder

Applying for a Debug Certificate and Debug Profile

A certificate is a digital certificate configuring signing information for a HarmonyOS app/meta-service, ensuring code integrity and publisher identity. In .cer format, it contains public keys, certificate fingerprints, etc. For applying for a debug certificate, refer to: Apply for a Debug Certificate

The Profile (.p7b format) contains the package name, digital certificate information, allowed certificate permissions, and debug device list (empty for Release-type apps/services). Each app/meta-service must include a Profile. For applying for a debug Profile, refer to: Apply for a Debug Profile

Copy the downloaded .p7b and .cer files to the sign folder and configure signing information in build-profile.json:

Note: The storePassword is not the password used when generating the signature. How to obtain it? Configure signing information via the project tool’s signing tool, which will automatically retrieve storePassword—this is the role of the material folder mentioned in signing.

Note: To generate a signature, first create an APPID on the AppGallery Connect platform:

Additional considerations:

Before using automatic signing, ensure the local system time matches Beijing Time (UTC/GMT +8.00); otherwise, signing will fail.
Each account can apply for up to two debug certificates. Automatic signing consumes debug certificate quotas. If two debug certificates already exist on AppGallery Connect, subsequent automatic signing for the account will fail.
A certificate is "active" upon successful application. If its status becomes "invalid" or "revoked," it is no longer usable, and all Profiles applied for with this certificate will also become invalid or revoked. You need to reapply for certificates and Profiles. Revoked certificates cannot be recovered, so proceed with caution.
An app can apply for up to 100 Profile files.
Modifying debug devices generates a new debug Profile; download it after it takes effect.
If a Profile’s status becomes "invalid" or "revoked," it is no longer usable; reapply for a Profile.
Obtain the device UDID using the command hdc shell bm get --udid.

If an account has already created two debug certificates, using it for automatic signing will fail with the following error:

Summary

This article introduces the HarmonyOS signing mechanism and how to handle signing conflict management in collaborative development.

Reference Documents

Mastering Image and Video Selection in HarmonyOS Next

kouwei qing — Mon, 30 Jun 2025 14:49:26 +0000

Mastering Image and Video Selection in HarmonyOS Next

Background

In chat applications, sending photos and videos from the album or capturing them via the camera is a common function. On Android and iOS, most apps use API-defined UIs to implement album photo/video selection and camera capture, supporting:

Album selection:
- Single or multiple selection.
- Option to select original image quality.
- Filters for video file size and duration.
- Tap to enlarge and preview images.
Camera capture:
- Tap to take photos, long-press to record videos.
- Video recording with max/min duration limits.
- Preview after capture/recording.

To implement these features in HarmonyOS apps, the system provides corresponding APIs requiring several permissions:

System album read permission
Microphone permission
Camera permission

Introduction to HarmonyOS Permission System

Compared to Android, HarmonyOS offers stricter permission control, governed by its application permission management strategy. It provides a universal way for apps to access system resources (e.g., contacts) and capabilities (e.g., camera, microphone) to protect data (including user personal data) and functions from misuse or malicious use. Permission protection objects fall into two categories:

Data: Personal data (photos, contacts, calendar, location) and device data (device ID, camera, microphone).
Functions: Device functions (accessing camera/microphone, making calls, networking) and app functions (floating windows, creating shortcuts).

HarmonyOS classifies permissions by authorization method into:

system_grant (System authorization): For non-sensitive data/operations with controlled impacts. The system automatically grants these permissions during app installation.
user_grant (User authorization): For sensitive data/operations with potential severe impacts. Requires both manifest declaration and dynamic runtime user authorization via a pop-up.

For example, microphone and camera permissions are user-grant types, with detailed usage rationales listed in the Application Permission List. Apps must display requested user-grant permissions on the AppGallery detail page.

Another key concept is APL (Ability Privilege Level):

APL Level	Description
normal	Default level for all apps.
system_basic	Provides basic system services.
system_core	Provides core OS capabilities (cannot be configured for normal apps).

Permissions are categorized by APL with varying access scopes:

APL Level	Description	Access Scope
normal	Access to ordinary system resources (e.g., Wi-Fi config, camera capture) with low privacy risk.	Apps with APL ≥ normal.
system_basic	Access to basic OS services (e.g., system settings, authentication) with higher risk.	1. Apps with APL ≥ system_basic. 2. Some permissions are restrictively open to normal apps (described as Restricted Permissions).
system_core	Access to core OS resources critical for system operation.	1. System apps with APL = system_core.

Design Rationale

Authorization methods:
- system_grant is similar to Android’s normal permissions (declared in the manifest), avoiding unnecessary user prompts for non-sensitive operations (e.g., network access).
- user_grant requires explicit user consent for sensitive operations (e.g., camera access), aligning with privacy best practices.
Permission levels:
- normal: For common app functions (e.g., camera, microphone) with clear usage scenarios.
- system_core: Exclusive to system apps to prevent critical system damage (e.g., like Android’s root permissions).
- system_basic: For system apps, with restricted openness to normal apps (e.g., album read permission is restricted because it allows silent data transmission, unlike camera/microphone which require active user interaction).

System Picker: Permission-Free Resource Access

Selecting images/videos requires system_basic restricted permissions, while camera/microphone access needs user authorization. To streamline workflows, HarmonyOS provides system Pickers—components allowing permission-free resource selection:

The system Picker (file/photo/contact selector) is implemented by an independent system process.
Apps obtain resources via cross-process scheduling, with temporary and restricted access rights granted by the user’s explicit actions.

Selecting from Album

HarmonyOS provides photoAccessHelper.PhotoViewPicker() to access album content. Example usage:

import { BusinessError } from '@kit.BasicServicesKit';
async function example01() {
  try {
    let photoSelectOptions = new photoAccessHelper.PhotoSelectOptions();
    photoSelectOptions.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;
    photoSelectOptions.maxSelectNumber = 5;

    let photoPicker = new photoAccessHelper.PhotoViewPicker();
    photoPicker.select(photoSelectOptions).then((photoSelectResult: photoAccessHelper.PhotoSelectResult) => {
      console.info('PhotoViewPicker.select successfully, PhotoSelectResult uri: ' + JSON.stringify(photoSelectResult));
    }).catch((err: BusinessError) => {
      console.error(`PhotoViewPicker.select failed with err: ${err.code}, ${err.message}`);
    });
  } catch (error) {
    let err: BusinessError = error as BusinessError;
    console.error(`PhotoViewPicker failed with err: ${err.code}, ${err.message}`);
  }
}

Key Objects

`PhotoSelectOptions` (selection parameters)

Name	Type	Required	Description
isEditSupported11+	boolean	No	Enable photo editing (default: true).
isOriginalSupported12+	boolean	No	Show "Select Original" button (default: true). Feature API: Available in ability models from API version 12.
subWindowName12+	string	No	Subwindow name. Feature API: Available in ability models from API version 12.

Inherits from BaseSelectOptions with additional configs:

Name	Type	Required	Description
MIMEType10+	PhotoViewMIMETypes	No	Allowed media types (default: images + videos). Feature API: Available in ability models from API version 11.
maxSelectNumber10+	number	No	Max selection count (max: 500, default: 50). Feature API: Available in ability models from API version 11.
isPhotoTakingSupported11+	boolean	No	Enable in-picker camera (default: true). Feature API: Available in ability models from API version 11.
isSearchSupported11+	boolean	No	Enable search (default: true). Feature API: Available in ability models from API version 11.
recommendationOptions11+	RecommendationOptions	No	Photo recommendation configs. Feature API: Available in ability models from API version 11.
preselectedUris11+	Array	No	Preselected media URIs. Feature API: Available in ability models from API version 11.
isPreviewForSingleSelectionSupported12+	boolean	No	Enable full-screen preview for single selection (default: true). Feature API: Available in ability models from API version 12.

`PhotoSelectResult` (selection result)

Name	Type	Readable	Writable	Description
photoUris	Array	Yes	Yes	URIs of selected media (usable via temporary authorization with photoAccessHelper.getAssets).
isOriginalPhoto	boolean	Yes	Yes	Whether original quality was selected.

Distinguishing Image and Video URIs

Use photoAccessHelper to parse media info:

public async uriGetAssets(uri: string): Promise<photoAccessHelper.PhotoAsset | undefined> {  
  try {  
    const context = getContext(this) as common.UIAbilityContext;  
    const phAccessHelper = photoAccessHelper.getPhotoAccessHelper(context);  
    const predicates: dataSharePredicates.DataSharePredicates = new dataSharePredicates.DataSharePredicates();  
    predicates.equalTo('uri', uri);  
    const fetchOption: photoAccessHelper.FetchOptions = {  
      fetchColumns: [photoAccessHelper.PhotoKeys.WIDTH, photoAccessHelper.PhotoKeys.HEIGHT, photoAccessHelper.PhotoKeys.TITLE, photoAccessHelper.PhotoKeys.DURATION],  
      predicates: predicates  
    };  
    const fetchResult: photoAccessHelper.FetchResult<photoAccessHelper.PhotoAsset> = await phAccessHelper.getAssets(fetchOption);  
    const asset: photoAccessHelper.PhotoAsset = await fetchResult.getFirstObject();  
    Logg.i(TAG, `asset displayName: ${asset.displayName}`);  
    Logg.i(TAG, `asset uri: ${asset.uri}`);  
    Logg.i(TAG, `asset photoType: ${asset.photoType}`);  
    return asset;  
  } catch (error) {  
    Logg.e(TAG, `uriGetAssets failed: ${JSON.stringify(error)}`);  
  }  
  return undefined;  
}

The photoType property of photoAccessHelper.PhotoAsset indicates media type (image/video).

Obtaining Video Thumbnails

Use getThumbnail() on photoAccessHelper.PhotoAsset to get a PixelMap, then convert it to an image:

import { BusinessError } from '@kit.BasicServicesKit';
async function Demo() {
  const readBuffer = new ArrayBuffer(96); // height * width * 4  
  if (pixelMap) {
    pixelMap.readPixelsToBuffer(readBuffer, (error: BusinessError, res: void) => {
      if (error) {
        console.error(`Failed to read pixel data: ${error.code}, ${error.message}`);
        return;
      }
      console.info('Pixel data read successfully.');
    });
  }
}

Use image.createImagePacker() to write the PixelMap to a file:

let imagePath: string | undefined = undefined;  
const pixelMap = await matedata.getThumbnail();  
const cacheDir = getContext().cacheDir;  
imagePath = `${cacheDir}/thumbnail${Date.now()}.jpg`;  
const dstFile = fs.openSync(imagePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE);  
const packOpts: image.PackingOption = { format: "image/jpeg", quality: 98 };  
await image.createImagePacker().packToFile(pixelMap, dstFile.fd, packOpts);  
fs.close(dstFile);

Capturing via Camera

Two methods to launch the system camera:

Using Want

invokeCamera(callback: (uri: string) => void) {  
  const context = getContext(this) as common.UIAbilityContext;  
  const want: Want = {  
    action: 'ohos.want.action.imageCapture',  
    parameters: {  
      "callBundleName": context.abilityInfo.bundleName,  
    }  
  };  
  const result: (error: BusinessError, data: common.AbilityResult) => void =  
    (error: BusinessError, data: common.AbilityResult) => {  
      if (error && error.code !== 0) {  
        console.log(`${TAG_CAMERA_ERROR} ${JSON.stringify(error.message)}`);  
        return;  
      }  
      const resultUri: string = data.want?.parameters?.resourceUri as string;  
      if (callback && resultUri) {  
        callback(resultUri);  
      }  
    };  
  context.startAbilityForResult(want, result);  
}

This method (referencing How to Call System Camera) doesn’t support video duration settings.

Using cameraPicker

import { cameraPicker as picker } from '@kit.CameraKit';
import { camera } from '@kit.CameraKit';
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
const mContext = getContext(this) as common.Context;

async function demo() {
  try {
    const pickerProfile: picker.PickerProfile = {
      cameraPosition: camera.CameraPosition.CAMERA_POSITION_BACK
    };
    const pickerResult: picker.PickerResult = await picker.pick(mContext,
      [picker.PickerMediaType.PHOTO, picker.PickerMediaType.VIDEO], pickerProfile);
    console.log(`Picker result: ${JSON.stringify(pickerResult)}`);
  } catch (error) {
    const err = error as BusinessError;
    console.error(`Picker failed: ${err.code}`);
  }
}

`PickerProfile` (camera settings)

Name	Type	Required	Description
cameraPosition	camera.CameraPosition	Yes	Front/back camera.
saveUri	string	No	URI to save captured media.
videoDuration	number	No	Max video recording duration.

`PickerResult` (capture result)

Name	Type	Required	Description
resultCode	number	Yes	0 for success, -1 for failure.
resultUri	string	Yes	Captured media URI (public path if saveUri is empty; same as saveUri if writable).
mediaType	PickerMediaType	Yes	Media type (photo/video).

Summary

This article introduces image/video selection and capture capabilities in HarmonyOS Next, focusing on permission-free implementations via photoAccessHelper and cameraPicker.

Reference Resources

Introduction to HarmonyOS Next Build Tool Lycium Principles

kouwei qing — Mon, 30 Jun 2025 14:48:37 +0000

Introduction to HarmonyOS Next Build Tool Lycium Principles

Background Introduction

Many system APIs in HarmonyOS Next are provided as C++ interfaces. To use C++ interfaces, NAPI must be used for interaction between ArkTS and C++. In such scenarios, the cross-compilation tools integrated in DevEco-Studio and the CMake build tool are fully sufficient. However, for scenarios involving third-party library migration, such as FFmpeg and OpenSSL, configuring the compilation environment and scripts independently can be cumbersome. Key concerns during cross-compilation include: how to perform cross-compilation with different build methods, how to configure cross-compilation environments for different build platforms, how to configure different cross-compilation architectures, and how to test and verify artifacts after cross-compilation. Currently, open-source C/C++ third-party libraries have diverse compilation methods, with the following mainstream cross-compilation approaches:

CMake build
Configure build
Make build

The official cross-compilation tool Lycium helps quickly build third-party libraries.

Introduction to Lycium Tool

Lycium is a compilation framework tool that assists developers in achieving rapid cross-compilation of C/C++ third-party libraries through shell scripts and quick verification on the OpenHarmony system. Developers only need to set the compilation method and parameters for the corresponding C/C++ third-party library, and Lycium can quickly build binary files operable on the OpenHarmony system.

The construction principle of Lycium is that the transplantation process must not modify source code (i.e., no patching of C/C++ files or build scripts). If patching is necessary for transplantation, it must undergo review with sufficient justification. (Business patches are not accepted.)

Lycium build tool address: https://gitee.com/openharmony-sig/tpc_c_cplusplus

Usage Example

Compilation Environment Preparation: The Lycium framework supports third-party libraries with various build methods. To ensure normal compilation, the environment must include basic compilation commands: gcc, cmake, make, pkg-config, autoconf, autoreconf, automake. If any command is missing, download the corresponding toolset from the official website or install it via commands on the build machine. For example, install CMake on Ubuntu with: sudo apt install cmake.
Modify Third-Party Library Compilation Methods and Parameters: The Lycium framework provides an HPKBUILD file for developers to configure compilation settings for corresponding C/C++ third-party libraries. Specific steps:
- Create a new directory for the third-party library named pkgname under the thirdparty directory.
- Copy the HPKBUILD template file to the new third-party library directory.
- Modify the HPKBUILD template based on the actual situation of the third-party library, referring to the minizip co-construction for file modification.
Quick Compilation of Third-Party Libraries: After configuring the compilation method parameters for the third-party library, execute ./build.sh pkgname in the Lycium directory to automatically compile the library and package it into usr/pkgname/ARCH/ in the current directory.
- ARCH directory: ./build.sh (compiles all libraries in the thirdparty directory by default).
- ./build.sh aaa bbb ccc ... (compiles specified libraries aaa, bbb, ccc, etc., in the thirdparty directory; if aaa has dependencies, ensure they are included in the parameters, or aaa will not compile).

The Lycium framework is written in Linux shell scripts. Next, we analyze the shell code of the build tool to understand the build process, which helps locate compilation failures.

Introduction to Build Script Principles

The Lycium framework mainly consists of the following components:

HPKBUILD build configuration
Top-level build script build.sh
Cross-compilation toolchain
Test verification environment

Build Process

1. Build Configuration Preparation

Developers need to create a directory for the third-party library to be compiled under the thirdparty directory and write an HPKBUILD build configuration file. The HPKBUILD file defines:

Source code acquisition method
Compilation parameter configuration
Dependency declaration
Installation rules

HPKBUILD build configuration file example:

# Contributor: Jeff Han <hanjinfei@foxmail.com>
# Maintainer: Jeff Han <hanjinfei@foxmail.com>
pkgname=FFmpeg
pkgver=n6.0
pkgrel=0
pkgdesc="FFmpeg is a collection of libraries and tools to process multimedia content such as audio, video, subtitles and related metadata."
url="https://github.com/FFmpeg/FFmpeg/"
archs=("armeabi-v7a" "arm64-v8a")
license=("GPL2" "GPL3" "LGPL3" "MIT" "X11" "BSD-styl")
depends=("rtmpdump" "openssl_1_0_2u")
makedepends=()
source="https://github.com/FFmpeg/$pkgname/archive/refs/tags/$pkgver.tar.gz"

autounpack=false
downloadpackage=true
buildtools="configure"

builddir=$pkgname-${pkgver}
packagename=$builddir.tar.gz
source envset.sh
buildhost=true
arch=
ldflags=

prepare() {
    if [ "$LYCIUM_BUILD_OS" == "Linux" ]
    then
        hostosname=linux
    elif [ "$LYCIUM_BUILD_OS" == "Darwi" ]
    then
        hostosname=darwin
    else
        echo "System cannot recognize, exiting"
        return -1
    fi
    if [ $buildhost == true ]
    then
        tar -zxf $packagename
        cd $builddir
        ./configure --enable-static --enable-shared --disable-doc --disable-htmlpages \
            --target-os=$hostosname --disable-optimizations --prefix=`pwd`/hostbuild > $publicbuildlog 2>&1
        $MAKE >> $publicbuildlog 2>&1
        $MAKE install >> $publicbuildlog 2>&1
        export LD_LIBRARY_PATH=`pwd`/hostbuild/lib:$LD_LIBRARY_PATH
        sed -i.bak 's/include $(SRC_PATH)\/tests\/fate\/source.mak/#include $(SRC_PATH)\/tests\/fate\/source.mak/g' tests/Makefile
        $MAKE check >> $publicbuildlog 2>&1
        ret=$?
        buildhost=false
        cd $OLDPWD
    fi

    mkdir $pkgname-$ARCH-build
    tar -zxf $packagename -C $pkgname-$ARCH-build
    cd  $pkgname-$ARCH-build/$builddir
    patch -p1 < ../../FFmpeg_oh_test.patch
    cd $OLDPWD

    if [ $ARCH == "armeabi-v7a" ]
    then
        setarm32ENV
        arch=arm
        ldflags="-L${OHOS_SDK}/native/sysroot/usr/lib/arm-linux-ohos"
    elif [ $ARCH == "arm64-v8a" ]
    then
        setarm64ENV
        arch=aarch64
        ldflags="-L${OHOS_SDK}/native/sysroot/usr/lib/aarch64-linux-ohos"
    else
        echo "${ARCH} not support"
        return -1
    fi

    return $ret
}

build() {
    cd $pkgname-$ARCH-build/$builddir
    PKG_CONFIG_LIBDIR="${pkgconfigpath}" ./configure "$@" --enable-neon --enable-asm --enable-network \
    --disable-vulkan --enable-cross-compile --enable-librtmp --disable-x86asm --enable-openssl --enable-protocols \
    --enable-static --enable-shared --disable-doc --disable-htmlpages --target-os=linux --arch=$arch \
    --cc=${CC} --ld=${CC} --strip=${STRIP} --host-cc="${CC}" --host-ld="${CC}" --host-os=linux \
    --host-ldflags=${ldflags} --sysroot=${OHOS_SDK}/native/sysroot > $buildlog 2>&1
    $MAKE >> $buildlog 2>&1
    ret=$?
    cd $OLDPWD
    return $ret
}

package() {
    cd $pkgname-$ARCH-build/$builddir
    $MAKE install >> $buildlog 2>&1
    cd $OLDPWD
}

checktestfiles() {
    cd $pkgname-$ARCH-build/$builddir/tests/ref

    tmpdir=("fate" "acodec" "lavf" "lavf-fate" "pixfmt" "seek" "vsynth")
    for dir in ${tmpdir[*]}
    do
        for file in `ls $dir`
        do
            if [ ! -f $dir/$file ]; then
                continue
            fi
            str=`cat $dir/$file | grep "\*tests"`
            if [ ! -z "$str" ]
            then
                sed -i.bak 's/\*tests/tests/g' $dir/$file
            fi
        done
    done

    cd $OLDPWD
}

copyhostbin() {
    file=$1
    if [[ -f tests/$file ]] && [[ ! -f tests/$file.${ARCH} ]]
    then
        mv tests/$file tests/$file.${ARCH}
        cp ../../$builddir/tests/$file tests/$file
    fi
}

check() {
    cd $pkgname-$ARCH-build/$builddir
    # disable running cmd
    sed -i.bak 's/  $(Q)$(SRC_PATH)\/tests\/fate-run.sh/#   $(Q)$(SRC_PATH)\/tests\/fate-run.sh/g' tests/Makefile
    # disable check git sources
    sed -i.bak 's/include $(SRC_PATH)\/tests\/fate\/source.mak/#include $(SRC_PATH)\/tests\/fate\/source.mak/g' tests/Makefile
    # disable check ffprobe,this use xmllint command, which ohos is not support
    sed -i.bak 's/include $(SRC_PATH)\/tests\/fate\/ffprobe.mak/#include $(SRC_PATH)\/tests\/fate\/ffprobe.mak/g' tests/Makefile

    # change x86 cmd for generate test target
    mv ffmpeg ffmpeg.${ARCH}
    cp ../../$builddir/ffmpeg ./
    retrytimes=0
    ret=0
    while true
    do
        $MAKE check >> $buildlog 2>&1
        if [ $? -eq 0 ]
        then
            break;
        fi

        copyhostbin base64
        copyhostbin audiomatch
        copyhostbin audiogen
        copyhostbin videogen
        copyhostbin tiny_psnr
        copyhostbin tiny_ssim
        copyhostbin rotozoom

        let retrytimes=$retrytimes+1
        if [ $retrytimes -gt 4 ]
        then
            ret=1
            break
        fi
    done

    mv ffmpeg.${ARCH} ffmpeg
    for file in `ls tests/*.${ARCH}`
    do
        tmpfile=${file%.*}
        mv $file $tmpfile
    done

    # reduction running cmd for real test
    sed -i.bak 's/# $(Q)$(SRC_PATH)\/tests\/fate-run.sh/    $(Q)$(SRC_PATH)\/tests\/fate-run.sh/g' tests/Makefile
    cd $OLDPWD
    checktestfiles

    echo "The test must be on an OpenHarmony device!"
    # skip running test on host
    # real test CMD
    # make check

    return $ret
}

recoverpkgbuildenv() {
    unset arch
    unset ldflags
    if [ $ARCH == "armeabi-v7a" ]
    then
        unsetarm32ENV
    elif [ $ARCH == "arm64-v8a" ]
    then
        unsetarm64ENV
    else
        echo "${ARCH} not support"
        return -1
    fi
}

# 清理环境
cleanbuild() {
    rm -rf ${PWD}/${builddir} ${PWD}/$pkgname-arm64-v8a-build ${PWD}/$pkgname-armeabi-v7a-build #${PWD}/$packagename
}

2. Build Process

The main entry build.sh script executes the following steps:

Parse command-line parameters to determine the target library to compile.
Check the compilation environment (compilation toolchain, etc.).
Read the HPKBUILD configuration of the target library.
Compile each library in the order of dependencies.
For each library, execute:
- Acquire source code
- Configure compilation parameters
- Perform compilation
- Install to the specified directory

Compilation environment check code:

# 检测操作系统类型
unames=`uname -s`
osname=${unames:0:5}

# 设置根目录
LYCIUM_ROOT=$(cd $(dirname ${BASH_SOURCE[0]}); pwd)

# 检查 OHOS_SDK 环境
if [ -z ${OHOS_SDK} ]
then
    echo "OHOS_SDK 未设置..."
    exit 1
fi

Dependency management check:

# 依赖库暂存文件
depend_tmp_file="/tmp/$USER-lycium_deps-$build_time"
export LYCIUM_DEPEND_PKGNAMES=$depend_tmp_file

# 已完成库列表
donelist=()
donelibs=()

The core function buildhpk() implements build process control:

Execute tasks in rounds.
Handle dependency relationships.
Implement error handling mechanisms.

Main variables:

nextroundlist: Next round of tasks to build
notdonelist: List of incomplete tasks
buildfalselist: List of build failures

Key function descriptions:

checkbuildenv(): Check if necessary build tools (e.g., gcc, cmake, make, autoconf, automake, git, curl) are installed.
prepareshell(): Prepare necessary scripts for each build directory (e.g., build_hpk.sh for project building, envset.sh for environment setup).
makelibsdir(): Manage build directories (check validity, filter built projects, and add to the build queue).

3. Cross-Compilation Support

The framework achieves cross-compilation through:

Using the cross-compilation toolchain provided by the OpenHarmony NDK.
Configuring cross-compilation parameters in HPKBUILD.
Supporting multi-architecture compilation (arm32/arm64/x86, etc.).

4. Artifact Output

Compilation artifacts are organized as follows:

usr/
  └── ${pkgname}/
       └── ${ARCH}/
            ├── lib/      # Library files
            ├── include/  # Header files
            └── bin/      # Executable files

build_hpk.sh Build Script Description

Core build function descriptions:

1. `prepare()`: Prepare the build environment (host build when `buildhost=true`), extract the source package, apply patches, and set up the cross-compilation environment.

2. `build()`: Execute the build process (configure build parameters, run `configure`, execute `make`, and return build results).

3. `package()`: Install and package (run `make install` and generate the final installation package).

4. `check()`: Test and verify (modify test configurations, prepare the test environment, execute test cases, and process results).

5. Environment management functions:

recoverpkgbuildenv(): Clean up compilation environment variables and restore the original environment.
cleanbuild(): Clean up build directories and delete temporary files.

Summary

This article introduces the functionality, usage, and principles of the HarmonyOS Next cross-platform build script, as well as the related shell code of the build script.

Introduction to DevEco Studio for HarmonyOS Next Development: ASan and TSan Detection to Cure Your C++ Phobia

kouwei qing — Mon, 30 Jun 2025 14:47:18 +0000

Introduction to DevEco Studio for HarmonyOS Next Development: ASan and TSan Detection to Cure Your C++ Phobia

1. Background Introduction

Many developers feel intimidated by C++, primarily due to memory operations. Improper memory operations such as array out-of-bounds access, memory leaks, and double-freeing can cause performance issues like high memory consumption,卡顿 (lag), or even program crashes. When an error terminates an app process, error logs are thrown to indicate the crash cause. Developers can analyze these logs—collected automatically by the system as FaultLog—to identify the problematic code. FaultLog includes:

App Freeze
CPP Crash
JS Crash
System Freeze
ASan
TSan

While other tools are commonly used, this article focuses on DevEco Studio's memory and thread debugging tools: ASan (Address Sanitizer) and TSan (Thread Sanitizer), as ArkTS's single-threading and non-shared memory multi-threading often shift complex multi-threading to the C++ layer.

2. ASan Detection

C++ memory issues mainly involve out-of-bounds access, memory leaks, and double-freeing. For performance reasons, compilers and runtime frameworks don’t check memory operations by default. DevEco Studio’s ASan helps detect such issues.

2.1 ASan Configuration

ASan is controlled by ASAN_OPTIONS parameters, which set detection levels, output formats, and error report details. Configure parameters in:

The project’s app.json5 (higher priority)
Run/Debug Configurations

2.1.1 Configuring in app.json5

In AppScope > app.json5:

{
  "app": {
    "appEnvironments": [
      {
        "name": "ASAN_OPTIONS",
        "value": "log_exe_name=true abort_on_error=0 print_cmdline=true" // For reference only
      }
    ],
    ...
  }
}

2.1.2 Configuring in Run/Debug Configurations

Add a configuration named ASAN_OPTIONS with the value: log_exe_name=true abort_on_error=0 print_cmdline=true.

2.1.3 Configurable Parameters

Parameter	Default	Required	Description
log_exe_name	true	Yes	Includes the executable name in memory error logs (non-modifiable).
log_path	/dev/asanlog/asan.log	No	Required for ROM versions < NEXT.0.0.68 (non-modifiable); deprecated in NEXT.0.0.68+.
abort_on_error	false	Yes	Specifies whether to call `abort()` or `_exit()` after printing errors: - `false`: Use `_exit()` - `true`: Use `abort()`
strip_path_prefix	-	No	Removes the configured prefix from file paths in error logs (e.g., `/data/storage/el1`).
detect_stack_use_after_return	false	No	Checks for access to freed stack space: - `true`: Enable check - `false`: Disable check.
halt_on_error	0	No	Determines if the program continues after detecting errors: - `0`: Continue - `1`: Terminate.
malloc_context_size	-	No	Number of call stack layers shown when a memory error occurs.
suppressions	""	No	Suppresses specified file names.
handle_segv	-	No	Checks for segmentation faults.
handle_sigill	-	No	Checks for SIGILL signals.
quarantine_size_mb	256	No	Size of the quarantine area for detecting freed stack space access errors.

2.2 Enabling ASan

Enable ASan in two ways:

In the run/debug window, click Diagnostics and check Address Sanitizer.

Add ASan configuration in AppScope/app.json5.

Note: For dependent native libraries, configure arguments: "-DOHOS_ENABLE_ASAN=ON" in the library’s build-profile.json5 to compile SO files in ASan mode.

When a memory error occurs, ASan logs appear. Click the link in the log to jump to the problematic code. For example, an array out-of-bounds error triggers:

2.3 ASan Error Codes

ASan reports specific error codes with causes:

2.3.1 heap-buffer-overflow

Cause/Impact: Out-of-bounds access, leading to security vulnerabilities and crash risks.
Fix: Check bounds for known-size collections; validate sizes before accessing dynamic collections.
Example:

  int heapBufferOverflow() {
      char *buffer = (char *)malloc(10);
      *(buffer + 11) = 'n'; // Overflow
      *(buffer + 12) = 'n'; // Overflow
      free(buffer);
      return buffer[1];
  }

2.3.2 stack-buffer-underflow

Cause/Impact: Access below the buffer bound, risking security and crashes.
Fix: Ensure indices are not less than the lower bound.
Example:

  int stackBufferUnderflow() {
      int subscript = -1;
      char buffer[42];
      buffer[subscript] = 42; // Underflow
      return 0;
  }

2.3.3 stack-use-after-scope

Cause/Impact: Using stack variables outside their scope, risking security and crashes.
Fix: Mind variable scoping.
Example:

  int *gp;
  bool b = true;
  int stackUseAfterScope() {
      if (b) {
          int x[5];
          gp = x + 1; // Pointer to stack variable
      }
      return *gp; // Use after scope ends
  }

2.3.4 attempt-free-nonallocated-memory

Cause/Impact: Freeing non-heap or unallocated memory, risking security and crashes.
Fix: Avoid free() on non-heap or unallocated memory.
Example:

  int main() {
      int value = 42;
      free(&value); // Free stack variable
      return 0;
  }

2.3.5 double-free

Cause/Impact: Freeing memory twice, risking security and crashes.
Fix: Initialize pointers to NULL and reset them after freeing.
Example:

  int main() {
      int *x = new int[42];
      delete [] x;
      delete [] x; // Double-free
      return 0;
  }

2.3.6 heap-use-after-free

Cause/Impact: Accessing freed memory, risking security and crashes.
Fix: Implement a free() alternative or destructor to reset pointers.
Example:

  #include <stdlib.h>
  int main() {
      int *array = new int[5];
      delete[] array;
      return array[5]; // Use after free
  }

2.4 Additional Notes

If any module enables ASan, the entry module must also enable ASan; otherwise, the app will crash on startup with a CPP Crash error.

3. TSan Detection

Another C++ challenge is multi-threading, where unpredictable execution orders complicate debugging. DevEco Studio’s TSan (ThreadSanitizer) detects data races, using a compiler instrumentation module and runtime library.

3.1 Key Application Scenarios

TSan helps identify multi-threading issues:

Data Race Detection: Occurs when two or more threads access the same memory without proper synchronization (at least one write), causing unpredictable behavior.
Lock Error Detection:
- Deadlock: Threads wait for each other’s locks, halting execution.
- Double Unlock: Unlocking an already unlocked lock.
- Unlock Without Hold: Unlocking a lock not held by the thread.
Condition Variable Error Detection:
- Wait Without Lock: Calling wait() without holding the related lock.
- Signal/Broadcast Without Lock: Calling signal()/broadcast() without holding the related lock.

3.2 TSan Configuration

Enable TSan in two ways:

In the run/debug window, click Diagnostics and check Thread Sanitizer.

Modify AppScope/app.json5 to add TSan configuration.

Note: For referenced native libraries, configure arguments: "-DOHOS_ENABLE_TSAN=ON" in the library’s build-profile.json5 to compile SO files in TSan mode.

3.3 Enabling TSan

When a thread error occurs during app run/debug, TSan logs appear. Click the link to jump to the problematic code:

TSan reports include:

Error type (e.g., data race, deadlock)
Memory address
Thread info (ID and stack trace)
Source code locations and stack traces
Context (read/write type, access size)

Note: call_once may trigger false positives. Add __attribute__((no_sanitize("thread"))) before the function to suppress this.

3.4 Additional Notes

TSan reduces performance by 5–15x and increases memory usage by 5–10x, potentially affecting features like GPU rendering.
ASan and TSan cannot be enabled simultaneously.
TSan supports API 12 and above.

4. Summary

This article introduces DevEco Studio’s ASan and TSan tools for debugging C++ memory and thread issues:

ASan detects address overflows, memory leaks, and double-freeing.
TSan detects data races, lock errors, and condition variable issues.

DevEco Studio’s tooling simplifies C++ development by identifying and resolving complex issues. Familiarizing yourself with these tools empowers you to tackle C++ challenges confidently, eliminating hidden risks through systematic detection.

HarmonyOS Private Repository Construction Practice

kouwei qing — Mon, 30 Jun 2025 14:46:36 +0000

HarmonyOS Private Repository Construction Practice

Background

In Android and iOS development, dependencies and collaboration often rely on binary artifacts. Android uses Maven as the repository, while iOS uses CocoaPods. Developers can leverage open-source libraries on official platforms, significantly improving development efficiency. However, some company-specific business libraries are not intended for external use, making it unsafe to upload them to public repositories. Many companies build internal private repositories, which enhance security and accelerate artifact management.

HarmonyOS faces similar challenges. While developers can easily use third-party artifacts from official repositories, internal business dependencies require private repositories. This article describes how to build a private repository using official tools.

Introduction to HarmonyOS Shared Packages

HarmonyOS shared packages are categorized into static and dynamic types:

HAR (Harmony Archive): A static shared package containing code, C++ libraries, resources, and configuration files. HAR enables multiple modules or projects to share ArkUI components, resources, and related code. Unlike HAP, HAR cannot be independently installed or run on devices and can only be referenced as a dependency of application modules.
HSP (Harmony Shared Package): A dynamic shared package. Static shared packages are packaged into each dependent HAP, leading to larger package sizes and duplicate resources/code. Dynamic shared packages allow multiple HAPs to share common resources and code. HSP only supports in-application sharing, not cross-application sharing.

Building a Private Repository with ohpm-repo

The official ohpm-repo tool helps developers quickly set up a lightweight ohpm private repository, compatible with the ohpm package manager. It caches dependencies on demand to accelerate installations in private networks.

ohpm-repo supports single-point and multi-instance deployments:

Single-point deployment: ohpm-repo runs on a single machine.
Multi-instance deployment: ohpm-repo is deployed across multiple machines with identical configurations and shared data storage.

Dependent Environment Installation

ohpm-repo relies on Node.js (version 16.x or higher). Install Node.js and configure the environment. Download Node.js from the official website (https://nodejs.org/download/release/latest/).

Downloading ohpm-repo

Download the ohpm-repo tool from: https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ide-software-download-0000001507075446
Unzip the ohpm-repo package.

Configuring ohpm-repo Environment Variables

Add the path to the bin directory in the unzipped ohpm-repo package to the system environment variable PATH: export PATH=$OHPM-REPO-PATH/bin:$PATH
Verify the installation by running ohpm-repo -v to check the version.

Configuring the ohpm-repo Service Configuration File

Go to the conf directory in the unzipped package and open config.yaml. The default configuration is as follows:

##### server configuration section #####
listen: 0.0.0.0:8088
# listen:
# - localhost:8088            # 监听本机环回地址
# - http://localhost:8088     # 监听本机环回地址
# - 0.0.0.0:8088              # 监听本机所有地址 (INADDR_ANY)
# 协议可配置 http 或者 https，默认为 http
# port: 1-65535(Windows系统)/ 1024-65535(Linux或Mac系统）

# 可选 (listen 为 https 协议时必须配置)
https_key: ''                 # https 服务使用的 key 的路径  (不配置默认为'')
https_cert: ''                # https 服务使用的 crt 的路径  (不配置默认为'')

##### server deploy root section #####
deploy_root: ''                # 安装根目录 (不配置默认为 `<现有用户home目录>/ohpm-repo`)，只支持绝对路径，且路径目录必须存在

##### server numeric limit section #####
max_package_size: 100          # 上传包大小限制，单位是MB (0, 100]，不配置默认为 100
max_extract_size: 500          # 压缩包解压后大小限制，单位是MB [max_package_size, 500]，不配置默认为 500
max_extract_file_num: 10240    # 压缩包解压后文件个数限制 (0, 102400]，不配置默认为 10240
user_rate_limit: 100           # 用户访问频率控制，单位是次/s (0, 10000]，不配置默认为 100
fetch_timeout: 60              # 请求/响应的超时时间，单位是秒 (0, 3600]，不配置默认为 60
keep_alive_timeout: 60         # TCP 保持连接的超时时间，单位是秒 (0, 3600]，不配置默认为 60
api_timeout: 60                # api超时时间，单位是秒(0, 3600]，不配置默认为 60
upload_lock_hour: 24           # 下架某一三方包所有版本后，限时禁止同名三方包上传，单位是小时 (0, 168]，不配置，默认为 24
upload_max_times: 100          # 单用户24小时内上传次数限制 (0, 10000]，不配置默认为 100

##### metadata storage section #####
## 数据存储类型 filedb 和 mysql 二选一，不可都配置
db:                         # 必须用 yaml 数组形式写法
  type: filedb
  config:                   # 如果想修改存储路径且保留旧的数据，则需要把旧路径下的数据文件迁移至新路径
    path: ./db              # 本地数据存储路径，不配置默认为<deploy_root>/db;

#db:                        # 必须用yaml数组形式写法
#  type: mysql
#  config:
#    host: "localhost"      # 数据库主机地址
#    port: 3306             # 数据库端口 (0,65535]
#    username: root         # 数据库的用户名
#    password: "password"   # 数据库的用户密码（请配置明文, 最终在部署目录中会转换为密文）
#    database: "repo"       # 数据库名

##### storage section #####
## 文件存储类型fs,sftp 和 custom 三选一，不可多选。

store:                               # 必须用 yaml 数组形式写法
  type: fs
  config:                            # 上传资源后如若要修改存储路径，则需要把旧路径下的数据迁移至新路径中
    path: ./storage                  # 已上架三方库存储路径，不配置默认为 <deploy_root>/storage;
    #server: http://localhost:8088   # 三方库下载链接，不配置默认取值

# 文件存储类型为 sftp 时，最多配置三个 sftp服务
#store:                               # 必须用 yaml 数组形式写法
#  type: sftp                         # 当且仅当 db 的类型为 mysql 时，store 的类型才能为 sftp
#  config:
#    location:
#      -
#        name: test_one_sftp          # 主机名字，名字不能与其他sftp配置重复
#        host: "localhost"            # 主机地址
#        port: 22                     # 主机端口 (0,65535]
#        read_username: "read"        # 主机有读权限的用户名字
#        read_password: "password"    # 主机有读权限的用户密码（请配置明文, 最终在部署目录中会转换为密文）
#        write_username: "write"      # 主机有写权限的用户名字
#        write_password: "password"   # 主机有写权限的用户密码（请配置明文, 最终在部署目录中会转换为密文）
#        path: /source22              # 相对 sftp 根目录的文件路径，仅限/开头，且路径文件夹必须存在
#      -
#        name: test_two_sftp
#        host: "localhost"
#        port: 24
#        read_username: "read"
#        read_password: "password"
#        write_username: "write"
#        write_password: "password"
#        path: /source24
#    #server: http://localhost:8088   # 本地仓库下载链接地址，不配置默认取 listen 的值、

#store:
#  type: custom                                            # custom是自定义存储插件类型，自定义存储插件开发流程见指导文档
#  config:
#    export_name: CustomStorage                            # 插件export的类名
#    plugin_path: ../plugins/CustomStorage.js              # 插件的绝对路径或者相对于ohpm-repo软件包的路径，建议将插件放在软件包的plugins目录下
#    custom_field: "test"                                  # 自定义字段，通过引入libs/common/getStorageConfigInfo.js的getStorageConfigInfo方法获取自定义字段的值
#    #server: http://localhost:8088                        # 本地仓库下载链接地址，不配置默认取listen的值
##### uplink section #####
uplink_cache_path: ./uplink      # 缓存路径，不配置默认为 <deploy_root>/uplink
uplink_cache_time: 168           # 远程包 metadata 缓存时间，单位为小时，默认 168 小时，取值范围为 (0, 8760]

##### log section #####
logs_path: ./logs                # 日志路径，不配置默认为 <deploy_root>/logs

##### log level section #####
# 日志级别: 级别由低到高分别是 all、trace、debug、info、warn、error、fatal、mark、off
# run，operate 和 access 不配置或者配置错误，默认为 info
loglevel_run: info
loglevel_operate: info
loglevel_access: info

The configuration includes listening ports, HTTPS settings, private repository deployment directory deploy_root, server configurations, storage settings db, logs, etc. Configure them according to actual needs.

Storage module notes:

db configures metadata storage, supporting fileDB (local) or MySQL.
store configures file storage, supporting local storage, SFTP storage, or custom plugin storage.

How to modify the configuration file after the private repository starts successfully:

If the configuration file was specified during the first startup with the install command: Modify the specified configuration file, then re-run install with the updated file and start the repository.
If no configuration file was specified during the first startup: Modify the configuration file in the conf directory of the unzipped package, then re-run install and start.

Installation and Startup

Run ohpm-repo install to install. After installation, configure environment variables as needed, then start the service with ohpm-repo start.

Using Private Repository Shared Packages

By default, the ohpm client pulls dependencies only from the official public repository. To pull from a private repository, use one of the following configurations:

Configure the private repository for all projects: ohpm config set registry <private_repo_address>/repos/ohpm
Configure for a specific dependency installation: ohpm install @ohos/lottie --registry <private_repo_address>/repos/ohpm

The private_repo_address is the store.config.server address in the configuration file. For example, if store.config.server is http://127.0.0.1:8088, the registry is http://127.0.0.1:8088/repos/ohpm. If store.config.server is not configured, use the default value.

Publishing Shared Packages

Local shared packages (both static and dynamic) can be published via ohpm commands or a web interface. Command-line publishing is typically preferred for efficiency:

Generate an SSH key locally: ssh-keygen -m PEM -t RSA -b 4096 -f <your_key_path>
Log in to the ohpm-repo management interface, go to Profile, add a public key, and paste the content of <your_key_path>.pub.
Set the private key path: ohpm config set key_path <your_key_path>
Log in to the ohpm-repo management interface, copy the publish ID from Profile.
Configure the publish ID in .ohpmrc: ohpm config set publish_id <your_publish_id>
Publish a static shared library: ohpm publish demo.har
Publish a dynamic shared package: ohpm publish demo.tgz
- HSP packages cannot be published directly; convert them to .tgz first.
- Switch to release mode during compilation to generate .tgz packages.

Module Configuration

In the library module (at the same level as the src folder), add the following files:

README.md: Must include package introduction and usage. Add detailed descriptions as needed.
CHANGELOG.md: Record version updates for the HAR.
LICENSE: License file.

The README.md is displayed on the private repository web platform, so clear documentation is essential.

oh_package.json5 configuration example:

{  
    "parameterFile": "../dependencies.json5",  
    "keywords": [  
        "asr"  
    ],  
    "name": "@xx/base-asr",  
    "version": "1.0.0-rc.9",  
    "repository": "http://gerrit.google.com/mobile_harmony/base_asr",  
    "description": "asr sdk",  
    "main": "Index.ets",  
    "author": "qingkouwei",  
    "license": "Apache-2.0",  
    "dependencies": {  

    }  
}

Module name, version, and description must meet requirements; otherwise, uploads will fail. Version numbers must increase sequentially (unlike Android's SNAPSHOT overwrite capability).

Best Practices

In practical development, projects with multiple SDKs may require frequent uploads to the private repository for debugging. Manually compiling and uploading each SDK is tedious, especially when SDKs have dependencies.

The optimal solution is to use scripts for one-click compilation, upload, and dependency-ordered publishing:

Create version.json5 to store SDK versions:

{  
  "project": {  
    "sdk_version": "1.1.0-rc.1",  
  }  
}

Automatic packaging script:

def run_commands(modulename, productname):  
    hvigor_home = '/Applications/DevEco-Studio.app/Contents/tools/hvigor'  

    # 打包命令
    command1 = 'node %s/bin/hvigorw.js --mode module -p product=default -p module=%s@default -p buildMode=debug assembleHar --analyze --parallel --incremental --daemon' %(hvigor_home,modulename)  

    # 等待第一个命令执行完成  
    process1.wait()  

    # 上传命令  
    ohpm publish productname
    process2.wait()

Automatic version update script:

def changeVersionAModule():  
    with open('version.json5', 'r') as f:  
        data = json5.load(f)  
        versionName = data['project']['sdk_version']  

        with open('AModule/oh-package.json5', 'r') as f:  
            aData = json5.load(f)  
            aData['version'] = versionName  
            with open('AModule/oh-package.json5', 'w') as f:  
                json.dump(aData, f, indent=4)  

        with open('dependencies.json5', 'r') as depf:  
            depData = json5.load(depf)  
            depData['version_base']['base-a'] = versionName  
            with open('dependencies.json5', 'w') as depf:  
                json.dump(depData, depf, indent=4)

Summary

This article introduces the construction of HarmonyOS private repositories, the dependency and publishing process for shared packages, and best practices for one-click packaging/uploading in complex module dependency scenarios.

References

HarmonyOS Next Video Compression Coding Principles and Best Practices

kouwei qing — Mon, 30 Jun 2025 14:46:02 +0000

HarmonyOS Next Video Compression Coding Principles and Best Practices

Background

Previous articles introduced that HarmonyOS Next allows the system album and camera tools to acquire images and videos without special permissions. After acquiring these assets, we generally need to compress them to reduce bandwidth and storage resource consumption. For example, a 10-second video shot by the Huawei Mate60 Pro's system camera generates a file of about 38MB, with an analysis showing a video bitrate as high as 30Mbps—significantly higher than required in many scenarios where video quality demands are lower:

Image compression methods have been discussed previously. This article focuses on video compression coding based on the HarmonyOS Next platform.

Principles of Video Compression

Related Concepts

What is a video?

A video is a sequence of continuous images. Typically, a frame rate of 18 frames per second (fps) ensures smooth playback.

What is video compression?

Video compression uses digital signal processing techniques and algorithms to reduce video data size, minimizing storage space and transmission bandwidth while maintaining original quality.

Why is compression possible?

Because images and video sequences contain redundant information, compression aims to remove this redundancy:

Intra-frame redundancy: Large areas of uniform color or blank spaces in an image can be stored with fewer bits.
Inter-frame redundancy: Adjacent frames in a video sequence (e.g., a person running) often differ only slightly (e.g., leg movements).

Key compression techniques include:

Intra-frame compression: Encodes individual frames without considering adjacent frames (e.g., DCT, Discrete Cosine Transform).
Inter-frame compression: Utilizes correlation between adjacent frames (e.g., motion estimation, motion compensation).
Transform coding: Converts spatial-domain image information to the frequency domain for efficient encoding.
Quantization: Reduces data volume by quantizing transformed coefficients.

What is compression transcoding?

The degree of video compression is measured by bitrate (bit rate), the number of bits transmitted per unit time (e.g., kbps, Mbps). Higher bitrates generally mean higher resolution, smoother motion, and more accurate color reproduction.

For example, a 1280×720 video at 18 fps in RGBA format would require:

1 second uncompressed: 1280×720×18 bytes = 3,686,400×18 bytes = 3,686,400×18×8 bits = 530 Mbps. In contrast, high-quality 4K/8K videos typically have bitrates of only a few Mbps, demonstrating the 100× compression achievable through coding.

Videos captured by mobile phone cameras are often large, but we may need to reduce their size for scenarios where full quality isn’t necessary—hence the focus on video compression coding.

Introduction to Audio-Video Processing Flow

The typical audio-video processing flow in daily scenarios is as follows:

The main principle of video compression coding is to:

Decode and demultiplex the video into raw data.
Optionally process the raw data.
Re-encode it with a new bitrate to reduce file size.

Introduction to HarmonyOS Next Audio-Video Codec APIs

Third-party libraries like FFmpeg can compress videos, but they rely on software codecs (CPU processing). Mobile phones often provide specialized hardware for audio-video processing, accessible via system-provided hardware codec interfaces. This section introduces HarmonyOS Next’s hardware audio-video codec APIs.

Software vs. Hardware Codecs:

Software codecs: Run on CPU, offering flexible iteration, better compatibility, and easier protocol/format extension.
Hardware codecs: Operate on dedicated hardware, delivering better power efficiency, lower latency, higher throughput, and reduced CPU load.

HarmonyOS Next provides audio-video codec interfaces only via C APIs, covering demultiplexing, decoding, encoding, and muxing.

Demultiplexing

Demultiplexing operates on files (local or network), parsing them to extract DRM information and media samples (audio, video, subtitles).

HarmonyOS Next supports data input types:

Remote connections (HTTP protocol, requires ohos.permission.INTERNET).
File descriptors (FD, requires ohos.permission.READ_MEDIA for local files).

Dynamic libraries for demultiplexing:

libnative_media_codecbase.so: Codec base library
libnative_media_avdemuxer.so: Demultiplexer library
libnative_media_avsource.so: Media source library
libnative_media_core.so: Media core library

Demultiplexing involves structured file reading (IO operations) with minimal CPU overhead.

1. Include Header Files

#include <multimedia/player_framework/native_avdemuxer.h>
#include <multimedia/player_framework/native_avsource.h>
#include <multimedia/player_framework/native_avcodec_base.h>
#include <multimedia/player_framework/native_avformat.h>
#include <multimedia/player_framework/native_avbuffer.h>
#include <fcntl.h>
#include <sys/stat.h>

2. Create a Resource Management Object

// Create a source object for an FD resource file (offset=0, size=fileSize is recommended for completeness)
OH_AVSource *source = OH_AVSource_CreateWithFD(fd, 0, fileSize);
if (source == nullptr) {
   printf("create source failed");
   return;
}

For network resources:

// Create a source object for a URI resource (optional)
OH_AVSource *source = OH_AVSource_CreateWithURI(uri);

For custom data sources (requires implementing AVSourceReadAt):

g_filePath = filePath;
OH_AVDataSource dataSource = {fileSize, AVSourceReadAt};
OH_AVSource *source = OH_AVSource_CreateWithDataSource(&dataSource);

3. Create a Demultiplexer Instance

// Create a demuxer for the source object
OH_AVDemuxer *demuxer = OH_AVDemuxer_CreateWithSource(source);
if (demuxer == nullptr) {
   printf("create demuxer failed");
   return;
}

4. Get the Number of File Tracks

// Get the source format to obtain the track count
OH_AVFormat *sourceFormat = OH_AVSource_GetSourceFormat(source);
if (sourceFormat == nullptr) {
   printf("get source format failed");
   return;
}
int32_t trackCount = 0;
if (!OH_AVFormat_GetIntValue(sourceFormat, OH_MD_KEY_TRACK_COUNT, &trackCount)) {
   printf("get track count from source format failed");
   return;
}
OH_AVFormat_Destroy(sourceFormat);

5. Get Track Indices and Information

uint32_t audioTrackIndex = 0;
uint32_t videoTrackIndex = 0;
int32_t w = 0, h = 0, trackType;
for (uint32_t index = 0; index < static_cast<uint32_t>(trackCount); index++) {
   OH_AVFormat *trackFormat = OH_AVSource_GetTrackFormat(source, index);
   if (trackFormat == nullptr) {
      printf("get track format failed");
      return;
   }
   if (!OH_AVFormat_GetIntValue(trackFormat, OH_MD_KEY_TRACK_TYPE, &trackType)) {
      printf("get track type from track format failed");
      return;
   }
   // Classify tracks as audio or video
   if (static_cast<OH_MediaType>(trackType) == OH_MediaType::MEDIA_TYPE_AUD) {
      audioTrackIndex = index;
   } else {
      videoTrackIndex = index;
      // Get video dimensions
      if (!OH_AVFormat_GetIntValue(trackFormat, OH_MD_KEY_WIDTH, &w) ||
          !OH_AVFormat_GetIntValue(trackFormat, OH_MD_KEY_HEIGHT, &h)) {
         printf("get track dimensions failed");
         return;
      }
   }
   OH_AVFormat_Destroy(trackFormat);
}

6. Select Tracks for the Demuxer

if (OH_AVDemuxer_SelectTrackByID(demuxer, audioTrackIndex) != AV_ERR_OK) {
   printf("select audio track failed: %d", audioTrackIndex);
   return;
}
if (OH_AVDemuxer_SelectTrackByID(demuxer, videoTrackIndex) != AV_ERR_OK) {
   printf("select video track failed: %d", videoTrackIndex);
   return;
}

Use OH_AVDemuxer_UnselectTrackByID to deselect tracks when done.

7. Start Demultiplexing and Read Samples

// Create a buffer to hold demuxed data
OH_AVBuffer *buffer = OH_AVBuffer_Create(w * h * 3 >> 1);
if (buffer == nullptr) {
   printf("build buffer failed");
   return;
}
OH_AVCodecBufferAttr info;
bool videoIsEnd = false, audioIsEnd = false;
int32_t ret;
while (!audioIsEnd || !videoIsEnd) {
   // Read audio samples
   if (!audioIsEnd) {
      ret = OH_AVDemuxer_ReadSampleBuffer(demuxer, audioTrackIndex, buffer);
      if (ret == AV_ERR_OK) {
         OH_AVBuffer_GetBufferAttr(buffer, &info);
         printf("audio info.size: %d\n", info.size);
         if (info.flags == OH_AVCodecBufferFlags::AVCODEC_BUFFER_FLAGS_EOS) {
            audioIsEnd = true;
         }
      }
   }
   // Read video samples
   if (!videoIsEnd) {
      ret = OH_AVDemuxer_ReadSampleBuffer(demuxer, videoTrackIndex, buffer);
      if (ret == AV_ERR_OK) {
         OH_AVBuffer_GetBufferAttr(buffer, &info);
         printf("video info.size: %d\n", info.size);
         if (info.flags == OH_AVCodecBufferFlags::AVCODEC_BUFFER_FLAGS_EOS) {
            videoIsEnd = true;
         }
      }
   }
}
OH_AVBuffer_Destroy(buffer);

Use OH_AVDemuxer_SeekToTime to seek to a specific time (like scrubbing in a player).

8. Destroy Demultiplexer Resources

OH_AVSource_Destroy(source);
OH_AVDemuxer_Destroy(demuxer);

Decoding

HarmonyOS Next supports AVC (H.264) and HEVC (H.265) for both software and hardware decoding.

Decoded data can be output via:

Surface: Uses OHNativeWindow for data transfer (e.g., to XComponent).
Buffer: Outputs decoded data via shared memory.

Like Android’s MediaCodec, HarmonyOS Next decoders operate as state machines with six main states:

State transitions:

OH_VideoDecoder_Reset or creation → Initialized
OH_VideoDecoder_Configure → Configured
OH_VideoDecoder_Prepare → Prepared
OH_VideoDecoder_Start → Executing
OH_VideoDecoder_Destroy → Released

Refer to the official flow chart for the interaction process:

Dynamic libraries for codecs:

libnative_media_codecbase.so: Codec base library
libnative_media_core.so: Media processing core
libnative_media_venc.so: Video encoding
libnative_media_vdec.so: Video decoding

For specific interfaces, see the official example:

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/video-decoding-V5

Decoders accept buffers from demuxers and output YUV buffers or surface data. Use OH_VideoDecoder_SetSurface(videoDec, window) to set a surface for direct rendering (reducing data copy overhead). Data writing is triggered via callback functions registered with OH_VideoDecoder_RegisterCallback:

// Error callback implementation
static void OnError(OH_AVCodec *codec, int32_t errorCode, void *userData)
{
    (void)codec;
    (void)errorCode;
    (void)userData;
}

// Stream change callback implementation
static void OnStreamChanged(OH_AVCodec *codec, OH_AVFormat *format, void *userData)
{
    (void)codec;
    (void)userData;
    OH_AVFormat_GetIntValue(format, OH_MD_KEY_VIDEO_PIC_WIDTH, &width);
    OH_AVFormat_GetIntValue(format, OH_MD_KEY_VIDEO_PIC_HEIGHT, &height);
    OH_AVFormat_GetIntValue(format, OH_MD_KEY_VIDEO_STRIDE, &widthStride);
    OH_AVFormat_GetIntValue(format, OH_MD_KEY_VIDEO_SLICE_HEIGHT, &heightStride);
}

// Input buffer request callback implementation
static void OnNeedInputBuffer(OH_AVCodec *codec, uint32_t index, OH_AVBuffer *buffer, void *userData)
{
    // Process input buffer index and data
}

// New output buffer callback implementation (buffer is null in Surface mode)
static void OnNewOutputBuffer(OH_AVCodec *codec, uint32_t index, OH_AVBuffer *buffer, void *userData)
{
    // Process output buffer index and data
}

// Register asynchronous callbacks
OH_AVCodecCallback cb = {&OnError, &OnStreamChanged, &OnNeedInputBuffer, &OnNewOutputBuffer};
int32_t ret = OH_VideoDecoder_RegisterCallback(videoDec, cb, NULL);
if (ret != AV_ERR_OK) {
    // Error handling
}

Software vs. Hardware Decoding Differences:

Software decoding (via MimeType) currently supports only H.264 (OH_AVCODEC_MIMETYPE_VIDEO_AVC).
Hardware decoding supports H.264 and H.265 (OH_AVCODEC_MIMETYPE_VIDEO_HEVC).

Encoding

Video encoding is the reverse of decoding, currently supporting only hardware encoding for H.264 and H.265.

Encoders accept input via Surface or Buffer modes (e.g., screen rendering or camera capture data).

Like decoders, encoders operate as state machines:

Refer to the official flow chart for the encoding process:

For specific interfaces, see:

https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/video-encoding-V5

To compress videos, focus on encoder configuration:


c
// Configure encoder parameters
double frameRate = 30.0;
bool rangeFlag = false;
int32_t primary = static_cast<int32_t>(OH_ColorPrimary::COLOR_PRIMARY_BT709);
int32_t transfer = static_cast<int32_t>(OH_TransferCharacteristic::TRANSFER_CHARACTERISTIC_BT709);
int32_t matrix = static_cast<int32_t>(OH_MatrixCoefficient::MATRIX_COEFFICIENT_IDENTITY);
int32_t profile = static_cast<int32_t>(OH_AVCProfile::AVC_PROFILE_BASELINE);
int32_t rateMode = static_cast<int32_t>(OH_VideoEncodeBitrateMode::CBR);
int32_t iFrameInterval = 23000;
int64_t bitRate = 3000000;
int64_t quality = 0;

// Create and configure the format
OH_AVFormat *format = OH_AVFormat_Create();
OH_AVFormat_SetIntValue(format, OH_MD_KEY_WIDTH, width);       // Required
OH_AVFormat_SetIntValue(format, OH_MD_KEY_HEIGHT, height);     // Required
OH_AVFormat_SetIntValue(format, OH_MD_KEY_PIXEL_FORMAT, DEFAULT_PIXELFORMAT); // Required

OH_AVFormat_SetDoubleValue(format, OH_MD_KEY_FRAME_RATE, frameRate);
OH_AVFormat_SetIntValue(format, OH_MD_KEY_RANGE_FLAG, rangeFlag);
OH_AVFormat_SetIntValue(format, OH_MD_KEY_COLOR_PRIMARIES, primary);
OH_AVFormat_SetIntValue(format, OH_MD_KEY_TRANSFER_CHARACTERISTICS, transfer);
OH_AVFormat_SetIntValue(format, OH_MD_KEY_MATRIX_COEFFICIENTS, matrix);
OH_AVFormat_SetIntValue(format, OH_MD_KEY_I_FRAME_INTERVAL, iFrameInterval);
OH_AVFormat_SetIntValue(format, OH_MD_KEY_PROFILE, profile);

// Set bitrate based on rate mode
if (rateMode == static_cast<int32_t>(OH_VideoEncodeBitrateMode::CQ)) {
    OH_AVFormat_SetIntValue(format, OH_MD_KEY_QUALITY, quality);
} else if (rateMode == static_cast<int32_t>(OH_VideoEncodeBit

HarmonyOS Next NAPI Asynchronous Call Introduction

kouwei qing — Mon, 30 Jun 2025 14:45:22 +0000

HarmonyOS Next NAPI Asynchronous Call Introduction

Why Asynchronous Calls Are Needed?

TS is single-threaded. If a TS-invoked C++ method performs time-consuming tasks (e.g., file operations, network requests, database operations, image processing), these tasks should be executed asynchronously via threads in the C++ layer. Asynchronous task results are typically obtained through callbacks. Maintaining synchronization between native and main threads requires effort, but NAPI (based on the asynchronous I/O library libuv) provides an asynchronous call mechanism to manage threads uniformly, simplifying development.

Introduction to NAPI Asynchronous Calls

HarmonyOS Next supports callback and promise-based asynchronous interfaces following the OpenHarmony Napi standard.

Introduction to Asynchronous Call APIs

Create Async Work: `napi_create_async_work()`

napi_status napi_create_async_work(napi_env env,
                                  napi_value async_resource,
                                  napi_value async_resource_name,
                                  napi_async_execute_callback execute,
                                  napi_async_complete_callback complete,
                                  void* data,
                                  napi_async_work* result);

Parameters:

[in] env: Execution environment provided by the framework (pass directly by default).
[in] async_resource: Optional, associated with async_hooks.
[in] async_resource_name: Identifier for async resource diagnostics via async_hooks API.
[in] execute: Business logic function executed by the worker thread pool (non-blocking).
[in] complete: Callback triggered after execute finishes or is canceled (runs in the EventLoop thread).
[in] data: User-provided context data for passing parameters.
[out] result: Pointer to the created async work item.
Return: napi_ok on success, otherwise an error code.

Queue Async Work: `napi_queue_async_work()`

napi_status napi_queue_async_work(napi_env env,
                                 napi_async_work work);

Parameters:

[in] env: Execution environment.
[in] work: Handle from napi_create_async_work().

Cancel Async Work: `napi_cancel_async_work()`

napi_status napi_cancel_async_work(napi_env env,
                                  napi_async_work work);

Parameters:

[in] env: Execution environment.
[in] work: Handle from napi_create_async_work().
Behavior: Cancels queued work if unstarted. Returns napi_generic_failure if started. The complete callback is invoked with napi_cancelled on success. Do not delete the work before the callback executes.

Delete Async Work: `napi_delete_async_work()`

napi_status napi_delete_async_work(napi_env env,
                                  napi_async_work work);

Parameters:

[in] env: Execution environment.
[in] work: Handle from napi_create_async_work().

Principle of Asynchronous Implementation

In synchronous mode, all code runs in the native method (main thread). Asynchronous mode uses napi_create_async_work() to create an async work item:

The native method receives and converts data, stores it in context, creates an async work item, queues it, and returns nullptr (callback) or a Promise (promise).
The async work item defines two functions:
- execute: Runs in the worker thread (non-blocking), processes business logic, and writes results to context.
- complete: Runs in the EventLoop thread after execute finishes/cancels, converts results to JS types, and invokes callbacks or resolves promises.

Asynchronous processing flow chart:

Advantages Over Native Threads

Thread Management: NodeJS abstracts thread lifecycle and synchronization. napi_create_async_work() executes tasks in the background and calls back to the JS thread automatically via libuv's event loop.
Memory Management: NodeJS garbage collection integrates with async work. N-API manages resource lifecycles to prevent premature recycling.
Callback Mechanism: Provides a seamless callback mechanism for JS-C++ interaction, integrating with the JS event loop.
Thread Pool & Concurrency: Leverages NodeJS's libuv thread pool, eliminating manual thread management.
Error Handling: Simplifies error propagation from native code to JS via callback exceptions.

Asynchronous Interface Implementation

Callback-Based Asynchronous Interface (Audio Encoding Example)

eTS Definition of the Example Interface

export const encodePcmDataForOpusWithOgg: (inputBuffer: ArrayBuffer, callback: () => void) => void;

Initialize Context Data

struct EncodeAudioData {  
    napi_async_work asyncWork = nullptr;  
    napi_ref callback = nullptr;  
    void* inputBuffer = nullptr;  
    size_t inputSize = 0;  
};

Create Async Work Item

static napi_value encodePCMToOpusOggNative(napi_env env, napi_callback_info info) {  
    size_t argc = 2;  
    napi_value args[2] = {nullptr};  
    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);  

    auto audioData = new EncodeAudioData{.asyncWork = nullptr};  
    napi_get_arraybuffer_info(env, args[0], &audioData->inputBuffer, &audioData->inputSize);  
    napi_create_reference(env, args[1], 1, &audioData->callback);  
    napi_value resourceName = nullptr;  
    napi_create_string_utf8(env, "encodePCMToOpusOggNative", NAPI_AUTO_LENGTH, &resourceName);  
    napi_create_async_work(env, nullptr, resourceName, encodeExecuteCB, encodeAsyncCompleteCB, (void*)audioData, &audioData->asyncWork);  
    napi_queue_async_work(env, audioData->asyncWork);  
    return nullptr;  
}

`execute` Function

static void encodeExecuteCB(napi_env env, void* data) {  
    EncodeAudioData* encodeAudioData = (EncodeAudioData*)data;  
    ope_encoder_write(pEnc, (short*)encodeAudioData->inputBuffer, encodeAudioData->inputSize / 2);  
}

`complete` Function

static void encodeAsyncCompleteCB(napi_env env, napi_status status, void* data) {  
    EncodeAudioData* encodeAudioData = (EncodeAudioData*)data;  
    napi_value callback = nullptr;  
    napi_value undefined = nullptr;  
    napi_get_undefined(env, &undefined);  
    napi_get_reference_value(env, encodeAudioData->callback, &callback);  
    napi_call_function(env, undefined, callback, 0, nullptr, &callbackResult);  

    if (encodeAudioData->callback != nullptr) {  
        napi_delete_reference(env, encodeAudioData->callback);  
    }  
    napi_delete_async_work(env, encodeAudioData->asyncWork);  
    delete encodeAudioData;  
}

eTS Call Interface

static encodePcmDataForOpusOgg(inputBuffer: ArrayBuffer): void {  
  opusOggEnc.encodePcmDataForOpusWithOgg(inputBuffer, () => {  
  });  
}

Promise-Based Asynchronous Interface

Create Promise

napi_status napi_create_promise(napi_env env, napi_deferred* deferred, napi_value* promise);

Initialize Context Data

struct EncodeAudioData {  
    napi_async_work asyncWork = nullptr;  
    napi_deferred deferred = nullptr;  
    void* inputBuffer = nullptr;  
    size_t inputSize = 0;  
};

Create Async Work Item

static napi_value encodePromise(napi_env env, napi_callback_info info) {  
    size_t argc = 1;  
    napi_value args[1] = {nullptr};  
    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);  
    napi_value promise = nullptr;  
    napi_deferred deferred = nullptr;  
    napi_create_promise(env, &deferred, &promise);  
    auto audioData = new EncodeAudioData{.asyncWork = nullptr, .deferred = deferred};  
    napi_get_arraybuffer_info(env, args[0], &audioData->inputBuffer, &audioData->inputSize);  
    napi_value resourceName = nullptr;  
    napi_create_string_utf8(env, "encodeAudioAsyncCallback", NAPI_AUTO_LENGTH, &resourceName);  
    napi_create_async_work(env, nullptr, resourceName, encodeExecuteCB, encodePromiseCompleteCB, (void*)audioData, &audioData->asyncWork);  
    napi_queue_async_work(env, audioData->asyncWork);  
    return promise;  
}

`complete` Callback

static void encodePromiseCompleteCB(napi_env env, napi_status status, void* data) {  
    EncodeAudioData* encodeAudioData = (EncodeAudioData*)data;  
    napi_value undefined;  
    napi_get_undefined(env, &undefined);  
    napi_resolve_deferred(env, encodeAudioData->deferred, undefined);  
    if (encodeAudioData->callback != nullptr) {  
        napi_delete_reference(env, encodeAudioData->callback);  
    }  
    napi_delete_async_work(env, encodeAudioData->asyncWork);  
    delete encodeAudioData;  
}

eTS Call Interface

static encodePcmDataForOpusOgg(inputBuffer: ArrayBuffer): void {  
  opusOggEnc.encodePcmDataForOpusWithOggPromise(inputBuffer).then(() => {  
  });  
}

Standardized Asynchronous Interface

If Promise support is enabled, async methods must support both callback and promise modes. Determine the mode by the number of parameters:

export function encodePcmDataForOpusWithOgg(inputBuffer: ArrayBuffer, callback: () => void): void;  
export function encodePcmDataForOpusWithOgg(inputBuffer: ArrayBuffer): Promise<void>;

Unified Context Structure

struct EncodeAudioData {  
    napi_async_work asyncWork = nullptr;  
    napi_ref callback = nullptr;  
    napi_deferred deferred = nullptr;  
    void* inputBuffer = nullptr;  
    size_t inputSize = 0;  
};

Native Method Implementation

static napi_value encodePCMToOpusOggNative(napi_env env, napi_callback_info info) {  
    size_t argc = 2;  
    napi_value args[2] = {nullptr};  
    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);  
    auto audioData = new EncodeAudioData{.asyncWork = nullptr};  
    if (argc == 1) {  
        napi_value promise = nullptr;  
        napi_deferred deferred = nullptr;  
        napi_create_promise(env, &deferred, &promise);  
        audioData->deferred = deferred;  
        napi_get_arraybuffer_info(env, args[0], &audioData->inputBuffer, &audioData->inputSize);  
        napi_value resourceName = nullptr;  
        napi_create_string_utf8(env, "encodePCMToOpusOggNativePromise", NAPI_AUTO_LENGTH, &resourceName);  
        napi_create_async_work(env, nullptr, resourceName, encodeExecuteCB, encodePromiseCompleteCB, (void*)audioData, &audioData->asyncWork);  
        napi_queue_async_work(env, audioData->asyncWork);  
        return promise;  
    } else {  
        napi_get_arraybuffer_info(env, args[0], &audioData->inputBuffer, &audioData->inputSize);  
        napi_create_reference(env, args[1], 1, &audioData->callback);  
        napi_value resourceName = nullptr;  
        napi_create_string_utf8(env, "encodePCMToOpusOggNativeCallback", NAPI_AUTO_LENGTH, &resourceName);  
        napi_create_async_work(env, nullptr, resourceName, encodeExecuteCB, encodeAsyncCompleteCB, (void*)audioData, &audioData->asyncWork);  
        napi_queue_async_work(env, audioData->asyncWork);  
        return nullptr;  
    }  
}

HarmonyOS Layout Practice 1: Implementation of Common TitleBar

kouwei qing — Mon, 30 Jun 2025 14:44:47 +0000

HarmonyOS Layout Practice 1: Implementation of Common TitleBar

Background

TitleBar is the most commonly used component in daily development. Although each application may have a different style, the overall layout generally consists of three areas:

Left return area
Middle title area
Right button area

Below are screenshots of the TitleBar effects from WeChat and My Huawei applications:

In WeChat, the content area is centered, while in My Huawei, it is left-aligned. In practical development, we may encounter both scenarios. Let's encapsulate a TitleBar to achieve the following functions:

The far left supports a return button + text.
The right side can have up to two buttons.
The middle title area should adaptively occupy space without exceeding the left and right areas, and can be controlled to align left or center.

Selection of Layout Container

The overall effect requires fixed left and right areas with the middle area expanding. In Android, we would first think of RelativeLayout, and HarmonyOS provides a similar relative layout called RelativeContainer. RelativeContainer supports setting relative position relationships for child elements, making it suitable for complex interface scenarios to align and arrange multiple sub-components. Child elements can specify siblings or the parent container as anchors for relative positioning.

RelativeContainer introduces two concepts: anchors and alignment methods:

Anchors: Set the position of the current element based on another element. Anchor settings define the positional dependency of child elements relative to the parent or siblings. Horizontally, left, middle, and right anchors can be set; vertically, top, center, and bottom anchors are supported. IDs must be set for the RelativeContainer and its child elements to specify anchor information. The RelativeContainer's default ID is "container", and other child elements use the id attribute. Components without an ID can still be displayed but cannot be used as anchors by other children. The framework will generate an ID for them, but the pattern is unpredictable and cannot be directly used.
Alignment Methods: Define whether the current element aligns top/middle/bottom or left/middle/right relative to the anchor.

Notes: Avoid circular dependencies, as they will cause all child components in the container to fail to render. If more than two position anchors are set in the same direction, and the anchor positions are out of order, the child component will have a size of 0 (i.e., not render).

Layout Implementation

The parent layout uses RelativeContainer. The left and right buttons are positioned relative to the parent's left and right sides, while the middle container is positioned relative to the right of the left layout and the left of the right layout. The overall structure is as follows:

build() {  
  RelativeContainer() {  
    Text('左侧')  
      .fontSize(10)  
      .fontWeight(FontWeight.Bold)  
      .id("base_title_left_container")  
      .alignRules({  
        bottom: { anchor: "__container__", align: VerticalAlign.Bottom },  
        left: { anchor: "__container__", align: HorizontalAlign.Start }  
      })  

    Text('右侧')  
        .fontSize(10)  
        .fontWeight(FontWeight.Bold)  
    .id("base_title_right_container")  
      .alignRules({  
        bottom: { anchor: "__container__", align: VerticalAlign.Bottom },  
        right: { anchor: "__container__", align: HorizontalAlign.End }  
      })  
      // .backgroundColor('#00ff00')  
    Row(){  
      Text('中间内容')  
        .fontSize(10)  
        .fontWeight(FontWeight.Bold)  

    }.alignRules({  
      bottom: { anchor: "__container__", align: VerticalAlign.Bottom },  
      left: { anchor: "base_title_left_container", align: HorizontalAlign.End },  
      right: { anchor: "base_title_right_container", align: HorizontalAlign.Start }  
    }).backgroundColor('#ff0000')  


  }  
  .height('40')  
  .width('100%')  
  .backgroundColor('#ccc')  
  .margin({top:100})  
}

The display effect is as follows:

This meets expectations. When the right side needs to display two buttons, wrap them in a container:

build() {  
  RelativeContainer() {  
    Text('左侧')  
      .fontSize(10)  
      .fontWeight(FontWeight.Bold)  
      .id("base_title_left_container")  
      .alignRules({  
        bottom: { anchor: "__container__", align: VerticalAlign.Bottom },  
        left: { anchor: "__container__", align: HorizontalAlign.Start }  
      })  

    Flex({ justifyContent: FlexAlign.End, alignItems: ItemAlign.Center }) {  
      Text('右侧2')  
        .fontSize(10)  
        .fontWeight(FontWeight.Bold)  
      Text('右侧1')  
        .fontSize(10)  
        .fontWeight(FontWeight.Bold)  
    }  
    .id("base_title_right_container")  
      .alignRules({  
        bottom: { anchor: "__container__", align: VerticalAlign.Bottom },  
        right: { anchor: "__container__", align: HorizontalAlign.End }  
      })  
      // .backgroundColor('#00ff00')  
    Row(){  
      Text('中间内容')  
        .fontSize(10)  
        .fontWeight(FontWeight.Bold)  

    }.alignRules({  
      bottom: { anchor: "__container__", align: VerticalAlign.Bottom },  
      left: { anchor: "base_title_left_container", align: HorizontalAlign.End },  
      right: { anchor: "base_title_right_container", align: HorizontalAlign.Start }  
    }).backgroundColor('#ff0000')  


  }  
  .height('40')  
  .width('100%')  
  .backgroundColor('#ccc')  
  .margin({top:100})  
}

Effect:

The middle content disappears. After adding a background color to the right container:

It is found that the right layout occupies the entire width. Why?

The issue is that Flex cannot adapt to child node sizes. Switch to the Row container instead:

build() {  
  RelativeContainer() {  
    Text('左侧')  
      .fontSize(10)  
      .fontWeight(FontWeight.Bold)  
      .id("base_title_left_container")  
      .alignRules({  
        bottom: { anchor: "__container__", align: VerticalAlign.Bottom },  
        left: { anchor: "__container__", align: HorizontalAlign.Start }  
      })  

    Row() {  
      Text('右侧2')  
        .fontSize(10)  
        .fontWeight(FontWeight.Bold)  
      Text('右侧1')  
        .fontSize(10)  
        .fontWeight(FontWeight.Bold)  
    }  
    .id("base_title_right_container")  
      .alignRules({  
        bottom: { anchor: "__container__", align: VerticalAlign.Bottom },  
        right: { anchor: "__container__", align: HorizontalAlign.End }  
      })  
      .backgroundColor('#00ff00')  
    Row(){  
      Text('中间内容')  
        .fontSize(10)  
        .fontWeight(FontWeight.Bold)  

    }.alignRules({  
      bottom: { anchor: "__container__", align: VerticalAlign.Bottom },  
      left: { anchor: "base_title_left_container", align: HorizontalAlign.End },  
      right: { anchor: "base_title_right_container", align: HorizontalAlign.Start }  
    }).backgroundColor('#ff0000')  


  }  
  .height('40')  
  .width('100%')  
  .backgroundColor('#ccc')  
  .margin({top:100})  
}

The effect returns to normal:

Summary

This article introduces the characteristics and attributes of HarmonyOS's RelativeContainer through the layout implementation of the common TitleBar control. It also highlights the difference in adaptive child node capabilities between Flex and Row: Row can adapt to child node widths, while Flex will fill the entire parent layout width.

HarmonyOS Next Best Practices for Ringing and Vibration in Call Pages

kouwei qing — Mon, 30 Jun 2025 14:44:06 +0000

HarmonyOS Next Best Practices for Ringing and Vibration in Call Pages

1. Background Introduction

In developing audio-video calling modules, call ringing is typically implemented on both outgoing and incoming call pages, similar to WeChat's video call interface. The called party often experiences vibration alongside ringing. On Android, MediaPlayer loops MP3 ringtones from the raw directory, and Vibrator achieves vibration effects. This article introduces how to implement ringing and vibration in HarmonyOS Next.

2. Ringing Implementation

For package size considerations, we usually place a short ringtone in the app and repeat it for continuous ringing. Call pages often limit the maximum duration to one minute, so the ringtone can play for up to one minute.

We place the ringtone file in rawfile and read it via resourceManager. HarmonyOS provides two ways to play audio:

SoundPool: Enables low-latency short sound playback, suitable for急促 brief sound effects (e.g., camera shutter, system notifications). It supports audio resources under 1MB; files over 1MB are truncated to 1MB.
AVPlayer: Achieves end-to-end playback of original media resources.

Since SoundPool's load method does not support rawfile directory resources, we focus on AVPlayer for audio playback.

AVPlayer Playback Workflow

The full process includes: creating an AVPlayer, setting playback resources, configuring parameters (volume/speed/focus mode), playback control (play/pause/seek/stop), resetting, and destroying resources.

AVPlayer is similar to Android's MediaPlayer, maintaining a state machine. You can actively get the current state via the state property or listen for changes using on('stateChange'). Operating on an AVPlayer in an error state may throw exceptions or cause undefined behavior.

Ringing Tool: `RingAVPlayer`

Create the player: let avPlayer: media.AVPlayer = await media.createAVPlayer();
Set state change callbacks: avPlayer.on('stateChange', async (state: string, reason: media.StateChangeReason) => {});
Get the local audio resource FD: let fileDescriptor = await context.resourceManager.getRawFd('ring.mp3');
Assign fdSrc to trigger the initialized state: avPlayer.fdSrc = fileDescriptor;
In the state callback, call avPlayer.prepare() after receiving initialized to trigger resource loading.
In the state callback, call avPlayer.play() after receiving prepared; set avPlayer.loop = true before playback for looping.
Call stop to end playback.

import { media } from '@kit.MediaKit';  
import { common } from '@kit.AbilityKit';  
import { BusinessError } from '@kit.BasicServicesKit';  
import { audio } from '@kit.AudioKit';  
import { Logg } from '../../../../../../../Index';  

const TAG = 'RingAVPlayer';  
export class RingAVPlayer {  
  private mAVPlayer: media.AVPlayer|undefined = undefined;  
  private count: number = 0;  

  // Register AVPlayer callback functions  
  setAVPlayerCallback(avPlayer: media.AVPlayer) {  
    // Seek operation result callback  
    avPlayer.on('seekDone', (seekDoneTime: number) => {  
      Logg.i(TAG, `AVPlayer seek succeeded, seek time is ${seekDoneTime}`);  
    })  
    // Error callback: call reset when an error occurs  
    avPlayer.on('error', (err: BusinessError) => {  
      Logg.e(TAG, `Invoke avPlayer failed, code is ${err.code}, message is ${err.message}`);  
      avPlayer.reset(); // Reset resources, trigger idle state  
    })  
    // State machine change callback  
    avPlayer.on('stateChange', async (state: string, reason: media.StateChangeReason) => {  
      switch (state) {  
        case 'idle':  
          console.info('AVPlayer state idle called.');  
          avPlayer.release();  
          break;  
        case 'initialized':  
          Logg.i(TAG, 'AVPlayer state initialized called.');  
          avPlayer.audioRendererInfo = {  
            usage: audio.StreamUsage.STREAM_USAGE_MUSIC,  
            rendererFlags: 0  
          }  
          avPlayer.prepare();  
          break;  
        case 'prepared':  
          Logg.i(TAG, 'AVPlayer state prepared called.');  
          avPlayer.loop = true;  
          avPlayer.play();  
          break;  
        case 'playing':  
          Logg.i(TAG, 'AVPlayer state playing called.');  
          break;  
        case 'paused':  
          Logg.i(TAG, 'AVPlayer state paused called.');  
          break;  
        case 'completed':  
          Logg.i(TAG, 'AVPlayer state completed called.');  
          break;  
        case 'stopped':  
          Logg.i(TAG, 'AVPlayer state stopped called.');  
          break;  
        case 'released':  
          Logg.i(TAG, 'AVPlayer state released called.');  
          break;  
        default:  
          Logg.i(TAG, 'AVPlayer state unknown called.');  
          break;  
      }  
    })  
  }  

  // Demo: Use resource manager to get media files in HAP and play via fdSrc  
  async startAVPlayer() {  
    this.mAVPlayer = await media.createAVPlayer();  
    this.setAVPlayerCallback(this.mAVPlayer);  
    let context = getContext(this) as common.UIAbilityContext;  
    let fileDescriptor = await context.resourceManager.getRawFd('call_music.mp3');  
    let avFileDescriptor: media.AVFileDescriptor =  
      { fd: fileDescriptor.fd, offset: fileDescriptor.offset, length: fileDescriptor.length };  
    this.mAVPlayer.fdSrc = avFileDescriptor;  
  }  

  stopAVPlayer() {  
    if (this.mAVPlayer) {  
      this.mAVPlayer.stop();  
      this.mAVPlayer.release();  
    }  
  }  
}

3. Vibration Implementation

On Android, Vibrator is used as follows:

protected long[] pattern = { 1000, 1000, 1000, 1000 };
mVibrator = (Vibrator) getSystemService(Context.VIBRATOR_SERVICE);  
mVibrator.vibrate(pattern, 0);

The array elements represent vibration durations (ms). The first element is the wait time before vibration, and subsequent elements alternate between vibration and pause. repeat determines repetition: -1 for no repeat, 0 for continuous vibration. { 1000, 1000, 1000, 1000 } means wait 1s, vibrate 1s, wait 1s, vibrate 1s, repeating. Call cancel to stop.

HarmonyOS Next provides corresponding vibration capabilities via the Vibrator module, supporting:

Key presses with different intensities and durations
Alarms and calls with single or periodic vibrations of varying intensities and durations

Three Vibration Types

Name	Description
Fixed-duration vibration	Specify a duration; the motor vibrates at default intensity and frequency. See `VibrateTime`.
Preset vibration	System-defined vibration effects for fixed scenarios (e.g., `haptic.clock.timer` for timer adjustments). See `VibratePreset`.
Custom vibration	Allows users to design vibration effects via configuration files. See `VibrateFromFile`.

Example Code

Fixed-Duration Vibration

import { vibrator } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  vibrator.startVibration({
    type: 'time',
    duration: 1000,
  }, {
    id: 0,
    usage: 'alarm'
  }, (error: BusinessError) => {
    if (error) {
      console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`);
      return;
    }
    console.info('Succeed in starting vibration');
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

// Stop fixed-duration vibration
import { vibrator } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  vibrator.stopVibration(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_TIME, (error: BusinessError) => {
    if (error) {
      console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`);
      return;
    }
    console.info('Succeed in stopping vibration');
  })
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

Preset Vibration

import { vibrator } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  vibrator.isSupportEffect('haptic.effect.soft', (err: BusinessError, state: boolean) => {
    if (err) {
      console.error(`Failed to query effect. Code: ${err.code}, message: ${err.message}`);
      return;
    }
    console.info('Succeed in querying effect');
    if (state) {
      vibrator.startVibration({
        type: 'preset',
        effectId: 'haptic.effect.soft',
        count: 1,
        intensity: 50,
      }, {
        usage: 'unknown'
      }, (error: BusinessError) => {
        if (error) {
          console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`);
        } else {
          console.info('Succeed in starting vibration');
        }
      });
    }
  })
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

// Stop preset vibration
import { vibrator } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  vibrator.stopVibration(vibrator.VibratorStopMode.VIBRATOR_STOP_MODE_PRESET, (error: BusinessError) => {
    if (error) {
      console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`);
      return;
    }
    console.info('Succeed in stopping vibration');
  })
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

Custom Vibration from File

import { vibrator } from '@kit.SensorServiceKit';
import { resourceManager } from '@kit.LocalizationKit';
import { BusinessError } from '@kit.BasicServicesKit';

const fileName: string = 'xxx.json';
let rawFd: resourceManager.RawFileDescriptor = getContext().resourceManager.getRawFdSync(fileName);

try {
  vibrator.startVibration({
    type: "file",
    hapticFd: { fd: rawFd.fd, offset: rawFd.offset, length: rawFd.length }
  }, {
    id: 0,
    usage: 'alarm'
  }, (error: BusinessError) => {
    if (error) {
      console.error(`Failed to start vibration. Code: ${error.code}, message: ${error.message}`);
      return;
    }
    console.info('Succeed in starting vibration');
  });
} catch (err) {
  let e: BusinessError = err as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

getContext().resourceManager.closeRawFdSync(fileName);

// Stop all vibrations
import { vibrator } from '@kit.SensorServiceKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  vibrator.stopVibration((error: BusinessError) => {
    if (error) {
      console.error(`Failed to stop vibration. Code: ${error.code}, message: ${error.message}`);
      return;
    }
    console.info('Succeed in stopping vibration');
  })
} catch (error) {
  let e: BusinessError = error as BusinessError;
  console.error(`An unexpected error occurred. Code: ${e.code}, message: ${e.message}`);
}

4. Reference Documents

5. Summary

This article introduces implementing custom ringing and vibration effects on call pages in HarmonyOS Next audio-video calling scenarios, focusing on AVPlayer and vibrator APIs.

HarmonyOS Next Best Practices for Actively Invoking Methods Encapsulated in Custom Control

kouwei qing — Mon, 30 Jun 2025 14:43:26 +0000

HarmonyOS Next Best Practices for Actively Invoking Methods Encapsulated in Custom Controls

1. Background Introduction

The primary development language for HarmonyOS Next is ArkTS, and its framework ArkUI is a declarative UI. Declarative UIs typically do not manipulate controls directly but drive UI refreshes through state variable updates. However, in some scenarios, state-driven UI refreshes cannot meet complex business logic, requiring parent layouts to invoke methods in child controls. How to handle this?

2. Reference to System Approaches

System-provided controls like Dialog, TextTimer, and TextArea require a controller during construction, allowing parent controls to directly invoke child control methods via the controller:

TextTimerController provides start, pause, and reset methods for parent components.
CustomDialogController provides open and close methods for parent components.

We can adopt a similar approach: encapsulate a controller for child components to enable parent-component invocation.

3. Encapsulation of Child Component Invocation

The parent component invokes methods of the child component by calling a controller exposed by the child component. This encapsulates capabilities like data processing, refreshing, animations, and notifications.

Implementation Steps:

Define a ChildController class with methods matching those in the child component:

class ChildController { 
  changeText = (value: string) => { console.log('11111') } 
} 
export let ChildRef = new ChildController()

In the child component, assign actual methods to the controller. In aboutToAppear, map the child component's methods to the controller's method variables:

@Component
struct Child {
  @State private text: string = '初始值';
  private controller: ChildController = new ChildController();

  aboutToAppear() {
    if (this.controller) {
      this.controller.changeText = this.changeText;
    }
    console.log('aaa');
  }

  private changeText = (value: string) => {
    this.text = value;
    console.log('bbb');
  }

  build() {
    Column() {
      Text(this.text);
    }
  }
}

In the parent component, create a controller object, pass it to the child component, and invoke the controller's methods:

@Entry
@Component
struct Parent {
  private ChildRef = new ChildController();
  build() {
    Column() {
      Text('调用 Child 的 changeText').fontSize('18vp').fontColor(Color.Gray);
      Divider();
      Child({ controller: this.ChildRef });
    }
  }
}

4. Design Analysis

This approach uses an intermediate controller object for indirect communication:

The parent component holds the controller, while the child component assigns its actual methods to the controller during initialization.
When the parent component invokes the controller's methods, it effectively calls the child component's methods.
This achieves loose coupling, avoiding direct parent dependency on child component internals, and enhances code maintainability and extensibility.

5. Summary

This article introduces a method for parent components to invoke child components in the declarative UI framework ArkUI. Through loose-coupling communication, it solves the challenge of parent components directly invoking child component methods without holding direct references.

HarmonyOS Next Audio-Video Practice: OPUS Audio Encoding

kouwei qing — Mon, 30 Jun 2025 14:42:45 +0000

HarmonyOS Next Audio-Video Practice: OPUS Audio Encoding

Background

In chat scenarios requiring short voice messages, audio content needs to be encoded and compressed. Initially, MP3 encoding was used, but later, as voice messages were applied to ASR model training, OPUS encoding became necessary for processing voice signals. Previously, Android did not support MP3 or OPUS encoding, but HarmonyOS now supports both. The encoder types supported by HarmonyOS are:

Container Format	Audio Encoding Type
mp4	AAC, Flac
m4a	AAC
flac	Flac
aac	AAC
mp3	MP3
raw	G711mu
amr	AMR
ogg	opus

After encoding with OPUS via system APIs, the audio file could not be played. Investigation showed the encoder did not automatically perform muxing, and the system Muxer does not support the OGG container. Current packaging capabilities are as follows:

Packaging Format	Video Codec Type	Audio Codec Type	Cover Type
mp4	AVC (H.264), HEVC (H.265)	AAC, MPEG (MP3)	jpeg, png, bmp
m4a	-	AAC	jpeg, png, bmp
mp3	-	MPEG (MP3)	-

Since HarmonyOS does not support the OGG container, we need to implement it manually.

Introduction to OPUS OGG Packaging

OGG organizes logical streams in units of "pages," each consisting of a page header and page data. The page header includes:

capture_pattern (Page Identifier): ASCII characters 0x4F 'O' 0x67 'g' 0x67 'g' 0x53 'S' (4 bytes), marking the start of a page.
stream_structure_version (Version ID): Typically 0 (1 byte).
header_type_flag (Type Indicator): Marks the page type (1 byte):
- 0x01: The media data on this page belongs to the same packet as the previous page. If unset, this page starts a new packet.
- 0x02: Indicates the first page of the logical stream (BOS flag). If unset, it is not the first page.
- 0x04: Indicates the last page of the logical stream (EOS flag). If unset, it is not the last page.
granule_position: Media encoding parameters (8 bytes). For audio streams, it stores the number of PCM samples up to this page, from which timestamps can be calculated. For video streams, it stores the number of encoded frames. A value of -1 means the packet is not yet complete (little-endian).
serial_number: Stream ID of the page (4 bytes), distinguishing this logical stream from others (little-endian).
page_sequence_number: Page sequence number in the logical stream (4 bytes).
CRC_cbecksum: Cyclic Redundancy Check (4 bytes) for page validity.
number_page_segments: Number of segments in the segment_table (1 byte).
segment_table: A table defining segment lengths (0–255). Packets end at the last segment not equal to 255. For example, segments FF 45 FF FF FF 40 FF 05 FF FF FF 66 (12 segments, 4 packets) yield packet lengths: 255+69=324, 829, 260, 847.

The page header length and total page length are calculated as:

header_size  = 27 + number_page_segments  (bytes)
page_size = header_size + sum of segment sizes in segment_table

Page header format:

Implementing OGG Packaging

Xiph provides the open-source libopusenc for OPUS OGG packaging, which depends on the libopus library. The simplest approach is to use libopusenc for both OPUS encoding and container packaging.

libopusenc Processing Flow

Creating the Encoder

First, create comments:

OggOpusComments *comments = ope_comments_create();  
ope_comments_add(comments, "ARTIST", "qingkouwei");  
ope_comments_add(comments, "TITLE", "qingkouwei-im");

Then create the encoder:

OggOpusEnc *pEnc = ope_encoder_create_file(outputFilePath_, comments, inSamplerate, inChannel,  
                                          quality, &error);  
if (pEnc) {    
    int ret = ope_encoder_ctl(pEnc, OPUS_SET_BITRATE(outBitrate));  
}

Parameters include the muxer output path, comment info, sampling rate, channel count, audio quality, etc.

Encoding PCM Data

static napi_value encodePCMToOpusOggNative(napi_env env, napi_callback_info info)  
{  
    size_t argc = 1;  
    napi_value args[1] = {nullptr};  
    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);  
    void* inputBuffer;   
    size_t inputLength;   
    napi_get_arraybuffer_info(env, args[0], &inputBuffer, &inputLength);   
    ope_encoder_write(pEnc, (short *)inputBuffer, inputLength/2);  
    return nullptr;
}

Transfer binary data from the TS layer to ope_encoder_write, which writes encoded data to the path specified during encoder creation.

Closing the Encoder Muxer

static napi_value closeOpusOggEncoderNative(napi_env env, napi_callback_info info)  
{  
   ope_encoder_drain(pEnc);  
   ope_encoder_destroy(pEnc);  
   if (comments != NULL) {  
       ope_comments_destroy(comments);  
       comments = NULL;  
   }  
   return nullptr;  
}

Release the encoder, comments, and other objects. The overall process is straightforward, and the final OGG container file can be played normally by general players:

Summary

This article introduces methods to implement OPUS encoding and OGG container packaging in HarmonyOS, addressing special audio encoding requirements in business scenarios.

HarmonyOS Native Intelligence: Speech Recognition Practice

kouwei qing — Mon, 30 Jun 2025 14:42:00 +0000

HarmonyOS Native Intelligence: Speech Recognition Practice

Background

Many business scenarios in our company utilize speech recognition. At the time, our speech team developed a self-research speech recognition model with a solution involving cloud-based models interacting with edge-side SDKs. The edge side handles speech collection, VAD (Voice Activity Detection), Opus encoding, and real-time transmission to the cloud, which then returns recognition results. During HarmonyOS adaptation, we discovered that HarmonyOS Native Intelligence provides a local speech recognition SDK, prompting us to encapsulate its capabilities.

Scenario Introduction

Native speech recognition supports two modes:

Short speech mode (≤60s)
Long speech mode (≤8h)

API Interface Introduction

1. Engine Initialization

speechRecognizer.createEngine

let asrEngine: speechRecognizer.SpeechRecognitionEngine;
// Create the engine and return via callback
// Set engine creation parameters
let extraParam: Record<string, Object> = {"locate": "CN", "recognizerMode": "short"};
let initParamsInfo: speechRecognizer.CreateEngineParams = {
  language: 'zh-CN',
  online: 1,
  extraParams: extraParam
};
// Invoke createEngine method
speechRecognizer.createEngine(initParamsInfo, (err: BusinessError, speechRecognitionEngine: speechRecognizer.SpeechRecognitionEngine) => {
  if (!err) {
    console.info('Succeeded in creating engine.');
    // Receive the created engine instance
    asrEngine = speechRecognitionEngine;
  } else {
    // Error code 1002200008 when unable to create engine: Engine is being destroyed
    console.error(`Failed to create engine. Code: ${err.code}, message: ${err.message}.`);
  }
});

Mainly need to construct speechRecognizer.CreateEngineParams:

language: Language
online: Mode (1 for offline; currently only offline engine is supported)
extraParams: Regional information, etc.
- locate: Regional info (optional, defaults to "CN"; currently only "CN" is supported)
- recognizerMode: Recognition mode ("short" for short speech, "long" for long speech)

Error information in callbacks:

Error code 1002200001: Engine creation failed due to unsupported language, mode, initialization timeout, or missing resources.
Error code 1002200006: Engine is busy (typically triggered when multiple apps call the speech recognition engine simultaneously).
Error code 1002200008: Engine is being destroyed.

2. Set RecognitionListener Callback

The callback handles events during recognition. The most important is onResult for processing recognized content, with different sessions corresponding to unique sessionIds:

// Create callback object
let setListener: speechRecognizer.RecognitionListener = {
  // Callback when recognition starts successfully
  onStart(sessionId: string, eventMessage: string) {

  },
  // Event callback
  onEvent(sessionId: string, eventCode: number, eventMessage: string) {

  },
  // Recognition result callback (includes intermediate and final results)
  onResult(sessionId: string, result: speechRecognizer.SpeechRecognitionResult) {

  },
  // Recognition completion callback
  onComplete(sessionId: string, eventMessage: string) {

  },
  // Error callback (error codes returned here, e.g., 1002200006: Engine is busy)
  onError(sessionId: string, errorCode: number, errorMessage: string) {

  }
}
// Set callback
asrEngine.setListener(setListener);

3. Start Recognition

let audioParam: speechRecognizer.AudioInfo = {audioType: 'pcm', sampleRate: 16000, soundChannel: 1, sampleBit: 16};
let extraParam: Record<string, Object> = {"vadBegin": 2000, "vadEnd": 3000, "maxAudioDuration": 40000};
let recognizerParams: speechRecognizer.StartParams = {
  sessionId: sessionId,
  audioInfo: audioParam,
  extraParams: extraParam
};
// Invoke start recognition method
asrEngine.startListening(recognizerParams);

Main parameters for starting recognition:

sessionId: Session ID (must correspond to the sessionId in onResult callbacks)
audioInfo: Audio configuration (optional)
- audioType: Currently only supports PCM (decode MP3 files before passing to the engine)
- sampleRate: Audio sampling rate (currently only 16000 is supported)
- sampleBit: Sampling bit depth (currently only 16-bit is supported)
- soundChannel: Audio channels (currently only mono/1 channel is supported)
- extraParams: Audio compression rate (defaults to 0 for PCM)
extraParams: Additional configuration
- recognitionMode: Real-time speech recognition mode (defaults to 1 if unspecified)
- 0: Real-time recording recognition (requires ohos.permission.MICROPHONE; call finish to stop)
- 1: Real-time audio-to-text (call writeAudio to pass audio stream)
- vadBegin: VAD (Voice Activity Detection) front-end point (range: [500,10000]ms; default 10000ms)
- vadEnd: VAD back-end point (range: [500,10000]ms; default 800ms)
- maxAudioDuration: Maximum supported audio duration
- Short speech mode: [20000-60000]ms (default 20000ms)
- Long speech mode: [20000 - 8*60*60*1000]ms

VAD primarily detects speech activity and skips silent segments.

4. Pass Audio Stream

asrEngine.writeAudio(sessionId, uint8Array);

Write audio data to the engine (can be from a microphone or audio file).

Note: Audio stream length must be 640 or 1280 bytes.

5. Other Interfaces

listLanguages: Query supported languages
finish: End recognition
cancel: Cancel recognition
shutdown: Release engine resources

Best Practices

For real-time recognition, read audio from the microphone and pass it to asrEngine, then handle results in the onResult callback.

Configure audio capture parameters and create an AudioCapturer instance:

import { audio } from '@kit.AudioKit';

let audioStreamInfo: audio.AudioStreamInfo = {
  samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_16000, // Sampling rate
  channels: audio.AudioChannel.CHANNEL_1, // Channels
  sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, // Sample format
  encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW // Encoding type
};

let audioCapturerInfo: audio.AudioCapturerInfo = {
  source: audio.SourceType.SOURCE_TYPE_MIC,
  capturerFlags: 0
};

let audioCapturerOptions: audio.AudioCapturerOptions = {
  streamInfo: audioStreamInfo,
  capturerInfo: audioCapturerInfo
};

audio.createAudioCapturer(audioCapturerOptions, (err, data) => {
  if (err) {
    console.error(`Invoke createAudioCapturer failed, code is ${err.code}, message is ${err.message}`);
  } else {
    console.info('Invoke createAudioCapturer succeeded.');
    let audioCapturer = data;
  }
});

Note: Sampling rate, channels, and bit depth must match ASR engine requirements (16k, mono, 16-bit).

Next, subscribe to audio data read events:

import { BusinessError } from '@kit.BasicServicesKit';
import { fileIo } from '@kit.CoreFileKit';

let bufferSize: number = 0;
class Options {
  offset?: number;
  length?: number;
}

let readDataCallback = (buffer: ArrayBuffer) => {
  // Write buffer to ASR engine
  asrEngine.writeAudio(sessionId, new Uint8Array(buffer));
}
audioCapturer.on('readData', readDataCallback);

Note: Buffer size must be 640 or 1280 bytes (ASR engine restriction).

Summary

This article introduces HarmonyOS' official speech recognition capabilities, details ASR engine interfaces, and demonstrates real-time microphone speech recognition by capturing audio data and processing results.

DEV Community: kouwei qing

Mastering the HarmonyOS Next Signature Verification Mechanism

Mastering the HarmonyOS Next Signature Verification Mechanism

Background Introduction

HarmonyOS Signing Mechanism

Role of the Key

Role of the Digital Certificate

Using AppGallery Connect Platform Debug Certificates

Generating a P12 Key

Applying for a Debug Certificate and Debug Profile

Summary

Reference Documents

Mastering Image and Video Selection in HarmonyOS Next

Mastering Image and Video Selection in HarmonyOS Next

Background

Introduction to HarmonyOS Permission System

Design Rationale

System Picker: Permission-Free Resource Access

Selecting from Album

Key Objects

PhotoSelectOptions (selection parameters)

PhotoSelectResult (selection result)

Distinguishing Image and Video URIs

Obtaining Video Thumbnails

Capturing via Camera

Using Want

Using cameraPicker

PickerProfile (camera settings)

PickerResult (capture result)

Summary

Reference Resources

Introduction to HarmonyOS Next Build Tool Lycium Principles

Introduction to HarmonyOS Next Build Tool Lycium Principles

Background Introduction

Introduction to Lycium Tool

Usage Example

Introduction to Build Script Principles

Build Process

1. Build Configuration Preparation

2. Build Process

3. Cross-Compilation Support

4. Artifact Output

build_hpk.sh Build Script Description

1. prepare(): Prepare the build environment (host build when buildhost=true), extract the source package, apply patches, and set up the cross-compilation environment.

2. build(): Execute the build process (configure build parameters, run configure, execute make, and return build results).

3. package(): Install and package (run make install and generate the final installation package).

4. check(): Test and verify (modify test configurations, prepare the test environment, execute test cases, and process results).

5. Environment management functions:

Summary

Introduction to DevEco Studio for HarmonyOS Next Development: ASan and TSan Detection to Cure Your C++ Phobia

Introduction to DevEco Studio for HarmonyOS Next Development: ASan and TSan Detection to Cure Your C++ Phobia

1. Background Introduction

2. ASan Detection

2.1 ASan Configuration

2.1.1 Configuring in app.json5

2.1.2 Configuring in Run/Debug Configurations

2.1.3 Configurable Parameters

2.2 Enabling ASan

2.3 ASan Error Codes

2.3.1 heap-buffer-overflow

2.3.2 stack-buffer-underflow

2.3.3 stack-use-after-scope

2.3.4 attempt-free-nonallocated-memory

2.3.5 double-free

2.3.6 heap-use-after-free

2.4 Additional Notes

3. TSan Detection

3.1 Key Application Scenarios

3.2 TSan Configuration

3.3 Enabling TSan

3.4 Additional Notes

4. Summary

HarmonyOS Private Repository Construction Practice

HarmonyOS Private Repository Construction Practice

Background

Introduction to HarmonyOS Shared Packages

Building a Private Repository with ohpm-repo

Dependent Environment Installation

Downloading ohpm-repo

Configuring ohpm-repo Environment Variables

`PhotoSelectOptions` (selection parameters)

`PhotoSelectResult` (selection result)

`PickerProfile` (camera settings)

`PickerResult` (capture result)

1. `prepare()`: Prepare the build environment (host build when `buildhost=true`), extract the source package, apply patches, and set up the cross-compilation environment.

2. `build()`: Execute the build process (configure build parameters, run `configure`, execute `make`, and return build results).

3. `package()`: Install and package (run `make install` and generate the final installation package).

4. `check()`: Test and verify (modify test configurations, prepare the test environment, execute test cases, and process results).

Create Async Work: `napi_create_async_work()`

Queue Async Work: `napi_queue_async_work()`

Cancel Async Work: `napi_cancel_async_work()`

Delete Async Work: `napi_delete_async_work()`

`execute` Function

`complete` Function

`complete` Callback

Ringing Tool: `RingAVPlayer`