文档转换服务

声网互动白板提供文档转换服务，支持将 PPT、PPTX、DOC、DOCX 和 PDF 格式的文件转换成静态图片，将 PPT 和 PPTX 的文件转换为动态 HTML 网页，转换后的图片或网页可作为演示资料在互动白板中展示。

功能概述

声网互动白板支持以下两种文档转换服务:

• 静态文档转换
• 动态文档转换

静态文档转换

静态文档转换是指将 PPT、PPTX、DOC、DOCX、PDF 格式的文件转换成 PNG、JPG 或 JPEG 格式的静态图片。转换后的文件不保留源文件的动画效果。

使用静态文档转换服务，你需要注意：

• 源文件最好在 50 页以内，超过 100 页可能会出现转换超时。
• 源文件内包含的图片分辨率越高，转换速度越慢。
• 在 PPT、PPTX、DOC、DOCX、PDF 格式的源文件中，PDF 文件的转换结果最为准确。如果转换后的文件样式过于不准确，可以将源文件转成 PDF 格式后重新转换。
• 本功能基于 Aspose 实现，因此声网目前无法及时响应定制化需求。建议你在使用前先做充分的测试，如果不符合预期请使用三方转换服务。
• 暂不支持资源包功能，但资源路径固定，用户可以自行下载。

动态文档转换

动态文档转换是指将用 Microsoft Office 编辑的 PPT 和 PPTX 格式的文件，转换成 HTML 网页。转换后的文件会保留源文件里的动画效果。

使用动态文档转换服务，你需要注意：

• 转换结果同时支持使用 Fastboard SDK 、 @netless/slide 与 @netless/projector-plugin 渲染为 canvas 版本的页面，几个方案不同点在于：

  • Fastboard SDK 是互动白板多窗口场景下的文档转换渲染方案。

  • @netless/slide 是纯净的文档转换渲染依赖，不包含互动白板、状态同步等内容。该方案需要你自己编写事件同步、状态保存等额外的代码以实现多人同步的效果，适用于单独使用 PPT 的场景。

  • @netless/projector-plugin 是基于 @netless/slide 开发的互动白板 SDK 的插件，支持状态同步，但是只能在单窗口场景下工作。

• 暂不支持 WPS 格式的文件转换。即使将 WPS 转成 PPTX 后再进行文件转换，也不能保证成功解析。

• 暂不支持资源包功能，但资源路径固定，用户可以自行下载。

• 如果转换结果字体缺失，可以使用 SDK 中的自定义字体功能，或者联系技术支持。

• 由于 PPT 格式本身的问题，PPT 文件仍然需要在后端转换为 PPTX 进行解析，该过程仍有一定的失败率，建议直接使用 PPTX 格式的文档。

新旧版本对比

新版本文档转换采用自研引擎，相较于旧版文档转换服务，有以下优势：

• 支持独立接入。新版本文档转换服务不再与互动白板绑定，支持接入第三方白板类产品。

• 更快的转换速度。转换速度提升 200% ~ 400%。

• 更强的内容解析能力。不仅支持解析旧版转换服务无法解析的内容，还支持解析更多动画特效、滤镜等效果，理论上可以解析所有 PPTX 文档内容。

• 更高的稳定性。解决了部分文档在原有的转换服务转换失败的问题。

• 新功能。支持用户暂停进行中的任务和调整任务优先级。

新版本文档转换服务生成的转换任务 uuid 无法调用旧版本进行查询进度，同时旧版本文档转换服务生成的 uuid 也无法通过新版查询进度，两者相互独立。如果想通过新版本文档转换服务查询旧版本转换服务进度请联系技术支持。

前提条件

使用互动白板文档转换服务前，你需要先完成以下准备工作。

开通第三方云存储账号

声网互动白板使用第三方云存储服务存储转换后的文件。因此，使用声网互动白板文档转换服务前，请确保你已开通第三方云存储服务。

开启文档转换服务

参考以下步骤在声网控制台开启互动白板文档转换服务并添加存储配置：

1. 进入声网控制台的项目管理页面，选择已开通互动白板服务的项目，点击编辑。

2. 在编辑项目页面，找到白板，点击配置。

3. 在配套服务下，选择数据中心，点击配置。该数据中心必须与你调用创建房间 API 时在 region 字段中填入的数据中心一致；否则，服务配置不生效。
   

4. 在服务配置下，找到文档转图片或文档转网页，选择已启用。
   

5. 设置存储空间：

   • 点击存储方框右侧的箭头，在下拉列表中选择你已配置的第三方存储空间。
   • 点击创建，新增一个存储空间配置。你需要填写以下信息：
     • 名称：（必填）存储空间的名称。
     • 供应商：（必填）第三方云存储服务的供应商。
     • 区域：（必填）创建 Bucket 时指定的数据中心所在区域。
     • accessKey：（必填）存储服务供应商提供的访问密钥中的 Access Key，用于识别访问者的身份。
     • secretKey：（必填）存储服务供应商提供的访问密钥中的 Secret Key，用于验证签名的密钥。
     • bucket：（必填）Bucket 的名称。
     • 存储路径：资源在 Bucket 中的存放路径，默认为根目录。
     • 外链域名：对外服务的访问域名。如果使用七牛云 OSS，该字段为必填，否则声网将无法访问该存储服务内的资源。该字段必须包含协议头，比如 https:// 或 http://。
   • 要获取第三方存储空间的配置信息，请参考对应的云存储服务供应商的官方文档。
   • 第三方存储空间应开启公共读或更高权限，以确保你的 app 客户端可以访问其中的文件。

6. 点击保存，仔细阅读弹窗提示后点击确定。

上传文件

发起文档转换任务前，你需要将待转换的文档上传至第三方云存储空间或你自己的 Nginx 服务器，生成一个声网互动白板服务可访问 URL 地址，确保声网互动白板服务可通过该 URL 地址访问待转换的文档。

使用文档转换服务

文档转换服务由声网互动白板服务端提供，需要由你的业务服务端根据 app 客户端的需求，调用 RESTful API 向互动白板服务端发起文档转换请求，如下图所示：

• 调用 RESTful API 发起文档转换任务时，你需要传入待转换文件的 URL 地址等参数。详见发起文档转换 API。
• 调用 RESTful API 查询转换任务进度时，你需要传入转换任务的 UUID 和用转换任务 UUID 生成的 Task Token。详见查询文档转换任务进度 API。
• 建议你设计轮询机制定时调用查询转换任务进度 API，以实时获取转换任务的状态。

文档转换服务按 QPS 计费

默认情况下，声网互动白板文档转换服务只能同时处理一个文档转换请求（即 QPS 为 1），在前一个转换完成后才会进行第二个任务的转换，并按成功转换的页数计费。

如果你的某个白板项目每秒并发请求数量较大，默认的 QPS 无法满足你的需求，你可以联系 sales@agora.io，申请调整该项目的 QPS 配置并按 QPS 计费。QPS 计费方案细节详见文档转换服务按 QPS 计费。