HarmonyOS之深入解析媒体会话的管理

Posted Forever_wj

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了HarmonyOS之深入解析媒体会话的管理相关的知识,希望对你有一定的参考价值。

一、简介

  • AVSession 是一套媒体播放控制框架,对媒体服务和界面进行解耦,并提供规范的通信接口,使应用可以自由、高效地在不同的媒体之间完成切换。
  • 在使用完 AVSession 类后,需要及时进行资源释放。
  • 播放器类需要使用 ohos.media.player.Player,否则无法正常接收按键事件。

二、应用场景

  • AVSession 框架有四个主要的类,控制着整个框架的核心,下图简单的说明四个核心媒体框架控制类的关系。

在这里插入图片描述

  • AVBrowser:
    • 媒体浏览器,通常在客户端创建,成功连接媒体服务后,通过媒体控制器 AVController 向服务端发送播放控制指令。
    • 其主要流程为,调用 connect 方法向 AVBrowserService 发起连接请求,连接成功后在回调方法 AVConnectionCallback.onConnected 中发起订阅数据请求,并在回调方法 AVSubscriptionCallback.onAVElementListLoaded 中保存请求的媒体播放数据。
    • 调用 AVBrowser的subscribeByParentMediaId(String, AVSubscriptionCallback) 之前,需要先执行 unsubscribeByParentMediaId(String),防止重复订阅。
  • AVController:
    • 媒体控制器,在客户端 AVBrowser 连接服务成功后的回调方法 AVConnectionCallback.onConnected 中创建,用于向 Service 发送播放控制指令,并通过实现 AVControllerCallback 回调来响应服务端媒体状态变化,例如曲目信息变更、播放状态变更等,从而完成 UI 刷新。
  • AVBrowserService:
    • 媒体浏览器服务,通常在服务端,通过媒体会话 AVSession 与媒体浏览器建立连接,并通过实现 Player 进行媒体播放。
    • AVBrowserService 有两个重要的方法:
      • onGetRoot,处理从媒体浏览器 AVBrowser 发来的连接请求,通过返回一个有效的AVBrowserRoot对象表示连接成功;
      • onLoadAVElementList,处理从媒体浏览器 AVBrowser 发来的数据订阅请求,通过 AVBrowserResult.sendAVElementList(List) 方法返回媒体播放数据。使用 onLoadAVElementList(String, AVBrowserResult) 的 result 返回数据前,需要执行 detachForRetrieveAsync()。
  • AVSession:
    • 媒体会话,通常在 AVBrowserService 的 onStart 中创建,通过 setAVToken 方法设置到 AVBrowserService 中,并通过实现 AVSessionCallback 回调来接收和处理媒体控制器 AVController 发送的播放控制指令,如播放、暂停、跳转至上一曲、跳转至下一曲等。
  • AVElement:媒体元素,用于将播放列表从 AVBrowserService 传递给 AVBrowser。

三、API

