通過設定檔自訂短視頻SDK濾鏡與轉場-ApsaraVideo for VOD-阿里雲

短視頻SDK提供了自訂特效能力，您可以基於通用特效設定檔，通過自訂OpenGL ES Shader（OpenGL ES 3.0文法），實現想要的濾鏡與轉場效果。有關OpenGL ES的知識點和解釋並不屬於本篇文檔的範疇，我們預設您已經對OpenGL ES及其Shader Language有所瞭解。

簡介

一個濾鏡或轉場的特效資源套件檔案夾，包含了一個名為config.json的通用特效設定檔以及一些圖片素材。在短視頻SDK中編輯視頻和錄製視頻時，支援使用轉場和濾鏡特效，即調用相關編輯和錄製介面時，傳入所配置的特效資源套件檔案夾目錄，來應用一個特效效果。

配置通用特效設定檔

通用特效設定檔採用JSON格式，描述了完整的渲染過程。整體結構分為兩個層級，第一層級描述了特效的基本資料，第二層級用節點樹描述了特效的實現細節。

特效基本資料-第一層級

特效的基本資料包含以下欄位：

欄位	說明
name	特效名稱。
module	模組標識，該欄位必須是`ALIVC_GECF`。
version	版本號碼，目前的版本為1。
type	特效類型，1表示濾鏡，2表示轉場。
nodeTree	節點樹，用於描述特效的實現細節，詳細內容請參見節點樹-第二層級。

以特效Intense濾鏡的設定檔為例，樣本如下：

{
    "name": "Intense",
    "module": "ALIVC_GECF",
    "version": 1,
    "type": 1,
    "nodeTree": [
        {
            "nodeId": 0,
            "name": "Intense",
            "fragment": "/** ...... */",
            "textures": [
                {
                    "name": "inputImageTexture",
                    "srcType": "INPUT_NODE",
                    "nodeId": 0
                },
                {
                    "name": "inputImageTexture2",
                    "srcType": "IMAGE",
                    "path": "color.png"
                }
            ]
        }
    ]
}

節點樹-第二層級

節點樹nodeTree用於描述一個渲染流程，包含了一個或多個節點。

在短視頻SDK中，渲染流程如圖所示：濾鏡及特效

據上圖所示，渲染過程被抽象為一系列節點群組成的樹狀結構。

輸入節點INPUT_NODE代表原始輸入源。在錄製情境下，輸入節點是網路攝影機採集的映像資料流。在編輯情境下，輸入節點是當前播放視頻流。在設計上，輸入節點可以是多個。例如轉場過程中，需要對前後兩個視頻做效果變換。此時，前一個視頻是INPUT_NODE0，後一個是INPUT_NODE1。
中間的節點樹部分即對應設定檔中的nodeTree欄位。一個節點樹可以包含一個或多個渲染節點。可以看到，整個渲染設定檔的關鍵就是有關節點的配置。
輸出節點OUTPUT_NODE代表渲染後的視頻流。在預覽模式下，輸出節點輸出到螢幕。在合成模式下，輸出節點輸出到編碼器編碼。

節點

節點欄位描述了整個渲染流程中，某一次繪製過程中的相關配置，這裡的配置包含了自訂特效所必須的著色器代碼以及相關參數描述。節點包含以下欄位：

欄位	說明
nodeId	節點id，用於標識當前節點。
name	節點名稱。
vertex	頂點著色器代碼。該欄位作用與vertexPath欄位相同，聲明其中任意一個即可。該欄位可以不寫，如果不填寫，SDK會提供預設實現如下： `attribute vec4 position; attribute vec4 inputTextureCoordinate; varying vec2 textureCoordinate; void main() { gl_Position = position; textureCoordinate = inputTextureCoordinate.xy; }`
vertexPath	頂點著色器代碼所在檔案路徑。該欄位作用與vertex欄位相同，聲明其中任意一個即可。
attributes	attributes列表，該欄位用於聲明頂點著色中attribute參數名name和類型type。 type取值為：POSITION，頂點座標；TEXTURECOORD，紋理座標。該欄位可以不填寫，如果不填寫，SDK會提供預設實現如下： `[ { "name": "position", "type": "POSITION" }, { "name": "inputTextureCoordinate", "type": "TEXTURECOORD" } ]`
fragment	片段著色器代碼。該欄位作用與fragmentPath欄位相同，聲明其中任意一個即可。
fragmentPath	片段著色器代碼所在檔案路徑。該欄位作用與fragment欄位相同，聲明其中任意一個即可。
textures	紋理列表。用於描述片段著色器中`sampler2D`紋理參數的相關屬性。屬性包括： name：紋理名。 srcType：紋理資料來源類型，代表待繪製的紋理資料從哪裡擷取。支援類型如下： IMAGE：當前紋理來自資源圖片，該類型需要同時聲明`path`欄位，並且把圖片檔案放到資源套件中 INPUT_NODE：當前紋理來自輸入節點傳入的映像資料，該類型需要同時聲明nodeId欄位 CUSTOM_NODE：當前紋理來自自訂節點處理後的映像資料，該類型需要同時聲明nodeId欄位。 nodeId：節點id。 srcType為CUSTOM_NODE或INPUT_NODE時需要填寫。當srcType為INPUT_NODE時，nodeId欄位不能隨意填寫。濾鏡情境下為0。轉場情境下前一個視頻流nodeId為0，後一個視頻流nodeId為1。 path：資源檔路徑，srcType為IMAGE時需要填寫。
params	參數列表。用於描述片段著色器中`uniform`參數的相關屬性。屬性包括： name：參數名。 type：參數類型。支援的類型請參見params參數類型（type）支援的類型。 value：參數取值。 maxValue：參數最大值。 minValue：參數最小值。

