扫一扫咨询方案
首页
登录/注册

{user.username}

ID: {user.id}

模板 SDK 文档

  • 云渲染

    • Demo下载
    • SDK
    • 开发指南
    • AI API 文档
    • 开发者 API 文档
    • 控制台指南
    • 快速入门
    • 产品简介
  • 模板SDK

    • 用户常见问题
    • Demo 下载
    • 开发指南
    • 服务端 SDK
    • iOS SDK
    • 安卓端 SDK
    • 产品简介
  • 剪辑SDK

    • Demo下载
    • SDK
    • 开发指南
    • 产品简介
  • 模板制作教程

    • 模板制作进阶教程
    • 测试模板素材案例下载
    • 常见模板制作案例
    • 模板制作教程
    • 模板制作工具下载
    • 入门指南
  • 剪辑制作教程

    • 剪辑特效导出教程
    • 剪辑特效测试素材
    • 剪辑特效制作工具下载
    • 入门指南
产品简介
安卓端 SDK
iOS SDK
服务端 SDK
开发指南
Demo 下载
用户常见问题
首页 > 安卓端 SDK > 动态模板接入 > 高级素材替换指南

高级素材替换指南

更新时间 : 2021-07-29 14:48:14

ReplaceableJson 是 VE 定义的替换数据规范,可以方便开发人员实现素材的高级替换。

通过 ReplaceableJson 可以更方便的实现模板高级字幕替换和图片替换,同时具有更好的扩展性,方便对替换素材增加更多的功能特性。

数据结构规范

大部分attr属性设置为非必须选项,可根据自己的需要设置对应的属性。 大部分type属性为必须选项,请注意不要设置错误的type类型 完全兼容旧版本数据格式

ReplaceableJson 是替换素材对象的 json 数组:

[
    {..}, //  替换素材对象,结构参考下文
    {..}
]

动态模板高级素材替换

动态模板替换分为主素材替换(main_file)、主素材所链接的子素材替换和ui_key精确替换(replaces)。3种替换可组装在同一个json中。主素材是用来构建模板的基本对象,有主素材才能生成动态模板的片段,多个片段拼接即可生成视频。子素材为主素材的关联替换素材,一般用作配字幕,2.4.0以上版本可通过ConfigUtils获取主素材所关联的子素材信息来组装replaces。ui_key精确替换是通过ui_key全局查找替换。

替换素材对象常用结构如下:

{
    "main_file" : "/path/to/asset_file.log", // 主替换素材
    "replaces": [  // 与主替换素材关联的高级替换素材
        {  // 图片替换
            "d_key_prefix": "dtext",    // 按前缀 dtext 查找替换 (新版标记方式中无需此字段)
            "type": 1, // 类型, 1-图片,2-文字,3-富文本
            "file": "/home/slayer/Desktop/workspace/assets/235_41_text1.png" // 替换图片路径
        },
        { // 文字替换
            "d_key_prefix": "dtext", // 按前缀 dtext 查找替换 (新版标记方式中无需此字段)
            "type": 2,
            "attr":{
                "text": "字幕四,居中"
            }
        }
    ]
}

实现高级素材的精确替换,使用没有 main_file 的替换素材对象结构:

{  // 没有 main_file, 表示 replaces 中的所有素材为精确查找 d_key 值替换,
    "replaces": [
        {
            "d_key": "headimg", // 按 headimg 精确查找替换图片,(注意字段为 d_key)
            "type": 1,
            "file": "/home/slayer/Desktop/workspace/assets/235_41_text7.png" // 图片路径
        },
        { // 高级文字替换
            "d_key": "title", // 按 title 精确查找替换文字, (注意字段为 d_key)
            "type": 2,
            "attr":{
                "text": "字幕四,居中"
            }
        }
    ]
 }

以上 replaces 中的对象结构,适用于实现动态模板高级字幕,图片的替换。 替换方式有

使用步骤:

注意事项

完善数据结构示例

