任务描述XML语法

一个典型的任务描述如下:

<root>
  <task>
    <input>
      <url>...</url>
      ...
    </input>
    <output>
      <extension>...</extension>
      ...
    </output>
  </task>
</root>

语法规则:

  1. root表示根元素,必须有
  2. task任务元素,一个task元素,可以嵌套至少一个或多个input和output元素
  3. 每个input元素都必须嵌套有url元素,并且url元素必须出现在第一个位置
  4. 每个output元素都必须嵌套有extension元素,且extension元素必须出现在第一个位置

下面分别介绍task,input和output元素中允许出现的元素

任务名称字符串

任务透传字串

输入描述 其下子元素见这里

输出格式描述 其下子元素见这里

输入url地址,可以是rtmp://, http://, rtsp:// 等各种协议名称开头的url

配置RTSP/RTP收流的缓冲区大小,在定义一个任务从rtsp/udp服务器拉流时有用。在拉一个高清流的时候,默认缓冲区往往会太小,导致有些udp报文丢失而解码失败出现花屏现象。 通过此配置项,可以显式地指定默认缓冲区的大小,增大缓冲区可以消除缓冲区过小导致的丢包问题。

只有输入源是RTSP或RTP且为UDP传输协议时才能使有此元素

显式指定RTSP媒体流的传输层协议,可用的配置值有udptcp

从源文件的指定时间开始读取。 如:

<start-time>00:00:10</start-time>

从第10秒开始读取。第一个00代表小时,第二个00代表分钟,第三个00代表秒。 此配置项一般用在截取视频或者指定时间段进行转码。视频剪辑的时候可以用这个参数指定从什么时间点开始剪辑

当输入源为tcp连接时,指定源的超时时间,即在这个超时时间内未收到任务数据包,则认为源已经坏了,任务会被停止。 这个配置项的单位是ms 此配置项在输入为rtsp源,且指定rtsp-transport为tcp时有用,在输入为rtmp源时也有效。 服务器加入了自动判断,如果任务的源是指定了rtsp-transport为tcp,默认值为30s

输出容器格式或流协议, 直播云支持的输出格式有:

  • flv
  • m3u8
  • mp3
  • mp4
  • aac
  • rtmp
  • ts (mpeg2ts)
  • udp (udp单播)
  • rtp

输出音频编码格式, 支持的编码格式值有:

  • libvo_aacenc (aac)
  • mp3
  • amr_nb
  • copy 拷贝模式,不进行转码,输出的编码和输入编码一样。

输出的视频编码格式,支持的视频编码格式有:

  • libx264 (h264)
  • h263
  • vp8
  • mpeg2video
  • flv
  • copy 拷贝模式,不进行转码,输出的编码和输入编码一样

当指定的输出视频的编码格式和输入音频的编码格式一样时,不进行转码。可极大地加快转码任务的执行进度。 此元素无需指定值,表达方式如下

<try-copy-video/>

当指定的输出音频的编码格式和输入音频的编码格式一样时,不进行转码。 此元素无需指定值,表达方式如下

<try-copy-audio/>

指定输出时长,当输出视频的时长达到此设定值时便停止任务。 表示方法有两种 时:分:秒 (00:01:12)和秒的绝对值(30),

指定输出视频的码流, 单位是bit/s, 以下三种表达方式等价

<bitrate-v>1204000</bitrate-v>
<bitrate-v>1204k</bitrate-v>
<bitrate-v>1M</bitrate-v>

指定输出音频的码流, 单位是bit/s, 以下三种表达方式等价

<bitrate-a>1204000</bitrate-a>
<bitrate-a>1204k</bitrate-a>

输出单声道

<channel-layout>mono</channel-layout>

输出立体声

<channel-layout>stereo</channel-layout>

一般来说,在直播云上不需要指定输出文件名,以防止同时多个任务的输出路径和文件名相同引起冲突,在有些情况下需要指定输出文件名时客户需要自己小心,规划好命名规则。关于固定直播地址的更多说明请参考常见问题中的相关描述

例如,下面的配置指定输出文件名为abc.m3u8

<output tag="t1"> 
    <extension>m3u8</extension>  
    <output-file-name>abc</output-file-name>
 </output> 

配置指定文件名时可以使用以下宏

意义
{u} 任务所属的用户名
{U} 任务所属用户名的hash值的hex表示字串
{D} 当前日期
{H} 当前时间的小时数值, 两位数字表示
{M} 当前时间的分钟数值, 两位数字表示
{SERVICE_CODE} 当前任务所属服务码

