美摄Web端SDK  3.12.1
详细开发引导

详细内容

1 概述

美摄SDK致力于解决web视频开发的技术门槛，使仅有web界面开发经验的程序员，都可以开发出性能优异、渲染效果丰富的的视频录制、编辑功能。我们的优势体现在：

  • 录制、剪辑不限时长
  • 行业最高标准的美颜效果
  • 剪辑、变速实时预览，无需转码
  • 图片、视频混编
  • 生成视频最高支持1080p
  • 丰富的转场、滤镜、字幕样式
  • 独家的主题
  • 支持4K制作和生成
  • 开放的自定义贴纸功能

1.1 支持格式

  • 输入规范：
    • 视频格式：MP4、MKV、TS、MTS、M2TS、AVI、FLV、MOV、M2P、MPG、RM、RMVB、WMV、VOB、3GP、GIF、MXF、M4V、WEBM
    • 音频格式：MP3、WAV、AAC、AC3、M4A、MXF、FLAC、OPUS、
    • 图片格式：PNG、JPG、JPEG、JPE、BMP、TGA、PSD、WEBP、
    • 视频编码：H264、WMV、MPEG4
    • 音频编码：MP3、AAC、PCM、FLAC
  • 输出规范：
    • 视频格式：MP4、MOV、WEBM、MXF、MPG、AVI
    • 视频编码：H264、MPEG2-IBP
    • 音频编码：AAC、MP3
  • 扩展包格式（扩展包是美摄用来承载扩展素材的内容包，包括字幕、滤镜、贴纸等）：
    • 字幕：.captionstyle
    • 组合字幕: .compoundCaption
    • 花字: .captionrenderer
    • 气泡: .captioncontext
    • 入动画: captioninanimation
    • 出动画: captionoutanimation
    • 组合动画: .captionanimation
    • 滤镜：.videofx
    • 贴纸：.animatedsticker
    • 贴纸入动画: .animatedstickerinanimation
    • 贴纸出动画: .animatedstickeroutanimation
    • 贴纸组合动画: .animatedstickeranimation
    • 转场：.videotransition
    • 模板: .template
    • 工程: .project

1.2 注意事项

  1. 运行环境如下：Chrome、FireFox、Edge、Safari等主流的浏览器几乎都支持,
  2. 美摄sdk使用了SharedArrayBuffer技术, 对于网站的开发环境和正式部署环境，需要添加下面两个标头，以实现网站的跨源隔离 
      Cross-Origin-Opener-Policy: same-origin
  Cross-Origin-Embedder-Policy: require-corp
    以开发环境为例 
      // vite.config.js
  export default defineConfig({
    plugins: [
        ...,
        {
            name: "configure-response-headers",
            configureServer: (server) => {
                server.middlewares.use((_req, res, next) => {
                res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
                res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
                next();
                });
            },
        },
    ],
    ...
  })
  3. 对于正式部署环境，还必须使用安全的上下文以支持SharedArrayBuffer技术

2 快速接入

2.1 导入库文件

如果没有MeisheSDK库，请先联系美摄商务获取sdk和授权：

  1. 引入美摄SDK接口文件NvEffectSdk.js 
      <script src="https://alieasset.meishesdk.com/NvWasm/domain/13/NvEffectSdk.js"></script>
  2. 使用美摄提供的加载工具加载wasm相关文件
  • (a) 安装meishewasmloader 参考 
      npm i meishewasmloader --save
  • (b) 使用WASMLoader加载wasm相关文件 
      import { WASMLoader }  from 'meishewasmloader';
  const wasmLoader = WASMLoader({
      // 加载进度回调       
      showLoader: function (state) {},
      // 失败回调
      showError(errorText: string) {},
      // 成功回调
      loadingFinished() {},
  });
  wasmLoader.loadEmscriptenModule("https://alieasset.meishesdk.com/NvWasm/domain/13/"); // 开始调用函数加载
注解
https://alieasset.meishesdk.com/NvWasm/domain/13/ 地址为美摄提供的测试公用地址，如果客户产品准备发布上线，需要联系商务获取sdk相关文件，私有化部署到客户的环境中，替换此地址再使用；
私有化部署wasm相关文件时，要对wasm文件配置brotli或者gzip进行压缩，有助于提升加载速度；
步骤1和2中的地址需要保持一致，否则会导致不可预期的结果；