//动态模版, ui_key请标记在图层上
[
    {
        "main_file" : "/path/to/asset_file.jpg", // 主替换素材
        "attr":{
            "loop": 1, // 视频/gif 素材有效,0- 使用引擎默认循环逻辑,1 - 循环, 2 - 不循环,(2.0 版本新增) 默认值为:0
            "volume": 0.5,  // 视频素材有效, 音量 >= 0, 标准音量范围为0~1,但可超出1(2.0 版本新增) 默认值为:0
        },
        "replaces": [  // 与主替换素材关联的高级替换素材(目前关联素材的数量与类型需与设计约定)
            {  // 图片替换
                "d_key_prefix": "dtext",    // 按前缀 dtext 查找替换 (新版标记方式中无需此字段)
                "type": 1, // 类型, 1-图片或视频,2-文字,3-高级字符文字
                "file": "/home/slayer/Desktop/workspace/assets/235_41_text1.png", // 替换图片路径
                "attr":{
                    "loop": 1, // 视频/gif 素材有效,0- 使用引擎默认循环逻辑,1 - 循环, 2 - 不循环,(2.0 版本新增) 默认值为:0
                    "volume": 0.5,  // 视频素材有效, 音量 >= 0, 标准音量范围为0~1,但可超出1(2.0 版本新增) 默认值为:0
                    "adapt_type":0,  //适配方式  0:不做适配,1:cover (图片居中填满空间),2:contain (完整居中显示图片), 3:fill(不等比缩放),4:transform(使用transform字段对应的矩阵) 默认值为:0
                    //2.2.0版本新增
                    "transform":[a,c,e,b,d,f] //行矩阵,[sclaeX, skewX, transX, skewY, scaleY, transY]。矩阵为在原始图片的局部坐标系矩阵,默认为单位矩阵
                    "clip_start":0.0,//视频裁剪开始时间,不需要裁剪不传即可,clip_end必须大于clip_start
                    "clip_end":-1.0, //视频裁剪结束时间,大于0表示需要裁剪,小于等于0表示末尾不需要裁剪
                }
            },
            { // 文字替换
                "d_key_prefix": "dtext", // 按前缀 dtext 查找替换 (新版标记方式中无需此字段)
                "type": 2,
                "attr":{
                    "text" : "", //文字内容  超出截断  
                    "adapt": true, //是否开启文字自适应,仅对文本框类型文字有效,默认关闭 (默认使用模版设计中的适配方式)
                    "fill" : "#FFFFFF", //文字填充颜色 格式为RGB
                    "stroke": "#FFFFFF", //文字描边颜色 格式为RGB
                    "stroke_width":0.0, //描边宽度
                    "stroke_over_fill":false, //描边是否在填充之上
                    "size":0, //文字大小, 单位为像素
                    "font_family":"", //字体系列名称 (SDK绘制时有效 通过字体系列名称查找SDK中加载过的字体,推荐此中方式)               | 二选一
                    "font_file":""  //字体文件路径  (SDK绘制时有效 直接使用此字体,建议使用ttf字体,不推荐使用包含多种语言的字体集)      | 二选一
                }
            },
            { // 高级文字替换
                "d_key_prefix": "dtext", // 按前缀 dtext 查找替换 (新版标记方式中无需此字段)
                "type": 3,
                "attr":{
                    "text" : "", //文字内容  超出截断  
                    "adapt": true, //是否开启文字自适应,仅对文本框类型文字有效,默认关闭 (默认使用模版设计中的适配方式)
                    "fill" : "#FFFFFF", //文字填充颜色 格式为RGB
                    "stroke": "#FFFFFF", //文字描边颜色 格式为RGB
                    "stroke_width":0.0, //描边宽度
                    "stroke_over_fill":false, //描边是否在填充之上
                    "size":0, //文字大小, 单位为像素
                    "font_family":"", //字体系列名称 (通过字体系列名称查找SDK中加载过的字体,推荐此中方式)                | 二选一
                    "font_file":""  //字体文件路径  (直接使用此字体,建议使用ttf字体,不推荐使用包含多种语言的字体集)   | 二选一
                }
            }
        ]
    },
    {  // 没有 main_file, 表示 replaces 中的所有素材为精确查找 d_key 值替换,
        "replaces": [
            { //图片替换
                "d_key": "headimg", // 按 headimg 精确查找替换图片,(注意字段为 d_key)
                "type": 1,
                "file": "/home/slayer/Desktop/workspace/assets/235_41_text7.png", // 图片路径
                "attr":{
                    "loop": 1, // 视频/gif 素材有效,0- 使用引擎默认循环逻辑,1 - 循环, 2 - 不循环,(2.0 版本新增) 默认值为:0
                    "volume": 0.5,  // 视频素材有效, 音量 >= 0, 标准音量范围为0~1,但可超出1(2.0 版本新增) 默认值为:0
                    "adapt_type":0,  //适配方式  0:不做适配,1:cover (图片居中填满空间),2:contain (完整居中显示图片), 3:fill(不等比缩放),4:transform(使用transform字段对应的矩阵) 默认值为:0
                    //2.2.0版本新增
                    "transform":[a,c,e,b,d,f] //行矩阵,[sclaeX, skewX, transX, skewY, scaleY, transY]。矩阵为在原始图片的局部坐标系矩阵,默认为单位矩阵
                    "clip_start":0.0,//视频裁剪开始时间,不需要裁剪不传即可,clip_end必须大于clip_start
                    "clip_end":-1.0, //视频裁剪结束时间,大于0表示需要裁剪,小于等于0表示末尾不需要裁剪
                }
            },
            { // 文字替换
                "d_key": "title", // 按 title 精确查找替换文字, (注意字段为 d_key)
                "type": 2,
                "attr":{
                    "text" : "", //文字内容  超出截断  
                    "adapt": true, //是否开启文字自适应,仅对文本框类型文字有效,默认关闭 (默认使用模版设计中的适配方式)
                    "fill" : "#FFFFFF", //文字填充颜色 格式为RGB
                    "stroke": "#FFFFFF", //文字描边颜色 格式为RGB
                    "stroke_width":0.0, //描边宽度
                    "stroke_over_fill":false, //描边是否在填充之上
                    "size":0, //文字大小, 单位为像素
                    "font_family":"", //字体系列名称 (SDK绘制时有效 通过字体系列名称查找SDK中加载过的字体,推荐此中方式)                   | 二选一
                    "font_file":""  //字体文件路径  (SDK绘制时有效 直接使用此字体,建议使用ttf字体,不推荐使用包含多种语言的字体集)      | 二选一
                }
            },
            { // 高级文字替换
                "d_key": "topic", // 按 topic 精确查找替换文字, (注意字段为 d_key)
                "type": 3,
                "attr":{
                    "text" : "", //文字内容  超出截断  
                    "adapt": true, //是否开启文字自适应,仅对文本框类型文字有效,默认关闭 (默认使用模版设计中的适配方式)
                    "fill" : "#FFFFFF", //文字填充颜色 格式为RGB
                    "stroke": "#FFFFFF", //文字描边颜色 格式为RGB
                    "stroke_width":0.0, //描边宽度
                    "stroke_over_fill":false, //描边是否在填充之上
                    "size":0, //文字大小, 单位为像素
                    "font_family":"", //字体系列名称 (通过字体系列名称查找SDK中加载过的字体,推荐此中方式)                | 二选一
                    "font_file":""  //字体文件路径  (直接使用此字体,建议使用ttf字体,不推荐使用包含多种语言的字体集)   | 二选一
                }
            }
#       ]
     }
]
首页 > 安卓端 SDK > 动态模板接入 > 高级素材替换指南
高级素材替换指南
更新时间 : 2021-07-29 14:48:14
  • 云渲染
    • Demo下载
    • SDK
    • 开发指南
    • AI API 文档
    • 开发者 API 文档
    • 控制台指南
    • 快速入门
    • 产品简介
  • 模板SDK
    • 用户常见问题
    • Demo 下载
    • 开发指南
    • 服务端 SDK
    • iOS SDK
    • 安卓端 SDK
    • 产品简介
  • 剪辑SDK
    • Demo下载
    • SDK
    • 开发指南
    • 产品简介
  • 模板制作教程
    • 模板制作进阶教程
    • 测试模板素材案例下载
    • 常见模板制作案例
    • 模板制作教程
    • 模板制作工具下载
    • 入门指南
  • 剪辑制作教程
    • 剪辑特效导出教程
    • 剪辑特效测试素材
    • 剪辑特效制作工具下载
    • 入门指南

ReplaceableJson 是 VE 定义的替换数据规范,可以方便开发人员实现素材的高级替换。

通过 ReplaceableJson 可以更方便的实现模板高级字幕替换和图片替换,同时具有更好的扩展性,方便对替换素材增加更多的功能特性。

数据结构规范

大部分attr属性设置为非必须选项,可根据自己的需要设置对应的属性。 大部分type属性为必须选项,请注意不要设置错误的type类型 完全兼容旧版本数据格式

ReplaceableJson 是替换素材对象的 json 数组:

[
    {..}, //  替换素材对象,结构参考下文
    {..}
]

动态模板高级素材替换

动态模板替换分为主素材替换(main_file)、主素材所链接的子素材替换和ui_key精确替换(replaces)。3种替换可组装在同一个json中。主素材是用来构建模板的基本对象,有主素材才能生成动态模板的片段,多个片段拼接即可生成视频。子素材为主素材的关联替换素材,一般用作配字幕,2.4.0以上版本可通过ConfigUtils获取主素材所关联的子素材信息来组装replaces。ui_key精确替换是通过ui_key全局查找替换。

替换素材对象常用结构如下:

{
    "main_file" : "/path/to/asset_file.log", // 主替换素材
    "replaces": [  // 与主替换素材关联的高级替换素材
        {  // 图片替换
            "d_key_prefix": "dtext",    // 按前缀 dtext 查找替换 (新版标记方式中无需此字段)
            "type": 1, // 类型, 1-图片,2-文字,3-富文本
            "file": "/home/slayer/Desktop/workspace/assets/235_41_text1.png" // 替换图片路径
        },
        { // 文字替换
            "d_key_prefix": "dtext", // 按前缀 dtext 查找替换 (新版标记方式中无需此字段)
            "type": 2,
            "attr":{
                "text": "字幕四,居中"
            }
        }
    ]
}

实现高级素材的精确替换,使用没有 main_file 的替换素材对象结构:

{  // 没有 main_file, 表示 replaces 中的所有素材为精确查找 d_key 值替换,
    "replaces": [
        {
            "d_key": "headimg", // 按 headimg 精确查找替换图片,(注意字段为 d_key)
            "type": 1,
            "file": "/home/slayer/Desktop/workspace/assets/235_41_text7.png" // 图片路径
        },
        { // 高级文字替换
            "d_key": "title", // 按 title 精确查找替换文字, (注意字段为 d_key)
            "type": 2,
            "attr":{
                "text": "字幕四,居中"
            }
        }
    ]
 }

以上 replaces 中的对象结构,适用于实现动态模板高级字幕,图片的替换。 替换方式有

  • d_key_prefix 指定的前缀查找替换
  • d_key 指定的精确查找替换

使用步骤:

  • d_key 与 d_key_prefix 都与模板标记的 ui_key 有关,需要按下文的步骤了解使用。

  • 先了解 ui_key 作用

    ui_key 的作用是什么

  • 设计师按照以下视频教程标记导出动态模板

    旧版标记方式-动态模板高级素材替换视频教程
    需要和开发者约定好, 替换的 ui_key 或 ui_key 前缀

    新版标记方式-动态模板高级素材替换视频教程

    无需与开发者约定好ui_key 前缀,但精确查找仍需要约定ui_key

  • 开发者根据上文介绍的 ReplaceableJson 规范,组装好数据并调用 setReplaceableJson 接口。对于replaces字段应该如何组装,2.4.0版本以上可通过ConfigUtils方法解析模板,获取所需要替换的元素信息来组装数据

注意事项

  • setReplaceableJson 已经实现 setReplaceableFiles / setDynamicSubFiles / setDynamicSubTexts所有的功能,不能同时调用

完善数据结构示例

//动态模版, ui_key请标记在图层上
[
    {
        "main_file" : "/path/to/asset_file.jpg", // 主替换素材
        "attr":{
            "loop": 1, // 视频/gif 素材有效,0- 使用引擎默认循环逻辑,1 - 循环, 2 - 不循环,(2.0 版本新增) 默认值为:0
            "volume": 0.5,  // 视频素材有效, 音量 >= 0, 标准音量范围为0~1,但可超出1(2.0 版本新增) 默认值为:0
        },
        "replaces": [  // 与主替换素材关联的高级替换素材(目前关联素材的数量与类型需与设计约定)
            {  // 图片替换
                "d_key_prefix": "dtext",    // 按前缀 dtext 查找替换 (新版标记方式中无需此字段)
                "type": 1, // 类型, 1-图片或视频,2-文字,3-高级字符文字
                "file": "/home/slayer/Desktop/workspace/assets/235_41_text1.png", // 替换图片路径
                "attr":{
                    "loop": 1, // 视频/gif 素材有效,0- 使用引擎默认循环逻辑,1 - 循环, 2 - 不循环,(2.0 版本新增) 默认值为:0
                    "volume": 0.5,  // 视频素材有效, 音量 >= 0, 标准音量范围为0~1,但可超出1(2.0 版本新增) 默认值为:0
                    "adapt_type":0,  //适配方式  0:不做适配,1:cover (图片居中填满空间),2:contain (完整居中显示图片), 3:fill(不等比缩放),4:transform(使用transform字段对应的矩阵) 默认值为:0
                    //2.2.0版本新增
                    "transform":[a,c,e,b,d,f] //行矩阵,[sclaeX, skewX, transX, skewY, scaleY, transY]。矩阵为在原始图片的局部坐标系矩阵,默认为单位矩阵
                    "clip_start":0.0,//视频裁剪开始时间,不需要裁剪不传即可,clip_end必须大于clip_start
                    "clip_end":-1.0, //视频裁剪结束时间,大于0表示需要裁剪,小于等于0表示末尾不需要裁剪
                }
            },
            { // 文字替换
                "d_key_prefix": "dtext", // 按前缀 dtext 查找替换 (新版标记方式中无需此字段)
                "type": 2,
                "attr":{
                    "text" : "", //文字内容  超出截断  
                    "adapt": true, //是否开启文字自适应,仅对文本框类型文字有效,默认关闭 (默认使用模版设计中的适配方式)
                    "fill" : "#FFFFFF", //文字填充颜色 格式为RGB
                    "stroke": "#FFFFFF", //文字描边颜色 格式为RGB
                    "stroke_width":0.0, //描边宽度
                    "stroke_over_fill":false, //描边是否在填充之上
                    "size":0, //文字大小, 单位为像素
                    "font_family":"", //字体系列名称 (SDK绘制时有效 通过字体系列名称查找SDK中加载过的字体,推荐此中方式)               | 二选一
                    "font_file":""  //字体文件路径  (SDK绘制时有效 直接使用此字体,建议使用ttf字体,不推荐使用包含多种语言的字体集)      | 二选一
                }
            },
            { // 高级文字替换
                "d_key_prefix": "dtext", // 按前缀 dtext 查找替换 (新版标记方式中无需此字段)
                "type": 3,
                "attr":{
                    "text" : "", //文字内容  超出截断  
                    "adapt": true, //是否开启文字自适应,仅对文本框类型文字有效,默认关闭 (默认使用模版设计中的适配方式)
                    "fill" : "#FFFFFF", //文字填充颜色 格式为RGB
                    "stroke": "#FFFFFF", //文字描边颜色 格式为RGB
                    "stroke_width":0.0, //描边宽度
                    "stroke_over_fill":false, //描边是否在填充之上
                    "size":0, //文字大小, 单位为像素
                    "font_family":"", //字体系列名称 (通过字体系列名称查找SDK中加载过的字体,推荐此中方式)                | 二选一
                    "font_file":""  //字体文件路径  (直接使用此字体,建议使用ttf字体,不推荐使用包含多种语言的字体集)   | 二选一
                }
            }
        ]
    },
    {  // 没有 main_file, 表示 replaces 中的所有素材为精确查找 d_key 值替换,
        "replaces": [
            { //图片替换
                "d_key": "headimg", // 按 headimg 精确查找替换图片,(注意字段为 d_key)
                "type": 1,
                "file": "/home/slayer/Desktop/workspace/assets/235_41_text7.png", // 图片路径
                "attr":{
                    "loop": 1, // 视频/gif 素材有效,0- 使用引擎默认循环逻辑,1 - 循环, 2 - 不循环,(2.0 版本新增) 默认值为:0
                    "volume": 0.5,  // 视频素材有效, 音量 >= 0, 标准音量范围为0~1,但可超出1(2.0 版本新增) 默认值为:0
                    "adapt_type":0,  //适配方式  0:不做适配,1:cover (图片居中填满空间),2:contain (完整居中显示图片), 3:fill(不等比缩放),4:transform(使用transform字段对应的矩阵) 默认值为:0
                    //2.2.0版本新增
                    "transform":[a,c,e,b,d,f] //行矩阵,[sclaeX, skewX, transX, skewY, scaleY, transY]。矩阵为在原始图片的局部坐标系矩阵,默认为单位矩阵
                    "clip_start":0.0,//视频裁剪开始时间,不需要裁剪不传即可,clip_end必须大于clip_start
                    "clip_end":-1.0, //视频裁剪结束时间,大于0表示需要裁剪,小于等于0表示末尾不需要裁剪
                }
            },
            { // 文字替换
                "d_key": "title", // 按 title 精确查找替换文字, (注意字段为 d_key)
                "type": 2,
                "attr":{
                    "text" : "", //文字内容  超出截断  
                    "adapt": true, //是否开启文字自适应,仅对文本框类型文字有效,默认关闭 (默认使用模版设计中的适配方式)
                    "fill" : "#FFFFFF", //文字填充颜色 格式为RGB
                    "stroke": "#FFFFFF", //文字描边颜色 格式为RGB
                    "stroke_width":0.0, //描边宽度
                    "stroke_over_fill":false, //描边是否在填充之上
                    "size":0, //文字大小, 单位为像素
                    "font_family":"", //字体系列名称 (SDK绘制时有效 通过字体系列名称查找SDK中加载过的字体,推荐此中方式)                   | 二选一
                    "font_file":""  //字体文件路径  (SDK绘制时有效 直接使用此字体,建议使用ttf字体,不推荐使用包含多种语言的字体集)      | 二选一
                }
            },
            { // 高级文字替换
                "d_key": "topic", // 按 topic 精确查找替换文字, (注意字段为 d_key)
                "type": 3,
                "attr":{
                    "text" : "", //文字内容  超出截断  
                    "adapt": true, //是否开启文字自适应,仅对文本框类型文字有效,默认关闭 (默认使用模版设计中的适配方式)
                    "fill" : "#FFFFFF", //文字填充颜色 格式为RGB
                    "stroke": "#FFFFFF", //文字描边颜色 格式为RGB
                    "stroke_width":0.0, //描边宽度
                    "stroke_over_fill":false, //描边是否在填充之上
                    "size":0, //文字大小, 单位为像素
                    "font_family":"", //字体系列名称 (通过字体系列名称查找SDK中加载过的字体,推荐此中方式)                | 二选一
                    "font_file":""  //字体文件路径  (直接使用此字体,建议使用ttf字体,不推荐使用包含多种语言的字体集)   | 二选一
                }
            }
#       ]
     }
]