Document to Picture

Static document conversion refers to the service of converting PPT, PPTX, Word, PDF and other format files into pictures. It is mainly to help customers insert presentation materials in whiteboards to assist online lectures or remote conferences. This function is provided by the SDK server and requires interaction with the server.

In the latest version, we have encapsulated this part of the interaction in the SDK. Developers only need to start the service in the background and configure the storage address. In the project, the Converter class (different platforms, slightly different names) For conversion.

The ideal number of pages is less than 50 pages, and documents with more than 100 pages may have a certain conversion timeout.
PDF, PPT, PPTX, Word, PDF conversion results are the most accurate.
The higher the resolution of the pictures referenced in the document, the slower the conversion speed.
The most popular picture formats are png and jpg.
If you find that the style expression is too inaccurate during the transcoding process, please export the pdf and re-convert.
The implementation of this function is based on libreoffice Because libreoffice has a long history and complex code, it is difficult for us to deal with conversion bugs by ourselves. Therefore, the customer should do a full test before using it. If it does not meet the expectations, please use the three-party conversion service.

Before calling the following api, please make sure that you have activated the document to image service on the console platform, otherwise the api will return the error code 403: service not enable

Ready to work

1. According to Configure Cloud Storage article, configure cloud storage in console

2. Start the static document service on the management console

Enter [console], click in the list on the left to enter the application management page.
Find "File to Picture" to activate, update QPS, and end the operation.

Click to expand: operation diagram in console

Static document conversion initial state
Static document conversion management page
Turn off static document conversion services

API instructions for use

The static document conversion function consists of two APIs, "Initiate Conversion Task" and "Query Conversion Task"

Initiate a conversion task

POST /services/conversion/tasks

You can use sdk token on the server. The client-side encapsulation class requires the use of roomToken to avoid sdk token leakage.

header parameter

Field	Type	Description
roomToken or token	string	{{roomtoken}} or {{token}}

body parameter

Field	Type	Description
sourceUrl	stirng	Address of the file to be converted
serviceType	string	Service type, static document conversion fixed to "static_conversion"

Before initiating the conversion task, please make sure that you have enabled the "Document to Picture" service on the console and configured the QPS upper limit to be greater than 0, otherwise the interface will report exceptions such as "Service not enable" and "Task waiting line is full"

body example

{
    "sourceUrl": "https://xxxx.xxx.xxx.com/xxxx.pptx",
    "serviceType": "static_conversion"
}

response example

{
    "code": 200,
    "msg": {
        "succeed": true,
        "reason": "",
        "taskUUID": "xxx6a660a6274c898b1689902734cxxx"
    }
}

task UUID is 32 bits in length and is the unique identifier of the conversion task

Query Conversion Task

GET /services/conversion/tasks/{{taskUUID}}/progress?serviceType=static_conversion

header parameter

Field	Type	Description
roomToken or token	string	{{roomtoken}} or {{token}}

response example

{
    "code": 200,
    "msg": {
        "task": {
            "convertStatus": "Finished",
            "reason": "",
            "totalPageSize": 3, // Total number of pages in the document
            "convertedPageSize": 3, // Document Completed Pages
            "convertedPercentage": 100, // Document conversion progress percentage
            "convertedFileList": [  // Document conversion result list
                {
                    "width": 1652,
                    "height": 2338,
                    "conversionFileUrl": "staticConvert/{{taskUUID}}/1.png"
                },
                {
                    "width": 1652,
                    "height": 2338,
                    "conversionFileUrl": "staticConvert/{{taskUUID}}/2.png"
                },
                {
                    "width": 1652,
                    "height": 2338,
                    "conversionFileUrl": "staticConvert/{{taskUUID}}/3.png"
                }
            ],
            "prefix": "https://xxxx.xxx.xxx.com/" // Document conversion result prefix
        }
    }
}

The static conversion task will return the width and height of each page, the unit of width and height is px, but because the number may be too large and the rendering is beyond the field of view when rendering in the whiteboard, the user can only use the proportion and customize the appropriate width or height

