Dynamic document conversion refers to the service of converting files in pptx format into web pages.
¶ List of functions not supported by document to webpage
The currently known unsupported pptx functions are as follows:
- Wps files are not supported, and the files converted from wps to pptx are not guaranteed to be parsed successfully
- Does not support gradient rendering
- The punctuation at the end of the text line is not supported beyond the text box (it will cause automatic line wrapping)
- Does not support word art
- Does not support charts such as histograms
- Graphics created by SmartArt function are not supported
- Does not support transition effects when switching pages
- Text animation and action pictures are not supported (that is, there is one animation per line in the text box)
- Does not support emf or wmf format pictures
- Most animation effects such as dissolve, checkerboard, etc. are not supported, currently only fade in and fade out effects
- If the font is missing in the conversion result, you can use the custom font function in the sdk or contact us
- Vertical layout of text is not supported
- Does not support video cropping function
- Does not support the conversion of hidden pages
The document to the web page is undergoing R&D iteration, the above list will be updated
Compared to static document conversion, dynamic document conversion retains the sequence animation in the ppt file and provides switching control functions.
The dynamicpptis based on theMicrosoft Officespecification and cannot guarantee that the WPS file can be parsed correctly.
¶ Ready to work
¶ 1. According to the Configure Cloud Storage article, configure cloud storage in console
¶ 2. Open the dynamic document service on the management console
-
Enter console, click
Application Managementin the list on the left to enter the application management page. -
Find
document to imageto activate, update QPS, and end the operation.
Click to expand: Operation diagram in console
-
Initial state of dynamic document conversion
-
Dynamic document conversion management page
-
Turn off dynamic document conversion service
¶ Conversion API
The dynamic document conversion function consists of two APIs: "Initiate conversion task" and "Query conversion task"
¶ 1. Initiate conversion
POST /services/conversion/tasks
Sdk token can be used on the server side. The client package 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 | The address of the file to be converted | |
| serviceType | string | Service type, dynamic document conversion is fixed as "dynamic_conversion" | |
| preview | boolean | (Optional) Whether to generate a preview image, the default is false |
Note: Only dynamic document conversion supports the preview image function, that is, when serviceType == "dynamic_conversion", it takes a long time to generate the preview image at the same time, please choose carefully
- body
{
//Please make sure the file is downloadable
"sourceUrl": "https://xxxx.xxx.xxx.com/xxxx.pptx",
"serviceType": "dynamic_conversion",
"preview": false
}
- response
Before initiating the conversion task, please make sure you have enabled the
Document to Webpageservice on console and configured the QPS upper limit to be greater than 0, otherwise the interface will reportService not enable,Task waiting line is full.
{
"code": 200,
"msg": {
"succeed": true,
"reason": "",
"taskUUID": "xxx6a660a6274c898b1689902734cxxx"
}
}
The task UUID is 32 bits in length and is the unique identification of the conversion task. This task needs to be used as a query in subsequent requests.
¶ 2. Check the conversion progress
GET /services/conversion/tasks/{{taskUUID}}/progress?serviceType=dynamic_conversion
- header parameter
| Field | Type | Description | |
|---|---|---|---|
| roomToken or token | string | {{roomtoken}} or {{token}} |
- response
{
"code": 200,
"msg": {
"task": {
"convertStatus": "Finished",
"currentStep": "Extracting", // current conversion task step, this field is only available when serviceType == dynamic_conversion
"reason": "",
"totalPageSize": 3, // total number of pages of the document
"convertedPageSize": 3, // The number of converted pages of the document
"convertedPercentage": 100, // Document conversion progress percentage
"convertedFileList": [// Document conversion result list
{
"width": 960,
"height": 720,
"conversionFileUrl": "dynamicConvert/{{taskUUID}}/slide/slide1.xml",
"preview": "https://xxx.xxx/xxx.png" // This field only appears when the parameter preview == true
},
{
"width": 960,
"height": 720,
"conversionFileUrl": "dynamicConvert/{{taskUUID}}/slide/slide2.xml",
"preview": "https://xxx.xxx/xxx.png"
},
{
"width": 960,
"height": 720,
"conversionFileUrl": "dynamicConvert/{{taskUUID}}/slide/slide3.xml",
"preview": "https://xxx.xxx/xxx.png"
}
],
"prefix": "pptx://xxxx.xxx.xxx.com/" // Prefix of document conversion result
}
}
}
- The dynamic conversion task will return the width and height of each page, the unit of width and height is px
- The user uses the "prefix" in the returned result only when the conversion result is "Finished"
- The conversion task requires users to poll the results, and the recommended time interval is more than 3 seconds
convertStatus has the following situations:
- Waiting: The task is waiting due to QPS reaching the upper limit, etc.
- Converting: The task is being executed
- NotFound: According to taskUUID, the corresponding task information is not found
- Finished: The task execution is completed and normal
- Fail: The task execution failed. When it fails, there will be a prompt reason
Since there are many dynamic conversion steps, we have added the current step field to indicate the progress of the task. currentStep has the following values
- Extracting: Resource extraction
- Packaging: Resource packaging
- GeneratingPreview: Generate preview image
- MediaTranscode: Media transcoding
¶ Data splicing
After obtaining the conversion result, you need to stitch and convert it into the scene data (scenes) usable by the SDK.
This part can be stitched by the client itself, or assembled on the server side and sent to the client in JSON format.
¶ 1. Let the client stitch together
Transfer the converted json, taskId, and prefix to the client for splicing. (Recommended method, because the client still needs to be converted to the scene class supported by sdk for input)
Web/Typescript
// info is the response returned by the conversion result
const count = info.totalPageSize;
const scenes: {name: string, ppt: PptDescription}[] = [];
const ppts = info.convertedFileList;
for (let i = 0; i <ppts; ++ i) {
const url = `${prefix}${ppts[i].conversionFileUrl}`;
slideURLs[i] = url;
scenes[i] = {
// Please use string
name: `${i + 1}`,
ppt: {src: url, width: info.width, height: info.height},
};
}
// scenes is the data format supported by the whiteboard
iOS/Objective-C
// response is the response returned by the conversion result
NSInteger count = [response[@"totalPageSize"] integerValue];
NSArray *ppts = response[@"convertedFileList"];
NSMutableArray<WhiteScene *> *scenes = [NSMutableArray arrayWithCapacity:count];
for (int i = 0; i <ppts; i++) {
NSDictionary *dict = ppts[i];
WhitePptPage *pptPage = [[WhitePptPage alloc] init];
pptPage.src = [NSString stringWithFormat:@"%@%@", prefixUrl?: @"", dict[@"conversionFileUrl"]];
pptPage.width = [response[@"width"] doubleValue];
pptPage.height = [response[@"height"] doubleValue];
WhiteScene *scene = [[WhiteScene alloc] initWithName:[NSString stringWithFormat:@"%d", i+1] ppt:pptPage];
[scenes addObject:scene];
}
// The scenes array, which is the data format supported by the whiteboard. After receiving JSON on the iOS side, it can actively convert to WhiteScenes
Android/Java
// json is the json returned by the query result API
Integer count = json.get("totalPageSize").getAsInt();
JsonArray ppts = json.get("convertedFileList").getAsJsonArray();
Scene[] scenes = new Scene[count];
for (int i = 0; i <ppts.size(); i++) {
PptPage pptPage = new PptPage(String.valueOf(i+1), json.get("width").getAsDouble(), json.get("height").getAsDouble());
JsonObject object = array.get(i).getAsJsonObject();
pptPage.setSrc(prefix + object.getAsJsonObject("conversionFileUrl").getAsString());
sliderURLs[i] = pptPage.getSrc();
scenes[i] = new Scene(String.valueOf(i+1), pptPage);
}
// The scenes array, which is the data format supported by the whiteboard. After Android receives JSON, it needs to actively convert
¶ 2. Convert to JSON and send to client
scenes: [
{
//name is a string
"name": "1",
// height, width is the width and height returned in info
"height": {info.heigh},
"width": {info.width},
//Digital index value +1, the first page is slide1.xml, the second page is slide2.xml
"src": {prefix}/{taskId}/slide/slide1.xml
},
{
//name is a string
"name": "2",
// height, width is the width and height returned in info
"height": {info.heigh},
"width": {info.width},
//Digital index value +1, the first page is slide1.xml, the second page is slide2.xml
"src": {prefix}/{taskId}/slide/slide2.xml
}
]
¶ SDK package class use
Based on the convenience of use, the complete request process of the conversion task has been encapsulated in the SDK. When testing, you can use this API.
Because the conversion task calculates QPS, that is, it is billed at the daily peak value, so it is not recommended to use the
SDKAPI in the production environment.
¶ Use Conversion API
iOS Android 2.2.0 new API
Web/Typescript
import {WhiteWebSdk} from "white-web-sdk";
const whiteWebSdk = new WhiteWebSdk();
// server authentication
const pptConverter = whiteWebSdk.pptConverter("Enter roomToken");
// 1. Call the member method convert of pptConverter to start transcoding
// 2. Refer to PptConvertParams for the parameter type of convert
type PptConvertParams = {
readonly url: string; //Network address of 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 time
readonly checkProgressTimeout?: number; // timeout
};
// Request transcoding, get data of each page
res = await pptConverter.convert({
// The address of ppt in cloud storage, note that it needs to be configured in the console
url: pptURL,
kind: "dynamic",
// Conversion progress monitoring
onProgressUpdated: progress => {
if (onProgress) {
onProgress(PPTProgressPhase.Converting, progress);
}
},
});
// Data structure returned by convert
export type Ppt = {
// On the server side, the uuid of the 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 attribute, 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}`);
iOS/Objective-C
#import <WhiteSDK.h>
// See sdk WhiteConverter.h WhiteConversionInfo.h for details
@implementation RoomCommandListController
-(void)convertStatic {
WhiteConverter *converter = [[WhiteConverter alloc] initWithRoomToken:self.roomToken];
[converter startConvertTask:@"document address" type:ConvertTypeDynamic 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:@"/dynamic" scenes:ppt.scenes index:0];
//The first page
[self.room setScenePath:@"/dynamic/1"];
}
}];
}
@end
Android/Java
Converter c = new Converter(this.roomToken);
c.startConvertTask("document address", Converter.ConvertType.Dynamic, 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("dynamic", ppt.getScenes(), 0);
// The first page
room.setScenePath("dynamic/1");
}
}
@Override
public void onProgress(Double progress, ConversionInfo convertInfo) {
logAction(String.valueOf(progress));
}
});
¶ Progress sequence switching
Web/Typescript
room.pptNextStep(); // Next page (next step)
room.pptPreviousStep() // Previous (previous step)
iOS/Objective-C
[room pptNextStep]; // Next page (next step)
[room pptPreviousStep]; // Previous (previous step)
Android/Java
room.pptNextStep(); // Next page (next step)
room.pptPreviousStep(); // Previous (previous step)