Meishe sdk template generation instructions

Templates are one of the important technologies of Meishe SDK. Generating templates is the first step in using template technology. The generation process is divided into two steps:

1. Generate template information.

Call writeTemplateXml of NvsAssetPackageManager The interface generates template information corresponding to a timeline, and the three parameters are passed in from the outside.

The function prototype is as follows: Output the information of the template package and return whether it is successful.

timeline timeline object
aspectRatio The required template aspect ratio, which is generally consistent with the timeline aspect ratio. Refer to template resource package aspect ratio

uuidString template resource package ID

  writeTemplateXml(
      timeline: NvsTimeline,
      aspectRatio: number, // aspect ratio
      uuidString: string, // special effect uuid
  ): boolean;

If you need the template to support multiple frames, you can call this interface multiple times, as long as the timeline and aspectRatio are the required frames and the uuidString is the same.

Before calling this interface, you need to perform some prerequisite operations on the timeline and specify some additional information required to generate template information. These information are specified through the setTemplateAttachment interface on NvsProjObj.

The function prototype is as follows:

  setTemplateAttachment(key: string, value: string): void;

Currently the information (key values) that can be set includes:

  {
      isThemePackage: 'MSTemplate-isThemePackage',
      themeTitle: 'MSTemplate-ThemeTitle',
      themeTail: 'MSTemplate-ThemeTail',
      fillTimelineDuration: 'MSTemplate-FillTimelineDuration',
      replaceId: 'MSTemplate-ReplaceId',
      footageId: 'MSTemplate-FootageId',
      footageTags: 'MSTemplate-FootageTags',
      footageName: 'MSTemplate-FootageName',
      footageM3u8Name: 'MSTemplate-FootageM3U8Name',
      footageCanReplace: 'MSTemplate-FootageCanReplace',
      footageNeedReverse: 'MSTemplate-FootageNeedReverse',
      volumeType: 'MSTemplate-VolumeType',
      footageType: 'MSTemplate-FootageType',
      fxGroup: 'MSTemplate-FxGroup',
      fxSeekTime: 'MSTemplate-BestSeekTime',
      clipRawWidth: 'MSTemplate-ClipRawWidth',
      clipRawHeight: 'MSTemplate-ClipRawHeight',
      curveSpeedType: 'MSTemplate-CurveSpeedType',
      trimIn: 'MSTemplate-TrimIn',
      trimOut: 'MSTemplate-TrimOut',
      templateInnerAsset: 'MSTemplate-InnerAsset',
  }

1.1. FootageId information (required)

The key value is "MSTemplate-FootageId" and the value value is any string. For example "footage0".

When the template is used, the material is replaced in units of foot. Multiple clips can correspond to the same footing, and one clip can also be a footing. The same footage means: the footageId is the same. Clips corresponding to the same footing should ensure the following conditions:

A. The trim duration is the same, that is, trimOut - trimIn are the same;

B. The tag information is consistent. Footage can carry tag information, such as scenery, animals and other attributes, for classification;

C. Whether it is replaceable;

D. Do you need to put it upside down?

1.2. Is footing replaceable (not required, default is true)

The key value is "MSTemplate-FootageCanReplace" and the value value is "true" or "false".

The footage can be set to whether it can be replaced. If it can be replaced, the user can pass in the footage for replacement when using the template to achieve the desired effect.

1.3. Footage name (this item only needs to be specified for non-replaceable footwear)

The key value is "MSTemplate-FootageName", and the value value is the material name used by the clip. For example "XXXX.jpg".

Non-replaceable footprint exists as a built-in resource of the template. For built-in video and audio materials, in order to reduce the size of the template package, a file of corresponding duration should be transcoded.

For example, if a ten-minute video is to be built in, and the trim segment actually used is the 5th to 20th second of the video, then a video of this trim segment should be transcoded, and the footwearName should be set to the transcoded file name.

1.4. Footage attributes (not required, default empty string)

The key value is "MSTemplate-FootageTags", and the value value is a combination of tags, such as "landscape, animal", separated by commas.

1.5. Footage type (required)

The key value is "MSTemplate-FootageType", and the value value can be:

A: "video";

B: "image";

C: "videoImage";

D: "audio".

Make your selections as needed.

Use this to specify the type of footer. Users can pass in the corresponding type of materials when using the template.

1.6. Whether the footage needs to be played backwards (not required, default false)

The key value is "MSTemplate-FootageNeedReverse" and the value value is "true" or "false".

Indicates whether this footage needs to be placed upside down. For footage that needs to be played backwards, the user needs to play the incoming material backwards when using the template. This setting is only valid for video type footage.

1.7, replaceId setting

In addition to the footer information that must be specified, there is also an optional piece of information that must be specified:

Various effects used on the timeline, including stickers, subtitles, filters, etc., can be replaced by setting the replaceId (key value is "MSTemplate-ReplaceId", value value is any string, such as "caption0 ". For similar effects, the value cannot be repeated).

1.8, opening and ending settings

For theme templates, we can set the title and ending by setting isThemePackage, themeTitle, and themeTail (the values of key and value are respectively "MSTemplate-isThemePackage", value is, 'true' or 'false'. If isThemePackage is 'true', it means it is a theme template, and themeTitle and themeTail are valid. "MSTemplate-ThemeTitle", value is, 'true' or 'false' "MSTemplate-ThemeTail", value is, 'true' or 'false' ).

Through the above settings, the calibration of the information required for the template can be completed.

Generate template file

2.1. Function description

