基于长时任务与实况窗的视频后台导出方案

概述

视频编辑类的应用在完成视频编辑导出视频时，如果应用切换到后台，或者锁屏、熄屏后，系统将冻结应用进程，导致视频导出暂停，影响用户体验和导出效率。为解决这一问题，系统提供了长时任务机制和Live View Kit（实况窗服务），使应用能够在后台持续执行视频导出，并通过实况窗向用户实时展示进度。本文旨在介绍如何基于系统能力实现完整的后台视频导出方案，通过使用长时任务和实况窗功能来实现视频的后台导出，当视频导出开始后，应用在切屏、锁屏、灭屏情况下依然可以在后台持续导出视频。

本文的主要内容包括：

1. 视频导出与进度回调：基于AVCodec NDK在C++ Native层构建多线程视频处理管线，完成视频解码、OpenGL ES水印合成与重新编码，通过解码帧数实时回调进度。
2. 后台任务管理：基于Background Tasks Kit（后台任务开发服务）申请长时任务，保障视频导出在后台持续运行。
3. 实况窗进度展示：通过Live View Kit（实况窗服务）创建实况窗，实时展示导出进度并在完成后通知用户。

整体方案

下图展示了正常导出流程中各模块的完整交互：用户点击导出后，应用依次完成草稿持久化、实况窗创建、长时任务启动、C++ Native管线逐帧解码-合成-编码与进度回调，最终将视频写入系统相册并结束实况窗和后台任务。

视频导出与进度回调

场景描述

视频导出涉及视频解码、水印合成与重新编码操作。本方案基于AVCodec NDK在C++ Native层构建多线程视频处理管线，通过OpenGL ES完成水印合成。导出过程中的进度信息通过NAPI线程安全回调传递回ArkTS层，驱动实况窗更新和UI展示。

实现原理

视频导出通过NativeExportUtil调用C++ Native模块，Native层内部使用音视频编解码完成视频解封装、硬件解码、OpenGL ES水印合成、硬件编码和封装的全流程。ArkTS层只需打开输入输出文件获取文件描述符，将水印参数和旋转角度传入，通过回调函数接收进度和完成通知。支持通过nativeexport.cancelExport()随时取消正在执行的导出任务。视频导出流程如下图所示：

关键接口：

• nativeexport.startExport(inputFd, inputFileOffset, inputFileSize, outputFd, watermarks, rotation, onProgress, onDone)：启动Native导出管线。
• nativeexport.cancelExport()：取消正在执行的导出任务。

开发步骤

1. 通过Promise等待导出完成：startExport()为异步调用，进度通过onProgress实时回调，导出完成或失败时通过onDone通知，在回调中关闭文件描述符并resolve Promise。
   收起

   自动换行

   深色代码主题

   复制

   return new Promise<number>((resolve) => {
     nativeexport.startExport(
       inputFile?.fd ?? -1,
       0,
       stat.size,
       outputFile?.fd ?? -1,
       wmParams,
       rotation,
       (percent: number) => {
         onProgress(percent);
       },
       (result: number) => {
         if (inputFile) {
           try {
             fileIo.closeSync(inputFile.fd);
           } catch (error) {
             Logger.error(TAG, `inputFile closeSync err, err.code is ${error.code}, message is ${error.message}`);
           }
         }
         if (outputFile) {
           try {
             fileIo.closeSync(outputFile.fd);
           } catch (error) {
             Logger.error(TAG, `outputFile closeSync err, err.code is ${error.code}, message is ${error.message}`);
           }
         }
         onProgress(PROGRESS_COMPLETE);
         onCoverReady(0, 0);
         resolve(result);
       }
     );
   });

   NativeExportUtil.ets
2. 支持取消正在执行的导出：调用nativeexport.cancelExport()中断Native管线，Native层会设置取消标志并唤醒所有工作线程，最终通过doneCallback(-1)通知ArkTS层。
   收起

   自动换行

   深色代码主题

   复制

   static cancelExport(): void {
     nativeexport.cancelExport();
   }

   NativeExportUtil.ets

后台任务管理

场景描述

视频导出类任务通常耗时较长，用户可能在导出过程中切换到其他应用或锁屏。如果没有后台任务保障，系统会挂起应用进程，导致导出中断。开发者需要申请长时任务，使应用在后台保持活跃状态，持续执行视频导出。

实现原理

Background Tasks Kit（后台任务开发服务）提供了ContinuousTaskRequest机制，应用通过声明MODE_SPECIAL_SCENARIO_PROCESSING模式和SUBMODE_MEDIA_PROCESS_NORMAL_NOTIFICATION子模式，向系统申请特殊场景的后台长时任务。该任务允许应用在后台持续运行，同时系统会在通知栏展示任务状态。后台任务管理流程如下图所示：

