File conversion overview

Interactive Whiteboard supports file conversion from PPT and PPTX files into dynamic HTML web pages. The generated web pages can be accessed directly or presented on the whiteboard.

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 RESTful API reference.

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

The file-conversion feature supports the following types of file conversion:

• Static-file conversion
• Dynamic-file conversion

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

When using static-file conversion, pay attention to the following issues:

• 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.
• PDF files generate the most accurate images when converted. If the generated image differs greatly from the source file in content or formatting, convert the source file to PDF and try again.
• Only valid PDF files are supported, that is, files that conform to PDF standards and have a valid header starting with %PDF.
• Note that because this feature is implemented with support from Aspose, Agora might 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 do not meet your expectations, consider using a third-party service.
• The new file conversion currently does not support generating resource packages. However, because the resources path is fixed, users can download resources by themselves.

Dynamic-file conversion refers to converting PPT/PPTX files edited with Microsoft Office to HTML web pages. The generated file preserves animations present in the source file.

When using dynamic-file conversion, pay attention to the following issues:

• Converting WPS files is not yet supported. You might also encounter problems when using PPTX files converted from WPS files.
• The new file conversion currently does not support generating resource packages. However, because the resources path is fixed, users can download resources by themselves.
• If a font is missing in a generated web page, you can either use the SDK to add a custom font or contact support@agora.io.
• Due to inherent constrains in the PPT file format, PPT files are converted into PPTX files at the backend before parsing, which might encounter failure. Therefore, Agora recommends you to upload PPTX files for conversion.
• A generated web page can be rendered into canvas pages via Fastboard SDK (coming soon), @netless/slide, or @netless/projector-plugin. The differences between these three rendering solutions are as follows:
  • Fastboard SDK is the rendering plan designed for multi-window scenarios in Agora Interactive Whiteboard. Fastboard SDK is coming soon.
  • @netless/slide is a stand-alone document conversion and rendering dependency that does not include such things as whiteboards or state synchronization. Adopting this solution requires you to write extra codes to synchronize states. It is designed for scenarios where PPT is used alone in whiteboard apps.
  • @netless/projector-plugin is a plug-in for Whiteboard SDK that supports state synchronization, but it only works in single-window scenarios.

Compared with the old version, the new file conversion adopts an engine developed by Agora and has the following advantages:

• Support for stand-alone access. The new file conversion is no longer bound to Interactive Whiteboard and can be integrated with third-party whiteboard SDKs.
• Faster conversion speed. The conversion speed of the new version is increased by 200% to 400%.
• Stronger content parsing. The new file conversion supports parsing content that the old version cannot, including additional animations, filters, and other effects. The new version can parse all normal PPTX content.
• Improved stability. The new file conversion fixes multiple issues in the old version that could cause conversion failures.
• New features. Users can now pause ongoing conversion tasks or adjust task priorities.

The new and the old versions of file conversion are independent of each other: The conversion task UUID generated by the new version cannot call the old version to query the progress, while the uuid generated by the old version cannot query the progress through the new version. If you want to query the progress of the old conversion tasks through the new version, contact support@agora.io.

Although Agora Interactive Whiteboard continues to maintain the old version of file conversion, some issues could arise due to inherent limits in the architectural design. Agora recommends you choose an appropriate time to switch to the new file conversion. If you need support for the old version of file conversion, see the following resources:

• Old File Conversion Overview
• Old File Conversion API Reference

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

To save files generated by file conversion, you need an account on a third-party cloud storage service such as Amazon S3, Google Cloud platform, or Alibaba.

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 produces a URL address for the file. Make sure that the Interactive Whiteboard can access the file via this URL address.

Refer to the following steps:

1. On the My Projects page in Agora Console, find the project that has the whiteboard feature enabled, and click Edit ✎.

2. Under ALL FEATURES, select Whiteboard > Whiteboard Services.

3. On the Services Configuration view, select a data center and click Configure ✎. 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 does not take effect.

   

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