2.2 授权验证

  • 只有通过授权验证之后才会去除默认的水印 
      // 授权验证的回调函数
  nvStreamingContext.onWebRequestAuthFinish = (success) => {
      if (!success) {
          console.error('SDK鉴权失败');
      } else {
          console.error('SDK鉴权成功');
      }
  };
  nvStreamingContext.verifySdkLicenseFile('鉴权地址')

3 使用说明

3.1 核心概念

3.1.1 NvsStreamingContext类

NvsStreamingContext是美摄SDK的流媒体上下文类，可视作整个SDK框架的入口。

3.1.2 用NvsLiveWindow类预览

  • NvsLiveWindow类的创建需要使用html的canvas标签， html代码 
      <canvas id="live-window"  />
注解
canva标签渲染视频会出现模糊的情况 需要在js中这样设置 
  var canvas = document.getElementById("live-window");
  canvas.width = canvas.clientWidth * window.devicePixelRatio;
  canvas.height = canvas.clientHeight * window.devicePixelRatio;

NvsLiveWindow的宽高比应该是1:1，4:3，16:9，9:16等，最好与要编辑的图像宽高比保持一致。否则，预览的图像是被裁剪后的图像。

  • NvsLiveWindow的填充模式：参见NvsLiveWindowFillModeEnum 
      declare const NvsLiveWindowFillModeEnum: Readonly<{
      //图像按比例均匀填充，必要时进行裁剪(默认模式)   
      PreserveAspectCrop: 0;
      //图像均匀地缩放来适合窗口，没有裁剪
      PreserveAspectFit: 1;
      //图像被缩放来适合窗口
      Stretch: 2;
  }

对于三种填充模式，图片展示如下：

  • PreserveAspectCrop模式：
  • PreserveAspectFit模式：
  • Stretch模式：

3.1.3 FS类

FS类是SDK的资源管理类，主要负责资源的加载、创建、删除等。通过FS.mkdir()、 FS.readFile()、 FS.writeFile()等方法管理资源。更多方法请参考

3.1.4 资源的使用

  • 美摄支持视频上传到云端，并提供相应的素材管理接口，对于上传的素材我们会做转码处理，生成m3u8格式的文件，方便网络传输。
  • 文件是通过FS对象写入到内存中的, 以视频或者图片为例： 
      const response = await fetch('https://alieasset.meishesdk.com/editor/2022/07/05/video/afd62303-3492-4c31-b09c-1c56c63b46a2/afd62303-3492-4c31-b09c-1c56c63b46a2.m3u8');
  const text = await response.text();
  const path = `/afd62303-3492-4c31-b09c-1c56c63b46a2.m3u8`
  FS.writeFile(path, text)
注解
path 就是素材的路径，后续sdk的操作都是基于这个路径进行的， text 是素材的二进制数据。
  • 为了方便管理不同素材，也会创建目录， 以视频或者图片为例: 
      FS.mkdir('/m3u8')
  const path = `/m3u8/afd62303-3492-4c31-b09c-1c56c63b46a2.m3u8.m3u8`
  FS.writeFile(path, text)

3.2 编辑

实现视频编辑的一般步骤：

  1. 先初始化NvsStreamingContext。 
      const nvStreamingContext = nvsGetStreamingContextInstance();
  2. 创建时间线(timeline)。通过NvsStreamingContext类对象创建时间线，时间线占用资源较小，如有需要，一个程序中可以创建多个时间线。一般创建一条时间线即可。
  3. 创建流媒体窗口(liveWindow) 通过NvsStreamingContext类对象创建流媒体窗口，流媒体窗口用于显示视频画面。 
      //NvsLiveWindow初始化
  const nvLiveWindow = nvStreamingContext.createLiveWindow("live-window");
  //设置填充模式
  nvLiveWindow.setFillMode(NvsLiveWindowFillModeEnum.PreserveAspectFit);
  4. 连接时间线到流媒体窗口 
      //连接时间线到流媒体窗口
  nvStreamingContext.connectTimelineWithLiveWindow(timeline, nvLiveWindow);
  5. 添加轨道，包括视频轨道(VideoTrack)与音频轨道(AudioTrack)。时间线上可以添加视频轨道和音频轨道，而在视频轨道上添加视频片段，音频轨道上添加音频片段。如果要实现画中画，则可添加两条视频轨道。添加音频轨道一般用来给视频加音乐或者配音功能。
  6. 把素材片段添加到轨道上。视频轨道上可以添加多个片段，可以是视频文件或者图片，实现图片和视频的混编。音频轨道上也可以添加多个音乐文件。

