The complete playback process includes the following steps: creating an AVPlayer instance, setting callback functions, setting playback resources, setting playback parameters (volume/playback speed/audio focus mode), setting the playback window, controlling playback (play/pause/seek/stop), resetting the player, and releasing the player instance.

During app development, you can proactively obtain playback process information through AVPlayer's information callback function OH_AVPlayerOnInfoCallback and error callback function OH_AVPlayerOnErrorCallback. If the app performs operations when the video player is in an error state, the system may throw exceptions or generate other undefined behaviors.

For detailed state descriptions, see AVPlayerState. When playback is in the prepared/playing/paused/completed state, the playback engine is in working state, which consumes a significant amount of system memory. If the client does not use the player temporarily, you can call reset() or release() to reclaim memory resources and use resources properly.

Playback state changes:

Development Suggestions

This guide only describes how to implement streaming media resource playback. To play local resources, see Using AVPlayer to Play Videos (C/C++). If your app development involves background playback, playback conflicts, or similar scenarios, refer to the following instructions as needed.

Avoid forced interruption of playback by the system. This feature is only available for ArkTS APIs. To use this feature, see Using AVPlayer to Play Videos (ArkTS).

During playback, if the media data being played involves audio, the playback may be interrupted by other apps according to the system audio management policy (see Handling Audio Focus Changes). You are advised to use OH_AVPlayer_SetOnInfoCallback() to proactively listen for the audio interruption event AVPlayerOnInfoType.AV_INFO_TYPE_INTERRUPT_EVENT, and handle it accordingly based on the specific information to avoid inconsistencies between the app state and the expected behavior.
When the device is connected to multiple audio output devices simultaneously, it is recommended to use OH_AVPlayer_SetOnInfoCallback() to proactively listen for the audio output device change event AVPlayerOnInfoType.AV_INFO_TYPE_AUDIO_OUTPUT_DEVICE_CHANGE and handle it accordingly.
During playback, the app may encounter exceptions due to internal system issues such as network data download failures or abnormal termination of media services. You are advised to set an error listener callback function through the OH_AVPlayer_SetOnErrorCallback() API, and handle different error types accordingly to prevent playback exceptions.

How to Develop

Link the following dynamic libraries in the CMake script:

target_link_libraries(entry PUBLIC
    libavplayer.so
    libnative_media_core.so
    libhilog_ndk.z.so
)

To use OH_AVPlayer_SetOnInfoCallback() and OH_AVPlayer_SetOnErrorCallback() to set the information callback and error callback, link the libnative_media_core.so dynamic library in the CMake script.

To use system logging, include the following header file:

#include <hilog/log.h>

Link the libhilog_ndk.z.so dynamic library in the CMake script.

By including the avplayer.h, avplayer_base.h, and native_averrors.h header files, you can use the APIs related to streaming media playback.

For detailed API descriptions, see AVPlayer.

Call OH_AVPlayer_Create() to create an AVPlayer instance. The AVPlayer is initialized to the AVPlayerState.AV_IDLE state.
```
OH_AVPlayer *player = OH_AVPlayer_Create();
```

Call OH_AVPlayer_SetOnInfoCallback() and OH_AVPlayer_SetOnErrorCallback() to set the information listener callback and error listener callback for use in full-process scenarios. While obtaining more information, you can also differentiate playback instances by setting userData.

The following table lists supported listener events.

Event Type	Description
OH_AVPlayerOnInfoCallback	Mandatory event. Listens for process information of the player. This listener must be set when the player is in the AV_IDLE state and before any resource setting API is called. If the listener is set after calling a resource setting API, the OH_AVPlayerOnInfoCallback events reported during resource setting cannot be received.
OH_AVPlayerOnErrorCallback	Mandatory event. Listens for error information of the player. This listener must be set when the player is in the AV_IDLE state and before any resource setting API is called. If the listener is set after calling a resource setting API, the OH_AVPlayerOnErrorCallback events reported during resource setting cannot be received.

Event Type

Description

OH_AVPlayerOnInfoCallback

Mandatory event. Listens for process information of the player.

This listener must be set when the player is in the AV_IDLE state and before any resource setting API is called. If the listener is set after calling a resource setting API, the OH_AVPlayerOnInfoCallback events reported during resource setting cannot be received.

OH_AVPlayerOnErrorCallback

Mandatory event. Listens for error information of the player.

This listener must be set when the player is in the AV_IDLE state and before any resource setting API is called. If the listener is set after calling a resource setting API, the OH_AVPlayerOnErrorCallback events reported during resource setting cannot be received.