5. Set up the storage space:

   • Click the Storage dropdown and select a previously configured storage space in the drop-down list or click Create to add a new storage space.

   

   To add a new storage space, fill in the following information:

   • Name: (Required) The name of your storage space.

   • Vendor: (Required) The third-party cloud storage vendor. Choose from the following options:

     • AWS
     • Alibaba Cloud
     • Google Cloud Platform

     If your vendor is Google Cloud Platform, refer to Google Cloud Storage configuration. If you chose AWS, or Alibaba Cloud, fill in the following information:

   • Region: (Required) The location of the data center you specified when creating a bucket.

   • Secret Key: (Required) The secret key provided by the third-party cloud storage vendor, which is used to authenticate signatures.

   • Access Key: (Required) The access key provided by the third-party cloud storage vendor, which is used by the vendor to identify visitors.

   • 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 configure storage parameters for GCP, see Google Cloud Storage configuration. To get configuration information for other third-party storage services, 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.

   Click Create to save the storage space parameters.

6. Click Save to save the service configuration. Read the prompt carefully, and click Confirm.

Take the following steps:

1. To start a file-conversion task, call the RESTful API and pass in the URL address of the source file along with other parameters. See Start file conversion.

2. To query the progress of a file-conversion task, pass in the corresponding task UUID and Task Token. See Query file-conversion progress. Agora recommends that you implement an algorithm to regularly query the conversion progress so that your data is up to date.

When converting PPT or PPTX files created in Microsoft PowerPoint into dynamic HTML web pages using File conversion, some elements—such as special effects, images, or animations—might not parse correctly. This can result in issues like missing or non-functional effects in the converted output. This section outlines the compatibility of the document conversion service with various PPT features, helping you identify and fix problematic elements in your presentations.

info

• These notes are only applicable to PPT or PPTX files made with MS PowerPoint. For PPT files made with WPS, Agora does not guarantee the conversion effect.
• Some functions and effects are not mentioned in the following list. This is due to functional inconsistencies caused by different versions which require manual testing.

PPT element	Effects menu	Support effect	Measures to take
Word	Font	Font, font style, font size: All Color and underline: All Effect: Supports strikethrough, double strikethrough, superscript, subscript, equal-height characters Character Spacing: All	After some fonts are converted, ensure that the font is installed locally for it to be displayed correctly.
	Paragraph	Bullet Serial number Text alignment: All Indentation Spacing Chinese version: All Multi-column layout	-
Shape	Shape Format	Shape Fill: All Shape Outlines/Lines: All	-
Sheet	Table Design	Table style options: All Table style: Subject: All Shading Frame Fill: color fill, picture fill, texture fill, gradient fill, pattern fill	-
	Table Layout	All	-
Picture	Image Format	Remove background Adjustments: All Image style: Style templates Frame Format Effects: shadow, reflection, glow, soft edge Arrangement: All Cropping	-
Audio and Video	Audio/Video Format	Cropping (progressive cropping) Add bookmark	-
Animation	Animation Type	Page cutting animation: fade in, fade out, push in, erase, split, reveal, cut in, random lines, shapes, uncover, cover, fall, hang, curtain, peel off, dissolve, chessboard, blinds, clock, ripple, switch, rotate, library, cube, box, comb, zoom, pan, carousel Appearance/disappearance animation: All Word animation: All Path Animation: All Template Animation: All Animation with sound	-
	Animation Properties	Timing: start condition, duration, delay, repeat Trigger: by click, by bookmark Set text animation and combine text.	-
Other	Other Menu	Modify PPT theme, customize theme	-