3.2.1 创建timeline设定视频尺寸

  • 创建timeline对于编辑是非常关键的，timeline的分辨率决定了生成视频文件的最大分辨率（尺寸）。请将timeline的分辨率和NvsLiveWindow的宽高比适配一致。 
      // html
      <canvas id="live-window"  />
  // js
  const liveWindow = document.getElementById("live-window");
  const width = 960;
  const height = 540 
  liveWindow.style.height = height + 'px';
  liveWindow.style.width = width + 'px';
  liveWindow.height = height * (window.devicePixelRatio || 1);
  liveWindow.width = width * (window.devicePixelRatio || 1);


  // 时间线创建的标识
  const TIMELINE_FLAGS =
      NvsCreateTimelineFlagEnum.DontAddDefaultVideoTransition +
      NvsCreateTimelineFlagEnum.ForceAudioSampleFormatUsed +
      NvsCreateTimelineFlagEnum.RecordingUserOperation +
      NvsCreateTimelineFlagEnum.SyncAudioVideoTrasitionInVideoTrack
  /*创建时间线*/
      nvTimeline = nvStreamingContext.createTimeline(
      new NvsVideoResolution(width, height),
      new NvsRational(25, 1),
      new NvsAudioResolution(44100, 2),
      TIMELINE_FLAGS,
  );
  • 方法参考createTimeline()方法。 
      createTimeline(videoRes: NvsVideoResolution, fps: NvsRational, audioRes: NvsAudioResolution, flags?: number): NvsTimeline;
  • 参数

3.2.2 多段视频、图片混编

一般情况下创建一条视频轨道，然后往轨道上添加图片或者视频素材。添加到轨道上的素材，我们称它为片段(clip)。图片和视频素材都是通过文件路径添加到轨道上的。 请注意：如果图片素材尺寸过大，需要降低图片尺寸，降低尺寸后的图片和创建timeline的分辨率的尺寸大小匹配最好。

  • 添加视频轨道： 
      const videoTrack = nvTimeline.appendVideoTrack();
  • 添加音频轨道： 
      const audioTrack = nvTimeline.appendAudioTrack();
  • 添加片段：参考资源使用 
      const response = await fetch('https://alieasset.meishesdk.com/editor/2022/07/05/video/afd62303-3492-4c31-b09c-1c56c63b46a2/afd62303-3492-4c31-b09c-1c56c63b46a2.m3u8');
  const text = await response.text();
  const path = `/afd62303-3492-4c31-b09c-1c56c63b46a2.m3u8`
  FS.writeFile(path, text)
  const clip = videoTrack.appendClip(path);

预览效果参考视频定位预览

3.2.3 视频播放与定位预览