① AVBrowser 的主要接口
接口名描述
AVBrowser(Context context, ElementName name, AVConnectionCallback callback, PacMap options)构造AVBrowser实例,用于浏览AVBrowserService提供的媒体数据
connect()连接AVBrowserService
disconnect()与AVBrowserService断开连接
isConnected()判断当前是否已经与AVBrowserService连接
getElementName()获取AVBrowserService的ohos.bundle.ElementName实例
getRootMediaId()获取默认媒体id
getOptions()获取AVBrowserService提供的附加数据
getAVToken()获取媒体会话的令牌
getAVElement(String mediaId, AVElementCallback callback)输入媒体的id,查询对应的ohos.media.common.sessioncore.AVElement信息,查询结果会通过callback返回
subscribeByParentMediaId(String parentMediaId, AVSubscriptionCallback callback)查询指定媒体id包含的所有媒体元素信息,并订阅它的媒体信息更新通知
subscribeByParentMediaId(String parentMediaId, PacMap options, AVSubscriptionCallback callback)基于特定于服务的参数来查询指定媒体id中的媒体元素的信息,并订阅它的媒体信息更新通知
unsubscribeByParentMediaId(String parentMediaId)取消订阅对应媒体id的信息更新通知
unsubscribeByParentMediaId(String parentMediaId, AVSubscriptionCallback callback)取消订阅与指定callback相关的媒体id的信息更新通知
② AVBrowserService 的主要接口
接口名描述
onGetRoot(String callerPackageName, int clientUid, PacMap options)回调方法,用于返回应用程序的媒体内容的根信息,在AVBrowser.connect()后进行回调
onLoadAVElementList(String parentMediaId, AVBrowserResult result)回调方法,用于返回应用程序的媒体内容的结果信息AVBrowserResult,其中包含了子节点的AVElement列表,在AVBrowser的方法subscribeByParentMediaId或notifyAVElementListUpdated执行后进行回调
onLoadAVElement(String mediaId, AVBrowserResult result)回调方法,用于获取特定的媒体项目AVElement结果信息,在AVBrowser.getAVElement方法执行后进行回调
getAVToken()获取AVBrowser与AVBrowserService之间的会话令牌
setAVToken(AVToken token)设置AVBrowser与AVBrowserService之间的会话令牌
getBrowserOptions()获取AVBrowser在连接AVBrowserService时设置的服务参数选项
getCallerUserInfo()获取当前发送请求的调用者信息
notifyAVElementListUpdated(String parentMediaId)通知所有已连接的AVBrowser当前父节点的子节点已经发生改变
notifyAVElementListUpdated(String parentId, PacMap options)通知所有已连接的AVBrowser当前父节点的子节点已经发生改变,可设置服务参数
③ AVController 的主要接口
接口名描述
AVController(Context context, AVToken avToken)构造AVController实例,用于应用程序与AVSession进行交互以控制媒体播放
setControllerForAbility(Ability ability, AVController controller)将媒体控制器注册到ability以接收按键事件
setAVControllerCallback(AVControllerCallback callback)注册一个回调以接收来自AVSession的变更,例如元数据和播放状态变更
releaseAVControllerCallback(AVControllerCallback callback)释放与AVSession之间的回调实例
getAVQueueElement()获取播放队列
getAVQueueTitle()获取播放队列的标题
getAVPlaybackState()获取播放状态
dispatchAVKeyEvent(KeyEvent keyEvent)应用分发媒体按键事件给会话以控制播放
sendCustomCommand(String command, PacMap pacMap, GeneralReceiver receiverCb)应用向AVSession发送自定义命令,参考ohos.media.common.sessioncore.AVSessionCallback.onCommand
getAVSessionAbility()获取启动用户界面的IntentAgent
getAVToken()获取应用连接到会话的令牌。此令牌用于创建媒体播放控制器
adjustAVPlaybackVolume(int direction, int flags)调节播放音量
setAVPlaybackVolume(int value, int flags)设置播放音量,要求支持绝对音量控制
getOptions()获取与此控制器连接的AVSession的附加数据
getFlags()获取AVSession的附加标识,标记在AVSession中的定义
getAVMetadata()获取媒体资源的元数据ohos.media.common.AVMetadata
getAVPlaybackInfo()获取播放信息
getSessionOwnerPackageName()获得AVSession实例的应用程序的包名称
getAVSessionInfo()获取会话的附加数据
getPlayControls()获取一个PlayControls实例,将用于控制播放,比如控制媒体播放、停止、下一首等
④ AVSession 的主要接口
接口名描述
AVSession(Context context, String tag)构造AVSession实例,用于控制媒体播放
AVSession(Context context, String tag, PacMap sessionInfo)构造带有附加会话信息的AVSession实例,用于控制媒体播放
setAVSessionCallback(AVSessionCallback callback)设置回调函数来控制播放器,控制逻辑由应用实现。如果callback为null则取消控制
setAVSessionAbility(IntentAgent ia)给AVSession设置一个IntentAgent,用来启动用户界面
setAVButtonReceiver(IntentAgent ia)为媒体按键接收器设置一个IntentAgent,以便应用结束后,可以通过媒体按键重新拉起应用
enableAVSessionActive(boolean active)设置是否激活媒体会话。当会话准备接收命令时,将输入参数设置为true。如果会话停止接收命令,则设置为false
isAVSessionActive()查询会话是否激活
sendAVSessionEvent(String event, PacMap options)向所有订阅此会话的控制器发送事件
release()释放资源,应用播放完之后需调用
getAVToken()获取应用连接到会话的令牌。此令牌用于创建媒体播放控制器
getAVController()获取会话构造时创建的控制器,方便应用使用
setAVPlaybackState(AVPlaybackState state)设置当前播放状态
setAVMetadata(AVMetadata avMetadata)设置媒体资源元数据ohos.media.common.AVMetadata
setAVQueue(List queue)设置播放队列
setAVQueueTitle(CharSequence queueTitle)设置播放队列的标题,UI会显示此标题
setOptions(PacMap options)设置此会话关联的附加数据
getCurrentControllerInfo()获取发送当前请求的媒体控制器信息
⑤ AVElement 的主要接口
接口名描述
AVElement(AVDescription description, int flags)构造AVElement实例
getFlags()获取flags的值
isScannable()判断媒体是否可扫描,如:媒体有子节点,则可继续扫描获取子节点内容
isPlayable()检查媒体是否可播放
getAVDescription()获取媒体的详细信息
getMediaId()获取媒体的id

