Skip to content
体验新版
项目
组织
正在加载...
登录
切换导航
打开侧边栏
OpenHarmony
Docs
提交
aebb8f20
D
Docs
项目概览
OpenHarmony
/
Docs
大约 1 年 前同步成功
通知
159
Star
292
Fork
28
代码
文件
提交
分支
Tags
贡献者
分支图
Diff
Issue
0
列表
看板
标记
里程碑
合并请求
0
Wiki
0
Wiki
分析
仓库
DevOps
项目成员
Pages
D
Docs
项目概览
项目概览
详情
发布
仓库
仓库
文件
提交
分支
标签
贡献者
分支图
比较
Issue
0
Issue
0
列表
看板
标记
里程碑
合并请求
0
合并请求
0
Pages
分析
分析
仓库分析
DevOps
Wiki
0
Wiki
成员
成员
收起侧边栏
关闭侧边栏
动态
分支图
创建新Issue
提交
Issue看板
体验新版 GitCode,发现更多精彩内容 >>
提交
aebb8f20
编写于
10月 25, 2022
作者:
L
leiiyb
浏览文件
操作
浏览文件
下载
电子邮件补丁
差异文件
add errorcode-avsession.md
Signed-off-by:
N
leiiyb
<
leiyanbo@huawei.com
>
上级
ab0844ff
变更
5
隐藏空白更改
内联
并排
Showing
5 changed file
with
3934 addition
and
0 deletion
+3934
-0
zh-cn/application-dev/media/avsession-guidelines.md
zh-cn/application-dev/media/avsession-guidelines.md
+635
-0
zh-cn/application-dev/media/avsession-overview.md
zh-cn/application-dev/media/avsession-overview.md
+52
-0
zh-cn/application-dev/media/figures/zh-cn_image_avsession.png
...n/application-dev/media/figures/zh-cn_image_avsession.png
+0
-0
zh-cn/application-dev/reference/apis/js-apis-avsession.md
zh-cn/application-dev/reference/apis/js-apis-avsession.md
+3116
-0
zh-cn/application-dev/reference/errorcodes/errorcode-avsession.md
...plication-dev/reference/errorcodes/errorcode-avsession.md
+131
-0
未找到文件。
zh-cn/application-dev/media/avsession-guidelines.md
0 → 100644
浏览文件 @
aebb8f20
# AVSession开发指导
## 会话接入端开发指导
### 基本概念
-
会话元数据
`'AVMetadata'`
: 媒体数据相关属性,包含标识当前媒体的ID(assetId),上一首媒体的ID(previousAssetId),下一首媒体的ID(nextAssetId),标题(title),专辑作者(author),专辑名称(album),词作者(writer),媒体时长(duration)等属性。
-
会话描述符
`'AVSessionDescriptor'`
: 描述媒体会话的相关信息。包含标识会话的ID(sessionId),会话的类型type(音频Audio/视频Video),会话自定义名称(sessionTag),会话所属应用的信息(elementName)等。
-
媒体播放状态
`'AVPlaybackState'`
:用于描述媒体播放状态的相关属性。包含当前媒体的播放状态(state)、位置(position)、速度(speed)、缓冲时间(bufferedTime)、循环模式(loopMode)、是否收藏(isFavorite)等属性。
### 接口说明
会话接入端常用接口如下表所示。接口返回值有两种返回形式:callback和promise,下表中为callback形式接口,promise和callback只是返回值方式不一样,功能相同。更多API说明请参见
[
API文档
](
../reference/apis/js-apis-avsession.md
)
。
表1:会话接入端常用接口
| 接口名 | 描述 |
|----------------------------------------------------------------------------------|-------------|
| createAVSession(context: Context, tag: string, type: AVSessionType, callback: AsyncCallback<AVSession
\>
): void | 创建会话 |
| setAVMetadata(data: AVMetadata, callback: AsyncCallback<void
\>
): void | 设置会话元数据 |
| setAVPlaybackState(state: AVPlaybackState, callback: AsyncCallback<void
\>
): void | 设置会话播放状态信息 |
| setLaunchAbility(ability: WantAgent, callback: AsyncCallback<void
\>
): void | 设置启动ability |
| getController(callback: AsyncCallback<AVSessionController
\>
): void | 获取当前会话自身控制器 |
| getOutputDevice(callback: AsyncCallback<OutputDeviceInfo
\>
): void | 获取音频输出设备信息 |
| activate(callback: AsyncCallback<void
\>
): void | 激活会话 |
| destroy(callback: AsyncCallback<void
\>
): void | 销毁会话 |
### 开发步骤
1.
导入模块接口
```
js
import
avSession
from
'
@ohos.multimedia.avsession
'
;
import
wantAgent
from
'
@ohos.wantAgent
'
;
import
featureAbility
from
'
@ohos.ability.featureAbility
'
;
```
2.
创建会话并激活会话
```
js
// 全局变量定义
let
mediaFavorite
=
false
;
let
currentSession
=
null
;
let
context
=
featureAbility
.
getContext
();
// 创建音频类型会话
avSession
.
createAVSession
(
context
,
"
AudioAppSample
"
,
'
audio
'
).
then
((
session
)
=>
{
currentSession
=
session
;
currentSession
.
activate
();
// 激活会话
}).
catch
((
err
)
=>
{
console
.
info
(
`createAVSession : ERROR :
${
err
.
message
}
`
);
});
```
3.
设置AVSession会话信息,包括:
-
设置会话元数据,除了媒体ID必选外,可选设置媒体标题、专辑信息、媒体作者、媒体时长、上一首/下一首媒体ID等。详细的会话元数据信息可参考API文档中的
`AVMetadata`
。
-
设置启动Ability,通过
`WantAgent`
的接口实现。WantAgent一般用于封装行为意图信息,如果想要了解更多信息,可以查阅
[
WantAgent开发指导
](
../reference/apis/js-apis-wantAgent.md
)
。
-
设置播放状态。
```
js
// 设置会话元数据
let
metadata
=
{
assetId
:
"
121278
"
,
title
:
"
lose yourself
"
,
artist
:
"
Eminem
"
,
author
:
"
ST
"
,
album
:
"
Slim shady
"
,
writer
:
"
ST
"
,
composer
:
"
ST
"
,
duration
:
2222
,
mediaImage
:
"
https://www.example.com/example.jpg
"
,
// 请开发者根据实际情况使用
subtitle
:
"
8 Mile
"
,
description
:
"
Rap
"
,
lyric
:
"
https://www.example.com/example.lrc
"
,
// 请开发者根据实际情况使用
previousAssetId
:
"
121277
"
,
nextAssetId
:
"
121279
"
,
};
currentSession
.
setAVMetadata
(
metadata
).
then
(()
=>
{
console
.
info
(
'
setAVMetadata successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`setAVMetadata : ERROR :
${
err
.
message
}
`
);
});
```
```
js
// 设置启动ability
let
wantAgentInfo
=
{
wants
:
[
{
bundleName
:
"
com.neu.setResultOnAbilityResultTest1
"
,
abilityName
:
"
com.example.test.MainAbility
"
,
}
],
operationType
:
wantAgent
.
OperationType
.
START_ABILITIES
,
requestCode
:
0
,
wantAgentFlags
:[
wantAgent
.
WantAgentFlags
.
UPDATE_PRESENT_FLAG
]
}
wantAgent
.
getWantAgent
(
wantAgentInfo
).
then
((
agent
)
=>
{
currentSession
.
setLaunchAbility
(
agent
).
then
(()
=>
{
console
.
info
(
'
setLaunchAbility successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`setLaunchAbility : ERROR :
${
err
.
message
}
`
);
});
});
```
```
js
// 设置播放状态
let
PlaybackState
=
{
state
:
avSession
.
PlaybackState
.
PLAYBACK_STATE_STOP
,
speed
:
1.0
,
position
:{
elapsedTime
:
0
,
updateTime
:
(
new
Date
()).
getTime
()},
bufferedTime
:
1000
,
loopMode
:
avSession
.
LoopMode
.
LOOP_MODE_SEQUENCE
,
isFavorite
:
false
,
};
currentSession
.
setAVPlaybackState
(
PlaybackState
).
then
(()
=>
{
console
.
info
(
'
setAVPlaybackState successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`setAVPlaybackState : ERROR :
${
err
.
message
}
`
);
});
```
```
js
// 获取当前session会话对象自身的控制器
currentSession
.
getController
().
then
((
selfController
)
=>
{
console
.
info
(
'
getController successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`getController : ERROR :
${
err
.
message
}
`
);
});
```
```
js
// 获取音频输出设备信息
currentSession
.
getOutputDevice
().
then
((
outputInfo
)
=>
{
console
.
info
(
`getOutputDevice successfully, deviceName :
${
outputInfo
.
deviceName
}
`
);
}).
catch
((
err
)
=>
{
console
.
info
(
`getOutputDevice : ERROR :
${
err
.
message
}
`
);
});
```
4.
注册控制命令监听
```
js
// 注册播放命令监听
currentSession
.
on
(
'
play
'
,
()
=>
{
console
.
log
(
"
调用AudioPlayer.play方法
"
);
// 设置播放状态
currentSession
.
setAVPlaybackState
({
state
:
avSession
.
PlaybackState
.
PLAYBACK_STATE_PLAY
}).
then
(()
=>
{
console
.
info
(
'
setAVPlaybackState successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`setAVPlaybackState : ERROR :
${
err
.
message
}
`
);
});
});
// 注册暂停命令监听
currentSession
.
on
(
'
pause
'
,
()
=>
{
console
.
log
(
"
调用AudioPlayer.pause方法
"
);
// 设置播放状态
currentSession
.
setAVPlaybackState
({
state
:
avSession
.
PlaybackState
.
PLAYBACK_STATE_PAUSE
}).
then
(()
=>
{
console
.
info
(
'
setAVPlaybackState successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`setAVPlaybackState : ERROR :
${
err
.
message
}
`
);
});
});
// 注册停止命令监听
currentSession
.
on
(
'
stop
'
,
()
=>
{
console
.
log
(
"
调用AudioPlayer.stop方法
"
);
// 设置播放状态
currentSession
.
setAVPlaybackState
({
state
:
avSession
.
PlaybackState
.
PLAYBACK_STATE_STOP
}).
then
(()
=>
{
console
.
info
(
'
setAVPlaybackState successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`setAVPlaybackState : ERROR :
${
err
.
message
}
`
);
});
});
// 注册下一首命令监听
currentSession
.
on
(
'
playNext
'
,
()
=>
{
// 如果媒体文件未准备好,则下载并缓存媒体文件,设置准备状态
currentSession
.
setAVPlaybackState
({
state
:
avSession
.
PlaybackState
.
PLAYBACK_STATE_PREPARE
}).
then
(()
=>
{
console
.
info
(
'
setAVPlaybackState successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`setAVPlaybackState : ERROR :
${
err
.
message
}
`
);
});
// 成功获取媒体文件
currentSession
.
setAVMetadata
({
assetId
:
'
58970105
'
,
title
:
'
不如我们明天见
'
}).
then
(()
=>
{
console
.
info
(
'
setAVMetadata successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`setAVMetadata : ERROR :
${
err
.
message
}
`
);
});
console
.
log
(
"
调用AudioPlayer.play方法
"
);
// 设置播放状态
let
time
=
(
new
Data
()).
getTime
();
currentSession
.
setAVPlaybackState
({
state
:
avSession
.
PlaybackState
.
PLAYBACK_STATE_PLAY
,
position
:
{
elapsedTime
:
0
,
updateTime
:
time
},
bufferedTime
:
2000
}).
then
(()
=>
{
console
.
info
(
'
setAVPlaybackState successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`setAVPlaybackState : ERROR :
${
err
.
message
}
`
);
});
});
// 注册播放快进命令监听
currentSession
.
on
(
'
fastForward
'
,
()
=>
{
console
.
log
(
"
调用AudioPlayer的倍速播放
"
);
// 设置播放状态
currentSession
.
setAVPlaybackState
({
speed
:
2.0
}).
then
(()
=>
{
console
.
info
(
'
setAVPlaybackState successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`setAVPlaybackState : ERROR :
${
err
.
message
}
`
);
});
});
// 注册跳播命令监听
currentSession
.
on
(
'
seek
'
,
(
time
)
=>
{
console
.
log
(
"
调用AudioPlayer的seek方法
"
);
// 设置播放状态
currentSession
.
setAVPlaybackState
({
position
:
{
elapsedTime
:
time
,
updateTime
:
(
new
Data
()).
getTime
()}}).
then
(()
=>
{
console
.
info
(
'
setAVPlaybackState successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`setAVPlaybackState : ERROR :
${
err
.
message
}
`
);
});
});
// 注册设置播放速度命令监听
currentSession
.
on
(
'
setSpeed
'
,
(
speed
)
=>
{
console
.
log
(
`调用AudioPlayer的倍速播放
${
speed
}
`
);
// 设置播放状态
currentSession
.
setAVPlaybackState
({
speed
:
speed
}).
then
(()
=>
{
console
.
info
(
'
setAVPlaybackState successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`setAVPlaybackState : ERROR :
${
err
.
message
}
`
);
});
});
// 注册设置播放循环模式命令监听
currentSession
.
on
(
'
setLoopMode
'
,
(
mode
)
=>
{
console
.
log
(
`应用自身切换循环模式
${
mode
}
`
);
// 设置播放状态
currentSession
.
setAVPlaybackState
({
loopMode
:
mode
}).
then
(()
=>
{
console
.
info
(
'
setAVPlaybackState successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`setAVPlaybackState : ERROR :
${
err
.
message
}
`
);
});
});
// 注册设置歌曲收藏命令监听
currentSession
.
on
(
'
toggleFavorite
'
,
(
assetId
)
=>
{
console
.
log
(
`应用保存当前assetId为喜爱
${
assetId
}
`
);
// 根据上一次的状态进行切换
let
favorite
=
mediaFavorite
==
false
?
true
:
false
;
currentSession
.
setAVPlaybackState
({
isFavorite
:
favorite
}).
then
(()
=>
{
console
.
info
(
'
setAVPlaybackState successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`setAVPlaybackState : ERROR :
${
err
.
message
}
`
);
});
mediaFavorite
=
favorite
;
});
// 注册媒体按键命令监听
currentSession
.
on
(
'
handleKeyEvent
'
,
(
event
)
=>
{
console
.
log
(
`用户按键
${
event
.
keyCode
}
`
);
});
// 注册播放设备变化命令监听
currentSession
.
on
(
'
outputDeviceChange
'
,
(
device
)
=>
{
console
.
log
(
`输出设备变更,更新显示
${
device
.
deviceName
}
`
);
});
```
5.
释放资源
```
js
// 取消注册回调
currentSession
.
off
(
'
play
'
);
currentSession
.
off
(
'
pause
'
);
currentSession
.
off
(
'
stop
'
);
currentSession
.
off
(
'
playNext
'
);
currentSession
.
off
(
'
playPrevious
'
);
currentSession
.
off
(
'
fastForward
'
);
currentSession
.
off
(
'
rewind
'
);
currentSession
.
off
(
'
seek
'
);
currentSession
.
off
(
'
setSpeed
'
);
currentSession
.
off
(
'
setLoopMode
'
);
currentSession
.
off
(
'
toggleFavorite
'
);
currentSession
.
off
(
'
handleKeyEvent
'
);
currentSession
.
off
(
'
outputDeviceChange
'
);
// 去激活session并销毁对象
currentSession
.
deactivate
().
then
(()
=>
{
currentSession
.
destory
();
});
```
### 调测验证
在媒体应用上点击播放、暂停、下一首等按键,媒体播放状态出现相应变化。
### 常见问题
1.
会话服务端异常
-
现象描述:
会话服务端异常,应用端无法获取服务端的消息响应。如会话服务未运行或者会话服务通信失败。返回错误信息: Session service exception。
-
可能原因:
会话重启过程中服务被杀。
-
解决办法
(1)定时重试,超过3s仍失败时,停止对该会话或者控制器进行操作。
(2)销毁当前会话或者会话控制器,并重新创建,如果重新创建失败,则停止会话相关操作。
2.
会话不存在
-
现象描述:
会话对象不存在时,向该会话设置参数或者发送命令。返回错误信息: The session does not exist。
-
可能原因:
会话已被销毁,服务端无会话记录。
-
解决办法
(1)如果在会话被控端产生该错误,请重新创建会话;如果是会话控制端,请停止向该会话发送查询或者控制命令。
(2)如果在会话管理端产生该错误,请重新查询系统当前会话记录,在创建控制器时传入正确的会话ID。
3.
会话未激活
-
现象描述:
会话没有激活时,向会话发送控制命令或者事件。。返回错误信息: The session not active。
-
可能原因:
会话处于未激活状态。
-
解决办法
停止发送该命令或事件,监听会话的激活状态,会话激活后恢复发送该命令或事件。
### 相关实例
提供
[
音乐Demo
](
https://gitee.com/openharmony/multimedia_av_session/blob/master/test/resource/player_index_js.md
)
的代码实例
## 会话控制端开发指导(播控中心)
### 基本概念
-
远端投播:将本地媒体投播到远端设备,通过本地控制器发送命令,可控制远端播放行为。
-
发送按键命令:控制器通过发送按键事件的方式控制媒体。
-
发送控制命令:控制器通过发送控制命令的方式控制媒体。
-
发送系统按键命令:应用拥有调用该接口的系统权限,通过发送按键事件的方式控制媒体,仅系统应用可用。
-
发送系统控制命令:应用拥有调用该接口的系统权限,通过发送控制命令的方式控制媒体,仅系统应用可用。
### 接口说明
会话控制端涉及的常用接口如下表所示。接口返回值有两种返回形式:callback和promise,下表中为callback形式接口,promise和callback只是返回值方式不一样,功能相同。更多API说明请参见
[
API文档
](
../reference/apis/js-apis-avsession.md
)
。
表2:会话控制端常用接口
| 接口名 | 描述 |
| ------------------------------------------------------------------------------------------------ | ----------------- |
| getAllSessionDescriptors(callback: AsyncCallback
<Array
<
Readonly
<
AVSessionDescriptor
>
>>): void | 获取所有会话的描述符 |
| createController(sessionId: string, callback: AsyncCallback
<AVSessionController>
): void | 创建控制器 |
| sendAVKeyEvent(event: KeyEvent, callback: AsyncCallback<void
\>
): void | 发送按键命令 |
| getLaunchAbility(callback: AsyncCallback<WantAgent
\>
): void | 拉起应用 |
| sendControlCommand(command: AVControlCommand, callback: AsyncCallback<void
\>
): void | 发送控制命令 |
| sendSystemAVKeyEvent(event: KeyEvent, callback: AsyncCallback
<void>
): void | 发送系统按键命令 |
| sendSystemControlCommand(command: AVControlCommand, callback: AsyncCallback
<void>
): void | 发送系统控制命令 |
| castAudio(session: SessionToken | 'all', audioDevices: Array
<audio.AudioDeviceDescriptor>
, callback: AsyncCallback
<void>
): void | 远端投播 |
### 开发步骤
1.
导入模块接口
```
js
import
avSession
from
'
@ohos.multimedia.avsession
'
;
import
{
Action
,
KeyEvent
}
from
'
@ohos.multimodalInput.KeyEvent
'
;
import
wantAgent
from
'
@ohos.wantAgent
'
;
import
audio
from
'
@ohos.multimedia.audio
'
;
```
2.
获取会话描述符,创建控制器
```
js
// 全局变量定义
let
g_controller
=
new
Array
<
avSession
.
AVSessionController
>
();
let
g_centerSupportCmd
:
Set
<
avSession
.
AVControlCommandType
>
=
new
Set
([
'
play
'
,
'
pause
'
,
'
playNext
'
,
'
playPrevious
'
,
'
fastForward
'
,
'
rewind
'
,
'
seek
'
,
'
setSpeed
'
,
'
setLoopMode
'
,
'
toggleFavorite
'
]);
let
g_validCmd
:
Set
<
avSession
.
AVControlCommandType
>
;
// 获取会话描述符,创建控制器
avSession
.
getAllSessionDescriptors
().
then
((
descriptors
)
=>
{
descriptors
.
forEach
((
descriptor
)
=>
{
avSession
.
createController
(
descriptor
.
sessionId
).
then
((
controller
)
=>
{
g_controller
.
push
(
controller
);
}).
catch
((
err
)
=>
{
console
.
error
(
'
createController error
'
);
});
});
}).
catch
((
err
)
=>
{
console
.
error
(
'
getAllSessionDescriptors error
'
);
});
// 注册会话创建监听,创建控制器
avSession
.
on
(
'
sessionCreate
'
,
(
session
)
=>
{
// 新增会话,需要创建控制器
avSession
.
createController
(
session
.
sessionId
).
then
((
controller
)
=>
{
g_controller
.
push
(
controller
);
}).
catch
((
err
)
=>
{
console
.
info
(
`createController : ERROR :
${
err
.
message
}
`
);
});
});
```
3.
监听AVSession会话状态以及AVSession服务变化
```
js
// 注册会话激活状态变更监听
controller
.
on
(
'
activeStateChange
'
,
(
isActive
)
=>
{
if
(
isActive
)
{
console
.
log
(
"
控制器卡片按键高亮
"
);
}
else
{
console
.
log
(
"
控制器卡片按键变更为无效
"
);
}
});
// 注册会话销毁监听
controller
.
on
(
'
sessionDestroy
'
,
()
=>
{
console
.
info
(
'
on sessionDestroy : SUCCESS
'
);
controller
.
destroy
().
then
(()
=>
{
console
.
info
(
'
destroy : SUCCESS
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`destroy : ERROR :
${
err
.
message
}
`
);
});
});
// 注册系统会话销毁监听
avSession
.
on
(
'
sessionDestroy
'
,
(
session
)
=>
{
let
index
=
g_controller
.
findIndex
((
controller
)
=>
{
return
controller
.
sessionId
==
session
.
sessionId
;
});
if
(
index
!=
0
)
{
g_controller
[
index
].
destroy
();
g_controller
.
splice
(
index
,
1
);
}
});
// 注册系统最高优先级会话变更监听
avSession
.
on
(
'
topSessionChange
'
,
(
session
)
=>
{
let
index
=
g_controller
.
findIndex
((
controller
)
=>
{
return
controller
.
sessionId
==
session
.
sessionId
;
});
// 将该会话显示排到第一个
if
(
index
!=
0
)
{
g_controller
.
sort
((
a
,
b
)
=>
{
return
a
.
sessionId
==
session
.
sessionId
?
-
1
:
0
;
});
}
});
// 注册服务异常监听
avSession
.
on
(
'
sessionServiceDie
'
,
()
=>
{
// 服务端异常,应用清理资源
console
.
log
(
"
服务端异常
"
);
})
```
4.
监听AVSession会话信息变化
```
js
// 注册元数据更新监听
let
metaFilter
=
[
'
assetId
'
,
'
title
'
,
'
description
'
];
controller
.
on
(
'
metadataChange
'
,
metaFilter
,
(
metadata
)
=>
{
console
.
info
(
`on metadataChange assetId :
${
metadata
.
assetId
}
`
);
});
// 注册播放状态更新监听
let
playbackFilter
=
[
'
state
'
,
'
speed
'
,
'
loopMode
'
];
controller
.
on
(
'
playbackStateChange
'
,
playbackFilter
,
(
playbackState
)
=>
{
console
.
info
(
`on playbackStateChange state :
${
playbackState
.
state
}
`
);
});
// 注册会话支持的命令变更监听
controller
.
on
(
'
validCommandChange
'
,
(
cmds
)
=>
{
console
.
info
(
`validCommandChange : SUCCESS : size :
${
cmds
.
size
}
`
);
console
.
info
(
`validCommandChange : SUCCESS : cmds :
${
cmds
.
values
()}
`
);
g_validCmd
.
clear
();
for
(
let
c
of
g_centerSupportCmd
)
{
if
(
cmds
.
has
(
c
))
{
g_validCmd
.
add
(
c
);
}
}
});
// 注册输出设备变更监听
controller
.
on
(
'
outputDeviceChange
'
,
(
device
)
=>
{
console
.
info
(
`on outputDeviceChange device isRemote :
${
device
.
isRemote
}
`
);
});
```
5.
控制AVSession会话行为
```
js
// 用户点击播放按键:发送控制命令--播放
if
(
g_validCmd
.
has
(
'
play
'
))
{
controller
.
sendControlCommand
({
command
:
'
play
'
}).
then
(()
=>
{
console
.
info
(
'
sendControlCommand successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`sendControlCommand : ERROR :
${
err
.
message
}
`
);
});
}
// 用户点击循环模式:发送控制命令--单曲循环
if
(
g_validCmd
.
has
(
'
setLoopMode
'
))
{
controller
.
sendControlCommand
({
command
:
'
setLoopMode
'
,
parameter
:
avSession
.
LoopMode
.
LOOP_MODE_SINGLE
}).
then
(()
=>
{
console
.
info
(
'
sendControlCommand successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`sendControlCommand : ERROR :
${
err
.
message
}
`
);
});
}
// 发送按键事件
let
keyItem
=
{
code
:
0x49
,
pressedTime
:
123456789
,
deviceId
:
0
};
let
event
=
{
action
:
2
,
key
:
keyItem
,
keys
:
[
keyItem
]};
controller
.
sendAVKeyEvent
(
event
).
then
(()
=>
{
console
.
info
(
'
sendAVKeyEvent Successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`sendAVKeyEvent : ERROR :
${
err
.
message
}
`
);
});
// 用户点击卡片空白位置拉起应用
controller
.
getLaunchAbility
().
then
((
want
)
=>
{
console
.
log
(
"
前台拉起应用
"
);
}).
catch
((
err
)
=>
{
console
.
info
(
`getLaunchAbility : ERROR :
${
err
.
message
}
`
);
});
// 发送系统媒体按键事件
let
keyItem
=
{
code
:
0x49
,
pressedTime
:
123456789
,
deviceId
:
0
};
let
event
=
{
action
:
2
,
key
:
keyItem
,
keys
:
[
keyItem
]};
avSession
.
sendSystemAVKeyEvent
(
event
).
then
(()
=>
{
console
.
info
(
'
sendSystemAVKeyEvent Successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`sendSystemAVKeyEvent : ERROR :
${
err
.
message
}
`
);
});
// 发送系统控制命令,系统会把控制命令发送到Top会话中
let
avcommand
=
{
command
:
'
toggleFavorite
'
,
parameter
:
"
false
"
};
avSession
.
sendSystemControlCommand
(
avcommand
).
then
(()
=>
{
console
.
info
(
'
sendSystemControlCommand successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`sendSystemControlCommand : ERROR :
${
err
.
message
}
`
);
});
// 投播到其他设备
let
audioManager
=
audio
.
getAudioManager
();
let
audioDevices
;
await
audioManager
.
getDevices
(
audio
.
DeviceFlag
.
OUTPUT_DEVICES_FLAG
).
then
((
data
)
=>
{
audioDevices
=
data
;
console
.
info
(
'
Promise returned to indicate that the device list is obtained.
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`getDevices : ERROR :
${
err
.
message
}
`
);
});
avSession
.
castAudio
(
'
all
'
,
audioDevices
).
then
(()
=>
{
console
.
info
(
'
createController : SUCCESS
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`createController : ERROR :
${
err
.
message
}
`
);
});
```
6.
释放资源
```
js
// 取消注册回调
controller
.
off
(
'
metadataChange
'
);
controller
.
off
(
'
playbackStateChange
'
);
controller
.
off
(
'
sessionDestroy
'
);
controller
.
off
(
'
activeStateChange
'
);
controller
.
off
(
'
validCommandChange
'
);
controller
.
off
(
'
outputDeviceChange
'
);
// 销毁controller对象
controller
.
destroy
().
then
(()
=>
{
console
.
info
(
'
destroy : SUCCESS
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`destroy : ERROR :
${
err
.
message
}
`
);
});
```
### 调测验证
在播控中心点击播放、暂停、下一首等按键,应用播放状态随即发生相应变化。
### 常见问题
1.
控制器不存在
-
现象描述:
会话控制器不存在时,向该控制器发送控制命令或者事件。返回错误信息: The session controller does not exist。
-
可能原因:
控制器已被销毁。
-
解决办法
请重新查询系统当前会话记录,并创建对应的会话控制器。
2.
远端会话连接失败
-
现象描述:
本端会话与远端会话通信失败。返回错误信息: The remote session connection failed。
-
可能原因:
设备间通信断开。
-
解决办法
停止对该会话发送控制命令,并监听输出设备变化,当输出设备发送变化后恢复发送。
3.
无效会话命令
-
现象描述:
会话被控端不支持该被控命令或事件。返回错误信息: Invalid session command。
-
可能原因:
被控端不支持该命令。
-
解决办法
停止发送该命令或事件,并查询被控会话支持的命令集,发送被控端支持的命令。
4.
消息过载
-
现象描述:
会话客户端在一段时间内向服务端发送了过多的消息或者命令,引起服务端消息过载。返回错误信息: Command or event overload。
-
可能原因:
服务端消息过载。
-
解决办法
检查自身命令发送是否过于频繁,控制自身查询和控制命令的发送频度。
### 相关实例
提供
[
播控中心Demo
](
https://gitee.com/openharmony/multimedia_av_session/blob/master/test/resource/controller_index_js.md
)
的代码实例
\ No newline at end of file
zh-cn/application-dev/media/avsession-overview.md
0 → 100644
浏览文件 @
aebb8f20
# AVSession开发概述
## 简介
AVSession(Audio & Video Session),音视频会话,即媒体会话。
-
对应用开发者而言,媒体会话提供了将应用内音视频接入系统播控中心的能力。
-
对系统开发者而言,媒体会话提供了对系统音视频应用的媒体信息进行展示和统一的媒体播放控制的能力。
通过AVSession,可以实现:
1.
统一播控入口,提升用户体验。
当设备上安装了多个音视频类应用时,用户需要切换、进入不同的应用来控制播放。通过接入AVSession,音视频应用可以通过系统的统一播控入口(如播控中心)来控制设备上的媒体播放,无需切换不同应用,提升使用体验。
2.
完善音视频后台管控。
当应用在后台自行启动音频播放时,用户难以快速定位对应的应用,造成体验问题。接入AVSession后,允许应用在后台进行音乐播放,便于用户在播控中心快速找到播放应用。
## 基本概念
-
媒体会话
用于应用和播控中心之间进行信息交换的通道。会话的一端连接被控的媒体应用,另一端连接媒体应用的控制端(如播控中心)。应用接入了媒体会话后,可以通过媒体会话将媒体播放信息传递给控制端,并能够接收到控制端发出的控制命令。
-
媒体会话控制器
媒体会话控制器的持有者可以控制接入了AVSession应用的播放行为。通过会话控制器,应用可以对三方应用进程的播放行为进行控制,支持获取三方应用的播放信息,发送播放控制命令,也支持监听三方应用的播放状态等的变化,确保媒体会话信息的同步。
-
播控中心
系统统一的媒体控制中心,会话控制器的持有者。通过控制器发送命令来控制媒体的播放、暂停等。
## 实现原理
该模块提供了
`AVSession`
会话类和
`AVSessionController`
控制器类。
**图1**
AVSession交互图
![
zh-ch_image_avsession
](
figures/zh-cn_image_avsession.png
)
-
应用与播控中心交互:首先,音频应用创建
`AVSession`
对象,并设置会话信息(包括媒体元数据、对应拉起的Ability、播放状态等)。然后,播控中心创建
`AVSessionController`
,可获取会话相关信息,向音频应用发送播放命令。最后,音频应用响应播控中心的命令并更新播放状态。
-
支持分布式投播:当组网内的设备创建本地会话之后,播控中心或者音频应用可以根据设备列表选择想要投播的其他设备,将本地会话同步到远端,生成远端会话,并支持远端控制。需要控制远端会话时,通过远端控制器将控制命令发送到远端会话控制中心。
## 约束和限制
-
播控中心展示的播放信息,依赖媒体应用主动将媒体信息写入到AVSession。
-
播控中心控制媒体应用播放,依赖于媒体应用侧对控制命令的响应。
-
AVSession只能够传递媒体播放信息和播放控制指令,不进行信息的展示和控制命令的执行。
-
普通应用不支持开发播控中心端。当普通音视频应用运行在OpenHarmony上时,默认控制端为系统应用播控中心,开发者无需做额外的操作。
-
播控中心为系统应用,当开发者需要基于OpenHarmony开发自己的系统时,可以开发本系统的播控中心应用。
-
为了解决音频在后台播放时用户无法获取到停止音频的入口,影响用户体验,AVSession服务增加了三方应用后台管控策略,只有三方应用接入了AVSession,才可以后台播放,否则当三方应用切后台时系统会强制暂停其音频播放。
zh-cn/application-dev/media/figures/zh-cn_image_avsession.png
0 → 100755
浏览文件 @
aebb8f20
47.9 KB
zh-cn/application-dev/reference/apis/js-apis-avsession.md
0 → 100755
浏览文件 @
aebb8f20
# 媒体会话管理
媒体会话管理提供媒体播控相关功能的接口,目的是让应用接入播控中心。
该模块提供以下媒体会话相关的常用功能:
-
[
AVSession
](
#section652893
)
: 会话,可用于设置元数据、播放状态信息等操作。
-
[
AVSessionController
](
#section974602
)
: 会话控制器,可用于查看会话ID,完成对会话发送命令及事件,获取会话元数据、播放状态信息等操作。
> **说明:**
>
> 本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
## 导入模块
```
js
import
avSession
from
'
@ohos.multimedia.avsession
'
;
```
## avSession.createAVSession
createAVSession(context: Context, tag: string, type: AVSessionType): Promise
\<
AVSession>
创建会话对象,一个Ability只能存在一个会话,重复创建会失败,结果通过Promise异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------------------------------- | ---- | ------------------------------ |
| context|
[
Context
](
../../ability/context-userguide.md
)
| 是| 应用上下文,提供获取应用程序环境信息的能力。 |
| tag | string | 是 | 会话的自定义名称。 |
| type |
[
AVSessionType
](
#avsessiontype
)
| 是 | 会话类型,当前支持音频和视频。 |
**返回值:**
| 类型 | 说明 |
| --------------------------------- | ------------------------------------------------------------ |
| Promise<
[
AVSession
](
#avsession
)
\>
| Promise对象。回调返回会话实例对象,可用于获取会话ID,以及设置元数据、播放状态,发送按键事件等操作。|
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
**示例:**
```
js
import
featureAbility
from
'
@ohos.ability.featureAbility
'
;
let
session
;
let
tag
=
"
createNewSession
"
;
let
type
=
"
audio
"
;
let
context
=
featureAbility
.
getContext
();
await
avSession
.
createAVSession
(
context
,
tag
,
type
).
then
((
avSession
)
=>
{
session
=
avSession
;
console
.
info
(
`CreateAVSession : SUCCESS : sessionId =
${
session
.
sessionId
}
`
);
}).
catch
((
err
)
=>
{
console
.
info
(
`CreateAVSession BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
## avSession.createAVSession
createAVSession(context: Context, tag: string, type: AVSessionType, callback: AsyncCallback
\<
AVSession>): void
创建会话对象,一个Ability只能存在一个会话,重复创建会失败,结果通过callback异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
| context|
[
Context
](
../../ability/context-userguide.md
)
| 是| 应用上下文,提供获取应用程序环境信息的能力。 |
| tag | string | 是 | 会话的自定义名称。 |
| type |
[
AVSessionType
](
#avsessiontype
)
| 是 | 会话类型,当前支持音频和视频。 |
| callback | AsyncCallback<
[
AVSession
](
#avsession
)
\>
| 是 | 回调函数。回调返回会话实例对象,可用于获取会话ID,以及设置元数据、播放状态,发送按键事件等操作。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
**示例:**
```
js
import
featureAbility
from
'
@ohos.ability.featureAbility
'
;
let
session
;
let
tag
=
"
createNewSession
"
;
let
type
=
"
audio
"
;
let
context
=
featureAbility
.
getContext
();
avSession
.
createAVSession
(
context
,
tag
,
type
,
function
(
err
,
avSession
)
{
if
(
err
)
{
console
.
info
(
`CreateAVSession BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
session
=
avSession
;
console
.
info
(
`CreateAVSession : SUCCESS : sessionId =
${
session
.
sessionId
}
`
);
}
});
```
## avSession.getAllSessionDescriptors
getAllSessionDescriptors(): Promise
\<
Array
\<
Readonly
\<
AVSessionDescriptor>>>
获取所有会话的相关描述。结果通过Promise异步回调方式返回。
**需要权限:**
ohos.permission.MANAGE_MEDIA_RESOURCES,仅系统应用可用。
**系统能力:**
SystemCapability.Multimedia.AVSession.Manager
**系统接口:**
该接口为系统接口。
**返回值:**
| 类型 | 说明 |
| ------------------------------------------------------------ | --------------------------------------------- |
| Promise
\<
Array
\<
Readonly
\<
[
AVSessionDescriptor
](
#avsessiondescriptor
)
\>\>\>
| Promise对象。返回所有会话描述的只读对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
**示例:**
```
js
avSession
.
getAllSessionDescriptors
().
then
((
descriptors
)
=>
{
console
.
info
(
`getAllSessionDescriptors : SUCCESS : descriptors.length :
${
descriptors
.
length
}
`
);
if
(
descriptors
.
length
>
0
){
console
.
info
(
`getAllSessionDescriptors : SUCCESS : descriptors[0].isActive :
${
descriptors
[
0
].
isActive
}
`
);
console
.
info
(
`GetAllSessionDescriptors : SUCCESS : descriptors[0].type :
${
descriptors
[
0
].
type
}
`
);
console
.
info
(
`GetAllSessionDescriptors : SUCCESS : descriptors[0].sessionTag :
${
descriptors
[
0
].
sessionTag
}
`
);
}
}).
catch
((
err
)
=>
{
console
.
info
(
`GetAllSessionDescriptors BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
## avSession.getAllSessionDescriptors
getAllSessionDescriptors(callback: AsyncCallback
\<
Array
\<
Readonly
\<
AVSessionDescriptor>>>): void
获取所有会话的相关描述。结果通过callback异步回调方式返回。
**需要权限:**
ohos.permission.MANAGE_MEDIA_RESOURCES,仅系统应用可用。
**系统能力:**
SystemCapability.Multimedia.AVSession.Manager
**系统接口:**
该接口为系统接口。
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------ |
| callback | AsyncCallback<Array<Readonly<
[
AVSessionDescriptor
](
#avsessiondescriptor
)
\>\>\>
| 是 | 回调函数。返回所有会话描述的只读对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 |Session service exception |
**示例:**
```
js
avSession
.
getAllSessionDescriptors
(
function
(
err
,
descriptors
)
{
if
(
err
)
{
console
.
info
(
`GetAllSessionDescriptors BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
console
.
info
(
`GetAllSessionDescriptors : SUCCESS : descriptors.length :
${
descriptors
.
length
}
`
);
if
(
descriptors
.
length
>
0
){
console
.
info
(
`getAllSessionDescriptors : SUCCESS : descriptors[0].isActive :
${
descriptors
[
0
].
isActive
}
`
);
console
.
info
(
`getAllSessionDescriptors : SUCCESS : descriptors[0].type :
${
descriptors
[
0
].
type
}
`
);
console
.
info
(
`getAllSessionDescriptors : SUCCESS : descriptors[0].sessionTag :
${
descriptors
[
0
].
sessionTag
}
`
);
}
}
});
```
## avSession.createController
createController(sessionId: string): Promise
\<
AVSessionController>
根据会话ID创建会话控制器,可以创建多个会话控制器。结果通过Promise异步回调方式返回。
**需要权限:**
ohos.permission.MANAGE_MEDIA_RESOURCES,仅系统应用可用。
**系统能力:**
SystemCapability.Multimedia.AVSession.Manager
**系统接口:**
该接口为系统接口。
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ------ | ---- | -------- |
| sessionId | string | 是 | 会话ID。 |
**返回值:**
| 类型 | 说明 |
| ----------------------------------------------------- | ------------------------------------------------------------ |
| Promise
<
[
AVSessionController
](
#avsessioncontroller
)\
>
| Promise对象。返回会话控制器实例,可查看会话ID,
<br>
并完成对会话发送命令及事件,获取元数据、播放状态信息等操作。|
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
let
controller
;
await
avSession
.
createController
(
session
.
sessionId
).
then
((
avcontroller
)
=>
{
controller
=
avcontroller
;
console
.
info
(
`CreateController : SUCCESS :
${
controller
.
sessionId
}
`
);
}).
catch
((
err
)
=>
{
console
.
info
(
`CreateController BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
## avSession.createController
createController(sessionId: string, callback: AsyncCallback
\<
AVSessionController>): void
根据会话ID创建会话控制器,可以创建多个会话控制器。结果通过callback异步回调方式返回。
**需要权限:**
ohos.permission.MANAGE_MEDIA_RESOURCES,仅系统应用可用。
**系统能力:**
SystemCapability.Multimedia.AVSession.Manager
**系统接口:**
该接口为系统接口。
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| sessionId | string | 是 | 会话ID。 |
| callback | AsyncCallback
<
[
AVSessionController
](
#avsessioncontroller
)\
>
| 是 | 回调函数。返回会话控制器实例,可查看会话ID,
<br>
并完成对会话发送命令及事件,获取元数据、播放状态信息等操作。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
let
controller
;
avSession
.
createController
(
session
.
sessionId
,
function
(
err
,
avcontroller
)
{
if
(
err
)
{
console
.
info
(
`CreateController BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
controller
=
avcontroller
;
console
.
info
(
`CreateController : SUCCESS :
${
controller
.
sessionId
}
`
);
}
});
```
## avSession.castAudio
castAudio(session: SessionToken | 'all', audioDevices: Array
<audio.AudioDeviceDescriptor>
): Promise
\<
void>
投播会话到指定设备列表。结果通过Promise异步回调方式返回。
调用此接口之前,需要导入
`ohos.multimedia.audio`
模块获取AudioDeviceDescriptor的相关描述。
**需要权限:**
ohos.permission.MANAGE_MEDIA_RESOURCES,仅系统应用可用。
**系统能力:**
SystemCapability.Multimedia.AVSession.Manager
**系统接口:**
该接口为系统接口。
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------------ |--------------------------------------------------------------------------------------------------------------------------------------------------------------------| ---- | ------------------------------------------------------------ |
| session |
[
SessionToken
](
#sessiontoken
)
|
'all' | 是 | 会话令牌。SessionToken表示单个token;字符串
`'all'`
指所有token。 |
| audioDevices | Array
\<
[
audio.AudioDeviceDescriptor
](
js-apis-audio.md#audiodevicedescriptor
)
\>
| 是 | 媒体设备列表。 |
**返回值:**
| 类型 | 说明 |
| -------------- | ----------------------------- |
| Promise<void
\>
| Promise对象。当投播成功,无返回结果,否则返回错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
| 6600104 | The remote session connection failed |
**示例:**
```
js
import
audio
from
'
@ohos.multimedia.audio
'
;
let
audioManager
=
audio
.
getAudioManager
();
let
audioDevices
;
await
audioManager
.
getDevices
(
audio
.
DeviceFlag
.
OUTPUT_DEVICES_FLAG
).
then
((
data
)
=>
{
audioDevices
=
data
;
console
.
info
(
'
Promise returned to indicate that the device list is obtained.
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`GetDevices BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
avSession
.
castAudio
(
'
all
'
,
audioDevices
).
then
(()
=>
{
console
.
info
(
'
CreateController : SUCCESS
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`CreateController BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
## avSession.castAudio
castAudio(session: SessionToken | 'all', audioDevices: Array
<audio.AudioDeviceDescriptor>
, callback: AsyncCallback
\<
void>): void
投播会话到指定设备列表。结果通过callback异步回调方式返回。
需要导入
`ohos.multimedia.audio`
模块获取AudioDeviceDescriptor的相关描述。
**需要权限:**
ohos.permission.MANAGE_MEDIA_RESOURCES,仅系统应用可用。
**系统能力:**
SystemCapability.Multimedia.AVSession.Manager
**系统接口:**
该接口为系统接口。
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------------ |--------------------------------------------| ---- | ------------------------------------------------------------ |
| session |
[
SessionToken
](
#sessiontoken
)
|
'all' | 是 | 会话令牌。SessionToken表示单个token;字符串
`'all'`
指所有token。 |
| audioDevices | Array
\<
[
audio.AudioDeviceDescriptor
](
js-apis-audio.md#audiodevicedescriptor
)
\>
| 是 | 媒体设备列表。 |
| callback | AsyncCallback<void
\>
| 是 | 回调函数。当投播成功,err为undefined,否则返回错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
| 6600104 | The remote session connection failed |
**示例:**
```
js
import
audio
from
'
@ohos.multimedia.audio
'
;
let
audioManager
=
audio
.
getAudioManager
();
let
audioDevices
;
await
audioManager
.
getDevices
(
audio
.
DeviceFlag
.
OUTPUT_DEVICES_FLAG
).
then
((
data
)
=>
{
audioDevices
=
data
;
console
.
info
(
'
Promise returned to indicate that the device list is obtained.
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`GetDevices BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
avSession
.
castAudio
(
'
all
'
,
audioDevices
,
function
(
err
)
{
if
(
err
)
{
console
.
info
(
`CastAudio BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
console
.
info
(
'
CastAudio : SUCCESS
'
);
}
});
```
## avSession.on('sessionCreate' | 'sessionDestroy' | 'topSessionChange')
on(type: 'sessionCreate' | 'sessionDestroy' | 'topSessionChange', callback: (session: AVSessionDescriptor) => void): void
会话的创建、销毁以及最新会话变更的监听事件。
**需要权限:**
ohos.permission.MANAGE_MEDIA_RESOURCES,仅系统应用可用。
**系统能力:**
SystemCapability.Multimedia.AVSession.Manager
**系统接口:**
该接口为系统接口。
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 事件回调类型,支持的事件包括:
<br/>
-
`'sessionCreate'`
:会话创建事件,检测到会话创建时触发。
<br/>
-
`'sessionDestroy'`
:会话销毁事件,检测到会话销毁时触发。
<br/>
-
`'topSessionChange'`
:最新会话的变化事件,检测到最新的会话改变时触发。|
| callback | (session:
[
AVSessionDescriptor
](
#avsessiondescriptor
)
) => void | 是 | 回调函数。参数为会话相关描述。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
**示例:**
```
js
avSession
.
on
(
'
sessionCreate
'
,
(
descriptor
)
=>
{
console
.
info
(
`on sessionCreate : isActive :
${
descriptor
.
isActive
}
`
);
console
.
info
(
`on sessionCreate : type :
${
descriptor
.
type
}
`
);
console
.
info
(
`on sessionCreate : sessionTag :
${
descriptor
.
sessionTag
}
`
);
});
avSession
.
on
(
'
sessionDestroy
'
,
(
descriptor
)
=>
{
console
.
info
(
`on sessionDestroy : isActive :
${
descriptor
.
isActive
}
`
);
console
.
info
(
`on sessionDestroy : type :
${
descriptor
.
type
}
`
);
console
.
info
(
`on sessionDestroy : sessionTag :
${
descriptor
.
sessionTag
}
`
);
});
avSession
.
on
(
'
topSessionChange
'
,
(
descriptor
)
=>
{
console
.
info
(
`on topSessionChange : isActive :
${
descriptor
.
isActive
}
`
);
console
.
info
(
`on topSessionChange : type :
${
descriptor
.
type
}
`
);
console
.
info
(
`on topSessionChange : sessionTag :
${
descriptor
.
sessionTag
}
`
);
});
```
## avSession.off('sessionCreate' | 'sessionDestroy' | 'topSessionChange')
off(type: 'sessionCreate' | 'sessionDestroy' | 'topSessionChange', callback?: (session: AVSessionDescriptor) => void): void
取消会话相关事件监听,取消后,不再进行相关事件的监听。
**需要权限:**
ohos.permission.MANAGE_MEDIA_RESOURCES,仅系统应用可用。
**系统能力:**
SystemCapability.Multimedia.AVSession.Manager
**系统接口:**
该接口为系统接口。
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 事件回调类型,支持的事件为:
<br/>
-
`'sessionCreate'`
:会话创建事件,检测到会话创建时触发。
<br/>
-
`'sessionDestroy'`
:会话销毁事件,检测到会话销毁时触发。
<br/>
-
`'topSessionChange'`
:最新会话的变化事件,检测到最新的会话改变时触发。|
| callback | (session:
[
AVSessionDescriptor
](
#avsessiondescriptor
)
) => void | 否 | 回调函数。当监听事件取消成功,err为undefined,否则返回错误对象。
<br>
该参数为会话相关描述,为可选参数,若不填写该参数,则认为取消所有相关会话的事件监听。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
**示例:**
```
js
avSession
.
off
(
'
sessionCreate
'
);
avSession
.
off
(
'
sessionDestroy
'
);
avSession
.
off
(
'
topSessionChange
'
);
```
## avSession.on('sessionServiceDie')
on(type: 'sessionServiceDie', callback: () => void): void
监听会话的服务死亡事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 事件回调类型,支持事件
`'sessionServiceDie'`
:会话服务死亡事件,检测到会话的服务死亡时触发。 |
| callback | callback: () => void | 是 | 回调函数。当监听事件注册成功,err为undefined,否则返回错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
**示例:**
```
js
avSession
.
on
(
'
sessionServiceDie
'
,
()
=>
{
console
.
info
(
'
on sessionServiceDie : session is Died
'
);
});
```
## avSession.off('sessionServiceDie')
off(type: 'sessionServiceDie', callback?: () => void): void
取消会话服务死亡监听,取消后,不再进行服务死亡监听。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ---------------------- | ---- | ------------------------------------------------------- |
| type | string | 是 | 事件回调类型,支持事件
`'sessionServiceDie'`
:会话服务死亡事件。|
| callback | callback: () => void | 否 | 回调函数。当监听事件取消成功,err为undefined,否则返回错误对象。
<br>
该参数为可选参数,若不填写该参数,则认为取消所有相关会话的服务死亡监听。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
**示例:**
```
js
avSession
.
off
(
'
sessionServiceDie
'
);
```
## avSession.sendSystemAVKeyEvent
sendSystemAVKeyEvent(event: KeyEvent): Promise
\<
void>
发送按键事件给置顶会话。结果通过Promise异步回调方式返回。
**需要权限:**
ohos.permission.MANAGE_MEDIA_RESOURCES,仅系统应用可用。
**系统能力:**
SystemCapability.Multimedia.AVSession.Manager
**系统接口:**
该接口为系统接口。
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------------------------------- | ---- | ---------- |
| event |
[
KeyEvent
](
js-apis-keyevent.md
)
| 是 | 按键事件。 |
**返回值:**
| 类型 | 说明 |
| -------------- | ----------------------------- |
| Promise<void
\>
| Promise对象。当事件发送成功,无返回结果,否则返回错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600105 | Invalid session command |
**示例:**
```
js
let
keyItem
=
{
code
:
0x49
,
pressedTime
:
2
,
deviceId
:
0
};
let
event
=
{
action
:
2
,
key
:
keyItem
,
keys
:[
keyItem
]};
avSession
.
sendSystemAVKeyEvent
(
event
).
then
(()
=>
{
console
.
info
(
'
SendSystemAVKeyEvent Successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`SendSystemAVKeyEvent BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
## avSession.sendSystemAVKeyEvent
sendSystemAVKeyEvent(event: KeyEvent, callback: AsyncCallback
\<
void>): void
发送按键事件给置顶会话。结果通过callback异步回调方式返回。
**需要权限:**
ohos.permission.MANAGE_MEDIA_RESOURCES,仅系统应用可用。
**系统能力:**
SystemCapability.Multimedia.AVSession.Manager
**系统接口:**
该接口为系统接口。
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------- |
| event |
[
KeyEvent
](
js-apis-keyevent.md
)
| 是 | 按键事件。 |
| callback | AsyncCallback<void
\>
| 是 | 回调函数。当事件发送成功,err为undefined,否则返回错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600105 | Invalid session command |
**示例:**
```
js
let
keyItem
=
{
code
:
0x49
,
pressedTime
:
2
,
deviceId
:
0
};
let
event
=
{
action
:
2
,
key
:
keyItem
,
keys
:[
keyItem
]};
avSession
.
sendSystemAVKeyEvent
(
event
,
function
(
err
)
{
if
(
err
)
{
console
.
info
(
`SendSystemAVKeyEvent BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
console
.
info
(
'
SendSystemAVKeyEvent : SUCCESS
'
);
}
});
```
## avSession.sendSystemControlCommand
sendSystemControlCommand(command: AVControlCommand): Promise
\<
void>
发送控制命令给置顶会话。结果通过Promise异步回调方式返回。
**需要权限:**
ohos.permission.MANAGE_MEDIA_RESOURCES,仅系统应用可用。
**系统能力:**
SystemCapability.Multimedia.AVSession.Manager
**系统接口:**
该接口为系统接口。
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | ------------------------------------- | ---- | ----------------------------------- |
| command |
[
AVControlCommand
](
#avcontrolcommand
)
| 是 | AVSession的相关命令和命令相关参数。 |
**返回值:**
| 类型 | 说明 |
| -------------- | ----------------------------- |
| Promise<void
\>
| Promise对象。当命令发送成功,无返回结果,否则返回错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600105 | Invalid session command |
| 6600107 | Command or event overload |
**示例:**
```
js
let
avcommand
=
{
command
:
'
play
'
};
// let avcommand = {command:'pause'};
// let avcommand = {command:'stop'};
// let avcommand = {command:'playNext'};
// let avcommand = {command:'playPrevious'};
// let avcommand = {command:'fastForward'};
// let avcommand = {command:'rewind'};
// let avcommand = {command:'seek', parameter:10};
// let avcommand = {command:'setSpeed', parameter:2.6};
// let avcommand = {command:'setLoopMode', parameter:avSession.LoopMode.LOOP_MODE_SINGLE};
// let avcommand = {command:'toggleFavorite', parameter:"false"};
avSession
.
sendSystemControlCommand
(
avcommand
).
then
(()
=>
{
console
.
info
(
'
SendSystemControlCommand successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`SendSystemControlCommand BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
## avSession.sendSystemControlCommand
sendSystemControlCommand(command: AVControlCommand, callback: AsyncCallback
\<
void>): void
发送控制命令给置顶会话。结果通过callback异步回调方式返回。
**需要权限:**
ohos.permission.MANAGE_MEDIA_RESOURCES,仅系统应用可用。
**系统能力:**
SystemCapability.Multimedia.AVSession.Manager
**系统接口:**
该接口为系统接口。
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------- | ---- | ------------------------------------- |
| command |
[
AVControlCommand
](
#avcontrolcommand
)
| 是 | AVSession的相关命令和命令相关参数。 |
| callback | AsyncCallback<void
\>
| 是 | 回调函数。当命令发送成功,err为undefined,否则返回错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600105 | Invalid session command |
| 6600107 | Command or event overload |
**示例:**
```
js
let
avcommand
=
{
command
:
'
play
'
};
// let avcommand = {command:'pause'};
// let avcommand = {command:'stop'};
// let avcommand = {command:'playNext'};
// let avcommand = {command:'playPrevious'};
// let avcommand = {command:'fastForward'};
// let avcommand = {command:'rewind'};
// let avcommand = {command:'seek', parameter:10};
// let avcommand = {command:'setSpeed', parameter:2.6};
// let avcommand = {command:'setLoopMode', parameter:avSession.LoopMode.LOOP_MODE_SINGLE};
// let avcommand = {command:'toggleFavorite', parameter:"false"};
avSession
.
sendSystemControlCommand
(
avcommand
,
function
(
err
)
{
if
(
err
)
{
console
.
info
(
`SendSystemControlCommand BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
console
.
info
(
'
sendSystemControlCommand successfully
'
);
}
});
```
## AVSession<a name="section652893"></a>
调用
[
avSession.createAVSession
](
#avsessioncreateavsession
)
后,返回会话的实例,可以获得会话ID,完成设置元数据,播放状态信息等操作。
### 属性
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
| 名称 | 类型 | 可读 | 可写 | 说明 |
| :-------- | :----- | :--- | :--- | :---------------------------- |
| sessionId | string | 是 | 否 | AVSession对象唯一的会话标识。 |
**示例:**
```
js
let
sessionId
=
session
.
sessionId
;
```
### setAVMetadata
setAVMetadata(data: AVMetadata): Promise
\<
void>
设置会话元数据。结果通过Promise异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------------------------- | ---- | ------------ |
| data |
[
AVMetadata
](
#avmetadata
)
| 是 | 会话元数据。 |
**返回值:**
| 类型 | 说明 |
| -------------- | ----------------------------- |
| Promise<void
\>
| Promise对象。当元数据设置成功,无返回结果,否则返回错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
let
metadata
=
{
assetId
:
"
121278
"
,
title
:
"
lose yourself
"
,
artist
:
"
Eminem
"
,
author
:
"
ST
"
,
album
:
"
Slim shady
"
,
writer
:
"
ST
"
,
composer
:
"
ST
"
,
duration
:
2222
,
mediaImage
:
"
https://www.example.com/example.jpg
"
,
subtitle
:
"
8 Mile
"
,
description
:
"
Rap
"
,
lyric
:
"
https://www.example.com/example.lrc
"
,
previousAssetId
:
"
121277
"
,
nextAssetId
:
"
121279
"
,
};
session
.
setAVMetadata
(
metadata
).
then
(()
=>
{
console
.
info
(
'
SetAVMetadata successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`SetAVMetadata BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
### setAVMetadata
setAVMetadata(data: AVMetadata, callback: AsyncCallback
\<
void>): void
设置会话元数据。结果通过callback异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------- | ---- | ------------------------------------- |
| data |
[
AVMetadata
](
#avmetadata
)
| 是 | 会话元数据。 |
| callback | AsyncCallback<void
\>
| 是 | 回调函数。当元数据设置成功,err为undefined,否则返回错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
let
metadata
=
{
assetId
:
"
121278
"
,
title
:
"
lose yourself
"
,
artist
:
"
Eminem
"
,
author
:
"
ST
"
,
album
:
"
Slim shady
"
,
writer
:
"
ST
"
,
composer
:
"
ST
"
,
duration
:
2222
,
mediaImage
:
"
https://www.example.com/example.jpg
"
,
subtitle
:
"
8 Mile
"
,
description
:
"
Rap
"
,
lyric
:
"
https://www.example.com/example.lrc
"
,
previousAssetId
:
"
121277
"
,
nextAssetId
:
"
121279
"
,
};
session
.
setAVMetadata
(
metadata
,
function
(
err
)
{
if
(
err
)
{
console
.
info
(
`SetAVMetadata BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
console
.
info
(
'
SetAVMetadata successfully
'
);
}
});
```
### setAVPlaybackState
setAVPlaybackState(state: AVPlaybackState): Promise
\<
void>
设置会话播放状态。结果通过Promise异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ----------------------------------- | ---- | ---------------------------------------------- |
| data |
[
AVPlaybackState
](
#avplaybackstate
)
| 是 | 会话播放状态,包括状态、倍数、循环模式等信息。 |
**返回值:**
| 类型 | 说明 |
| -------------- | ----------------------------- |
| Promise<void
\>
| Promise对象。当播放状态设置成功,无返回结果,否则返回错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
let
PlaybackState
=
{
state
:
avSession
.
PlaybackState
.
PLAYBACK_STATE_PLAY
,
speed
:
1.0
,
position
:{
elapsedTime
:
10
,
updateTime
:(
new
Date
()).
getTime
()},
bufferedTime
:
1000
,
loopMode
:
avSession
.
LoopMode
.
LOOP_MODE_SINGLE
,
isFavorite
:
true
,
};
session
.
setAVPlaybackState
(
PlaybackState
).
then
(()
=>
{
console
.
info
(
'
SetAVPlaybackState successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`SetAVPlaybackState BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
### setAVPlaybackState
setAVPlaybackState(state: AVPlaybackState, callback: AsyncCallback
\<
void>): void
设置会话播放状态。结果通过callback异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------------------------- | ---- | ---------------------------------------------- |
| data |
[
AVPlaybackState
](
#avplaybackstate
)
| 是 | 会话播放状态,包括状态、倍数、循环模式等信息。 |
| callback | AsyncCallback<void
\>
| 是 | 回调函数。当播放状态设置成功,err为undefined,否则返回错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
let
PlaybackState
=
{
state
:
avSession
.
PlaybackState
.
PLAYBACK_STATE_PLAY
,
speed
:
1.0
,
position
:{
elapsedTime
:
10
,
updateTime
:(
new
Date
()).
getTime
()},
bufferedTime
:
1000
,
loopMode
:
avSession
.
LoopMode
.
LOOP_MODE_SINGLE
,
isFavorite
:
true
,
};
session
.
setAVPlaybackState
(
PlaybackState
,
function
(
err
)
{
if
(
err
)
{
console
.
info
(
`SetAVPlaybackState BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
console
.
info
(
'
SetAVPlaybackState successfully
'
);
}
});
```
### setLaunchAbility
setLaunchAbility(ability: WantAgent): Promise
\<
void>
设置一个WantAgent用于拉起会话的Ability。结果通过Promise异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------- | --------------------------------- | ---- | ----------------------------------------------------------- |
| ability |
[
WantAgent
](
js-apis-wantAgent.md
)
| 是 | 应用的相关属性信息,如bundleName,abilityName,deviceId等。 |
**返回值:**
| 类型 | 说明 |
| -------------- | ----------------------------- |
| Promise<void
\>
| Promise对象。当Ability设置成功,无返回结果,否则返回错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
import
wantAgent
from
'
@ohos.wantAgent
'
;
//WantAgentInfo对象
let
wantAgentInfo
=
{
wants
:
[
{
deviceId
:
"
deviceId
"
,
bundleName
:
"
com.neu.setResultOnAbilityResultTest1
"
,
abilityName
:
"
com.example.test.MainAbility
"
,
action
:
"
action1
"
,
entities
:
[
"
entity1
"
],
type
:
"
MIMETYPE
"
,
uri
:
"
key={true,true,false}
"
,
parameters
:
{
mykey0
:
2222
,
mykey1
:
[
1
,
2
,
3
],
mykey2
:
"
[1, 2, 3]
"
,
mykey3
:
"
ssssssssssssssssssssssssss
"
,
mykey4
:
[
false
,
true
,
false
],
mykey5
:
[
"
qqqqq
"
,
"
wwwwww
"
,
"
aaaaaaaaaaaaaaaaa
"
],
mykey6
:
true
,
}
}
],
operationType
:
wantAgent
.
OperationType
.
START_ABILITIES
,
requestCode
:
0
,
wantAgentFlags
:[
wantAgent
.
WantAgentFlags
.
UPDATE_PRESENT_FLAG
]
}
wantAgent
.
getWantAgent
(
wantAgentInfo
).
then
((
agent
)
=>
{
session
.
setLaunchAbility
(
agent
).
then
(()
=>
{
console
.
info
(
'
SetLaunchAbility successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`SetLaunchAbility BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
});
```
### setLaunchAbility
setLaunchAbility(ability: WantAgent, callback: AsyncCallback
\<
void>): void
设置一个WantAgent用于拉起会话的Ability。结果通过callback异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------------- | ---- | ----------------------------------------------------------- |
| ability |
[
WantAgent
](
js-apis-wantAgent.md
)
| 是 | 应用的相关属性信息,如bundleName,abilityName,deviceId等。 |
| callback | AsyncCallback<void
\>
| 是 | 回调函数。当Ability设置成功,err为undefined,否则返回错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
import
wantAgent
from
'
@ohos.wantAgent
'
;
//WantAgentInfo对象
let
wantAgentInfo
=
{
wants
:
[
{
deviceId
:
"
deviceId
"
,
bundleName
:
"
com.neu.setResultOnAbilityResultTest1
"
,
abilityName
:
"
com.example.test.MainAbility
"
,
action
:
"
action1
"
,
entities
:
[
"
entity1
"
],
type
:
"
MIMETYPE
"
,
uri
:
"
key={true,true,false}
"
,
parameters
:
{
mykey0
:
2222
,
mykey1
:
[
1
,
2
,
3
],
mykey2
:
"
[1, 2, 3]
"
,
mykey3
:
"
ssssssssssssssssssssssssss
"
,
mykey4
:
[
false
,
true
,
false
],
mykey5
:
[
"
qqqqq
"
,
"
wwwwww
"
,
"
aaaaaaaaaaaaaaaaa
"
],
mykey6
:
true
,
}
}
],
operationType
:
wantAgent
.
OperationType
.
START_ABILITIES
,
requestCode
:
0
,
wantAgentFlags
:[
wantAgent
.
WantAgentFlags
.
UPDATE_PRESENT_FLAG
]
}
wantAgent
.
getWantAgent
(
wantAgentInfo
).
then
((
agent
)
=>
{
session
.
setLaunchAbility
(
agent
,
function
(
err
)
{
if
(
err
)
{
console
.
info
(
`SetLaunchAbility BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
console
.
info
(
'
SetLaunchAbility successfully
'
);
}
});
});
```
### getController
getController(): Promise
\<
AVSessionController>
获取本会话对应的控制器。结果通过Promise异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**返回值:**
| 类型 | 说明 |
| ---------------------------------------------------- | ----------------------------- |
| Promise
<
[
AVSessionController
](
#avsessioncontroller
)
>
| Promise对象。返回会话控制器。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
let
controller
;
session
.
getController
().
then
((
avcontroller
)
=>
{
controller
=
avcontroller
;
console
.
info
(
`GetController : SUCCESS : sessionid :
${
controller
.
sessionId
}
`
);
}).
catch
((
err
)
=>
{
console
.
info
(
`GetController BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
### getController
getController(callback: AsyncCallback
\<
AVSessionController>): void
获取本会话相应的控制器。结果通过callback异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------------------------------------------------- | ---- | -------------------------- |
| callback | AsyncCallback<
[
AVSessionController
](
#avsessioncontroller
)
\>
| 是 | 回调函数。返回会话控制器。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
let
controller
;
session
.
getController
(
function
(
err
,
avcontroller
)
{
if
(
err
)
{
console
.
info
(
`GetController BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
controller
=
avcontroller
;
console
.
info
(
`GetController : SUCCESS : sessionid :
${
controller
.
sessionId
}
`
);
}
});
```
### getOutputDevice
getOutputDevice(): Promise
\<
OutputDeviceInfo>
通过会话获取播放设备信息。结果通过Promise异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**返回值:**
| 类型 | 说明 |
| ---------------------------------------------- | --------------------------------- |
| Promise
<
[
OutputDeviceInfo
](
#outputdeviceinfo
)
>
| Promise对象。返回播放设备信息。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
session
.
getOutputDevice
().
then
((
outputDeviceInfo
)
=>
{
console
.
info
(
`GetOutputDevice : SUCCESS : isRemote :
${
outputDeviceInfo
.
isRemote
}
`
);
}).
catch
((
err
)
=>
{
console
.
info
(
`GetOutputDevice BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
### getOutputDevice
getOutputDevice(callback: AsyncCallback
\<
OutputDeviceInfo>): void
通过会话获取播放设备相关信息。结果通过callback异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------------------------------------------- | ---- | ------------------------------ |
| callback | AsyncCallback<
[
OutputDeviceInfo
](
#outputdeviceinfo
)
\>
| 是 | 回调函数,返回播放设备信息。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
session
.
getOutputDevice
(
function
(
err
,
outputDeviceInfo
)
{
if
(
err
)
{
console
.
info
(
`GetOutputDevice BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
console
.
info
(
`GetOutputDevice : SUCCESS : isRemote :
${
outputDeviceInfo
.
isRemote
}
`
);
}
});
```
### activate
activate(): Promise
\<
void>
激活会话,激活后可正常使用会话。结果通过Promise异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**返回值:**
| 类型 | 说明 |
| -------------- | ----------------------------- |
| Promise<void
\>
| Promise对象。当会话激活成功,无返回结果,否则返回错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
session
.
activate
().
then
(()
=>
{
console
.
info
(
'
Activate : SUCCESS
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`Activate BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
### activate
activate(callback: AsyncCallback
\<
void>): void
激活会话,激活后可正常使用会话。结果通过callback异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------- | ---- | ---------- |
| callback | AsyncCallback<void
\>
| 是 | 回调函数。当会话激活成功,err为undefined,否则返回错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
session
.
activate
(
function
(
err
)
{
if
(
err
)
{
console
.
info
(
`Activate BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
console
.
info
(
'
Activate : SUCCESS
'
);
}
});
```
### deactivate
deactivate(): Promise
\<
void>
禁用当前会话的功能,可通过
[
activate
](
#activate
)
恢复。结果通过Promise异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**返回值:**
| 类型 | 说明 |
| -------------- | ----------------------------- |
| Promise<void
\>
| Promise对象。当禁用会话成功,无返回结果,否则返回错误对象。|
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
session
.
deactivate
().
then
(()
=>
{
console
.
info
(
'
Deactivate : SUCCESS
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`Deactivate BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
### deactivate
deactivate(callback: AsyncCallback
\<
void>): void
禁用当前会话。结果通过callback异步回调方式返回。
禁用当前会话的功能,可通过
[
activate
](
#activate
)
恢复。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------- | ---- | ---------- |
| callback | AsyncCallback<void
\>
| 是 | 回调函数。当禁用会话成功,err为undefined,否则返回错误对象。|
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
session
.
deactivate
(
function
(
err
)
{
if
(
err
)
{
console
.
info
(
`Deactivate BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
console
.
info
(
'
Deactivate : SUCCESS
'
);
}
});
```
### destroy
destroy(): Promise
\<
void>
销毁当前会话,使当前会话完全失效。结果通过Promise异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**返回值:**
| 类型 | 说明 |
| -------------- | ----------------------------- |
| Promise<void
\>
| Promise对象。当会话销毁成功,无返回结果,否则返回错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
session
.
destroy
().
then
(()
=>
{
console
.
info
(
'
Destroy : SUCCESS
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`Destroy BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
### destroy
destroy(callback: AsyncCallback
\<
void>): void
销毁当前会话,使当前会话完全失效。结果通过callback异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------- | ---- | ---------- |
| callback | AsyncCallback<void
\>
| 是 | 回调函数。当会话销毁成功,err为undefined,否则返回错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
session
.
destroy
(
function
(
err
)
{
if
(
err
)
{
console
.
info
(
`Destroy BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
console
.
info
(
'
Destroy : SUCCESS
'
);
}
});
```
### on('play'|'pause'|'stop'|'playNext'|'playPrevious'|'fastForward'|'rewind')
on(type: 'play'|'pause'|'stop'|'playNext'|'playPrevious'|'fastForward'|'rewind', callback: () => void): void
设置播放命令监听事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 事件回调类型,支持的事件包括:
`'play'`
,
`'pause'`
,
`'stop'`
,
` 'playNext'`
,
` 'playPrevious'`
,
`'fastForward'`
,
` 'rewind'`
。
<br/>
当对应的播放命令被发送到会话时,触发该事件回调。 |
| callback | callback: () => void | 是 | 回调函数。当监听事件注册成功,err为undefined,否则为错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
session
.
on
(
'
play
'
,
()
=>
{
console
.
info
(
'
on play entry
'
);
});
session
.
on
(
'
pause
'
,
()
=>
{
console
.
info
(
'
on pause entry
'
);
});
session
.
on
(
'
stop
'
,
()
=>
{
console
.
info
(
'
on stop entry
'
);
});
session
.
on
(
'
playNext
'
,
()
=>
{
console
.
info
(
'
on playNext entry
'
);
});
session
.
on
(
'
playPrevious
'
,
()
=>
{
console
.
info
(
'
on playPrevious entry
'
);
});
session
.
on
(
'
fastForward
'
,
()
=>
{
console
.
info
(
'
on fastForward entry
'
);
});
session
.
on
(
'
rewind
'
,
()
=>
{
console
.
info
(
'
on rewind entry
'
);
});
```
### on('seek')
on(type: 'seek', callback: (time: number) => void): void
设置跳转节点监听事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ---------------------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 事件回调类型,支持事件
`'seek'`
:当跳转节点命令被发送到会话时,触发该事件。 |
| callback | (time: number) => void | 是 | 回调函数。参数time是时间节点,单位为毫秒。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
The session does not exist
```
js
session
.
on
(
'
seek
'
,
(
time
)
=>
{
console
.
info
(
`on seek entry time :
${
time
}
`
);
});
```
### on('setSpeed')
on(type: 'setSpeed', callback: (speed: number) => void): void
设置播放速率的监听事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 事件回调类型,支持事件
`'setSpeed'`
:当设置播放速率的命令被发送到会话时,触发该事件。 |
| callback | (speed: number) => void | 是 | 回调函数。参数speed是播放倍速。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
session
.
on
(
'
setSpeed
'
,
(
speed
)
=>
{
console
.
info
(
`on setSpeed speed :
${
speed
}
`
);
});
```
### on('setLoopMode')
on(type: 'setLoopMode', callback: (mode: LoopMode) => void): void
设置循环模式的监听事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------- | ---- | ---- |
| type | string | 是 | 事件回调类型,支持事件
`'setLoopMode'`
:当设置循环模式的命令被发送到会话时,触发该事件。 |
| callback | (mode:
[
LoopMode
](
#loopmode
)
) => void | 是 | 回调函数。参数mode是循环模式。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
session
.
on
(
'
setLoopMode
'
,
(
mode
)
=>
{
console
.
info
(
`on setLoopMode mode :
${
mode
}
`
);
});
```
### on('toggleFavorite')
on(type: 'toggleFavorite', callback: (assetId: string) => void): void
设置是否收藏的监听事件
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 事件回调类型,支持事件
`'toggleFavorite'`
:当是否收藏的命令被发送到会话时,触发该事件。 |
| callback | (assetId: string) => void | 是 | 回调函数。参数assetId是媒体ID。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
session
.
on
(
'
toggleFavorite
'
,
(
assetId
)
=>
{
console
.
info
(
`on toggleFavorite mode :
${
assetId
}
`
);
});
```
### on('handleKeyEvent')
on(type: 'handleKeyEvent', callback: (event: KeyEvent) => void): void
设置按键事件的监听
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 事件回调类型,支持事件
`'handleKeyEvent'`
:当按键事件被发送到会话时,触发该事件。 |
| callback | (event:
[
KeyEvent
](
js-apis-keyevent.md
)
) => void | 是 | 回调函数。参数event是按键事件。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
session
.
on
(
'
handleKeyEvent
'
,
(
event
)
=>
{
console
.
info
(
`on handleKeyEvent event :
${
event
}
`
);
});
```
### on('outputDeviceChange')
on(type: 'outputDeviceChange', callback: (device: OutputDeviceInfo) => void): void
设置播放设备变化的监听事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 事件回调类型,支持事件
`'outputDeviceChange'`
:当播放设备变化时,触发该事件。 |
| callback | (device:
[
OutputDeviceInfo
](
#outputdeviceinfo
)
) => void | 是 | 回调函数。参数device是设备相关信息。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
session
.
on
(
'
outputDeviceChange
'
,
(
device
)
=>
{
console
.
info
(
`on outputDeviceChange device isRemote :
${
device
.
isRemote
}
`
);
});
```
### off('play'|'pause'|'stop'|'playNext'|'playPrevious'|'fastForward'|'rewind')
off(type: 'play' | 'pause' | 'stop' | 'playNext' | 'playPrevious' | 'fastForward' | 'rewind', callback?: () => void): void
取消会话相关事件监听,关闭后,不再进行相关事件回调。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------- |
| type | string | 是 | 关闭对应的监听事件,支持的事件包括:
`'play'`
,
` 'pause'`
,
`'stop'`
,
`'playNext'`
,
` 'playPrevious'`
,
` 'fastForward'`
,
` 'rewind'`
。 |
| callback | callback: () => void | 否 | 回调函数。当监听事件取消成功,err为undefined,否则返回错误对象。
<br>
该参数为可选参数,若不填写该参数,则认为取消所有相关会话的事件监听。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
session
.
off
(
'
play
'
);
session
.
off
(
'
pause
'
);
session
.
off
(
'
stop
'
);
session
.
off
(
'
playNext
'
);
session
.
off
(
'
playPrevious
'
);
session
.
off
(
'
fastForward
'
);
session
.
off
(
'
rewind
'
);
```
### off('seek')
off(type: 'seek', callback?: (time: number) => void): void
取消监听跳转节点事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ---------------------- | ---- | ----------------------------------------- |
| type | string | 是 | 关闭对应的监听事件,支持关闭事件
`'seek'`
。 |
| callback | (time: number) => void | 否 | 回调函数,参数time是时间节点,单位为毫秒。
<br>
当监听事件取消成功,err为undefined,否则返回错误对象。
<br>
该参数为可选参数,若不填写该参数,则认为取消所有相关会话的事件监听。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
session
.
off
(
'
seek
'
);
```
### off('setSpeed')
off(type: 'setSpeed', callback?: (speed: number) => void): void
取消监听播放速率变化事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------------- | ---- | -------------------------------------------|
| type | string | 是 | 关闭对应的监听事件,支持关闭事件
`'setSpeed'`
。 |
| callback | (speed: number) => void | 否 | 回调函数,参数speed是播放倍速。
<br>
当监听事件取消成功,err为undefined,否则返回错误对象。
<br>
该参数为可选参数,若不填写该参数,则认为取消所有相关会话的事件监听。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
session
.
off
(
'
setSpeed
'
);
```
### off('setLoopMode')
off(type: 'setLoopMode', callback?: (mode: LoopMode) => void): void
取消监听循环模式变化事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------- | ---- | ----- |
| type | string | 是 | 关闭对应的监听事件,支持关闭事件
`'setLoopMode'`
。|
| callback | (mode:
[
LoopMode
](
#loopmode
)
) => void | 否 | 回调函数,参数mode是循环模式。
<br>
当监听事件取消成功,err为undefined,否则返回错误对象。
<br>
该参数为可选参数,若不填写该参数,则认为取消所有相关会话的事件监听。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
session
.
off
(
'
setLoopMode
'
);
```
### off('toggleFavorite')
off(type: 'toggleFavorite', callback?: (assetId: string) => void): void
取消监听是否收藏的事件
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------- | ---- | -------------------------------------------------------- |
| type | string | 是 | 关闭对应的监听事件,支持关闭事件
`'toggleFavorite'`
。 |
| callback | (assetId: string) => void | 否 | 回调函数,参数assetId是媒体ID。
<br>
当监听事件取消成功,err为undefined,否则返回错误对象。
<br>
该参数为可选参数,若不填写该参数,则认为取消所有相关会话的事件监听。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
session
.
off
(
'
toggleFavorite
'
);
```
### off('handleKeyEvent')
off(type: 'handleKeyEvent', callback?: (event: KeyEvent) => void): void
取消监听按键事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 关闭对应的监听事件,支持关闭事件
`'handleKeyEvent'`
。 |
| callback | (event:
[
KeyEvent
](
js-apis-keyevent.md
)
) => void | 否 | 回调函数,参数event是按键事件。
<br>
当监听事件取消成功,err为undefined,否则返回错误对象。
<br>
该参数为可选参数,若不填写该参数,则认为取消所有相关会话的事件监听。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
session
.
off
(
'
handleKeyEvent
'
);
```
### off('outputDeviceChange')
off(type: 'outputDeviceChange', callback?: (device: OutputDeviceInfo) => void): void
取消监听播放设备变化的事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------ |
| type | string | 是 | 关闭对应的监听事件,支持关闭事件
`'outputDeviceChange'`
。 |
| callback | (device:
[
OutputDeviceInfo
](
#outputdeviceinfo
)
) => void | 否 | 回调函数,参数device是设备相关信息。
<br>
当监听事件取消成功,err为undefined,否则返回错误对象。
<br>
该参数为可选参数,若不填写该参数,则认为取消所有相关会话的事件监听。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
**示例:**
```
js
session
.
off
(
'
outputDeviceChange
'
);
```
## AVSessionController<a name="section974602"></a>
调用
[
avSession.createController
](
#avsessioncreatecontroller
)
后,返回会话控制器实例。控制器可查看会话ID,并可完成对会话发送命令及事件,获取会话元数据,播放状态信息等操作。
### 属性
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
| 名称 | 类型 | 可读 | 可写 | 说明 |
| :-------- | :----- | :--- | :--- | :-------------------------------------- |
| sessionId | string | 是 | 否 | AVSessionController对象唯一的会话标识。 |
**示例:**
```
js
let
sessionId
;
await
avSession
.
createController
(
session
.
sessionId
).
then
((
controller
)
=>
{
sessionId
=
controller
.
sessionId
;
}).
catch
((
err
)
=>
{
console
.
info
(
`CreateController BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
### getAVPlaybackState
getAVPlaybackState(): Promise
\<
AVPlaybackState>
获取当前会话播放状态相关信息。结果通过Promise异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**返回值:**
| 类型 | 说明 |
| --------------------------------------------- | --------------------------- |
| Promise<
[
AVPlaybackState
](
#avplaybackstate
)
\>
| Promise对象。返回播放状态对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
| 6600103 | The session controller does not exist |
**示例:**
```
js
controller
.
getAVPlaybackState
().
then
((
playbackState
)
=>
{
console
.
info
(
`GetAVPlaybackState : SUCCESS : state :
${
playbackState
.
state
}
`
);
}).
catch
((
err
)
=>
{
console
.
info
(
`GetAVPlaybackState BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
### getAVPlaybackState
getAVPlaybackState(callback: AsyncCallback
\<
AVPlaybackState>): void
获取当前播放状态相关信息。结果通过callback异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------------------------------- | ---- | ---------------------------- |
| callback | AsyncCallback<
[
AVPlaybackState
](
#avplaybackstate
)
\>
| 是 | 回调函数,返回当前播放状态对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
| 6600103 | The session controller does not exist |
**示例:**
```
js
controller
.
getAVPlaybackState
(
function
(
err
,
playbackState
)
{
if
(
err
)
{
console
.
info
(
`GetAVPlaybackState BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
console
.
info
(
`GetAVPlaybackState : SUCCESS : state :
${
playbackState
.
state
}
`
);
}
});
```
### getAVMetadata
getAVMetadata(): Promise
\<
AVMetadata>
获取会话元数据。结果通过Promise异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**返回值:**
| 类型 | 说明 |
| ----------------------------------- | ----------------------------- |
| Promise<
[
AVMetadata
](
#avmetadata
)
\>
| Promise对象,返回会话元数据。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
| 6600103 | The session controller does not exist |
**示例:**
```
js
controller
.
getAVMetadata
().
then
((
metadata
)
=>
{
console
.
info
(
`GetAVMetadata : SUCCESS : assetId :
${
metadata
.
assetId
}
`
);
}).
catch
((
err
)
=>
{
console
.
info
(
`GetAVMetadata BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
### getAVMetadata
getAVMetadata(callback: AsyncCallback
\<
AVMetadata>): void
获取会话元数据。结果通过callback异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------------------------------- | ---- | -------------------------- |
| callback | AsyncCallback<
[
AVMetadata
](
#avmetadata
)
\>
| 是 | 回调函数,返回会话元数据。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
| 6600103 | The session controller does not exist |
**示例:**
```
js
controller
.
getAVMetadata
(
function
(
err
,
metadata
)
{
if
(
err
)
{
console
.
info
(
`GetAVMetadata BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
console
.
info
(
`GetAVMetadata : SUCCESS : assetId :
${
metadata
.
assetId
}
`
);
}
});
```
### getOutputDevice
getOutputDevice(): Promise
\<
OutputDeviceInfo>
获取播放设备信息。结果通过Promise异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**返回值:**
| 类型 | 说明 |
| ----------------------------------------------- | --------------------------------- |
| Promise<
[
OutputDeviceInfo
](
#outputdeviceinfo
)
\>
| Promise对象,返回播放设备信息。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600103 | The session controller does not exist |
**示例:**
```
js
controller
.
getOutputDevice
().
then
((
deviceInfo
)
=>
{
console
.
info
(
`GetOutputDevice : SUCCESS : isRemote :
${
deviceInfo
.
isRemote
}
`
);
}).
catch
((
err
)
=>
{
console
.
info
(
`GetOutputDevice BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
### getOutputDevice
getOutputDevice(callback: AsyncCallback
\<
OutputDeviceInfo>): void
获取播放设备信息。结果通过callback异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------------------------------------------- | ---- | ------------------------------ |
| callback | AsyncCallback<
[
OutputDeviceInfo
](
#outputdeviceinfo
)
\>
| 是 | 回调函数,返回播放设备信息。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600103 | The session controller does not exist |
**示例:**
```
js
controller
.
getOutputDevice
(
function
(
err
,
deviceInfo
)
{
if
(
err
)
{
console
.
info
(
`GetOutputDevice BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
console
.
info
(
`GetOutputDevice : SUCCESS : isRemote :
${
deviceInfo
.
isRemote
}
`
);
}
});
```
### sendAVKeyEvent
sendAVKeyEvent(event: KeyEvent): Promise
\<
void>
发送按键事件到控制器对应的会话。结果通过Promise异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------------------------------------------------------------ | ---- | ---------- |
| event |
[
KeyEvent
](
js-apis-keyevent.md
)
| 是 | 按键事件。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
| 6600103 | The session controller does not exist |
| 6600105 | Invalid session command |
| 6600106 | The session not active |
**返回值:**
| 类型 | 说明 |
| -------------- | ----------------------------- |
| Promise<void
\>
| Promise对象。当事件发送成功,无返回结果,否则返回错误对象。 |
**示例:**
```
js
let
keyItem
=
{
code
:
0x49
,
pressedTime
:
2
,
deviceId
:
0
};
let
event
=
{
action
:
2
,
key
:
keyItem
,
keys
:[
keyItem
]};
controller
.
sendAVKeyEvent
(
event
).
then
(()
=>
{
console
.
info
(
'
SendAVKeyEvent Successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`SendAVKeyEvent BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
### sendAVKeyEvent
sendAVKeyEvent(event: KeyEvent, callback: AsyncCallback
\<
void>): void
发送按键事件到会话。结果通过callback异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------------ | ---- | ---------- |
| event |
[
KeyEvent
](
js-apis-keyevent.md
)
| 是 | 按键事件。 |
| callback | AsyncCallback<void
\>
| 是 | 回调函数。当事件发送成功,err为undefined,否则返回错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
| 6600103 | The session controller does not exist |
| 6600105 | Invalid session command |
| 6600106 | The session not active |
**示例:**
```
js
let
keyItem
=
{
code
:
0x49
,
pressedTime
:
2
,
deviceId
:
0
};
let
event
=
{
action
:
2
,
key
:
keyItem
,
keys
:[
keyItem
]};
controller
.
sendAVKeyEvent
(
event
,
function
(
err
)
{
if
(
err
)
{
console
.
info
(
`SendAVKeyEvent BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
console
.
info
(
'
SendAVKeyEvent Successfully
'
);
}
});
```
### getLaunchAbility
getLaunchAbility(): Promise
\<
WantAgent>
获取应用在会话中保存的WantAgent对象。结果通过Promise异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**返回值:**
| 类型 | 说明 |
| ------------------------------------------- | ------------------------------------------------------------ |
| Promise<
[
WantAgent
](
js-apis-wantAgent.md
)
\>
| Promise对象,返回在
[
setLaunchAbility
](
#setlaunchability
)
保存的对象,包括应用的相关属性信息,如bundleName,abilityName,deviceId等。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
| 6600103 | The session controller does not exist |
**示例:**
```
js
import
wantAgent
from
'
@ohos.wantAgent
'
;
controller
.
getLaunchAbility
().
then
((
agent
)
=>
{
console
.
info
(
`GetLaunchAbility : SUCCESS : wantAgent :
${
agent
}
`
);
}).
catch
((
err
)
=>
{
console
.
info
(
`GetLaunchAbility BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
### getLaunchAbility
getLaunchAbility(callback: AsyncCallback
\<
WantAgent>): void
获取应用在会话中保存的WantAgent对象。结果通过callback异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------- | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback<
[
WantAgent
](
js-apis-wantAgent.md
)
\>
| 是 | 回调函数。返回在
[
setLaunchAbility
](
#setlaunchability
)
保存的对象,包括应用的相关属性信息,如bundleName,abilityName,deviceId等。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
| 6600103 | The session controller does not exist |
**示例:**
```
js
import
wantAgent
from
'
@ohos.wantAgent
'
;
controller
.
getLaunchAbility
(
function
(
err
,
agent
)
{
if
(
err
)
{
console
.
info
(
`GetLaunchAbility BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
console
.
info
(
`GetLaunchAbility : SUCCESS : wantAgent :
${
agent
}
`
);
}
});
```
### getRealPlaybackPositionSync
getRealPlaybackPositionSync(): number
获取当前播放位置。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**返回值:**
| 类型 | 说明 |
| ------ | ------------------ |
| number | 时间节点,毫秒数。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600103 | The session controller does not exist |
**示例:**
```
js
let
time
=
controller
.
getRealPlaybackPositionSync
();
```
### isActive
isActive(): Promise
\<
boolean>
获取会话是否被激活。结果通过Promise异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**返回值:**
| 类型 | 说明 |
| ----------------- | ------------------------------------------------------------ |
| Promise<boolean
\>
| Promise对象,返回会话是否为激活状态,true表示被激活,false表示禁用。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
| 6600103 | The session controller does not exist |
**示例:**
```
js
controller
.
isActive
().
then
((
isActive
)
=>
{
console
.
info
(
`IsActive : SUCCESS : isactive :
${
isActive
}
`
);
}).
catch
((
err
)
=>
{
console
.
info
(
`IsActive BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
### isActive
isActive(callback: AsyncCallback
\<
boolean>): void
判断会话是否被激活。结果通过callback异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------------- | ---- | ------------------------------------------------------------ |
| callback | AsyncCallback<boolean
\>
| 是 | 回调函数,返回会话是否为激活状态,true表示被激活,false表示禁用。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
| 6600103 | The session controller does not exist |
**示例:**
```
js
controller
.
isActive
(
function
(
err
,
isActive
)
{
if
(
err
)
{
console
.
info
(
`IsActive BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
console
.
info
(
`IsActive : SUCCESS : isactive :
${
isActive
}
`
);
}
});
```
### destroy
destroy(): Promise
\<
void>
销毁当前控制器,销毁后当前控制器不可再用。结果通过Promise异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**返回值:**
| 类型 | 说明 |
| -------------- | ----------------------------- |
| Promise<void
\>
| Promise对象。当控制器销毁成功,无返回结果,否则返回错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600103 | The session controller does not exist |
**示例:**
```
js
controller
.
destroy
().
then
(()
=>
{
console
.
info
(
'
Destroy : SUCCESS
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`Destroy BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
### destroy
destroy(callback: AsyncCallback
\<
void>): void
销毁当前控制器,销毁后当前控制器不可再用。结果通过callback异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------- | ---- | ---------- |
| callback | AsyncCallback<void
\>
| 是 | 回调函数。当控制器销毁成功,err为undefined,否则返回错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600103 | The session controller does not exist |
**示例:**
```
js
controller
.
destroy
(
function
(
err
)
{
if
(
err
)
{
console
.
info
(
`Destroy BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
console
.
info
(
'
Destroy : SUCCESS
'
);
}
});
```
### getValidCommands
getValidCommands(): Promise
\<
Array
\<
AVControlCommandType>>
获取会话支持的有效命令。结果通过Promise异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**返回值:**
| 类型 | 说明 |
| ------------------------------------------------------------ | --------------------------------- |
| Promise<Array<
[
AVControlCommandType
](
#avcontrolcommandtype
)
\>\>
| Promise对象。返回有效命令的集合。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
| 6600103 | The session controller does not exist |
**示例:**
```
js
controller
.
getValidCommands
.
then
((
validCommands
)
=>
{
console
.
info
(
`GetValidCommands : SUCCESS : size :
${
validCommands
.
length
}
`
);
}).
catch
((
err
)
=>
{
console
.
info
(
`GetValidCommands BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
### getValidCommands
getValidCommands(callback: AsyncCallback
\<
Array
\<
AVControlCommandType>>): void
获取会话支持的有效命令。结果通过callback异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------ |
| callback | AsyncCallback
\<
Array
\<
[
AVControlCommandType
](
#avcontrolcommandtype
)
\>\>
| 是 | 回调函数,返回有效命令的集合。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
| 6600103 | The session controller does not exist |
**示例:**
```
js
controller
.
getValidCommands
(
function
(
err
,
validCommands
)
{
if
(
err
)
{
console
.
info
(
`GetValidCommands BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
console
.
info
(
`GetValidCommands : SUCCESS : size :
${
validCommands
.
length
}
`
);
}
});
```
### sendControlCommand
sendControlCommand(command: AVControlCommand): Promise
\<
void>
通过控制器发送命令到其对应的会话。结果通过Promise异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 名称 | 类型 | 必填 | 说明 |
| ------- | ------------------------------------- | ---- | ------------------------------ |
| command |
[
AVControlCommand
](
#avcontrolcommand
)
| 是 | 会话的相关命令和命令相关参数。 |
**返回值:**
| 类型 | 说明 |
| -------------- | ----------------------------- |
| Promise<void
\>
| Promise对象。当命令发送成功,无返回结果,否则返回错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
| 6600103 | The session controller does not exist |
| 6600105 | Invalid session command |
| 6600106 | The session not active |
| 6600107 | Command or event overload |
**示例:**
```
js
let
avCommand
=
{
command
:
'
play
'
};
// let avCommand = {command:'pause'};
// let avCommand = {command:'stop'};
// let avCommand = {command:'playNext'};
// let avCommand = {command:'playPrevious'};
// let avCommand = {command:'fastForward'};
// let avCommand = {command:'rewind'};
// let avCommand = {command:'seek', parameter:10};
// let avCommand = {command:'setSpeed', parameter:2.6};
// let avCommand = {command:'setLoopMode', parameter:avSession.LoopMode.LOOP_MODE_SINGLE};
// let avCommand = {command:'toggleFavorite', parameter:"false"};
controller
.
sendControlCommand
(
avCommand
).
then
(()
=>
{
console
.
info
(
'
SendControlCommand successfully
'
);
}).
catch
((
err
)
=>
{
console
.
info
(
`SendControlCommand BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
});
```
### sendControlCommand
sendControlCommand(command: AVControlCommand, callback: AsyncCallback
\<
void>): void
通过会话控制器发送命令到其对应的会话。结果通过callback异步回调方式返回。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------- | ---- | ------------------------------ |
| command |
[
AVControlCommand
](
#avcontrolcommand
)
| 是 | 会话的相关命令和命令相关参数。 |
| callback | AsyncCallback<void
\>
| 是 | 回调函数。当命令发送成功,err为undefined,否则返回错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ------------------------------- |
| 6600101 | Session service exception |
| 6600102 | The session does not exist |
| 6600103 | The session controller does not exist |
| 6600105 | Invalid session command |
| 6600106 | The session not active |
| 6600107 | Command or event overload |
**示例:**
```
js
let
avCommand
=
{
command
:
'
play
'
};
// let avCommand = {command:'pause'};
// let avCommand = {command:'stop'};
// let avCommand = {command:'playNext'};
// let avCommand = {command:'playPrevious'};
// let avCommand = {command:'fastForward'};
// let avCommand = {command:'rewind'};
// let avCommand = {command:'seek', parameter:10};
// let avCommand = {command:'setSpeed', parameter:2.6};
// let avCommand = {command:'setLoopMode', parameter:avSession.LoopMode.LOOP_MODE_SINGLE};
// let avCommand = {command:'toggleFavorite', parameter:"false"};
controller
.
sendControlCommand
(
avCommand
,
function
(
err
)
{
if
(
err
)
{
console
.
info
(
`SendControlCommand BusinessError: code:
${
err
.
code
}
, message:
${
err
.
message
}
`
);
}
else
{
console
.
info
(
'
SendControlCommand successfully
'
);
}
});
```
### on('metadataChange')
on(type: 'metadataChange', filter: Array
\<
keyof AVMetadata> | 'all', callback: (data: AVMetadata) => void)
设置元数据变化的监听事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 事件回调类型,支持事件
`'metadataChange'`
:当元数据变化时,触发该事件。 |
| filter | Array
\<
keyof
[AVMetadata](#avmetadata)\>
|
'all' | 是 | 'all' 表示关注元数据所有字段变化;Array<keyof
[
AVMetadata
](
#avmetadata
)
\>
表示关注Array中的字段变化。 |
| callback | (data:
[
AVMetadata
](
#avmetadata
)
) => void | 是 | 回调函数,参数data是变化后的元数据。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ------------------------------ |
| 6600101 | Session service exception |
| 6600103 | The session controller does not exist |
**示例:**
```
js
controller
.
on
(
'
metadataChange
'
,
'
all
'
,
(
metadata
)
=>
{
console
.
info
(
`on metadataChange assetId :
${
metadata
.
assetId
}
`
);
});
let
metaFilter
=
[
'
assetId
'
,
'
title
'
,
'
description
'
];
controller
.
on
(
'
metadataChange
'
,
metaFilter
,
(
metadata
)
=>
{
console
.
info
(
`on metadataChange assetId :
${
metadata
.
assetId
}
`
);
});
```
### on('playbackStateChange')
on(type: 'playbackStateChange', filter: Array
\<
keyof AVPlaybackState> | 'all', callback: (state: AVPlaybackState) => void)
设置播放状态变化的监听事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 事件回调类型,支持事件
`'playbackStateChange'`
:当播放状态变化时,触发该事件。 |
| filter | Array
\<
keyof
[AVPlaybackState](#avplaybackstate)\>
|
'all' | 是 | 'all' 表示关注播放状态所有字段变化;Array<keyof
[
AVPlaybackState
](
#avplaybackstate
)
\>
表示关注Array中的字段变化。 |
| callback | (state:
[
AVPlaybackState
](
#avplaybackstate
)
) => void | 是 | 回调函数,参数state是变化后的播放状态。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ------------------------------ |
| 6600101 | Session service exception |
| 6600103 | The session controller does not exist |
**示例:**
```
js
controller
.
on
(
'
playbackStateChange
'
,
'
all
'
,
(
playbackState
)
=>
{
console
.
info
(
`on playbackStateChange state :
${
playbackState
.
state
}
`
);
});
let
playbackFilter
=
[
'
state
'
,
'
speed
'
,
'
loopMode
'
];
controller
.
on
(
'
playbackStateChange
'
,
playbackFilter
,
(
playbackState
)
=>
{
console
.
info
(
`on playbackStateChange state :
${
playbackState
.
state
}
`
);
});
```
### on('sessionDestroy')
on(type: 'sessionDestroy', callback: () => void)
会话销毁的监听事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ---------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 事件回调类型,支持事件
`'sessionDestroy'`
:当检测到会话销毁时,触发该事件)。 |
| callback | () => void | 是 | 回调函数。当监听事件注册成功,err为undefined,否则为错误对象。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ------------------------------ |
| 6600101 | Session service exception |
| 6600103 | The session controller does not exist |
**示例:**
```
js
controller
.
on
(
'
sessionDestroy
'
,
()
=>
{
console
.
info
(
'
on sessionDestroy : SUCCESS
'
);
});
```
### on('activeStateChange')
on(type: 'activeStateChange', callback: (isActive: boolean) => void)
会话的激活状态的监听事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 事件回调类型,支持事件
`'activeStateChange'`
:当检测到会话的激活状态发生改变时,触发该事件。 |
| callback | (isActive: boolean) => void | 是 | 回调函数。参数isActive表示会话是否被激活。true表示被激活,false表示禁用。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ----------------------------- |
| 6600101 | Session service exception |
| 6600103 |The session controller does not exist |
**示例:**
```
js
controller
.
on
(
'
activeStateChange
'
,
(
isActive
)
=>
{
console
.
info
(
`on activeStateChange : SUCCESS : isActive
${
isActive
}
`
);
});
```
### on('validCommandChange')
on(type: 'validCommandChange', callback: (commands: Array
\<
AVControlCommandType>) => void)
会话支持的有效命令变化监听事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 事件回调类型,支持事件
`'validCommandChange'`
:当检测到会话的合法命令发生改变时,触发该事件。 |
| callback | (commands: Array
<
[
AVControlCommandType
](
#avcontrolcommandtype
)\
>
) => void | 是 | 回调函数。参数commands是有效命令的集合。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ------------------------------ |
| 6600101 | Session service exception |
| 6600103 | The session controller does not exist |
**示例:**
```
js
controller
.
on
(
'
validCommandChange
'
,
(
validCommands
)
=>
{
console
.
info
(
`validCommandChange : SUCCESS : size :
${
validCommands
.
size
}
`
);
console
.
info
(
`validCommandChange : SUCCESS : validCommands :
${
validCommands
.
values
()}
`
);
});
```
### on('outputDeviceChange')
on(type: 'outputDeviceChange', callback: (device: OutputDeviceInfo) => void): void
设置播放设备变化的监听事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 事件回调类型,支持事件为
`'outputDeviceChange'`
:当播放设备变化时,触发该事件)。 |
| callback | (device:
[
OutputDeviceInfo
](
#outputdeviceinfo
)
) => void | 是 | 回调函数,参数device是设备相关信息。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ----------------------- |
| 6600101 | Session service exception |
| 6600103 | The session controller does not exist |
**示例:**
```
js
controller
.
on
(
'
outputDeviceChange
'
,
(
device
)
=>
{
console
.
info
(
`on outputDeviceChange device isRemote :
${
device
.
isRemote
}
`
);
});
```
### off('metadataChange')
off(type: 'metadataChange', callback?: (data: AVMetadata) => void)
控制器取消监听元数据变化的事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------ | ---- | ------------------------------------------------------ |
| type | string | 是 | 取消对应的监听事件,支持事件
`'metadataChange'`
。 |
| callback | (data:
[
AVMetadata
](
#avmetadata
)
) => void | 否 | 回调函数,参数data是变化后的元数据。
<br>
该参数为可选参数,若不填写该参数,则认为取消所有相关会话的事件监听。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------- |
| 6600101 | Session service exception |
**示例:**
```
js
controller
.
off
(
'
metadataChange
'
);
```
### off('playbackStateChange')
off(type: 'playbackStateChange', callback?: (state: AVPlaybackState) => void)
控制器取消监听播放状态变化的事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------------ | ---- | ----------------------------------------------------- |
| type | string | 是 | 取消对应的监听事件,支持事件
`'playbackStateChange'`
。 |
| callback | (state:
[
AVPlaybackState
](
#avplaybackstate
)
) => void | 否 | 回调函数,参数state是变化后的播放状态。
<br>
该参数为可选参数,若不填写该参数,则认为取消所有相关会话的事件监听。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------- |
| 6600101 | Session service exception |
**示例:**
```
js
controller
.
off
(
'
playbackStateChange
'
);
```
### off('sessionDestroy')
off(type: 'sessionDestroy', callback?: () => void)
控制器取消监听会话的销毁事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ---------- | ---- | ----------------------------------------------------- |
| type | string | 是 | 取消对应的监听事件,支持事件
`'sessionDestroy'`
。 |
| callback | () => void | 否 | 回调函数。当监听事件取消成功,err为undefined,否则返回错误对象。
<br>
该参数为可选参数,若不填写该参数,则认为取消所有相关会话的事件监听。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------- |
| 6600101 | Session service exception |
**示例:**
```
js
controller
.
off
(
'
sessionDestroy
'
);
```
### off('activeStateChange')
off(type: 'activeStateChange', callback?: (isActive: boolean) => void)
控制器取消监听会话激活状态变化的事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | --------------------------- | ---- | ----------------------------------------------------- |
| type | string | 是 | 取消对应的监听事件,支持事件
`'activeStateChange'`
。 |
| callback | (isActive: boolean) => void | 否 | 回调函数。参数isActive表示会话是否被激活。true表示被激活,false表示禁用。
<br>
该参数为可选参数,若不填写该参数,则认为取消所有相关会话的事件监听。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------- |
| 6600101 | Session service exception |
**示例:**
```
js
controller
.
off
(
'
activeStateChange
'
);
```
### off('validCommandChange')
off(type: 'validCommandChange', callback?: (commands: Array
\<
AVControlCommandType>) => void)
控制器取消监听会话有效命令变化的事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------------ | ---- | -------------------------------------------------------- |
| type | string | 是 | 取消对应的监听事件,支持事件
`'validCommandChange'`
。 |
| callback | (commands: Array
<
[
AVControlCommandType
](
#avcontrolcommandtype
)\
>
) => void | 否 | 回调函数。参数commands是有效命令的集合。
<br>
该参数为可选参数,若不填写该参数,则认为取消所有相关会话的事件监听。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------- |
| 6600101 | Session service exception |
**示例:**
```
js
controller
.
off
(
'
validCommandChange
'
);
```
### off('outputDeviceChange')
off(type: 'outputDeviceChange', callback?: (device: OutputDeviceInfo) => void): void
控制器取消监听分布式设备变化的事件。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------- | ---- | ------------------------------------------------------ |
| type | string | 是 | 取消对应的监听事件,支持事件
`'outputDeviceChange'`
。 |
| callback | (device:
[
OutputDeviceInfo
](
#outputdeviceinfo
)
) => void | 否 | 回调函数,参数device是设备相关信息。
<br>
该参数为可选参数,若不填写该参数,则认为取消所有相关会话的事件监听。 |
**错误码:**
以下错误码的详细介绍请参见
[
ohos.multimedia.avsession(多媒体会话)错误码
](
../errorcodes/errorcode-avsession.md
)
。
| 错误码ID | 错误信息 |
| -------- | ---------------- |
| 6600101 | Session service exception |
**示例:**
```
js
controller
.
off
(
'
outputDeviceChange
'
);
```
## SessionToken
会话令牌的信息。
**需要权限:**
ohos.permission.MANAGE_MEDIA_RESOURCES,仅系统应用可用。
**系统能力:**
SystemCapability.Multimedia.AVSession.Manager
**系统接口:**
该接口为系统接口。
| 名称 | 类型 | 必填 | 说明 |
| :-------- | :----- | :--- | :----------- |
| sessionId | string | 是 | 会话ID |
| pid | number | 是 | 会话的进程ID |
| uid | number | 是 | 用户ID |
## AVSessionType
当前会话支持的会话类型。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
| 名称 | 类型 | 说明 |
| ----- | ------ | ---- |
| audio | string | 音频 |
| video | string | 视频 |
## AVSessionDescriptor
会话的相关描述信息。
**系统能力:**
SystemCapability.Multimedia.AVSession.Manager
**系统接口:**
该接口为系统接口。
| 名称 | 类型 | 可读 | 可写 | 说明 |
| ------------ | ------------------------------------------------------------ | ---- | --------------------------------------------------- | --------------------------------------------------- |
| sessionId | string | 是 | 否 | 会话ID |
| type |
[
AVSessionType
](
#avsessiontype
)
| 是 | 否 | 会话类型 |
| sessionTag | string | 是 | 否 | 会话的自定义名称 |
| elementName |
[
ElementName
](
js-apis-bundle-ElementName.md
)
| 是 | 否 | 会话所属应用的信息(包含bundleName、abilityName等) |
| isActive | boolean | 是 | 否 | 会话是否被激活 |
| isTopSession | boolean | 是 | 否 | 会话是否为最新的会话 |
| outputDevice |
[
OutputDeviceInfo
](
#outputdeviceinfo
)
| 是 | 否 | 分布式设备相关信息 |
## AVControlCommandType
会话可传递的命令。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
| 名称 | 类型 | 说明 |
| -------------- | ------ | ------------ |
| play | string | 播放 |
| pause | string | 暂停 |
| stop | string | 停止 |
| playNext | string | 下一首 |
| playPrevious | string | 上一首 |
| fastForward | string | 快进 |
| rewind | string | 快退 |
| seek | string | 跳转某一节点 |
| setSpeed | string | 设置播放倍速 |
| setLoopMode | string | 设置循环模式 |
| toggleFavorite | string | 是否收藏 |
## AVControlCommand
会话接受的命令的对象描述。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
| 名称 | 类型 | 必填 | 说明 |
| --------- | ------------------------------------------------- | ---- | -------------- |
| command |
[
AVControlCommandType
](
#avcontrolcommandtype
)
| 是 | 命令 |
| parameter |
[
LoopMode
](
#loopmode
)
|
string
|
number | 否 | 命令对应的参数 |
## AVMetadata
媒体元数据的相关属性。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
| 名称 | 类型 | 必填 | 说明 |
| --------------- |-------------------------| ---- |---------------------------------------------------------------------|
| assetId | string | 是 | 媒体ID。 |
| title | string | 否 | 标题。 |
| artist | string | 否 | 艺术家。 |
| author | string | 否 | 专辑作者。 |
| album | string | 否 | 专辑名称。 |
| writer | string | 否 | 词作者。 |
| composer | string | 否 | 作曲者。 |
| duration | string | 否 | 媒体时长,单位毫秒(ms)。 |
| mediaImage | image.PixelMap
|
string | 否 | 图片的像素数据或者图片路径地址(本地路径或网络路径)。 |
| publishDate | Date | 否 | 发行日期。 |
| subtitle | string | 否 | 子标题。 |
| description | string | 否 | 媒体描述。 |
| lyric | string | 否 | 歌词文件路径地址(本地路径或网络路径) |
| previousAssetId | string | 否 | 上一首媒体ID。 |
| nextAssetId | string | 否 | 下一首媒体ID。 |
## AVPlaybackState
媒体播放状态的相关属性。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
| 名称 | 类型 | 必填 | 说明 |
| ------------ | ------------------------------------- | ---- | ------- |
| state |
[
PlaybackState
](
#playbackstate
)
| 否 | 播放状态 |
| speed | number | 否 | 播放倍速 |
| position |
[
PlaybackPosition
](
#playbackposition
)
| 否 | 播放位置 |
| bufferedTime | number | 否 | 缓冲时间 |
| loopMode |
[
LoopMode
](
#loopmode
)
| 否 | 循环模式 |
| isFavorite | boolean | 否 | 是否收藏 |
## PlaybackPosition
媒体播放位置的相关属性。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
| 名称 | 类型 | 必填 | 说明 |
| ----------- | ------ | ---- | ------------------ |
| elapsedTime | number | 是 | 已用时间,单位毫秒(ms)。 |
| updateTime | number | 是 | 更新时间,单位毫秒(ms)。 |
## OutputDeviceInfo
播放设备的相关信息。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
| 名称 | 类型 | 必填 | 说明 |
| ---------- | -------------- | ---- | ---------------------- |
| isRemote | boolean | 是 | 设备是否连接。 |
| audioDeviceId | Array<number
\>
| 是 | 播放设备的ID集合。 |
| deviceName | Array<string
\>
| 是 | 播放设备的名称集合。 |
## PlaybackState
表示媒体播放状态的枚举。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
| 名称 | 值 | 说明 |
| --------------------------- | ---- | ----------- |
| PLAYBACK_STATE_INITIAL | 0 | 初始状态 |
| PLAYBACK_STATE_PREPARE | 1 | 播放准备状态 |
| PLAYBACK_STATE_PLAY | 2 | 正在播放 |
| PLAYBACK_STATE_PAUSE | 3 | 暂停 |
| PLAYBACK_STATE_FAST_FORWARD | 4 | 快进 |
| PLAYBACK_STATE_REWIND | 5 | 快退 |
| PLAYBACK_STATE_STOP | 6 | 停止 |
## LoopMode
表示媒体播放循环模式的枚举。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
| 名称 | 值 | 说明 |
| ------------------ | ---- | -------- |
| LOOP_MODE_SEQUENCE | 0 | 顺序播放 |
| LOOP_MODE_SINGLE | 1 | 单曲循环 |
| LOOP_MODE_LIST | 2 | 表单循环 |
| LOOP_MODE_SHUFFLE | 3 | 随机播放 |
## AVSessionErrorCode
会话发生错误时的错误码。
**系统能力:**
SystemCapability.Multimedia.AVSession.Core
| 名称 | 值 | 说明 |
| ------------------------------ | ------- | ------------------------------- |
| ERR_CODE_SERVICE_EXCEPTION | 6600101 | Session service exception |
| ERR_CODE_SESSION_NOT_EXIST | 6600102 | The session does not exist |
| ERR_CODE_CONTROLLER_NOT_EXIST | 6600103 | The session controller does not exist |
| ERR_CODE_REMOTE_CONNECTION_ERR | 6600104 | The remote session connection failed |
| ERR_CODE_COMMAND_INVALID | 6600105 | Invalid session command |
| ERR_CODE_SESSION_INACTIVE | 6600106 | The session not active |
| ERR_CODE_MESSAGE_OVERLOAD | 6600107 | Command or event overload |
\ No newline at end of file
zh-cn/application-dev/reference/errorcodes/errorcode-avsession.md
0 → 100644
浏览文件 @
aebb8f20
# 媒体会话管理错误码
## 6600101 会话服务端异常
**错误信息**
Session service exception
**错误描述**
会话服务端异常,应用端无法获取服务端的消息响应。如会话服务未运行或者会话服务通信失败。
**可能原因**
会话重启过程中服务被杀。
**处理步骤**
1.
定时重试,超过3s仍失败时,停止对该会话或者控制器进行操作。
2.
销毁当前会话或者会话控制器,并重新创建,如果重新创建失败,则停止会话相关操作。
## 6600102 会话不存在
**错误信息**
The session does not exist
**错误描述**
会话对象不存在时,向该会话设置参数或者发送命令。
**可能原因**
会话已被销毁,服务端无会话记录。
**处理步骤**
1.
如果在会话被控端产生该错误,请重新创建会话;如果是会话控制端,请停止向该会话发送查询或者控制命令。
2.
如果在会话管理端产生该错误,请重新查询系统当前会话记录,在创建控制器时传入正确的会话ID。
## 6600103 会话控制器不存在
**错误信息**
The session controller does not exist
**错误描述**
会话控制器不存在时,向该控制器发送控制命令或者事件。
**可能原因**
控制器已被销毁。
**处理步骤**
请重新查询系统当前会话记录,并创建对应的会话控制器。
## 6600104 远端会话连接失败
**错误信息**
The remote session connection failed
**错误描述**
本端会话与远端会话通信失败。
**可能原因**
设备间通信断开。
**处理步骤**
停止对该会话发送控制命令,并监听输出设备变化,当输出设备发送变化后恢复发送。
## 6600105 无效会话命令
**错误信息**
Invalid session command
**错误描述**
会话被控端不支持该被控命令或事件。
**可能原因**
被控端不支持该命令。
**处理步骤**
停止发送该命令或事件,并查询被控会话支持的命令集,发送被控端支持的命令。
## 6600106 会话未激活
**错误信息**
The session not active
**错误描述**
会话没有激活时,向会话发送控制命令或者事件。
**可能原因**
会话处于未激活状态。
**处理步骤**
停止发送该命令或事件,监听会话的激活状态,会话激活后恢复发送该命令或事件。
## 6600107 命令&消息过载
**错误信息**
Command or event overload
**错误描述**
会话客户端在一段时间内向服务端发送了过多的消息或者命令,引起服务端消息过载。
**可能原因**
服务端消息过载。
**处理步骤**
检查自身命令发送是否过于频繁,控制自身查询和控制命令的发送频度。
\ No newline at end of file
编辑
预览
Markdown
is supported
0%
请重试
或
添加新附件
.
添加附件
取消
You are about to add
0
people
to the discussion. Proceed with caution.
先完成此消息的编辑!
取消
想要评论请
注册
或
登录