音视频点播VOD

    开发者指南

    快速入门

    1. 新建 VodClient

      VodClient是与VOD交互的核心Class,所有VOD操作均需通过VodClient完成。

    2. 创建媒资。

      点播所需的大量媒资文件须迁移到 VOD 平台。VodClient 提供了 createMediaResource() 方法用于上传音视频文件,成功后 VOD 平台将返回媒资对应的 MediaID,用于查询管理媒资的状态、获取播放地址及播放器代码。

    3. 管理媒资。

      媒资状态请参见VOD核心概念-媒资状态

      媒资上传成功后,以 MediaID 为索引,开发者可以通过接口函数 getMediaResource() 查询媒资的信息和状态,并可通过函数 publishMediaResource()/stopMediaResource()/deleteMediaResource() 恢复/停用/删除媒资。

    4. 获取播放地址和播放器代码。

      媒资上传之后,开发者可以通过接口函数 generateMediaPlayerCode() 得到 VOD 平台生成的Web播放器代码,从而方便地将视频播放集成到自己的网页中。

      如果在Android或者iOS移动端播放视频,开发者可以调用接口函数 generateMediaDeliveryInfo() 获取媒资的播放URL地址,使用百度智能云的 Android 或者 iOS 播放器 SDK 播放。

    媒资管理

    上传媒资文件

    VOD 通过 createMediaResource() 上传媒资文件,包括本地文件上传、从BOS导入媒资两种方式:

    本地文件上传

    假设本地媒资文件由变量 File file 指定,标题和描述通过 title 和 description 设置,transcodingPresetGroupName指定转码模板组名字,下面示例代码用于通过 createMediaResource() 上传媒资文件。

    代码示例:

    public void createMediaResource(VodClient vodClient, String title, String description, File file, String transcodingPresetGroupName, int priority) {
        CreateMediaResourceResponse response = vodClient.createMediaResource(title, description, file, transcodingPresetGroupName, priority);
        String mediaId = response.getMediaId();
    }

    从BOS(“华北-北京”区域)导入媒资

    指定BOS Bucket和BOS Key,使用BOS上传视频文件。需要说明,使用本方法需要将object授予客户帐号读权限,参考设置BOS bucket权限

    代码示例:

    public void createMediaResource(VodClient vodClient, String bucketName, String objectKey, String title, String description, String transcodingPresetGroupName, int priority) {
        CreateMediaResourceResponse response = vodClient.createMediaResource(bucketName, objectKey, title, description, transcodingPresetGroupName, priority);
        String mediaId = response.getMediaId();
    } 

    从公网URL中导入媒资

    代码示例:

    public void createMediaResource(VodClient vodClient, String sourceUrl, String title, String description, String transcodingPresetGroupName, int priority) {
        CreateMediaResourceResponse response = vodClient.createMediaResource(sourceUrl, title, description, transcodingPresetGroupName, priority);
        String mediaId = response.getMediaId();
    }

    说明:

    • transcodingPresetGroupName 传入null,表示默认模板组。
    • priority 优先级,当用户同时提交了大量转码时,这个值用于每个用户队列的内部排序和调度参考,不做跨用户比较。合法范围为0-9,0为最低,9为最高。
    • mode:以上三个方法均有一个带mode的可选参数同名函数,用户默认传null即可。mode详见API说明。

    申请媒资

    用于生成媒资的唯一标识mediaId、用于存储源视频文件的sourceBucket以及源媒资文件在BOS存储中的key。sourceBucket对用户开放写权限,对于用户的BOS空间不可见。

    public void applyMedia(VodClient vodClient) {
    GenerateMediaIdResponse Response = vodClient.applyMedia();
    String mediaId = response.getMediaId();
    String sourceBucket = response.getSourceBucket();
    String sourceKey = response.getSourceKey();
    }

    VodClient还提供一个public GenerateMediaIdResponse applyMedia(String mode);方法。一般来说,用户无需调用这个函数。mode详见API说明。

    处理媒资

    用于对已完成申请和视频上传的媒资进行处理。

    public void processMedia(VodClient vodClient, String mediaId, String title, String description, String sourceExtension, String transcodingPresetGroupName, int priority) {
    InternalCreateMediaRequest request =
            new InternalCreateMediaRequest()
                    .withMediaId(mediaId)
                    .withTitle(title)
                    .withDescription(description)
                    .withSourceExtension(sourceExtension)
                    .withTranscodingPresetGroupName(transcodingPresetGroupName)
                    .withPriority(priority);
     
    InternalCreateMediaResponse response = vodClient.processMedia(request);
        String mediaId = response.getMediaId();
    }

    对已完成申请和视频上传的媒资进行处理时,有自定义参数。代码示例如下:

    public void processMedia(VodClient vodClient, String mediaId, String title, String description, String sourceExtension, String transcodingPresetGroupName, int priority, ActionAttributes actionAttributes) {
    InternalCreateMediaRequest request =
            new InternalCreateMediaRequest()
                    .withMediaId(mediaId)
                    .withTitle(title)
                    .withDescription(description)
                    .withSourceExtension(sourceExtension)
                    .withTranscodingPresetGroupName(transcodingPresetGroupName)
                    .withPriority(priority)
                    .withActionAttributes(actionAttributes);
     
    InternalCreateMediaResponse response = vodClient.processMedia(request);
        String mediaId = response.getMediaId();
    }

    查询指定的媒资信息

    通过媒资的唯一标识 mediaId 查询指定媒资的详细信息。代码示例如下:

    public void getMediaResource(VodClient vodClient, String mediaId) {
            GetMediaResourceResponse response = vodClient.getMediaResource(mediaId);
            String status = response.getStatus();
            String createTime = response.getCreateTime();
            String publishTime = response.getPublishTime();
            String title = response.getAttributes().getTitle();
            String description = response. getAttributes().getDescription();
            long duration = response.getMeta().getDurationInSeconds();
            long size = response.getMeta().getSizeInBytes();
    		String transcodingPresetGroupName = response.getTranscodingPresetGroupName();
            List<PlayableUrl> playableUrlList = response.getPlayableUrlList();
            List<String> thumbnailList = response.getThumbnailList();
    }

    媒资属性见下表:

    参数 类型 描述
    mediaId String 媒资的唯一标识,开发者可通过 mediaId 查询指定媒资的详细信息
    status Object 媒资状态,可选值PROCESSING/RUNNING/FAILED/PUBLISHED/DISABLED/BANNED
    attributes Object 媒资属性
    +title String 媒资名称,“媒资属性”的子参数
    +description String 媒资描述,“媒资属性”的子参数
    meta Object 媒资元数据
    +sourceSizeInBytes Number 媒资源文件大小,“媒资元数据”的子参数
    +sizeInBytes Number 媒资数据大小,“媒资元数据”的子参数
    +durationInSeconds Number 媒资时长,“媒资元数据”的子参数
    error String 错误码,“错误信息”的子参数,有效值:TRANSCODING_FAILED(转码失败)、THUMBNAIL_FAILED(缩略图失败)、MEDIA_OVERTIME(媒资处理超时)
    message String 错误描述,“错误信息”的子参数
    publishTime String 媒资发布时间
    createTime String 媒资创建时间
    transcodingPresetGroupName String 使用的转码模板组名称间
    playableUrlList Array 处理后可以播放的视频信息
    +transcodingPresetName String 使用的转码模板名称
    +url String 可以播放视频文件的地址
    thumbnailList Array 缩略图文件的地址

    查询媒资并分页显示

    对特定用户的所有媒资进行条件筛选并分页显示。代码示例如下:

    public void listMediaResources(VodClient vodClient) {
            int pageNo = 1;
            int pageSize = 20;
            String status = "PUBLISHED";
            Date begin = DateUtils.parseAlternateIso8601Date("2016-01-15T08:46:56Z");
            Date end = DateUtils.parseAlternateIso8601Date("2016-01-18T08:46:56Z");
            String title = "test";
            ListMediaResourceResponse responce = vodClient.listMediaResources(pageNo, pageSize, status, begin, end, title);
            for (MediaResource mediaResource : responce.getMedia()) {
                String mediaId = mediaResource.getMediaId();
                String status = mediaResource.getStatus();
                String createTime = mediaResource.getCreateTime();
                String publishTime = mediaResource.getPublishTime();
                String title = mediaResource.getAttributes().getTitle();
                String description = mediaResource.getAttributes().getDescription();
                long duration = mediaResource.getMeta().getDurationInSeconds();
                long size = mediaResource.getMeta().getSizeInBytes();
            }
    }

    参数详情见下表:

    参数 类型 描述 是否必须
    pageNo Integer 页数。首页为第一页,有效值:正整数
    pageSize Integer 每页大小。有效值:1-1000的整数
    status String 媒资状态,用于筛选处于特定状态的媒资
    begin Date 媒资创建时间(createTime)上限,用于筛选创建时间等于或晚于begin的媒资
    end Date 媒资创建时间(createTime)下限,用于筛选创建时间等于或早于end的媒资

    查询媒资并用marker机制显示

    对特定用户的所有媒资进行条件筛选并分页显示。代码示例如下:

    public void listMediaResourcesByMarker(VodClient vodClient, String marker) {
            int pageSize = 20;
            String status = "PUBLISHED";
            Date begin = DateUtils.parseAlternateIso8601Date("2016-01-15T08:46:56Z");
            Date end = DateUtils.parseAlternateIso8601Date("2016-01-18T08:46:56Z");
            String title = "test";
            ListMediaResourceByMarkerResponse response = vodClient.listMediaResources(marker, pageSize, status, begin, end, title);
            for (MediaResource mediaResource : response.getMedia()) {
                String mediaId = mediaResource.getMediaId();
                String status = mediaResource.getStatus();
                String createTime = mediaResource.getCreateTime();
                String publishTime = mediaResource.getPublishTime();
                String title = mediaResource.getAttributes().getTitle();
                String description = mediaResource.getAttributes().getDescription();
                long duration = mediaResource.getMeta().getDurationInSeconds();
                long size = mediaResource.getMeta().getSizeInBytes();
            }
            if (response.getIsTruncated()) {
            	  marker = response.getNextMarker();
            	  listMediaResourcesByMarker(client, marker);
            }
    }

    参数详情见下表:

    参数 类型 描述 是否必须
    marker String 本次请求的marker,标记查询的起始位置,是上次marker机制查询返回的nextMarker,首次查询不提供本字段
    maxSize Integer 本次请求返回的任务列表的最大元素个数,有效值:[1-1000],默认值:1000
    status String 媒资状态,用于筛选处于特定状态的媒资
    begin Date 媒资创建时间(createTime)上限,用于筛选创建时间等于或晚于begin的媒资
    end Date 媒资创建时间(createTime)下限,用于筛选创建时间等于或早于end的媒资
    title String 媒资标题前缀,用于筛选标题以title开头的媒资

    更新指定媒资

    通过媒资的唯一标识 mediaId 更新指定媒资的属性,包括名称和描述。代码示例如下:

    public void updateMediaResource(VodClient vodClient, String mediaId, String title, String description) {
            vodClient.updateMediaResource(mediaId, title, description);
    }

    停用指定媒资

    通过媒资的唯一标识 mediaId 停用指定媒资,仅对状态为PUBLISHED的媒资有效。代码示例如下:

    public void stopMediaResource(VodClient vodClient, String mediaId) {
            vodClient.stopMediaResource(mediaId);
    }

    恢复指定媒资

    通过媒资的唯一标识 mediaId 恢复指定媒资,仅对状态为DISABLED的媒资有效。代码示例如下:

    public void publishMediaResource(VodClient vodClient, String mediaId) {
            vodClient.publishMediaResource(mediaId);
    }

    删除指定媒资

    通过媒资的唯一标识 mediaId 删除指定媒资,对状态为RUNNING的媒资无效。删除后,媒资不可见。删除操作不可逆。

    下述示例代码用于删除指定媒资。

    public void deleteMediaResource(VodClient vodClient, String mediaId) {
            vodClient.deleteMediaResource(mediaId);
    }

    获取媒资原始视频的下载地址

    用于查询指定媒资的原始视频下载地址。

    public void getMediaSourceDownload (VodClient vodClient, String mediaId, long expiredInSeconds) {
    GetMediaSourceDownloadResponse response = vodClient. getMediaSourceDownload (expiredInSeconds);
    String url = response.getSourceUrl();
    }

    通知管理

    创建通知

    通过用户提供的回调地址进行创建通知。如果您在创建/申请媒资文件时指定了通知,在文件处理完成后,VOD会向您指定的回调地址推送通知消息。

    public void createNotification(VodClient client, String name, String endpoint) {
        client.createNotification(name, endpoint);
    }

    查询指定通知

    查询指定通知的详细信息。代码示例如下:

    public void getNotification(VodClient client, String name) {
        GetNotificationResponse resp = client.getNotification(name);
        System.out.println("name: " + resp.getName());
        System.out.println("name: " + resp.getEndpoint());
    }

    查询所有通知

    查询已创建的全部通知。代码示例如下:

    public void listNotifications(VodClient client) {
        ListNotificationsResponse resp = client.listNotifications();
        for (Notification notification : resp.getNotifications()) {
            System.out.println("name: " + notification.getName());
            System.out.println("name: " + notification.getEndpoint());
        }
    }

    删除通知

    删除指定通知。代码示例如下:

    public void deleteNotification(VodClient client, String name) {
        client.deleteNotification(name);
    }

    统计分析

    媒资统计

    通过媒资的唯一标识 mediaId 查询指定媒资的播放信息,包括指定时间段内的播放次数、最大并发播放次数及下行流量。输入查询时间段的起止时间,按日统计,日期格式举例:2018-02-07。

    public void getMediaStatisticResponse(VodClient vodClient, String mediaId, Date startTime, Date endTime,  boolean aggregate) {
    GetMediaStatisticResponse response = vodClient.getMediaStatistic(mediaId, startTime, endTime, aggregate);
    }

    播放器管理

    由于 VOD 平台开发者(VOD的客户)面向的终端用户((VOD 平台开发者的客户))所使用设备中不能存储 AK/SK 对,即 VOD 平台开发者的播放器代码需要运行在匿名环境中,VOD 通过播放器服务接口向 VOD 平台开发者提供一套独立的鉴权逻辑,根据 mediaId来返回可播放的文件地址。开发者使用安全播放器时,须嵌入此处的接口逻辑,从而固定的播放器代码可以随着 VOD 系统升级而自动调整播放路径。

    查询媒资分发信息

    通过媒资的唯一标识 mediaId 查询指定媒资的标题、时长、可播放文件及媒资封面图的实际路径等,用于自定义播放器的开发。代码示例如下:

    public void generateMediaDeliveryInfo(VodClient vodClient, String mediaId) {
            GenerateMediaDeliveryInfoResponse response = vodClient.generateMediaDeliveryInfo(mediaId);
            // 获取媒资对应的可播放源文件的地址
            String mediaSourceUrl = response.getFile();
            // 获取媒资对应的封面图片的地址
            String mediaCoverPage = playableUrl.getCover();
    }

    分发信息见下表:

    参数 类型 描述
    mediaId String 媒资的唯一标识,开发者可通过 mediaId 查询指定媒资的详细信息
    file String 可播放文件的实际路径
    cover String 媒资封面图的实际路径。获取到路径后,可通过图片服务(图片样式除外)对媒资封面图进行缩放、裁剪、格式转换、旋转、添加水印等实时处理
    title String 媒体标题
    duration Integer 媒资播放时长,单位:秒

    获取到媒资缩略图(cover)的实际路径后,可通过图片服务(图片样式除外)对媒资封面图进行缩放、裁剪、格式转换、旋转、添加水印等实时处理,URL格式如下所示:

    # 例1:将媒资封面图(600×330)缩略成宽度为200,高度按原图比例等比例缩放
    http://gcikixy9wpfkpdx3qbb.exp.bcevod.com/mda-gcseezyb93g5hqpp/mda-gcseezyb93g5hqpp.jpg@w_200
    
    # 例2:将媒资封面图(600×330)拉伸到200×150的比例,再等比例缩放至宽200,高150
    http://gcikixy9wpfkpdx3qbb.exp.bcevod.com/mda-gcseezyb93g5hqpp/mda-gcseezyb93g5hqpp.jpg@s_1,w_200,h_150
    
    # 例3:将媒资封面图(600×330)等比例缩小330/150倍,再居中裁剪至宽200,高150
    http://gcikixy9wpfkpdx3qbb.exp.bcevod.com/mda-gcseezyb93g5hqpp/mda-gcseezyb93g5hqpp.jpg@s_2,w_200,h_150

    查询播放器代码

    通过媒资的唯一标识 mediaId、基本外观数据及AK生成可扩展的播放器代码,便于开发者开发简单的播放器,仅对状态为PUBLISHED的媒资有效。开发者还可基于获取到的播放器代码继续进行高级定制。代码示例如下:

    public void generateMediaPlayerCode(VodClient vodClient, String mediaId, int width, int height, boolean autoStart) {
            GenerateMediaPlayerCodeResponse response = vodClient.generateMediaPlayerCode(mediaId, width, height, autoStart);
            String htmlCode = “”;
            String fileCode = "";
            String coverFile = "";
            for (PlaybackCode code : response.getCodes()) {
                switch(code.getCodeType()) {
                    case "html":
                        htmlCode = code.getSourceCode();
                        break;
                    case "file":
                        fileCode = code.getSourceCode();
                        break;
                    case "cover":
                        coverFile = code.getSourceCode();
                        break;
                }
            }
    }

    外观数据及AK等基本信息如下:

    参数 类型 描述 是否必须
    mediaId String 媒资的唯一标识,开发者可通过 mediaId 查询指定媒资的详细信息
    width Number 播放器宽度
    height Number 播放器高度
    autostart Boolean 是否自动播放,可选值: true, false
    ak String Access Key ID,用于用户鉴权

    日志

    VOD Java SDK发布版本中增加了logback作为slf4j的实现,开发者可以直接使用。如果工程中有其他框架实现,例如log4j,也可以用来替代logback。

    默认日志

    如果使用默认的logback,需要配置logback.xml到classpath中。不做配置时,日志级别默认为DEBUG。

     <configuration>
        <property name="LOG_HOME" value="./log/"/>
        <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
            <!-- encoders are assigned the type
                 ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->
            <encoder>
                <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
            </encoder>
        </appender>
        <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
            <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
                <FileNamePattern>${LOG_HOME}/VODUnitTest.%d{yyyy-MM-dd}.log</FileNamePattern>
                <MaxHistory>30</MaxHistory>
            </rollingPolicy>
            <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
                <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n</pattern>
            </encoder>
            <triggeringPolicy class="ch.qos.logback.core.rolling.SizeBasedTriggeringPolicy">
                <MaxFileSize>10MB</MaxFileSize>
            </triggeringPolicy>
        </appender>
    
        <root level="info">
            <appender-ref ref="STDOUT"/>
            <appender-ref ref="FILE"/>
        </root>
     </configuration>

    自有日志模块

    如果使用自己的日志实现模块,例如项目依赖于Maven,则可以参考下面的配置到pom.xml中来去除logback。

    <?xml version="1.0" encoding="utf-8"?>
    
    <dependency>
      <groupId>com.baidubce</groupId>
      <artifactId>bce-java-sdk</artifactId>
      <version>${bce.sdk.version}</version>
      <exclusions>
        <exclusion>
          <groupId>ch.qos.logback</groupId>
          <artifactId>logback-classic</artifactId>
        </exclusion>
        <exclusion>
          <artifactId>logback-core</artifactId>
          <groupId>ch.qos.logback</groupId>
        </exclusion>
        <exclusion>
          <groupId>org.slf4j</groupId>
          <artifactId>jcl-over-slf4j</artifactId>
        </exclusion>
      </exclusions>
    </dependency>
    上一篇
    安装VOD-Java-SDK
    下一篇
    版本更新记录