3.2.3.1 视频播放

  • 方法[playbackTimeline()](NvsStreamingContext::playbackTimeline() 
      playbackTimeline(timeline: NvsTimeline, startTime: number, endTime: number, videoSizeMode: number, preload: boolean, flags: number): boolean;
  • 使用示例 
      nvStreamingContext.playbackTimeline(
      nvTimeline, // 当前时间线对象
      nowTime, // 开始时间
      endTime, // 结束时间 -1 代表播放到结尾
      NvsVideoPreviewSizeModeEnum.LiveWindowSize, // 视频大小模式 
      preload, // 是否预加载 设为true
      (flags |= NvsPlaybackFlagEnum.BuddyHostOriginVideoFrame) // 播放标记
  );
  • 参数
    • timeline 时间线对象
    • startTime 开始时间，单位微秒，1/1000000秒。
    • endTime，结束时间，单位微秒，1/1000000秒 值可以是timeline.duration或者-1。
    • videoSizeMode 参考NvsVideoPreviewSizeModeEnum 建议设置为NvsVideoPreviewSizeModeEnum.LiveWindowSize。若无特殊需求，设为NvsVideoPreviewSizeModeEnum.FullSize的模式会影响性能。
    • preload 是否预加载，true表示预加载，false表示不预加载。
    • flags 播放标记 NvsPlaybackFlagEnum
注解
美摄SDK的时间单位是微秒，1/1000000秒。

3.2.3.2 视频定位预览

  • 方法seekTimeline 
      seekTimeline(timeline: NvsTimeline, timestamp: number, videoSizeMode: number, flags: number): boolean;
  • 使用示例 
      nvStreamingContext.seekTimeline(
      nvTimeline, // 当前时间线对象
      nowTime, // 开始时间
      NvsVideoPreviewSizeModeEnum.LiveWindowSize, // 视频预览大小模式
      (flags |= NvsSeekFlagEnum.BuddyHostOriginVideoFrame), // 定位标识
  );
  • 参数
    • timeline 时间线对象
    • timestamp 开始时间，单位微秒，1/1000000秒。
    • videoSizeMode 参考NvsVideoPreviewSizeModeEnum 建议设置为NvsVideoPreviewSizeModeEnum.LiveWindowSize。若无特殊需求，设为NvsVideoPreviewSizeModeEnum.FullSize的模式会影响性能。
    • flags 定位标记 NvsSeekFlagEnum
注解
想要预览对时间线操作的修改效果（包括素材的添加、移除、排序、裁剪等），需要调用此方法。

3.2.4 视频裁剪

  • 改变片段的入出点，裁剪片段。 
      const clip = videoTrack.getClipByIndex(0);
  clip.changeTrimInPoint(trim_in, true);
  clip.changeTrimOutPoint(trim_out, true);

3.2.5 从轨道上移除片段

  • 移除片段： 
      videoTrack.removeClip(0, false);

3.2.6 片段排序

  • 轨道上的片段可以互换位置，moveClip()的参数clipIndex和destClipIndex分别代表互换的两个素材的位置索引。 
      videoTrack.moveClip(0,3);

3.2.7 图片时长设定

  • NvsVideoTrack类提供appendClip2(filePath, trimIn, trimOut)可以根据需要自由设定图片时长。
  • filePath是图片素材的路径，trimIn设置0，trimOut设置为8000000，则图片显示为8秒。 
      const assetUrl = https://alieasset.meishesdk.com/test/2023/07/10/image/0c3c43a5-f9f8-4223-84f2-2c35c535f104/0c3c43a5-f9f8-4223-84f2-2c35c535f104.m3u8
  const response = await fetch(assetUrl);
  const text = await response.text();
  const path = `/0c3c43a5-f9f8-4223-84f2-2c35c535f104.m3u8`
  FS.writeFile(path, text)
  videoTrack.appendClip2(path,0,8000000);
  • 如果通过appendClip(String filePath)添加图片，则图片默认显示时长是4秒。

3.2.8 移除时间线与轨道

创建的时间线，添加的视频轨道和音频轨道，如果当前不再需要，则要进行移除。操作如下：

  • 移除时间线： 
      nvStreamingContext.removeTimeline(nvTimeline);
  • 移除视频轨道： 
      nvTimeline.removeVideoTrack(0);
  • 移除音频轨道： 
      nvTimeline.removeAudioTrack(0);

预览效果参考视频定位预览

3.3 音乐

3.3.1 添加音乐

  • 给视频添加音乐是通过音频轨道添加音频片段实现的。创建时间线后，通过appendAudioTrack()添加音频轨道，然后把音乐文件以音频片段的形式添加到音频轨道上即可。可以添加多段音乐，音乐会连续播放。 
      const assetUrl = 'https://alieasset.meishesdk.com/test/2024/05/24/audio/6dc60190-c22b-4740-a299-3981d1a8c7ec/6dc60190-c22b-4740-a299-3981d1a8c7ec.m3u8'
  const audioTrack = nvTimeline.appendAudioTrack();
  const response = await fetch(assetUrl);
  const text = await response.text();
  const path = `/6dc60190-c22b-4740-a299-3981d1a8c7ec.m3u8`
  FS.writeFile(path, text)
  audioTrack.appendClip(path);

3.3.2 音乐裁剪

  • 音乐裁剪与视频裁剪是一样的，也是通过设置入出点的方式进行裁剪。 
      const clip = audioTrack.getClipByIndex(0);
  clip.changeTrimInPoint(trim_in, true);
  clip.changeTrimOutPoint(trim_out, true);

预览效果参考视频定位预览

3.4 字幕

添加，删除以及获取字幕都是在时间线(timeline)上进行执行的，调用addCaption()，可以参考SdkDemo示例的addCaption() 方法

3.4.1 添加与删除字幕

  • 添加字幕，可设置字幕显示的时长。 
      const timelineCapion = nvTimeline.addCaption("Meishe SDK", 0, nvTimeline.getDuration(), captionStylePackageId,false);

captionStylePackageId是素材样式包id，添加字幕之前需要先安装字幕样式包,参考素材包管理, 试用字幕样式包好物种草

  • 当字幕文字是中文时，预览是乱码，需要安装字体，字体安装: 
      const fontUrl = 'https://alieasset.meishesdk.com/font/站酷酷黑体.ttf'
  const response = await Axios.get(fontUrl, {
      responseType: 'arraybuffer',
  })
  const fontInFS = '/' + fontUrl.split('/').pop()
  await FS.writeFile(fontInFS, new Uint8Array(response.data))
  // 对字幕做字体设置
  caption.setFontByFilePath(fontInFS)
  • 移除字幕，返回下一个时间线字幕对象。如果没有下一个字幕，则返回null。 
      const nextCaption = nvTimeline.removeCaption(timelineCapion);

3.4.2 获取timeline上的字幕

  • 有多种方式获取字幕： 
      //获得时间线上的第一个字幕
  const firstCaption = nvTimeline.getFirstCaption();

  //获得时间线上的最后一个字幕
  const lastCaption = nvTimeline.getLastCaption();

  //获得时间线上的当前字幕的前一个字幕
  const prevCaption = nvTimeline.getPrevCaption(currentCaption);

  //获得时间线上的当前字幕的后一个字幕
  const nextCaption = nvTimeline.getNextCaption(currentCaption);

根据时间线上的位置获得字幕,返回保存当前位置字幕的List集合。获取的字幕列表排序规则如下：

  • 添加时字幕入点不同，按入点的先后顺序排列；
  • 添加时字幕入点相同，按添加字幕的先后顺序排列。 
      const cpationList = nvTimeline.getCaptionsByTimelinePosition(1000000);

3.4.3 改变字幕的属性

修改字幕属性可通过NvsTimelineCaption类的方法实现。获取字幕后，可设置字幕文本，颜色，加粗，斜体，描边等。

  • 以修改字幕文本为例： 
      currentCaption.setText("Meishe SDK");

3.4.4 改变字幕的入出点

  • 获取字幕后，可以修改字幕在时间线上的入点，出点以及偏移值。 
      //改变入点
  currentCaption.changeInPoint(1000000);

  //改变出点
  currentCaption.changeOutPoint(5000000);

  //改变显示位置(入点和出点同时偏移offset值)
  currentCaption.movePosition(1000000);

预览效果参考视频定位预览

3.5 动画贴纸

添加，删除以及获取动画贴纸也是在时间线(timeline)上进行执行的，可以参考SdkDemo示例的贴纸模块。

3.5.1 添加与删除动画贴纸

  • 添加动画贴纸： 
      nvTimeline.addAnimatedSticker(0, nvTimeline.getDuration(), stickerId);
    stickerId是动画贴纸包Id，添加动画贴纸之前需要先安装动画贴纸包,参考素材包管理, 试用贴纸奶油蛋糕
  • 移除动画贴纸，返回当前贴纸的下一个贴纸。如果没有下一下贴纸，则返回null。 
      const nextSticker = nvTimeline.removeAnimatedSticker(currentSticker);

3.5.2 获取timeline上的动画贴纸

  • 有多种方式获取时间线上添加的动画贴纸。 
      //获取时间线上第一个动画贴纸
  const firstSticker = nvTimeline.getFirstAnimatedSticker();

  //获取时间线上最后一个动画贴纸
  const lastSticker = nvTimeline.getLastAnimatedSticker();

  //获取时间线当前动画贴纸的前一个动画贴纸
  const prevSticker = nvTimeline.getPrevAnimatedSticker(currentSticker);

  //获取时间线当前动画贴纸的后一个动画贴纸
  const nextSticker = nvTimeline.getNextAnimatedSticker(currentSticker);

根据时间线上的位置获得动画贴纸,返回保存当前位置动画贴纸对象的List集合。 获取的动画贴纸列表排序规则如下：

  • 添加时入点不同，按入点的先后顺序排列；
  • 添加时入点相同，按添加动画贴纸的先后顺序排列。 
      const stickerList = nvTimeline.getAnimatedStickersByTimelinePosition(1000000);

3.5.3 改变动画贴纸的属性

修改贴纸属性可通过NvsTimelineAnimatedSticker类的方法实现。获取贴纸后，可设置缩放值，水平翻转，旋转角度，平移等。

  • 以修改贴纸缩放为例： 
      currentSticker.setScale(1.2);
  • 如果是全景图动画贴纸，则还可以设置贴纸中心点的极角，中心点的方位角等。以设置中心点的极角为例： 
      currentSticker.setCenterPolarAngle(1.2);

3.5.4 改变动画贴纸的入出点

  • 获取贴纸后，可以修改动画贴纸在时间线上的入点，出点以及偏移值。 
      //改变入点
  currentSticker.changeInPoint(1000000);

  //改变出点
  currentSticker.changeOutPoint(5000000);

  //改变显示位置(入点和出点同时偏移offset值)
  currentSticker.movePosition(1000000);

预览效果参考视频定位预览

3.6 片段时间线

片段时间线是在视频轨道上添加的, 可以参考sdkDemo的 addTimelineClip 方法。

  1. 首先需要创建时间线 
      const timeline = nvStreamingContext.createTimeline(
     new NvsVideoResolution(width, height),
     new NvsRational(25, 1),
     new NvsAudioResolution(44100, 2),
     TIMELINE_FLAGS,
  );
  2. 然后创建视频轨道 
      const videoTrack = timeline.appendVideoTrack();
  3. 然后创建片段 
      const clip = videoTrack.appendClip(filePath);
  4. 最后需要把该时间线添加到主时间线的视频轨道上 
      const timelineClip = videoTrack.addTimelineClip(timeline,0);
  • addTimelineClip 方法的返回值是NvsVideoClip对象，可以参考NvsVideoClip,可以通过 isTimelineClip 方法判断是否为时间线片段。可以通过 getInternalTimeline 方法获取内部时间线。 
      addTimelineClip(timeline: NvsTimeline, inPoint: number): NvsVideoClip;

预览效果参考视频定位预览

3.7 视频转场

视频转场包括内嵌式转场和包裹式转场。设置视频内嵌转场：参考setBuiltinTransition

  • 支持的内置转场,参考内建视频转场 
      videoTrack.setBuiltinTransition(0,transitionName);
  • 视频转场包：参考setPackagedTransition 
      videoTrack.setPackagedTransition(1，transitionId);
    transitionId是视频包式转场Id，添加视频包式转场之前需要先安装视频包式转场,参考素材包管理，试用转场三维旋转03

预览效果参考视频定位预览

3.8 特效

在视频后续编辑中，经常会使用到几种特效，分别是视频特效(NvsVideoFx)，音频特效(NvsAudioFx)，时间线视频特效(NvsTimelineVideoFx)。

3.8.1 视频特效

视频特效是使用在视频片段上的，每个视频片段可以添加若干个视频特效。视频特效包括内嵌视频特效，包裹视频特效，美颜特效。

  • 添加内嵌视频特效：
  • 支持的内置视频特效参考内建视频特效 
      videoClip.appendBuiltinFx(fxName);
  • 添加视频特效包： 
      videoClip.appendPackagedFx(fxPackageId);
    fxPackageId是视频特效包Id，添加视频特效包之前需要先安装视频特效包,参考素材包管理 试用转场垂直镜像

移除视频特效包括移除指定索引值特效和移除所有视频特。

  • 移除指定索引值的特效： 
      videoClip.removeFx(0);
  • 移除所有视频特效： 
      videoClip.removeAllFx();

3.8.2 音频特效

音频特效是使用在音频片段上的，每个音频片段可以添加若干个音频特效。

  • 添加音频特效：
  • 支持的内置音频特效参考内建音频特效 
      audioClip.appendFx(fxName);
  • 移除指定索引的音频特效： 
      audioClip.removeFx(0);

3.8.3 时间线视频特效

时间线视频特效是使用在时间线上的一种特效，包含内嵌特效和包裹特效。时间线上可以添加若干个时间线视频特效。

3.8.3.1 添加与删除时间线特效

添加时间线特效：

  • 添加内嵌时间线特效：
  • 支持的内置时间线特效参考内建视频特效 
      nvTimeline.addBuiltinTimelineVideoFx(1000000,5000000,fxName);
  • 添加视频特效包： 
      nvTimeline.addPackagedTimelineVideoFx(1000000,5000000,fxPackageId);
    fxPackageId是视频特效包Id，添加时间线特效包之前需要先安装时间线特效,参考素材包管理

3.8.3.2 获取时间线特效

  • 有多种方法获取时间线特效。 
      //获取时间线上第一个时间线视频特效
  const firstTimelineFx = nvTimeline.getFirstTimelineVideoFx();
  //获取时间线上最后一个时间线视频特效
  const lastTimelineFx = nvTimeline.getLastTimelineVideoFx();
  //获取时间线上某个时间线视频特效的前一个时间线视频特效
  const prevTimelineFx = nvTimeline.getPrevTimelineVideoFx(currentTimelineFx);
  //获取时间线上某个时间线视频特效的下一个时间线视频特效
  const nextTimelineFx = nvTimeline.getNextTimelineVideoFx(currentTimelineFx);

根据时间线上的位置获得时间线视频特效,返回当前位置时间线视频特效对象的数组。获取的时间线视频特效数组排序规则如下：

  • 添加时入点不同，按入点的先后顺序排列；
  • 添加时入点相同，按添加时间线视频特效的先后顺序排列。 
    const timelineFxArray = nvTimeline.getTimelineVideoFxByTimelinePosition(2000000);

3.8.3.3 改变时间线特效的入出点

  • 获取时间线特效后，可以修改时间线特效在时间线上的入点，出点以及偏移值。 
      //改变入点
  currentTimelineFx.changeInPoint(1000000);
  //改变出点
  currentTimelineFx.changeOutPoint(5000000);
  //改变显示位置(入点和出点同时偏移offset值)
  currentTimelineFx.movePosition(1000000);
    预览效果参考视频定位预览

3.9 素材包管理

美摄SDK提供了丰富的素材库，包括动画贴纸，主题，字幕样式，转场等。素材包可以从网络上下载，或者由美摄SDK项目组提供，用户可以根据需要选择使用这些素材包。美摄SDK通过NvsAssetPackageManager类对这些素材包进行管理，可以安装，卸载,获取素材包的状态，版本号等。 详细参考NvsAssetPackageManager

  • 使用installAssetPackage方法安装素材包,以动画贴纸为例： 
      import axios from 'axios';

  const packageUrl = "https://qasset.meishesdk.com/material/pu/animatedsticker/A1509C3D-7F5C-43CB-96EE-639ED7616BB7/A1509C3D-7F5C-43CB-96EE-639ED7616BB7.1.animatedsticker";
  const response = await axios.get(packageUrl, { responseType: 'arraybuffer' });
  const packageFile = '/' + packageUrl.split('/').pop();
  await FS.writeFile(packageFile, new Uint8Array(response.data));
  let packageLicenseFile = '';
  let packageType = NvsAssetPackageTypeEnum.AnimatedSticker;
  const assetPackageManager = nvsGetStreamingContextInstance().getAssetPackageManager();
  assetPackageManager.onFinishAssetPackageInstallation = (assetPackageId, assetPackageFilePath, assetPackageType, error) => {};
  assetPackageManager.installAssetPackage(packageFile, packageLicenseFile, packageType);
注解
onFinishAssetPackageInstallation()是特效包安装的回调函数；
  • packageType类型是NvsAssetPackageTypeEnum，不同的特效包资源对应不同的类型；
  • packageFile要保持和原始资源包同名，不可以随意修改名称，否则安装会失败；
  • packageLicenseFile在sdk没有校验授权时，可以设置为空字符串，如果sdk已经校验授权文件，就需要使用每一个特效包对应的授权文件，此授权文件是每一个特效包独有的，并不是sdk的授权文件。
  • 素材包卸载，方法uninstallAssetPackage： 
      const error = nvStreamingContext.getAssetPackageManager().uninstallAssetPackage(stickerId,NvsAssetPackageTypeEnum.AnimatedSticker);

3.10 回调

美摄SDK提供了很多回调接口，如果要查询采集设备状态，采集录制状态，视频播放状态，文件生成状态，资源包安装状态等，则必须在创建NvsStreamingContext对象后设置回调并实现对应的回调方法。参考nvStreamingContext

  • 以视频播放回调onPlaybackTimelinePosition为例： 
      nvStreamingContext.onPlaybackTimelinePosition = (timeline, position) => {
      console.log(`当前播放位置${position}`);
  }

3.11 生成视频

web端为了编辑效率，并没有使用原始视频进行编辑，而是采用了低分辨率的视频，合成视频需要调用后端的接口生成视频，可以参考sdkDemo中exportVideo()方法。

4 附件

更多功能，请参考：https://www.meishesdk.com/cloudedit，会有详细介绍。

制作者 doxygen 1.9.1