params參數類型（type）支援的類型

類型	參數取值樣本
INT	[1]
FLOAT	[-2.0]
VEC2I	[3, 2]
VEC3I	[1, 2, 3]
VEC4I	[4, 3, 2, 1]
VEC2F	[-1.0, 1.0]
VEC3F	[0.5, 0.5, 0.5]
VEC4F	[1.0, -1.0, 1.0, -1.0]
MAT3F	[1.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 1.0]
MAT4F	[1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0, 0.0, 0.0, 0.0, 1.0]

以特效Translate轉場的設定檔為例，樣本如下：

{
    "name": "Translate",
    "module": "ALIVC_GECF",
    "version": 1,
    "type": 2,
    "nodeTree": [
        {
            "nodeId": 0,
            "name": "Translate",
            "vertex": "/** ...... */",
            "attributes": [
                {
                    "name": "a_position",
                    "type": "POSITION"
                },
                {
                    "name": "a_texcoord",
                    "type": "TEXTURECOORD"
                }
            ],
            "fragment": "/** ...... */",
            "textures": [
                {
                    "name": "RACE_Tex0",
                    "srcType": "INPUT_NODE",
                    "nodeId": 0
                },
                {
                    "name": "RACE_Tex1",
                    "srcType": "INPUT_NODE",
                    "nodeId": 1
                }
            ],
            "params": [
                {
                    "name": "direction",
                    "type": "INT",
                    "value": [
                        0
                    ],
                    "maxValue": [
                        3
                    ],
                    "minValue": [
                        0
                    ]
                }
            ]
        }
    ]
}

內建變數

SDK中內建了一些變數，您可以在shader中直接聲明，目前有以下內建變數：

uniform highp float BUILTIN_PROGRESS; // 轉場進度：0~1
uniform highp float BUILTIN_WIDTH;    // 映像寬
uniform highp float BUILTIN_HEIGHT;   // 映像高

在短視頻SDK中使用特效

使用特效通常需要先建立特效對象，再應用特效，最後按需更新特效參數。

初始化後的特效對象內可以擷取到描述特效配置的AliyunEffectConfig對象，該對象內部結構與特效設定檔的結構相對應。如果某一個自訂特效設定檔裡包含有params欄位，對應在代碼中可以通過AliyunEffectConfig-> nodeTree -> params擷取到AliyunParam對象。AliyunParam對象中的value欄位就是當前參數的值。更新特效參數需要以下兩步：

通過AliyunValue對象提供的update設值方法更新參數值。
調用特效更新方法更新參數。具體特效更新方法請參見如下操作步驟中的第三步更新特效參數。

Android操作步驟

濾鏡
1. 調用EffectFilter(String path)方法建立特效對象，path參數為特效檔案夾路徑。
2. 調用int addAnimationFilter(EffectFilter filter);方法應用濾鏡特效。
3. 調用int updateAnimationFilter(EffectFilter filter);方法更新濾鏡特效參數。
轉場
1. 調用TransitionBase(String path)建立特效對象，path參數為特效檔案夾路徑。
2. 調用int setTransition(int index, TransitionBase transition);方法應用轉場特效。
3. 調用int updateTransition(int clipIndex, TransitionBase transitionBase);方法更新轉場特效參數。

iOS操作步驟

濾鏡
1. 調用AliyunEffectFilter的- (instancetype)initWithFile:(NSString *)path;方法建立特效對象，path參數為特效檔案夾路徑。
2. 調用- (int)applyAnimationFilter:(AliyunEffectFilter *)filter;方法應用濾鏡特效。
3. 調用- (int)updateAnimationFilter:(AliyunEffectFilter *)filter;方法更新濾鏡特效參數。
轉場
1. 調用AliyunTransitionEffect的-(instancetype)initWithPath:(NSString *)path;方法建立特效對象，path參數為特效檔案夾路徑。
2. 調用- (int)applyTransition:(AliyunTransitionEffect *)transition atIndex:(int)clipIdx;方法應用轉場特效。
3. 調用-(int)updateTransition:(AliyunTransitionEffect *)transition atIndex:(int)clipIdx;方法更新轉場特效參數。