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

Posted 2021-07-31 Forever_wj

一、简介

• 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;
	    }
	    // 其它回调方法（可选）
	    // ...
	}