鸿蒙AVSession Kit

------ ArkTS 与 C/C++ 双语言、Provider 与 Controller 全角色

适用版本：HarmonyOS API 12+

覆盖：本地会话提供方（Provider）、会话控制方（Controller）、后台播放

一、设计总览（Mermaid）

任何进程都能读会话（获取元数据/状态）
任何进程都能写会话（发命令）------只要拿到对应 AVSessionController

二、ArkTS 完整落地

依赖

ts 复制代码

import { avSession } from '@kit.AVSessionKit';
import { BackgroundTasks } from '@kit.BackgroundTasksKit';

会话提供方（Provider）

ts 复制代码

class MyProvider {
  private session: avSession.AVSession | null = null;

  async init(ctx: Context) {
    /* 1. 长时任务 */
    await BackgroundTasks.startBackgroundRunning(ctx, 'AUDIO_PLAYBACK', 'music');

    /* 2. 创建会话 */
    this.session = await avSession.createAVSession(ctx, 'MusicSession', 'audio');

    /* 3. 元数据 */
    await this.session.setAVMetadata({
      assetId: '10086',
      title: 'Bohemian Rhapsody',
      artist: 'Queen',
      duration: 355000,
      mediaImage: 'https://xx/cover.jpg',
      previousAssetId: '10085',
      nextAssetId: '10087'
    });

    /* 4. 播放状态 */
    await this.session.setAVPlaybackState({
      state: avSession.PlaybackState.PLAYBACK_STATE_PLAYING,
      position: { elapsedTime: 60000, updateTime: Date.now() },
      speed: 1.0,
      loopMode: avSession.LoopMode.LOOP_MODE_LIST
    });

    /* 5. 注册命令（被动） */
    this.session.on('play',     () => this.player.play());
    this.session.on('pause',    () => this.player.pause());
    this.session.on('seek',     (pos: number) => this.player.seek(pos));
    this.session.on('playNext', () => this.player.next());

    /* 6. 激活 */
    await this.session.activate();
  }

  private player = { play:()=>{}, pause:()=>{}, seek:()=>{}, next:()=>{} };

  async destroy() {
    this.session?.destroy();
    BackgroundTasks.stopBackgroundRunning(getContext(this));
  }
}

会话控制方（Controller）

ts 复制代码

class MyController {
  private ctrl: avSession.AVSessionController | null = null;

  async attach(sessionId: string) {
    this.ctrl = await avSession.createController(sessionId);
  }

  async play()  { await this.ctrl?.sendControlCommand({ command: 'play' }); }
  async pause() { await this.ctrl?.sendControlCommand({ command: 'pause' }); }
  async seek(ms: number) {
    await this.ctrl?.sendControlCommand({ command: 'seek', parameters: { position: ms } });
  }
}

枚举会话

ts 复制代码

const sessions = await avSession.getAllActiveSessions();
console.log('当前活跃会话', sessions.map(s => s.sessionTag));

三、C/C++（NDK）完整落地

CMake

cmake 复制代码

find_library(avsession-lib libohavsession.so)
target_link_libraries(your_target ${avsession-lib})

会话提供方（Provider）

cpp 复制代码

// 1. 创建
OH_AVSession* session;
OH_AVSession_Create("MusicSess", SESSION_TYPE_AUDIO,
                    "com.demo", "MainAbility", &session);

// 2. 元数据
OH_AVMetadataBuilder* mb = OH_AVMetadataBuilder_Create();
OH_AVMetadataBuilder_SetAssetId(mb, "10086");
OH_AVMetadataBuilder_SetTitle(mb, "Rhapsody");
OH_AVMetadata* meta = OH_AVMetadataBuilder_Build(mb);
OH_AVSession_SetAVMetadata(session, meta);

// 3. 播放状态
OH_AVPlaybackState* ps = OH_AVPlaybackState_Create();
OH_AVPlaybackState_SetState(ps, PLAYBACK_STATE_PLAYING);
OH_AVSession_SetAVPlaybackState(session, ps);

// 4. 注册命令
OH_AVSession_RegisterCommandCallback(
    session, COMMAND_PLAY,
    [](void*){ /* real play */ }, nullptr);

OH_AVSession_Activate(session);

会话控制方（Controller）

cpp 复制代码

// 枚举
AVSession_SessionInfo* infos;
size_t cnt;
OH_AVSessionManager_GetAllActiveSessions(&infos, &cnt);

// 创建 Controller
OH_AVSessionController* ctrl;
OH_AVSessionController_Create(infos[0].sessionId, &ctrl);

// 发命令
OH_AVControllerCommand cmd = { .command = COMMAND_SEEK, .parameters.position = 30000 };
OH_AVSessionController_SendCommand(ctrl, &cmd);

清理

cpp 复制代码

OH_AVSessionController_Destroy(ctrl);
OH_AVSession_Destroy(session);

四、命令全集（两语言通用）

命令 ArkTS 参数 C++ 枚举 play { command:'play' } COMMAND_PLAY pause { command:'pause' } COMMAND_PAUSE stop { command:'stop' } COMMAND_STOP seek { command:'seek', parameters:{ position } } COMMAND_SEEK setSpeed { command:'setSpeed', parameters:{ speed } } COMMAND_SET_SPEED setLoopMode { command:'setLoopMode', parameters:{ loopMode } } COMMAND_SET_LOOP_MODE toggleFavorite { command:'toggleFavorite' } COMMAND_TOGGLE_FAVORITE playNext / playPrevious { command:'playNext'/'playPrevious' } COMMAND_PLAY_NEXT / PREVIOUS skipToQueueItem { command:'skipToQueueItem', parameters:{ itemId } } COMMAND_SKIP_TO_QUEUE_ITEM commonCommand { command:'commonCommand', parameters:{ command, extras } } COMMAND_COMMON

五、后台播放 checklist（上架必过）

createAVSession 的 type 与音频流类型匹配（audio / video / voice_call）
激活前已 setAVMetadata + setAVPlaybackState + 注册命令
已申请 AUDIO_PLAYBACK 长时任务且 pause/stop 时主动取消
退出业务时 destroy 会话
若支持歌单/冷启动续播，已注册 PlayMusicList / PlayAudio 意图

至此，ArkTS 与 C/C++ 双语言、Provider 与 Controller 全角色一次讲透。