指定输出文件保存的相对路径。一般来说,在直播云上创建任务都不需要使用此配置项。 只有当应用需要固定直播m3u8输出地址时才需要使用此配置项,其他直播输出格式,如flv, rtmp都不需要指定此配置项。

当应用业务需要固定直播m3u8输出地址时,output-relative-dir元素的值必须是这样的形式:

{SERVICE_CODE}/YYYYMMDD形式的日期字串/HH形式的24小时字串/mm形式的分钟表示字串/{E}/

其中:

  • {SERVICE_CODE}和{E}是强制固定写法.
  • YYYYMMDD形式的日期字串必须是2015010和调用任务时当时日期之间内的时间字串。
  • HH是24小时制表示的小时数值
  • MM是分钟字串

如以下值是合法的 {SERVICE_CODE}/20151205/12/23/{E}/{SERVICE_CODE}/20151205/12/63/{E}/ 是不合法的,因为63不是一个有效的分钟字串。

当xml中包含有不合法的 output-relative-dir 元素值时,创建任务的请求会被直播云拒绝。

当需要以rtp/rtmp推流输出至另外的服务器时,可以使用此配置项指定推流目标服务器的地址。注意此配置项中不需要再写协议头了, 协议头由extension配置项决定。如推流输出至rtmp服务器xyz.the3rd.com:

<extension>rtmp</extension>
<output-url>xyz.the3rd.com:1935/live</output-url>

output-url配置的地址并不是完整推流地址,完整的推流地址还由任务id(随机生成)或由 output-file-name决定。举例来说,如果以上配置再加上<output-file-name>abc</output-file-name> 则完整的推流地址是 rtmp://xyz.the3rd.com:1935/live/abc, 不加output-file-name,则推流地址是rtmp://xyz.the3rd.com:1935/live/开头的随机地址。

此配置项也可以使用output-file-name描述的宏定义.

以下两种表达方式等效

<size>vga</size>
<size>640x480</size>

指定从源视频中剪辑出从1分01秒开始,时长为10秒的视频, 剪辑出的视频格式,编码格式,分辨率,码流维持和原来一样。

<root> 
  <task> 
    <name>cut1</name>  
    <input> 
      <url>源视频url</url>  
      <start-time>00:01:01</start-time> 
    </input>  
    <output tag="t1"> 
      <extension>mp4</extension>  
      <duration>10</duration>  
      <codec-v>copy</codec-v>  
      <codec-a>copy</codec-a> 
    </output> 
  </task> 
</root>

注意 extension和源视频一致,原来是mp4则填写mp4, 原来是flv则填写flv, 原来是m3u8则填写m3u8

指定从源视频中剪辑出从1分01秒开始,时长为10秒的视频, 剪辑出的视频格式为mp4,输出视频编码格式为h264,分辨率指定发qvga,码流为300k, 音频为aac如果源视频中也为aac则不转码,如果源视频中音频为其他格式则转码。

  <root> 
      <task> 
        <name>cut2</name>  
        <input> 
          <url>源视频url</url>  
          <start-time>00:01:01</start-time> 
        </input>  
        <output tag="t1"> 
          <extension>mp4</extension>  
          <duration>10</duration>  
          <codec-v>libx264</codec-v>
          <size>qvga</size>
          <bitrate-v>300k</bitrate-v>
          <codec-a>libvo_aacenc</codec-a>
          <codec-a>copy</codec-a>
          <try-copy-audio/>
        </output> 
      </task> 
    </root>

http://a.b.com/1.m3u8http://a.b.com/2.m3u8合并成一个视频 先生成一个合并源文件的列表文件,并让这个文件可通过http下载得到 假设这个列表文件名为 list.txt, 其内容如下:

file http://a.b.com/1.m3u8
file http://a.b.com/2.m3u8

假设其http uri地址为 http://a.a.com/list.txt

则任务如下

   <root> 
      <task> 
        <name>merge1</name>  
        <input> 
          <url>http://a.a.com/list.txt</url>
          <input-format>concat</input-format>
        </input> 
        <output tag="t2">
          <extension>m3u8</extension>
          <codec-v>libx264</codec-v>
          <try-copy-video/>
          <codec-a>libvo_aacenc</codec-a>
          <try-copy-audio/>
        </output> 
      </task> 
    </root>