四、使用流程

  • 使用 AVSession 媒体框架创建一个播放器示例,分为创建客户端和创建服务端。
① 创建客户端
  • 在客户端 AVClientAbility 中声明 avBrowser 和 avController,通过 avBrowser 并向服务端发送连接请求,然后将 avController 注册到 ability:
	public class AVClientAbility extends Ability {
	    // 媒体浏览器
	    private AVBrowser avBrowser;
	    // 媒体控制器
	    private AVController avController;
	    // 服务端回传的媒体列表
	    List<AVElement> avElements;
	    @Override
	    public void onStart(Intent intent) {
	        super.onStart(intent);
	        // 用于指向媒体浏览器服务的包路径和类名
	        ElementName elementName = new ElementName("", "com.samples.audioplayer", "com.samples.audioplayer.AVService");
	        // connectionCallback在调用avBrowser.connect方法后进行回调。
	        avBrowser = new AVBrowser(context, elementName, connectionCallback, null);
	        // avBrowser发送对媒体浏览器服务的连接请求,connect方法需要确保当前处于断开连接状态。
	        avBrowser.connect();
	        // 将媒体控制器注册到ability以接收按键事件。
	        AVController.setControllerForAbility(this, avController);
	    }
	}
  • AVConnectionCallback 回调接口中的方法为可选实现,通常需要会在 onConnected 中订阅媒体数据和创建媒体控制器 AVController:
	// 发起连接(avBrowser.connect)后的回调方法实现
	private AVConnectionCallback connectionCallback = new AVConnectionCallback() {
	    @Override
	    public void onConnected() {
	        // 成功连接媒体浏览器服务时回调该方法,否则回调onConnectionFailed()。
	        // 重复订阅会报错,所以先解除订阅。
	        avBrowser.unsubscribeByParentMediaId(avBrowser.getRootMediaId());
	        // 第二个参数AVSubscriptionCallback,用于处理订阅信息的回调。
	        avBrowser.subscribeByParentMediaId(avBrowser.getRootMediaId(), avSubscriptionCallback);
	        AVToken token = avBrowser.getAVToken();
	        avController = new AVController(AVClient.this, token); // AVController第一个参数为当前类的context
	        // 参数AVControllerCallback,用于处理服务端播放状态及信息变化时回调。
	        avController.setAVControllerCallback(avControllerCallback);
	        // ...
	    }
	    // 其它回调方法(可选)
	    // ...
	};
  • 通常在订阅成功时,在 AVSubscriptionCallback 回调接口 onAVElementListLoaded 中保存服务端回传的媒体列表:
	// 发起订阅信息(avBrowser.subscribeByParentMediaId)后的回调方法实现
	private AVSubscriptionCallback avSubscriptionCallback = new AVSubscriptionCallback() {
	    @Override
	    public void onAVElementListLoaded(String parentId, List<AVElement> children) {
	        // 订阅成功时回调该方法,parentID为标识,children为服务端回传的媒体列表
	        super.onAVElementListLoaded(parentId, children);
	        avElements.addAll(children);
	        // ...
	    }
	};
  • AVControllerCallback 回调接口中的方法均为可选方法,主要用于服务端播放状态及信息的变化后对客户端的回调,客户端可在这些方法中实现 UI 的刷新:
	// 服务对客户端的媒体数据或播放状态变更后的回调 
	private AVControllerCallback avControllerCallback = new AVControllerCallback() {
	    @Override
	    public void onAVMetadataChanged(AVMetadata metadata) {
	        // 当服务端调用avSession.setAVMetadata(avMetadata)时,此方法会被回调。
	        super.onAVMetadataChanged(metadata);
	        AVDescription description = metadata.getAVDescription();
	        String title = description.getTitle().toString();
	        PixelMap pixelMap = description.getIcon();
	        // ...
	    }
	    @Override
	    public void onAVPlaybackStateChanged(AVPlaybackState playbackState) {
	        // 当服务端调用avSession.setAVPlaybackState(...)时,此方法会被回调。
	        super.onAVPlaybackStateChanged(playbackState);
	        long position = playbackState.getCurrentPosition();
	        // ...
	    }
	    // 其它回调方法(可选)
	    // ...
	};
  • 完成以上实现后,则应用可以在 UI 事件中调用 avController 的方法向服务端发送播放控制指令:
	// 在UI播放与暂停按钮的点击事件中向服务端发送播放或暂停指令
	public void toPlayOrPause() {
	    switch (avController.getAVPlaybackState().getAVPlaybackState()) {
	        case AVPlaybackState.PLAYBACK_STATE_NONE: {
	            avController.getPlayControls().prepareToPlay();
	            avController.getPlayControls().play();
	            break;
	        }
	        case AVPlaybackState.PLAYBACK_STATE_PLAYING: {
	            avController.getPlayControls().pause();
	            break;
	        }
	        case AVPlaybackState.PLAYBACK_STATE_PAUSED: {
	            avController.getPlayControls().play();
	            break;
	        }
	        default: {
	            // ...
	        }
	    }
	}
  • 其它播放控制根据业务是否需要实现,比如:
	avController.getPlayControls().playNext();
	avController.getPlayControls().playPrevious();
	avController.getPlayControls().playFastForward();
	avController.getPlayControls().rewind();
	avController.getPlayControls().seekTo(1000);
	avController.getPlayControls().stop();
	// ...
  • 也可以主动获取媒体信息、播放状态等数据:
	AVMetadata avMetadata = avController.getAVMetadata();
	AVPlaybackState avPlaybackState = avController.getAVPlaybackState();
	// ...
