Merge pull request #858 from wechat-miniprogram/feat/audio_doc

docs: update audio video
wechat-miniprogram · Sep 2, 2024 · 624f4f6 · 624f4f6
2 parents 1dfec25 + a1b61c5
commit 624f4f6
Show file tree

Hide file tree

Showing 6 changed files with 79 additions and 4 deletions.
diff --git a/.config/.vitepress/config.mts b/.config/.vitepress/config.mts
@@ -133,6 +133,7 @@ export default defineConfig({
         text: "能力适配",
         items: [
           { text: "WX SDK 平台能力适配", link: "/Design/WX_SDK" },
+          { text: "音频视频适配", link: "/Design/AudioAndVideo" },
           { text: "屏幕适配", link: "/Design/fixScreen" },
           { text: "输入法适配", link: "/Design/InputAdaptation" },
           { text: "排行榜与微信关系数据", link: "/Design/OpenData" },

diff --git a/Design/AudioAndVideo.md b/Design/AudioAndVideo.md
@@ -0,0 +1,75 @@
+## 音频
+
+目前 UnityAudio 已自动适配微信小游戏，优先建议使用 UnityAudio 来播放音频，也支持 FMOD 插件
+
+## 兼容原理
+
+UnityAudio 原理：
+
+-   长音频播放使用的是[InnerAudio](https://developers.weixin.qq.com/minigame/dev/api/media/audio/InnerAudioContext.html)
+-   短音频播放使用的是[WebAudio](https://developers.weixin.qq.com/minigame/dev/api/media/audio/WebAudioContext.html)
+-   Unity 插件会根据音频文件大小自动适配使用不同的播放方式
+
+FMOD 原理：
+
+-   全部使用[WebAudio](https://developers.weixin.qq.com/minigame/dev/api/media/audio/WebAudioContext.html)，因此不推荐背景音乐等大文件使用 FMOD 播放，会占用很大内存
+
+### QA
+
+1. 在 IOS 17.5 以上的版本，小游戏退后台后返回音效无法继续播放了
+
+-   可以尝试更新最新的插件版本，可以避免一些出现的情况，我们正在尝试兼容 IOS 的更新
+
+2. IOS 偶现音频报错 operateAudio:fail jsapi has no permission
+
+-   音频播放时小游戏退后台就有可能出现，没有实际影响，可以忽略
+
+3. 音频播放时游戏卡顿
+
+-   如果同时播放的音频数量过多，是有可能造成游戏延迟卡顿的，建议限制同时播放的音频数量
+
+4. 部分音频文件在安卓无法循环播放
+
+-   已知问题，8.0.51 客户端版本修复
+
+5. 音频在 PC 端无法循环播放完整音频
+
+-   已知问题，更新最新的 Unity 导出插件
+
+6. 推荐使用什么音频格式
+
+-   推荐 mp3 或者 aac 格式，在双端有较好的兼容
+
+## 视频
+
+目前 VideoPlayer 已自动适配微信小游戏
+
+### 支持版本
+
+不同客户端的支持情况不同，以下为最低支持版本：
+
+| 参数        | 版本                        |
+| ----------- | --------------------------- |
+| IOS 高性能+ | 8.0.51                      |
+| IOS 高性能  | 8.0.41                      |
+| 安卓        | 8.0.40                      |
+| PC          | 基础库 3.2.1                |
+| 开发者工具  | 基础库 3.2.1 + 1.06.2310312 |
+
+### QA
+
+1. 视频在 IOS 无法播放，在其他平台都可以播放？
+
+-   可以尝试把视频播放链接替换我们这个视频链接试试看是否正常，一般这种情况都是服务端设置问题，会报错`Origin weapp://wechat-game-runtime is not allowed by Access-Control-Allow-Origin`，但是没有打印到客户端，只需要配置服务端允许微信跨域访问即可（视频链接：https://wxsnsdy.tc.qq.com/105/20210/snsdyvideodownload?filekey=30280201010421301f0201690402534804102ca905ce620b1241b726bc41dcff44e00204012882540400&bizid=1023&hy=SH&fileparam=302c020101042530230204136ffd93020457e3c4ff02024ef202031e8d7f02030f42400204045a320a0201000400 ）
+
+2. 视频在 IOS 播放有声音没画面？
+
+-   开启了高性能+，先临时关闭高性能+
+
+3. 为什么 IOS 高性能模式只能同时播放一个视频？
+
+-   IOS 的播放策略，只能从逻辑上兼容
+
+4. 是否应该使用 VideoPlayer？
+
+-   如果只是单纯使用全屏的视频播放，更推荐使用小游戏 API 视频播放能力。请参考[小游戏开发者文档](https://developers.weixin.qq.com/minigame/dev/api/media/video/wx.createVideo.html)以及示例[Video Demo](https://github.com/wechat-miniprogram/minigame-unity-webgl-transform/tree/main/Demo/WX_Video)
diff --git a/Design/DataCDN.md b/Design/DataCDN.md
@@ -45,7 +45,7 @@
 - CDN：当不使用小游戏分包时，需要部署到服务器。
 
 ### Assets
-如果有用到纹理压缩和微信音频API，导出插件自动生成。将此目录部署到服务器即可
+如果有用到纹理压缩，导出插件自动生成。将此目录部署到服务器即可
 
 ### StreamingAssets
 AssetBundle和Addressables资源目录。

diff --git a/Design/DevelopmentQAList.md b/Design/DevelopmentQAList.md
@@ -146,7 +146,7 @@ if (WXConvertCore.DoExport() == WXConvertCore.WXExportError.SUCCEED) {
 - 不行，不提供内嵌webview或跳转的能力
 #### 5.小游戏是否支持Unity VideoPlayer
 
-- 支持，但是IOS有限制只能同时播放一个，并且需要注意基础库版本限制，低版本无法播放。如果只是单纯使用全屏的视频播放，更推荐使用小游戏API视频播放能力。请参考[小游戏开发者文档](https://developers.weixin.qq.com/minigame/dev/api/media/video/wx.createVideo.html)以及示例[Video Demo](https://github.com/wechat-miniprogram/minigame-unity-webgl-transform/tree/main/Demo/WX_Video)
+- 支持，详情查看[音频视频适配](AudioAndVideo.md)
 #### 6.小游戏应该使用哪个接口进行限制帧率？
 
 - Application.targetFrameRate

diff --git a/Design/HowToDebug.md b/Design/HowToDebug.md
@@ -91,4 +91,4 @@ python3 -m pip install brotli
 字体必须打包到项目中，才能正常展示。
 
 5. 音频被切到后台会停止
-小游戏被切到后台会停止播放音频需代码中监听 [WX.OnShow](https://developers.weixin.qq.com/minigame/dev/api/base/app/life-cycle/wx.onShow.html)事件和 [WX.OnAudioInterruptionEnd](https://developers.weixin.qq.com/minigame/dev/api/base/app/app-event/wx.onAudioInterruptionEnd.html)事件，在该事件之后重新播放音频
+小游戏被切到后台会停止播放音频需代码中监听[WX.OnAudioInterruptionEnd](https://developers.weixin.qq.com/minigame/dev/api/base/app/app-event/wx.onAudioInterruptionEnd.html)事件，在该事件之后重新播放音频
diff --git a/Design/Transform.md b/Design/Transform.md
@@ -109,7 +109,6 @@ bundleHashLength -- bundle名中hash长度
 preloadFiles -- 预下载文件列表，用;分隔
 // SDK功能
 UseFriendRelation -- 使用好友关系链
-UseAudioApi -- 使用微信音频API
 // 调试编译选项
 DevelopBuild -- Development Build
 AutoProfile -- Autoconnect Profiler