关键接口：

• ContinuousTaskRequest：长时任务请求对象，配置后台模式和子模式。
• backgroundTaskManager.startBackgroundRunning()：启动后台长时任务，返回ContinuousTaskNotification包含任务ID。
• backgroundTaskManager.stopBackgroundRunning()：根据任务ID停止后台任务。
• ContinuousTaskRequest.checkSpecialScenarioAuth()：检查用户是否已授权特殊场景后台权限。
• ContinuousTaskRequest.requestAuthFromUser()：向用户弹窗请求后台权限授权。

开发步骤

1. 在module.json5配置文件中声明后台任务模式backgroundModes为specialScenarioProcessing，并且在requestPermissions中申请两项后台运行权限。
   收起

   自动换行

   深色代码主题

   复制

   "abilities": [
     {
       // ...
       "backgroundModes": [
         "specialScenarioProcessing"
       ]
     }
   ],
   "requestPermissions": [
     {
       "name": "ohos.permission.KEEP_BACKGROUND_RUNNING_SPECIAL_SCENARIO",
       "reason": "$string:background_running_reason",
       "usedScene": {
         "abilities": ["EntryAbility"],
         "when": "always"
       }
     },
     {
       "name": "ohos.permission.KEEP_BACKGROUND_RUNNING",
       "reason": "$string:background_running_reason",
       "usedScene": {
         "abilities": ["EntryAbility"],
         "when": "always"
       },
     }
   ],

   module.json5
2. 构建长时任务请求并配置后台模式：创建ContinuousTaskRequest对象，设置backgroundTaskModes为MODE_SPECIAL_SCENARIO_PROCESSING，backgroundTaskSubmodes为SUBMODE_MEDIA_PROCESS_NORMAL_NOTIFICATION，指定任务类型为媒体处理通知场景。
   收起

   自动换行

   深色代码主题

   复制

   private static getTask(): backgroundTaskManager.ContinuousTaskRequest {
     let continuousTaskRequest = new backgroundTaskManager.ContinuousTaskRequest();
     let modeList: number[] = [backgroundTaskManager.BackgroundTaskMode.MODE_SPECIAL_SCENARIO_PROCESSING];
     continuousTaskRequest.backgroundTaskModes = modeList;
     let subModeList: number[] =
       [backgroundTaskManager.BackgroundTaskSubmode.SUBMODE_MEDIA_PROCESS_NORMAL_NOTIFICATION];
     continuousTaskRequest.backgroundTaskSubmodes = subModeList;
     return continuousTaskRequest;
   }

   ContinueTaskController.ets
3. 检查权限并启动后台长时任务：先通过isRunning()防止重复启动，构建WantAgent用于通知栏点击跳转，调用startBackgroundRunning()启动任务并保存返回的continuousTaskId。
   收起

   自动换行

   深色代码主题

   复制

   public isRunning(): boolean {
     // Prevent duplicate start of background continuous task
     return this.continuousTaskId !== undefined && this.continuousTaskId > 0;
   }
   
   public async start(): Promise<void> {
     if (this.isRunning()) {
       Logger.warn(TAG, `continuous task already running, id=${this.continuousTaskId}`);
       return;
     }
     if (!this.context) {
       Logger.error(TAG, `invalid context`);
       return;
     }
     try {
       let wantAgentObj = this.wantAgentCache ?? await this.buildWantAgent();
       if (!wantAgentObj) {
         Logger.error(TAG, `wantAgent is undefined`);
         return;
       }
       // Build continuousTaskRequest object
       let continuousTaskRequest: backgroundTaskManager.ContinuousTaskRequest = ContinueTaskController.getTask();
       if (continuousTaskRequest === undefined) {
         Logger.info(TAG, `continuousTaskRequest is undefined`);
         return;
       }
       continuousTaskRequest.wantAgent = wantAgentObj;
       continuousTaskRequest.combinedTaskNotification = false;
       continuousTaskRequest.continuousTaskId = -1;
   
       let res: backgroundTaskManager.ContinuousTaskNotification =
         await backgroundTaskManager.startBackgroundRunning(this.context, continuousTaskRequest);
       Logger.info(TAG,
         `Operation startBackgroundRunning succeeded.
          notificationId=${res.notificationId} continuousTaskId=${res.continuousTaskId}`);
       this.continuousTaskId = res.continuousTaskId;
     } catch (error) {
       Logger.error(TAG, `Operation startBackgroundRunning failed, code is ${error.code}, message is ${error.message}`);
     }
   
   }

   ContinueTaskController.ets