② 创建服务端
  • 在服务端 AVService 中声明 AVSession 和 Player:
	public class AVService extends AVBrowserService {
	    // 根媒体ID
	    private static final String AV_ROOT_ID = "av_root_id";
	    // 媒体会话
	    private AVSession avSession;
	    // 媒体播放器
	    private Player player;
	
	    @Override
	    public void onStart(Intent intent) {
	        super.onStart(intent);
	        avSession = new AVSession(this, "AVService");
	        setAVToken(avSession.getAVToken());
	        // 设置sessioncallback,用于响应客户端的媒体控制器发起的播放控制指令。
	        avSession.setAVSessionCallback(avSessionCallback);
	        // 设置播放状态初始状态为AVPlaybackState.PLAYBACK_STATE_NONE。
	        AVPlaybackState playbackState = new AVPlaybackState.Builder().setAVPlaybackState(AVPlaybackState.PLAYBACK_STATE_NONE, 0, 1.0f).build();
	        avSession.setAVPlaybackState(playbackState);
	        // 完成播放器的初始化,如果使用多个Player,也可以在执行播放时初始化。
	        player = new Player(this);
	    }
	    @Override
	    public AVBrowserRoot onGetRoot(String clientPackageName, int clientUid, PacMap rootHints) {
	        // 响应客户端avBrowser.connect()方法。若同意连接,则返回有效的AVBrowserRoot实例,否则返回null
	        return new AVBrowserRoot(AV_ROOT_ID, null);
	    }
	    @Override
	    public void onLoadAVElementList(String parentId, AVBrowserResult result) {
	         HiLog.info(TAG, "onLoadChildren");
	         // 响应客户端avBrowser.subscribeByParentMediaId(...)方法。
	         // 先执行该方法detachForRetrieveAsync() 
	         result.detachForRetrieveAsync();
	         // externalAudioItems缓存媒体文件,请开发者自行实现。
	         result.sendAVElementList(externalAudioItems.getAudioItems());
	    }
	    @Override
	    public void onLoadAVElementList(String s, AVBrowserResult avBrowserResult, PacMap pacMap) {
	         // 响应客户端avBrowser.subscribeByParentMediaId(String, PacMap, AVSubscriptionCallback)方法。
	    }
	    @Override
	    public void onLoadAVElement(String s, AVBrowserResult avBrowserResult) {
	        // 响应客户端avBrowser.getAVElement(String, AVElementCallback)方法。
	    }
	}
  • 响应客户端的媒体控制器发起的播放控制指令的回调实现:
	private AVSessionCallback avSessionCallback = new AVSessionCallback() {
	    @Override
	    public void onPlay() {
	        super.onPlay();
	        // 当客户端调用avController.getPlayControls().play()时,该方法会被回调。
	        // 响应播放请求,开始播放。
	        if (avSession.getAVController().getAVPlaybackState() == AVPlaybackState.PLAYBACK_STATE_PAUSED) {
	            if (player.play()) {
	                AVPlaybackState playbackState = new AVPlaybackState.Builder().setAVPlaybackState(
	                    AVPlaybackState.PLAYBACK_STATE_PLAYING, player.getCurrentTime(),
	                    player.getPlaybackSpeed()).build();
	                avSession.setAVPlaybackState(playbackState);
	            }
	        }
	    }
	    @Override
	    public void onPause() {
	        super.onPause();
	        // 当客户端调用avController.getPlayControls().pause()时,该方法会被回调。
	        // 响应暂停请求,暂停播放。
	    }
	    @Override
	    public void onPlayNext() {
	        super.onPlayNext();
	        // 当客户端调用avController.getPlayControls().playNext()时,该方法会被回调。
	        // 响应播放下一曲请求,通过avSession.setAVMetadata设置下一曲曲目的信息。
	        avSession.setAVMetadata(avNextMetadata);
	    }
	    // 重写以处理按键事件
	    @Override
	    public boolean onMediaButtonEvent(Intent mediaButtonIntent) {
	        KeyEvent ke = mediaButtonIntent.getSequenceableParam(AVSession.PARAM_KEY_EVENT);
	        if (ke == null) {
	            HiLog.error(TAG, "getSequenceableParam failed");
	            return false;
	        }
	        if (ke.isKeyDown()) {
	            // 只处理按键抬起事件
	            return true;
	        }
	
	        switch (ke.getKeyCode()) {
	            case KeyEvent.KEY_MEDIA_PLAY_PAUSE: {
	                if (playbackState.getAVPlaybackState() == AVPlaybackState.PLAYBACK_STATE_PAUSED) {
	                    onPlay();
	                    break;
	                }
	                if (playbackState.getAVPlaybackState() == AVPlaybackState.PLAYBACK_STATE_PLAYING) {
	                    onPause();
	                    break;
	                }
	                break;
	            }
	            case KeyEvent.KEY_MEDIA_PLAY: {
	                onPlay();
	                break;
	            }
	            case KeyEvent.KEY_MEDIA_PAUSE: {
	                onPause();
	                break;
	            }
	            case KeyEvent.KEY_MEDIA_STOP: {
	                onStop();
	                break;
	            }
	            case KeyEvent.KEY_MEDIA_NEXT: {
	                onPlayNext();
	                break;
	            }
	            case KeyEvent.KEY_MEDIA_PREVIOUS: {
	                onPlayPrevious();
	                break;
	            }
	            default: {
	                break;
	            }
	        }
	        return true;
	    }
	    // 其它回调方法(可选)
	    // ...
	}

以上是关于HarmonyOS之深入解析媒体会话的管理的主要内容,如果未能解决你的问题,请参考以下文章

HarmonyOS之深入解析视频的功能和使用

HarmonyOS之深入解析通知的使用

HarmonyOS之深入解析线程管理

HarmonyOS之深入解析编译构建的配置和代码混淆

HarmonyOS之深入解析音频的功能和使用

HarmonyOS之深入解析Ability的功能和使用