Deprecated file conversion overview

Interactive Whiteboard released a new version of file conversion service on July 27, 2022, that greatly improves conversion speed, content parsing, and stability. The new version also adds the ability to integrate with third-party whiteboard SDKs. Agora strongly recommends you use the new version of file conversion. See File conversion overview.

Interactive Whiteboard supports file conversion from PPT, PPTX, DOC, DOCX, and PDF files into static images, as well as from PPTX files into dynamic HTML web pages. The generated images and web pages can be presented on the whiteboard.

The file-conversion feature supports:

• Static-file conversion
• Dynamic-file conversion

Static-file conversion refers to converting PPT, PPTX, DOC, DOCX, and PDF files to static images in PNG, JPG/JPEG, and WEBP formats. The generated file does not preserve animations present in the source file.

When using static-file conversion, keep in mind the following helpful guidelines::

• The conversion process works best when the source file is less than 50 pages long. If the source file has more than 100 pages, you may experience a conversion timeout.
• The higher the image resolution in the source file, the slower the conversion.
• Agora recommends the PNG and JPG/JPEG formats for generated images.
• Out of all source file formats, conversions of PDF files result in the most accurate images. If the generated image differs greatly from the source file in content or formatting, you can convert the source file to PDF and try again.
• Please note that because this feature is implemented with support from Aspose, Agora may not be able to respond to requests for customization as quickly as usual. Agora recommends that you run sufficient tests of the file-conversion feature. If the test result does not meet your expectations, you can use a third-party service.

If a font is missing in the generated web page, you can either use the SDK to add a custom font or contact support@agora.io.

Dynamic-file conversion refers to converting PPTX files edited with Microsoft Office to HTML web pages. The generated file preserves animations present in the source file. Currently, dynamic-file conversion does not support the following formats and features:

• Converting WPS files, or PPTX files converted from WPS files.
• Gradient colors.
• WordArt.
• Shape effects.
• Some picture effects.
• SmartArt animations.
• Transition effects between slides.
• Animated text, or words that appear one line at a time.
• Animations, such as Dissolve and Checkerboard.
• All text directions except for Horizontal and Vertical.
• Some audio playback options and video format settings.
• Converting hidden pages.

If a font is missing in the generated web page, you can either use the SDK to add a custom font or contact support@agora.io.

Before using the file-conversion feature, ensure that you have completed the following preparatory steps:

You need to use an Amazon S3 cloud storage service to save files generated by file conversion.

To enable the file-conversion feature, do the following steps:

1. Go to the Project Management page in Agora Console, find the project that has the whiteboard feature enabled, and click Edit.

2. On the Edit Project page, find Whiteboard, and click Config.

3. Under Services, select a data center, and click Config. The data center must be the same as the one you fill in the region field when calling the Create a room API; otherwise, the service configurations do not take effect.

4. On the Services configuration page, select Enabled for Docs to Picture or Docs to web.

5. Set up the storage space:

• Click the arrowhead to the right of Storage, and select a previously configured storage space in the drop-down list.

• Click Create to add a new storage space. You need to fill in the following information:

  • Name: (Required) The name of your storage space.
  • Vendor: (Required) The third-party cloud storage vendor.
  • Region: (Required) The location of the data center you specified when creating a bucket.
  • accessKey: (Required) The Access Key provided by the third-party cloud storage vendor, which is used by the vendor to identify visitors.
  • secretKey: (Required) The Secret Key provided by the third-party cloud storage vendor, which is used to authenticate signatures.
  • bucket: (Required) The name of the bucket.
  • Storage path: The path used to save the resources in the storage space. The default is the root directory.
  • Domain: The domain name used to access the third-party cloud storage service.
  • To get the above information about a third-party storage service, see the documentation provided by the vendor.
  • You should enable public access or higher permission for third-party storage spaces so that your app clients can access files saved in the space.

7. Click Save, read the pop-up prompt carefully, and click Confirm.

Before you launch a file-conversion task, you must upload the source file to a third-party cloud storage space or your Nginx server. This will produce a URL address for the file. Make sure that the whiteboard service can access the file via this URL address.

The file-conversion feature is implemented by Agora's server for the whiteboard service. When an app client requests to convert a file, your app server needs to call the Interactive Whiteboard RESTful API to send the request to the Agora server. The full process is illustrated in the following diagram:

• To start a file-conversion task, call the RESTful API by passing in the URL address of the source file, the task type, as well as other relevant parameters. See Start file conversion.
• To query the progress of a conversion task, pass in the corresponding Task UUID and Task Token. See Query file-conversion progress.
• To ensure that your data is up to date, Agora recommends that you design an algorithm to regularly query the conversion progress.