// Set the callback to listen for information.
LOG("call OH_AVPlayer_SetOnInfoCallback");
int32_t ret = OH_AVPlayer_SetOnInfoCallback(player, OHAVPlayerOnInfoCallback, nullptr);
LOG("OH_AVPlayer_SetOnInfoCallback ret:%{public}d", ret);

LOG("call OH_AVPlayer_SetOnErrorCallback");
ret = OH_AVPlayer_SetOnErrorCallback(player, OHAVPlayerOnErrorCallback, nullptr);
LOG("OH_AVPlayer_SetOnErrorCallback ret:%{public}d", ret);

Call OH_AVPlayer_SetURLSource() to set the URL (supports on-demand and live streaming sources). The AVPlayer enters the AVPlayerState.AV_INITIALIZED (initialized) state.

LOG("player %{public}s >> URL source", url);
LOG("call %{public}s", "OH_AVPlayer_SetURLSource");
ret = OH_AVPlayer_SetURLSource(player, url);
LOG("OH_AVPlayer_SetURLSource ret:%{public}d", ret);

(Optional) In live streaming scenarios, call OH_AVPlayer_SetPlaybackStrategy() to enable smart frame catching for the AVPlayer.

void OHAVPlayerSetPlaybackStrategy(OH_AVPlayer *player)
{
    // Set the playback strategy.
    OH_AVPlaybackStrategy *myStrategy = OH_AVPlaybackStrategy_Create();
    double waterLine = 6.0;
    OH_AVPlaybackStrategy_SetThresholdForAutoQuickPlay(myStrategy, waterLine); // Set smart frame chasing for live streaming scenarios.
    int32_t ret = OH_AVPlayer_SetPlaybackStrategy(player, myStrategy);
    LOG("OH_AVPlayer_SetPlaybackStrategy ret:%{public}d", ret);
    OH_AVPlaybackStrategy_Destroy(myStrategy);
}

(Optional) Call OH_AVPlayer_SetAudioRendererInfo() to set the audio stream type for the AVPlayer.

// Set the audio stream type.
LOG("call %{public}s", "OH_AVPlayer_SetAudioRendererInfo");
OH_AudioStream_Usage streamUsage = OH_AudioStream_Usage::AUDIOSTREAM_USAGE_UNKNOWN;
ret = OH_AVPlayer_SetAudioRendererInfo(player, streamUsage);
LOG("OH_AVPlayer_SetAudioRendererInfo ret:%{public}d", ret);

(Optional) Call OH_AVPlayer_SetAudioInterruptMode() to set the audio stream interruption mode for the AVPlayer.

// Set the audio stream interrupt mode.
LOG("call OH_AVPlayer_SetAudioInterruptMode");
OH_AudioInterrupt_Mode interruptMode = OH_AudioInterrupt_Mode::AUDIOSTREAM_INTERRUPT_MODE_INDEPENDENT;
ret = OH_AVPlayer_SetAudioInterruptMode(player, interruptMode);
LOG("OH_AVPlayer_SetAudioInterruptMode ret:%{public}d", ret);

Call OH_AVPlayer_SetVideoSurface() to set the playback window. This function must be called after SetSource and before Prepare.
```
ret = OH_AVPlayer_SetVideoSurface(player, context->nativeWindow_);
LOG("OH_AVPlayer_SetVideoSurface ret:%{public}d", ret);
```

Call OH_AVPlayer_Prepare(). The AVPlayer enters the AVPlayerState.AV_PREPARED state, where you can obtain the duration and set the volume.

ret = OH_AVPlayer_Prepare(player); // Triggered after the playback source is set.
if (ret != AV_ERR_OK) {
    // Handle the exception.
    LOG("player %{public}s", "OH_AVPlayer_Prepare Err");
}

(Optional) Call OH_AVPlayer_SetAudioEffectMode() to set the audio effect mode for the AVPlayer.

LOG("AVPlayerState AV_PREPARED");
ret = OH_AVPlayer_SetAudioEffectMode(player, EFFECT_NONE); // Set the audio effect mode.
LOG("OH_AVPlayer_SetAudioEffectMode ret:%{public}d", ret);

Call OH_AVPlayer_Play(), OH_AVPlayer_Pause(), OH_AVPlayer_Seek(), and OH_AVPlayer_Stop() to control the playback.

