基础播控
====

#### 媒体封面

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/41/v3/6FM_xbumQiigxEc2m2UkGw/notice_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=63F6DAA99C2E8CCD43CE99680199B5644AF9753691992AA3D5F9BFDC7D33592A)

**自验证关注点：** 播放过程中查看播控中心是否显示媒体封面，封面图是否清晰。

应用提供媒体内容的封面图片（[AVMetadata.mediaImage](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-avsession-i#avmetadata10)），如音乐专辑封面、视频海报等。如果应用提供的媒体封面比例或分辨率不满足要求，将会被自动缩放、裁切到合适大小。这可能导致封面图片内的信息损失或模糊，体验下降。mediaImage设置PixelMap性能更优。

音乐类媒体内容应提供比例为 1:1 的方形封面图片，建议分辨率为 800px \* 800px（如果应用提供的图片分辨率更大，将被压缩到 800px \* 800px 显示），最小分辨率是 300px \* 300px。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/ab/v3/_QeNahBYRdS4PZFwi6nkWQ/zh-cn_image_0000002625108331.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=7C8DBA911EC174EEFFB9071910A43FF80495226B893C92276999FA402D650F52)

视频及其他类型的媒体内容除了上述建议分辨率的方形模板外，还支持纵向及横向的矩形封面模板。

纵向矩形模板的宽高比为13:18，如小于此比例，将会被自动缩放、裁切到该比例。

横向矩形模板的宽高比为16:9，如大于此比例，将会被自动缩放、裁切到该比例。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/b1/v3/t6P7Tb4dQNaBOeS1zS1ypg/zh-cn_image_0000002594668814.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=AA9C16021E87006A2A199AF63C956F4BB794522E21A24E0AB220A13C09D057CC)

#### 主标题

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/47/v3/fHTwFl7PRTGGDg389nyzdg/notice_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=93ACE6A875BB391550CDA3DA0C1DC20D5C6C133B8327DCCC76F1B19603331914)

**自验证关注点：** 播放过程中查看播控中心是否显示主标题，显示是否正确。

主标题（[AVMetadata.title](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-avsession-i#avmetadata10)）用于显示歌曲名、影片名等内容名称，直播应用也可设置直播间名等，用于向用户展示当前正在播放的媒体内容，建议采用简短的字符串。字符串超长时会从右向左滚动显示。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/d7/v3/q5m31EpaTvqX2Jl_mM9rvQ/zh-cn_image_0000002594828742.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=C285FCBC4228BB120BEF0963AAD7981FE356D3540E6D0133D07C8AC85B2AF67B)

#### 进度与时间

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/1a/v3/7GU8igx5RsSURQUvS4OJTA/notice_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=4827C3309725C1630A5E728BC5910499E183EC503B41D8F7D9766C86AAE9EE45)

**自验证关注点：** 播放过程中查看播控中心进度条是否正常显示，是否支持拖拽，拖拽后是否正确响应，不出现进度条回弹、抖动等。

**进度的显示**

播控中心支持显示如下三种形式的进度条，为保证用户体验，应用需尽量支持第一种进度条。

1.  应用内本身支持进度调节，提供当前播放的媒体内容的播放时长（[AVMetadata.duration](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-avsession-i#avmetadata10)），注册进度控制（[seek](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-avsession-avsession#onseek10)）。播控显示第一种可拖动进度条。
    
2.  应用内本身不支持进度调节，可提供当前播放的媒体内容播放时长，不注册进度控制。播控显示第二种不可拖动，但进度随时间自动前进的进度条。
    
3.  应用内本身不支持进度调节，且无法获取媒体内容播放时长（如直播），可不提供媒体播放时长，不注册进度控制。播控显示第三种进度条，告知用户当前进度条不可使用。
    

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/b3/v3/miEtXtJ8QgKEdrZx35g22g/zh-cn_image_0000002625188189.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=6085E1476F5AEA362BC5CB1140DE3AD75161F8F879E6C7CD5D9D2F442415194C)