The use of "prefix" in the returned result is only valid when the conversion result is "Finished"

The conversion task requires users to poll the results, and the interval is recommended to be more than 3 seconds

convertStatus the following situations exist:

Waiting: The task is waiting due to QPS reaching the upper limit, etc.
Converting: Task in progress
NotFound: No corresponding task information was found according to taskUUID
Finished: Task execution completed and normal
Fail: The task execution fails. When it fails, there will be a prompt reason

SDK wrapper class use

iOS Android 2.2.0 New API

Web/Typescript

iOS/Objective-C

Android/Java

import {WhiteWebSdk} from "white-web-sdk";
const whiteWebSdk = new WhiteWebSdk();
// Server authentication
const pptConverter = whiteWebSdk.pptConverter("input roomToken");


// 1. Call the member method convert of pptConverter to start transcoding
// 2、Convert parameter type reference PptConvertParams
type PptConvertParams = {
    readonly url: string; // Network address of the static document, please make sure it can be downloaded
    readonly kind: PptKind; // Document conversion type, static is PptKind.static (typescript) or "static" (javascript)
    readonly onProgressUpdated?: (progress: number) => void;
    readonly checkProgressInterval?: number;  // Polling interval
    readonly checkProgressTimeout?: number; // overtime time
};

// Request transcoding, get data for each page
res = await pptConverter.convert({
    // ppt address in cloud storage, note that you need to configure in the console
    url: pptURL,
    kind: "static",
    // Conversion progress monitoring
    onProgressUpdated: progress => {
        if (onProgress) {
            onProgress(PPTProgressPhase.Converting, progress);
        }
    },
});

// Data structure returned by convert
export type Ppt = {
    // Server-side, uuid of conversion task
    readonly uuid: string;
    readonly kind: PptKind;
    readonly width: number;
    readonly height: number;
    // Preview page address
    readonly slideURLs: ReadonlyArray<string>;
    // Ppt scene data format, using this property, you can directly insert a new scene page
    readonly scenes: ReadonlyArray<SceneDefinition>;
};

blog
room.putScenes(`/${filename}`, res.scenes);
room.setScenePath(`/${filename}/${res.scenes[0].name}`);

#import <WhiteSDK.h>
// See sdk  sdk WhiteConverter.h WhiteConversionInfo.h for detail
@implementation RoomCommandListController
- (void)convertStatic {
  WhiteConverter *converter = [[WhiteConverter alloc] initWithRoomToken:self.roomToken];
  [converter startConvertTask:@"Document url" type:ConvertTypeStatic progress:^(CGFloat progress, WhiteConversionInfo * _Nullable info) {
      NSLog(@"progress:%f", progress);
  } completionHandler:^(BOOL success, ConvertedFiles * _Nullable ppt, WhiteConversionInfo * _Nullable info, NSError * _Nullable error) {
      NSLog(@"success:%d ppt: %@ error:%@", success, [ppt yy_modelDescription], error);
      if (ppt) {
          // Scene-related content, please refer to [Scene Management](/docs/advance/scenes.md) document for details
          [self.room putScenes:@"/static" scenes:ppt.scenes index:0];
          // First page
          [self.room setScenePath:@"/static/1"];
      }
  }];
}
@end

Converter c = new Converter(this.roomToken);
c.startConvertTask("document url", Converter.ConvertType.Static, new ConverterCallbacks(){
    @Override
    public void onFailure(ConvertException e) {
        logAction("ppt fail");
    }

    @Override
    public void onFinish(ConvertedFiles ppt, ConversionInfo convertInfo) {
        if (ppt.getScenes() != null) {
            // Scene-related content, please refer to [Scene Management](/docs/advance/scenes.md) document for details
            room.putScenes("static", ppt.getScenes(), 0); 
            // First page
            room.setScenePath("static/1");
        }
    }

    @Override
    public void onProgress(Double progress, ConversionInfo convertInfo) {
        logAction(String.valueOf(progress));
    }
});