4. 在导出页面检查权限并按需申请：导出页面在aboutToAppear()中检查长时任务权限状态，已授权则直接启动后台任务，未授权则弹窗请求。若用户拒绝，则页面内提示无法退出后台继续导出。
   收起

   自动换行

   深色代码主题

   复制

   continueTaskController.checkSpecialScenarioAuth().then(async (result) => {
     // Request permission when no background continuous task permission for special scenario
     if (result !== backgroundTaskManager.UserAuthResult.GRANTED_ONCE &&
       result !== backgroundTaskManager.UserAuthResult.GRANTED_ALWAYS) {
       this.hasContinueTaskPermission = false;
       continueTaskController.requestPermit(async (authResult) => {
         // Start continuous task if permission is granted
         if (authResult === backgroundTaskManager.UserAuthResult.GRANTED_ONCE ||
           authResult === backgroundTaskManager.UserAuthResult.GRANTED_ALWAYS) {
           this.hasContinueTaskPermission = true;
           await ContinueTaskController.getInstance(this.context.getHostContext() as common.UIAbilityContext).start();
           return;
         }
       });
     } else { // Start continuous task directly if permission already granted
       this.hasContinueTaskPermission = true;
       await ContinueTaskController.getInstance(this.context.getHostContext() as common.UIAbilityContext).start();
     }
   }).catch((err: BusinessError) => {
     Logger.error(TAG, `checkSpecialScenarioAuth failed: ${err.code} ${err.message}`);
   });

   ExportProgressPage.ets
5. 导出完成后停止后台任务：在视频导出成功或失败后，在适当时机调用stopBackgroundRunning()释放后台任务资源。停止时机通过TimeoutManager管理，应用处于前台时立即停止，应用处于后台时则设置一定延迟，确保用户有足够时间通过实况窗感知结果，本案例中通过BACKGROUND_LIVEVIEW_TIMEOUT_MS常量将延迟设为5分钟。
   收起

   自动换行

   深色代码主题

   复制

   const isForeground = AppStorage.get<boolean>(StorageConstants.IS_APP_FOREGROUND) ?? true;
   TimeoutManager.getInstance().addTimeout(
     async () => { // Timer: delay stopping LiveView if app is in background
       try {
         await liveViewController.stopLiveViewSucc(isForeground);
         await ContinueTaskController.getInstance(context).stop();
       } catch (e) {
         Logger.error(TAG, `stopLiveView fail`);
       }
     },
     async () => { // Stop LiveView immediately if app enters foreground after export
       try {
         await liveViewController.stopLiveViewSucc(true);
         await ContinueTaskController.getInstance(context).stop();
       } catch (e) {
         Logger.error(TAG, `stopLiveViewSucc on user click fail`);
       }
     },
     isForeground ? BACKGROUND_LIVEVIEW_TIMEOUT_0 : BACKGROUND_LIVEVIEW_TIMEOUT_MS // Timer delay duration
   );
   WaterMarkNativeUtil.cleanupTempFiles(outVideoPath, inputVideoPath, tempFiles, outVideoPath + '.cover.jpg');

   WaterMarkNativeUtil.ets
6. 在UIAbility销毁时兜底清理：在onDestroy()生命周期中停止所有活跃的实况窗和后台任务，防止资源泄漏。
   收起

   自动换行

   深色代码主题

   复制

   async onDestroy(): Promise<void> {
     Logger.info(TAG, `Ability onDestroy`);
     await LiveViewController.stopAllActiveLiveView(this.context);
     await ContinueTaskController.getInstance(this.context).stop();
   }

   EntryAbility.ets

实况窗进度展示

场景描述

用户在后台导出视频时，需要直观地了解导出进度和结果。实况窗（Live View）是HarmonyOS提供的系统级UI能力，可以在状态栏、锁屏和通知中心展示实时信息，是后台任务进度反馈的最佳载体。

实现原理

实况窗的生命周期分为三个阶段：创建（startLiveView）、更新（updateLiveView）和结束（stopLiveView）。导出开始时创建实况窗并显示初始进度，Native管线每回调一次进度就更新实况窗内容，导出完成或失败时更新为最终状态并结束实况窗。实况窗管理流程如下图所示：

关键接口：

• liveViewManager.startLiveView()：创建并展示实况窗，传入LiveView配置对象。
• liveViewManager.updateLiveView()：更新实况窗内容，包括进度、标题和胶囊状态。
• liveViewManager.stopLiveView()：结束实况窗，设置最终展示状态和保留时间。
• liveViewManager.isLiveViewEnabled()：检查实况窗功能开关是否开启。
• ExtensionType.EXTENSION_TYPE_PROGRESS：进度条扩展类型，用于在实况窗中展示进度条。

开发步骤