**进度的控制**

第一种可拖动进度条，表示用户可通过播控中心，调节应用媒体播放进度。为了达到进度调节的一致体验，请参考如下内容开发：

1.  应用不需要通过[AVPlaybackState](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-avsession-i#avplaybackstate10)实时设置进度，播控中心会根据应用设置的信息自行进行播放进度的计算。只需要在应用播放状态、播放进度、倍速发生变化时，再更新AVPlaybackState。
    
    如：
    
    （1）应用播放、暂停时需要设置播放状态或暂停状态，及当前播放或暂停时的进度。
    
    （2）用户通过播控中心调节进度条，应用收到调节的回调，或在应用内调节进度条，应用都需要通知播控当前调节完毕的状态与进度。
    
    （3）应用在真实播放开始时，再设置起始进度；若播放存在缓冲状态，可以先上报播放状态为[PLAYBACK\_STATE\_BUFFERING](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-avsession-e#playbackstate10)，来通知播控显示为播放但不走进度。
    
2.  VIP/广告进度处理。
    
    *   支持试听/试看
        
        a. 应用不需要设置完整的歌曲时长，则只需要设置歌曲的试听时长。当应用仅设置歌曲的试听时长而不是完整时长，用户在播控中心触发进度控制时，应用收到的时长也是VIP试听时长内的相对时间戳位置，而不是完整歌曲的绝对时间戳位置，应用需要重新计算歌曲从零开始的绝对时间戳进行实际响应处理。
        
        b. 如果应用设置完整歌曲时长，但需要系统支持试听片段，也可以在播放时上报起始进度position，当收到的seek指令超过试听片段时，上报试听截止position，系统播控的进度会跟随回弹。
        
    *   不支持试听/试看
        
        等同于不支持进度条，可按照第三种进度显示接入。
        
    *   支持广告
        
        *   播放广告时，单独设置广告的时长duration。
        *   当进入到正片播放的时候，则重新设置一次新的时长，以与广告进行区分。

#### 副标题

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/57/v3/QY7hSwp5R2eiqOptvwJOxA/notice_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=F039CE17545716EEF56DED1C4A52A6C46391DFA32B98F92E279D3CF8F419275E)

**自验证关注点：** 播放过程中查看播控中心是否显示副标题，显示是否正确。

副标题用于显示媒体内容的辅助信息，如歌曲的歌手名、影片的发布者信息、剧集/综艺节目的选集信息等。可通过[AVMetadata.subtitle](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-avsession-i#avmetadata10)或者[AVMetadata.artist](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-avsession-i#avmetadata10)，选其一设置。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/4d/v3/ZBzlqrPzRS6N6DjFRYT6uQ/zh-cn_image_0000002625108333.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=92C05AF0FD2DFD2DD024C09BE4BFE66EB85D32C57D887EAD415A11FFC50F7944)

#### 滚动歌词

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/68/v3/owhu2uWuTHSijIs5vrhUyw/notice_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=1AA6F1F08D55B70EC7D706A961CED942E7FABE2BC6B7827EFF204D3C693672CB)

**自验证关注点：** 播放过程中查看播控中心是否显示歌词，显示是否正确，是否随进度正确刷新显示。

歌曲类媒体内容如有歌词信息，可以选择在副标题区域显示歌词。将当前播放歌曲的全曲歌词内容，按照标准lyric格式拼接为字符串，如\[00:25.44\]xxx\\r\\n\[00:26.44\]xxx\\r\\n，通过[AVMetadata.lyric](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-avsession-i#avmetadata10)设置给播控中心。播控中心会自动按照进度，在副标题位置刷新显示，应用不需要实现其余功能。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/2b/v3/d_d5C1awTdq2GkwlezGwKw/zh-cn_image_0000002594668816.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=6CD77317C4950D5DFA51519BF050C128D585933320422999AACBCA134D245BDC)

#### 媒体音源特殊标识

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/d8/v3/K9k1gFL_RpCNo3HaLhmPJw/notice_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=BC109C2F3356117AA05B6AC3FE4899DF05D0137DC5E6BFA9F8BCDE6EC2C1715D)

**自验证关注点：** 播放过程中查看播控中心是否显示“AudioVivid”等标识。

应用可以提供当前播放的媒体内容的资源标签信息（[AVMetadata.displayTags](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-avsession-i#avmetadata10)）。根据媒体资源的属性，应用可用提供标签信息以体现该媒体内容的特殊性，如：AudioVivid。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/63/v3/7na_i88oSviscU6aOq2-0Q/zh-cn_image_0000002594828744.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=A464F34873B8BF88E12D21F9D72A4F3BB63058C6FB75A86DAF615F5F942BDE06)

#### 播放/暂停

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/13/v3/pEDOUFouSW-90dHavhxnZQ/notice_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=8E3DA2B7461B5145344990B7BC31F21C184F73101BF3DCFA397AE12887625A30)

**自验证关注点：** 播放过程中，进入播控中心，点击播放暂停查看是否生效，状态是否与应用内对应。

应用需支持播控中心播放暂停，在接收到播控的播放/暂停回调，或者用户在应用内播放暂停，需上报当前的播放状态与进度。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/be/v3/5Sh5fnz3Qi-C4A-vFfhDug/zh-cn_image_0000002625188191.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=7C2CF1C8A8A469E24A4DBEA305A390D721E8383956EC4B5960D9242121963061)