static napi_value NAPI_Global_Play(napi_env env, napi_callback_info info) {
    int ret = -1;
    auto context = SampleManager::GetInstance();
    if (context->player_ != NULL) {
        ret = OH_AVPlayer_Play(context->player_);
        LOG("OH_AVPlayer_Play ret:%{public}d", ret);
    } else {
        LOG("no found Player Instances");
    }
    napi_value value;
    napi_create_int32(env, ret, &value);
    return value;
}

static napi_value NAPI_Global_Pause(napi_env env, napi_callback_info info) {
    int ret = 100;
    auto context = SampleManager::GetInstance();
    if (context->player_ != NULL) {
        ret = OH_AVPlayer_Pause(context->player_);
        LOG("OH_AVPlayer_Pause ret:%{public}d", ret);
    } else {
        LOG("no found Player Instances");
    }
    napi_value value;
    napi_create_int32(env, ret, &value);
    return value;
}

static napi_value NAPI_Global_Seek(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);
    int seekValue;
    napi_get_value_int32(env, args[0], &seekValue);
    int mode;
    napi_get_value_int32(env, args[1], &mode);
    auto context = SampleManager::GetInstance();
    if (context->player_ != NULL) {
        int ret;
        switch (mode) {
        case 0:
            LOG("call NAPI_Global_Seek value:%{public}d  mode:AV_SEEK_NEXT_SYNC", seekValue);
            ret = OH_AVPlayer_Seek(context->player_, seekValue, AV_SEEK_NEXT_SYNC);
            break;
        case 1:
            LOG("call NAPI_Global_Seek value:%{public}d  mode:AV_SEEK_PREVIOUS_SYNC", seekValue);
            ret = OH_AVPlayer_Seek(context->player_, seekValue, AV_SEEK_PREVIOUS_SYNC);
            break;
        case 2:
            LOG("call NAPI_Global_Seek value:%{public}d  mode:AV_SEEK_CLOSEST", seekValue);
            ret = OH_AVPlayer_Seek(context->player_, seekValue, AV_SEEK_CLOSEST);
            break;
        default:
            LOG("call NAPI_Global_Seek value:%{public}d  mode:AV_SEEK_PREVIOUS_SYNC", seekValue);
            ret = OH_AVPlayer_Seek(context->player_, seekValue, AV_SEEK_PREVIOUS_SYNC);
            break;
        }
        LOG("OH_AVPlayer_Seek ret:%{public}d", ret);
    } else {
        LOG("no found Player Instances");
    }
    napi_value value;
    napi_create_int32(env, 0, &value);
    return value;
}

static napi_value NAPI_Global_Stop(napi_env env, napi_callback_info info) {
    int ret = 100;
    auto context = SampleManager::GetInstance();
    if (context->player_ != NULL) {
        ret = OH_AVPlayer_Stop(context->player_);
        LOG("OH_AVPlayer_Stop ret:%{public}d", ret);
    } else {
        LOG("no found Player Instances");
    }
    napi_value value;
    napi_create_int32(env, ret, &value);
    return value;
}

(Optional) Call OH_AVPlayer_Reset() to reset the resource. AVPlayer re-enters the AVPlayerState.AV_IDLE state, allowing the resource URL to be changed.

static napi_value NAPI_Global_Reset(napi_env env, napi_callback_info info) {
    int ret = 100;
    auto context = SampleManager::GetInstance();
    if (context->player_ != NULL) {
        ret = OH_AVPlayer_Reset(context->player_);
        LOG("OH_AVPlayer_Reset ret:%{public}d", ret);
    } else {
        LOG("no found Player Instances");
    }
    napi_value value;
    napi_create_int32(env, ret, &value);
    return value;
}

Call OH_AVPlayer_Release() to destroy the instance. AVPlayer enters the AVPlayerState.AV_RELEASED state and exits playback. Any subsequent operations on the AVPlayer instance will result in undefined behavior, which may cause the app process to crash or the app to exit abnormally.

static napi_value NAPI_Global_Release(napi_env env, napi_callback_info info) {
    int ret = -1;
    auto context = SampleManager::GetInstance();
    if (context->player_ != NULL) {
        ret = OH_AVPlayer_Release(context->player_);
        LOG("OH_AVPlayer_Release ret:%{public}d", ret);
    } else {
        LOG("no found Player Instances");
    }
    napi_value value;
    napi_create_int32(env, ret, &value);
    return value;
}

Running the Complete Sample

Create a project and download the sample project.
Compile the newly created project and run it.

目录

Using AVPlayer to Play Streaming Media (C/C++)

Development Suggestions

How to Develop

Running the Complete Sample