PPT element	Unsupported effects	Imperfectly supported effects	Measures to take
Word	Font effect: All Caps, Small Caps Shape format - Text Options: Shadow, reflection, glow, soft edges, 3D format, 3D rotation	Text stroke: Cannot perfectly restore the effect in PPT. Custom fonts: Some font line breaks are inconsistent with the original PPT. Vertical text: Line spacing that is not single-spaced may be inconsistent with the original PPT, and the horizontal coordinate of the font will be offset. WordArt: The conversion effect is not perfect.	Avoid inserting too much text on one page. Avoid using line breaks continuously. It is recommended to split large paragraphs into multiple text boxes.
Shape	Shapes with formulas do not support adding color fill animations.	Shape Format - Effects: When using shadow, reflection, glow, or soft edge effects, the entire shape is displayed first, and the special effects will take effect later. Shape Format - Shape Outline: When you select Dashed Line, dashed lines smaller than 1.5 pt are converted to solid lines. Arrows may shift after conversion.	Some special graphics should not exceed the graphic boundary, and the part beyond the boundary is not displayed.
Sheet	Shape Format - Fill: Pattern Fill The option to tile the image as a texture is not supported in image or texture fills. Shape Format - Effects: Shadow, reflection, glow, soft edge, 3D format, 3D rotation.	-	-
Picture	Image format-effect: 3D format, 3D rotation.	Image format - Remove background: Support is not perfect, the converted image may have white edges. Image format - Image color: Images that are recolored or use color filters may have color differences after conversion. Image Format - Image Correction: Brightness and contrast adjustment effects are not perfectly restored.	-
Audio and Video	Option: Play across slides. Style: Play in the background.	-	-
Animation	Page cutting animation: airplane, origami, fragments, vortex, shining, smooth. Emphasis animation: Zoom in or zoom out (only for text, not supported)/ brush color, color stretch, color pulse, underline. Path Animation: Rewind after playback is complete.	Timing-delay: There may be a small error in the animation delay time. Advanced Animation triggered by click: Click events penetrate the underlying elements.	-
Other	Extract annotations The following effects are not effective in the thumbnails generated after document conversion preview: All gradient effects All page switching animations Animations that involve changes to the inside of a shape do not work, including: blinds, checkerboard, dissolve, random Lines, shapes, splits, stairs, wheels, erase, fade, float Transparency Recolor Shadow, reflection, glow, soft edge	The hide slide function does not support hiding the first page of the slide.	-

If some effects are missing in the converted PPT or are different from the original PPT, refer to the following steps to locate the problematic elements and fix them:

1. Locate the problematic element

   Compare the PPT before and after conversion to find the problematic elements.

2. Deal with problematic elements

   Resolve the problem using one of the following methods:

   • Remove the problematic element directly or remove unsupported effects on the element.
   • Replace the effect that is already supported by other document transformations for the element in question.
   • Save the problematic element as a picture, delete the element, and then reinsert the picture to the original position. If there are many problematic elements, combine those elements first and convert them to pictures.

3. Restart the conversion

   Call the RESTful API again to restart the conversion. After the conversion is successful, compare the PPT effects before and after the conversion. If there are any remaining problems, repeat the previous steps.

This section contains information that completes the information on this page, or points you to documentation that explains other aspects of this product.

To set up cloud storage and obtain configuration information for Google Cloud Platform, take the following steps:

1. Create an account on Google Cloud and assign permissions on the settings page of Google Cloud storage.

2. After creation, click on the button in the upper right corner and select Project settings.

3. Under IAM and Admin, select Service Accounts. In the service account list, click on the button for the account just added, and select Manage keys.

4. Click ADD KEY > Create new key. Select JSON in the pop-up box and click CREATE. A json file is downloaded with the name format projectId-xxxxxxxx.json.

5. Open the downloaded json file, which looks like the following example:

   
   

   _13

   {

   _13

   "type": "service_account",

   _13

   "project_id": "argon-jetty-395210",

   _13

   "private_key_id": "yourprivateidkeyyourprivateidkeyyourprivateidkey",

   _13

   "private_key": "-----BEGIN PRIVATE KEY-----\nThisisYourPrivateKeyThisisYourPrivateKeyThisisYourPrivateKey\nThisisYourPrivateKey\nThisisYourPrivateKey\nThisisYourPrivateKey\n-----END PRIVATE KEY-----\n",

   _13

   "client_email": "xxxx-111@argon-jetty-395210.iam.gserviceaccount.com",

   _13

   "client_id": "123456789012345678901",

   _13

   "auth_uri": "https://accounts.google.com/o/oauth2/auth",

   _13

   "token_uri": "https://oauth2.googleapis.com/token",

   _13

   "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",

   _13

   "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/xxxx-111%40argon-jetty-395210.iam.gserviceaccount.com",

   _13

   "universe_domain": "googleapis.com"

   _13

   }

   
   

6. Use the information in the json file to fill-in the Google Cloud Storage configuration:

   The project_id in the json file corresponds to the projectId on Agora Console, client_email corresponds to clientEmail, private_key corresponds to privateKey, and bucket is filled with the name of the bucket to be used. The remaining parameters have the same meaning as for the AWS configuration. When copying the private_key, make sure that your text editor has not added any extra line breaks or \n after each \n.

7. Ensure that the newly created service account has writable permission for the Google storage bucket.