#### 上下一首/集

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/7f/v3/vhtUrYabRKmS6wwZFfAbqQ/notice_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=81C7663DF3BC5EDCEAC4B77FCFB369DBC56FE3897ED53293894F2DB51ED2EAC4)

**自验证关注点：** 播放过程中，进入播控中心，点击上一首、下一首查看是否生效，播放内容是否与应用内对应。

应用按照内部实现，接入上下一首/集，在接收到播控的上下一首/集回调，或者用户在应用切歌切集时，需上报切换后新的媒体信息，播放状态、进度。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/44/v3/tXMkFXmNTl-JttSpTpiGnQ/zh-cn_image_0000002625108335.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=0846ABE5A4CA5BF49A2FFDC9A0BE1A0AAF6EFB86AA1C6429F153F2613E11E5F3)

#### 按钮置灰

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/99/v3/ogMSQFZ9QKWilpPUsdbhVQ/notice_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=47D561D4301249A319CD82F89AFDF6324D5F484D839AC2CC75CAEA55C1C63BA4)

**自验证关注点：** 播放过程中，进入播控中心，查看不支持的功能按钮是否已置灰。请按照自检表按应用类型接入必需的控制指令，以保障用户的体验。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/d6/v3/chPpbK8sRneGmnrGrz-IlA/zh-cn_image_0000002594668818.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=E8FDFCBE32987C8C483E40CB57243A11FAB5BDB3D8A8B9E47F1EB2F7DEAA834F)

应用按照内部实现，按需注册支持的播放控制指令。对于未注册的播放控制指令，在播控中心会显示为上图置灰样式，明确告知用户当前指令该应用不支持。具体实现可参考[应用接入AVSession-不支持命令的处理](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/avsession-access-scene#不支持命令的处理)。

#### 点击播控卡片跳转应用指定页面

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/ec/v3/13KsTfY6TnKuUbcmZOfEMQ/notice_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=BFAF0D6077762D47B956CE7B4CDC8EE2036DD02B45C2165A1BCE9E8088ED99D6)

**自验证关注点：** 播放过程中，进入播控中心，点击封面大图查看是否跳转至应用当前播放页面。