Call the generateTemplatePackage interface on NvsAssetPackageManager to generate a .templagte template file. The function prototype is as follows:

  //Generate template package and return whether successful
  generateTemplatePackage(
      innerAssetDir: string, // Built-in resource path
      uuidString: string, // template uuid
      outputPath: string, // output path
  ): boolean;

All three parameters are specified externally. in:
- uuidString must be consistent with the uuid used by the exportTemplateInfo interface;
- innerAssetDir is a folder directory of various resource packages used by timeline;
- outputPath is the folder path of the generated template file.

Finally, the interface generates a file with the uuid specified by uuidString and the suffix name template in the outputPath path.

The folder specified by innerAssetDir is the focus of this interface, and it is also the preparation work that needs to be done before calling this interface.

The folder directory structure is as follows:

Contains an info.json file and some folders.

Note: On the web side, we can view this path through FS.readdir(innerAssetDir). FS is an object provided by the SDK to operate the file system.

[ ".", "..", "empty.png", "a2a3b690-f7b1-42c3-8f0a-6dc018c8e217.jpg", "captionstyle", "captionrenderer", "captioncontext", "captionanimation", "captioninanimation", "captionoutanimation", "compoundcaption", "videotransition", "videofx", "animatedsticker", "animatedstickeranimation", "animatedstickerinanimation", "animatedstickeroutanimation", "resources", "info.json" ]

2.2. Explanation of files and folders

2.2.1, info.json file

This file is a description of the template, which needs to be generated by the front end. Its structure is as follows:

  {
      "allAspectRatioInfos": [
          {
              "aspectRatio": "16v9",
              "captionInfos": [],
              "duration": 10000,
              "footageCount": 2,
              "footageInfos": [],
              "innerAssetCount": 0,
              "stickerInfos": [],
              "timelineVideoFxInfos": [],
              "transitionInfos": [],
              "videoFxInfos": [
              ]
          },
          ...
      ],
      "captionInfos": [
          {
              "font": "Noto Sans CJK SC [NotoSansCJKsc-Regular]",
              "packageId": "331BCA93-6CA0-4C01-AA2D-479A8EC28E3E",
              "replaceId": "replace18",
              "text": "Good species of grass"
          },
          ...
      ],
      "cover": "6FBCC5DF-135A-4D70-845D-85DDEDE1EAC7.jpg",
      "defaultAspectRatio": "3v4",
      "description": "muli-111",
      "duration": 10000,
      "footageCount": 1,
      "footageInfos": [
          {
              "canReplace": false,
              "duration": 5000000,
              "footageId": "footage7",
              "footageName": "bd8b10f37fd542b7aff3a71af0d384b7.jpg",
              "type": "videoImage"
          },
          ...
      ],
      "innerAssetTotalCount": 5,
      "minSdkVersion": "2.18.0",
      "name": "muli-111",
      "platform": "bseditor",
      "sdkVersion": "3.10.2",
      "stickerInfos": [
          {
              "name_ch": "cream cake",
              "name_en": "Cream Cake",
              "packageId": "914904F1-E973-45F2-A4A7-577AA70DEBDF",
              "replaceId": "replace19"
          }
      ],
      "supportedAspectRatio": "16v9|9v16|1v1|3v4",
      "timelineVideoFxInfos": [
          {
              "name_ch": "Kraft paper open",
              "name_en": "Paper",
              "packageId": "2B8602E4-A840-4E7F-A70C-CCB29E446855",
              "replaceId": "replace17"
          }
      ],
      "transitionInfos": [
          {
              "name_ch": "Film light leak 03",
              "name_en": "Film Burn 03",
              "packageId": "EEE233D9-432E-4D19-8DC3-5DA3D4E37FD8",
              "replaceId": "replace16"
          }
      ],
      "translation": [
          {
              "originalText": "muli-111",
              "targetLanguage": "zh_CN",
              "targetText": "Multiple frames"
          }
      ],
      "uuid": "6FBCC5DF-135A-4D70-845D-85DDEDE1EAC7",
      "version": 1,
      "videoFxInfos": [
      ]
  }

cover: The cover of the template, optional;
minSdkVersion: the minimum sdk version supported by the template, the value must be 2.19.0 or above;
name: the name of the template;
supportedAspectRatio: the aspect ratio supported by the template, before calling exportTemplateInfo What proportion of template information is generated by the interface, and what proportion needs to be added here;
defaultAspectRatio: default aspect ratio;
translation: Chinese and English translation;
uuid: The uuid of the template must be consistent with the uuid passed in by the calling interface;
version: the version number of the template;
innerAssetTotalCount: The number of resource packages used by this template;
footageCount: the number of replaceable footage;
duration: the duration of the template;
creator: creator;
description: Description of the template.
allAspectRatioInfos: Template information for all frames, including frame, subtitles, stickers, filters and other information.
stickerInfos: sticker information.
captionInfos: subtitle information.
transitionInfos: transition information.
videoFxInfos: filter information.
timelineVideoFxInfos: timeline video special effects information.

2.2.2. Other folders

The package type resource packages used by Timeline need to be classified and placed in this folder. The classification standard is the suffix name of the resource package. The name of the classification folder must be consistent with the suffix name of the resource package, as shown in the figure above.

Each category is not necessary. If there is a resource package using this category, put it in a folder of this category. There is no need to create an empty folder.

The folder structure diagram of a certain category is as follows:

After the innerAssetDir folder is ready, call the generateTemplatePackage interface on NvsAssetPackageManager to complete template file generation.