用户通过点击播控卡片，应跳转到应用的具体业务页，如：音乐/听书/视频的播放详情页，直播间页，新闻阅读播放页，浏览器具体tab页。具体实现可参考[媒体会话提供方-开发步骤](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/using-avsession-developer#开发步骤)的第3步。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/44/v3/8gDZ0NpdR0irz0XYle_4fg/zh-cn_image_0000002594828746.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=CE052953C70C55EBDCA5B359E98047CEA1EC614EF98A70D01C3036B8C4CED56A)

#### 收藏

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/80/v3/FRMNhoHsSQqF-Fpv0UltOQ/notice_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=ED618C1378F19291012DE5D63FFC1714935A3E74F3E9627A072CA7FC5CE928D3)

**自验证关注点：** 播放过程中，进入播控中心，点击收藏按钮，查看是否生效，是否与应用内同功能按钮状态一致。

音乐/听书类应用，如应用内支持收藏/喜欢功能，可按需适配播控的收藏功能，用户播放过程中可以通过播控中心点击收藏/取消收藏。应用适配收藏功能，接收到播控的收藏/取消收藏的回调，或者用户在应用内点击收藏/取消收藏，均需上报当前播放内容的收藏状态，保证应用与播控的显示一致。具体实现可参考[应用接入AVSession-收藏](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/avsession-access-scene#收藏)。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/6f/v3/Jf9KD_TOQKm1Y5933z-YCg/zh-cn_image_0000002625188193.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=825EA736B08ADF19458B3234E431525BE3B79E0C7D631D7B79344E2EE4C925C2)

#### 循环模式

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/c1/v3/ocATo3spSAWm2SA-_IfeRQ/notice_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=7F2706B505D1C7DFEB05331B8A8C7AF5CAFF956C532D54155D2F365AE645C23D)

**自验证关注点：** 播放过程中，进入播控中心，点击切换循环模式，查看是否生效。

音乐/听书类应用，如应用内支持播放模式的切换，可按需适配播控的循环模式切换功能。

播控可支持的播放模式有：顺序播放、列表循环、单曲循环、随机播放。

应用适配循环模式切换功能，收到播控中心循环模式切换的回调后，或用户在应用内切换循环模式时，按照应用内定义的顺序，向播控上报切换后的循环模式。

例：收到播控切换循环模式回调参数为列表循环，表示当前的循环模式，应用内下一个循环模式为随机播放，就切换到随机播放，并设置AVPlaybackState的LoopMode为随机播放。

若应用内支持的循环模式不在系统固定的四个循环模式内，需要选择四个固定循环模式其一向系统上报，由应用自定。

例：收到播控切换循环模式回调参数为列表循环，表示当前的循环模式，应用内下一个循环模式为心动模式，可上报为随机播放。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/68/v3/maBZvXaQR-GHChLt3EmK6g/zh-cn_image_0000002625108337.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=8470A7A42F215A086B12E9E90729CAB955AC881B631F4F707DD5BAFCEA42AE45)

#### 快进/快退

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/6d/v3/lHMeGpkSR8yqpRGhz-kHZQ/notice_3.0-zh-cn.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=3DBB916BC0E07D066ED178A8CA09B323A2B74AE9DB07F52FC707EDA5BC7FCC33)

**自验证关注点：** 播放过程中，进入播控中心，点击快进、快退查看是否正常响应，播控中心进度是否显示正确。

对于需要频繁调节播放进度的媒体内容（如播客、听书等长音频媒体，或长视频媒体），应用可以适配快进快退功能。

可选择快进快退的时间长度：[10s、15s、30s](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/arkts-apis-avsession-e#skipintervals11)。如下图显示。用户通过播控中心快进/快退，或在应用内快进快退，应用都需要通知播控当前调节完毕的状态与进度。

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/29/v3/6NZZlzrcQ8qNzlrxMUHGxg/zh-cn_image_0000002594668820.png?HW-CC-KV=V1&HW-CC-Date=20260612T073511Z&HW-CC-Expire=86400&HW-CC-Sign=05581E0BB7E376BCBBD1351C6A134F5EF09A7006100D824109BC8A931DEB9BE7)