媒体转码

重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

本文档描述的媒体转码功能指的是使用PDS提供的默认Web界面预览音视频,或者通过API/SDK的方式对音视频按照指定参数进行转换并获取处理结果的预览地址。以上两种方式都需要先开通媒体转码服务,下文将会对媒体转码服务和使用方式进行介绍。

媒体转码服务和使用步骤

本章节将先简述媒体转码服务。然后描述媒体转码的使用步骤,如下:

1 开通媒体转码服务

2 上传音/视频文件

3 获取媒体转码信息

媒体转码服务简述

PDS提供的媒体转码服务是以音视频为处理对象、模板为处理单元的Domain级服务。对于Domain上的同一个媒体文件(哈希值相同的数据都属于同一个文件),其所有模板均只会触发一次转码,后续不会重复进行转码,为用户提供良好的预览体验和成本控制。

根据不同业务场景需求,PDS提供以下两大类专业的转码解决方案:离线转码(offline_video / offline_audio)主要针对音视频文件的离线处理,支持多样化的音视频格式转换;边转边播(live_transcoding)和快速转码(quick_video,边转边播 2.0)适用于实时视频流媒体处理,满足低延迟、高实时性的业务需求

对于离线转码,它是指将一个媒体文件完整地转换为另一种媒体文件的流程。它的特点是适配性好,支持绝大多数转换参数,但是在转码完成前无法获取转码结果的预览地址,因此称为离线转码。

对于边转边播和快速转码(边转边播 2.0),它们将转码任务切分为播放列表的生成任务和多个小分片的转码任务,进而实现转码结果的快速预览。当视频上传完成后进行转码信息获取时,即可快速完成播放列表的生成任务得到预览地址。而通过预览地址在播放器进行播放时,若转码已完成,则用户可以快速起播,反之也仅需播放器等待重试起播所需分片的转码任务完成(通常不超过 10 秒)。当用户拖动到未转码完成的分片时,也仅需等待秒级的小分片转码任务的缓冲时间。相较于快速转码,早期推出的边转边播在部分播放器上进行拖动播放时存在缓冲时间较长的缺点,因此目前只支持开通快速转码。对于已经开通边转边播的客户,我们也提供无缝迁移快速转码的方案,详细可参考下文的迁移边转边播到快速转码

下图是 PDS 提供的转码服务的大致工作逻辑,主要包括检查转码信息、选取转码模板和发起转码任务三大步骤。

image

关于转码模板选取,PDS 根据媒体类型不同存在不同的逻辑。对于音频文件,PDS会选取所有Domain 上配置的模板进行转码,其中开通离线音频转码(offline_audio)时默认的模板如下:

参数\模板

LQ

HQ

SQ

音频编码器

mp3

mp3

mp3

音频采样率(Hz)

44100

44100

44100

音频声道数

2

2

2

音频码率(kbps)

128

320

640

对于视频文件,PDS默认会选取所有分辨率小于源视频分辨率和第一个分辨率不小于源视频分辨率的模板进行转码。源视频的分辨率会先进行宽高交换使得宽不小于高。只要变换后的分辨率中的宽高中有一项大于模板分辨率中的对应项,则认为源视频的分辨率大于该模板的分辨率。此外,对于分辨率大于源视频的那个模板,实际转码会以源视频分辨率进行转码,返回预览地址的时候则会通过keep_original_resolution 这个标记字段标识是否保留了原视频分辨率。

举个例子,对于配置模板分辨率分别为720x480, 1280x720, 1920x1080Domain和分辨率为540x720的源视频,720x4801280x720的模板会被选取,输出转码结果的分辨率则分别为720x480720x540。对于三种类型的视频转码能力,开通后Domain上默认的模板如下:

参数\模板

264_480p

264_720p

264_1080p

视频编码器

h264

h264

h264

视频分辨率

720x480

1280x720

1920x1080

视频码率(kbps)

600

1500

3000

视频帧率(fps)

25

25

25

音频编码器

aac

aac

aac

音频采样率(Hz)

44100

44100

44100

音频声道数

2

2

2

音频码率(kbps)

72

128

160

如果默认模板和模板选择策略不满足您的业务需求,您也可以联系我们添加自定义模板和模板选择策略(企业版暂不支持自定义模板和模板选择策略)。以下是 PDS 支持的所有模板参数:

参数名

参数类型

必填

参数说明

TemplateID

string

音/视频模板 ID。

Width

int64

输出视频的宽度,必须是正偶数,取值范围为 (0, 4096]。

Height

int64

输出视频的高度,必须是正偶数,取值范围为 (0, 4096]。

警告

如果该参数大于参数 Width 的值,则该模板在进行转码时将被忽略。

VideoCodec

string

视频编码格式。取值范围如下:

  • 转码类型为 offline_video 或 live_transcoding 时:copy、h264, h265, vp9。

警告

当该参数为 copy 时,表示将需要处理的视频流直接拷贝到输出文件,此时其余视频相关模板参数无效。copy 不可用于视频拼接,通常应用于视频转封装场景。

  • 转码类型为 quick_video 时:h264,h265。

VideoFrameRate

int64

视频帧率。

VideoBitrate

int64

视频码率,单位为千比特每秒(kbit/s)。

说明

该参数与 VideoCRF 互斥。若该参数与参数 VideoCRF 都为空值,则按照参数 VideoCRF 为 23 进行编码。

VideoBFrames

int64

转码类型为 offline_video 或 quick_video 时有效。连续 B 帧的数量,默认值为 3。

VideoBufferSize

int64

转码类型为 offline_video 或 quick_video 时有效。动态码率下解码缓存大小,单位为比特每秒(bit/s)。

说明

该参数需要与参数 VideoCRF 一起使用才有效。

VideoCRF

float64

转码类型为 offline_video 或 quick_video 时有效。指定恒定质量模式。与参数 VideoBitrate 互斥,取值范围为[0,51],数值越大画质越差,建议取值范围为[18,38]。

VideoGOPSize

int64

转码类型为 offline_video 或 quick_video 时有效。关键帧间隔帧数,默认值为 150。

VideoMaxBitrate

int64

转码类型为 offline_video 或 quick_video 时有效。动态码率下限定最大码率。使用该参数时,必须指定参数 VideoBufferSize。

说明

该参数需要与参数 VideoCRF 一起使用才有效。

VideoRefs

int64

转码类型为 offline_video 或 quick_video 时有效。参考帧的数量,默认值为 2。

VideoResolution

string

转码类型为 offline_video 或 quick_video 时有效。输出视频的分辨率,格式为宽 x 高,优先级比 Width 和 Height 高,单边取值范围为(0,4096]。

说明

若源视频存在旋转信息,宽高、长短边的判断以旋转后的情况为准,即以播放分辨率为准。

VideoPreset

string

转码类型为 offline_video 或 quick_video 时有效。

VideoResolutionFixPolicy

string

转码类型为 offline_video 时有效。分辨率参数 Resolution 为单边分辨率时,固定特定边为固定值的策略。取值范围如下:

  • align_long_side:固定长边分辨率。

  • align_short_side:固定短边分辨率。

示例:

Resolution 配置为 480x,VideoResolutionFixPolicy 配置为 align_long_side。输入视频分辨率为 960x720,输出视频分辨率为 480x360;输入视频分辨率为 720x960,输出视频分辨率为 360x480

说明

该参数需要配合参数 VideoResolution 一起使用,同时需要参数 VideoResolution 配置为单边分辨率模式,如配置为 480x。

AudioCodec

int64

音频编码方式。取值范围如下:

  • 转码类型为 offline_video, offline_audio 或 live_transcoding 时:copy, mp3, vorbis, aac, flac, ac3, opus, amr。

  • 转码类型为 quick_video 时:aac。

说明

当该参数为 copy 时,表示将需要处理的音频流直接拷贝到输出文件,此时其余模板音频参数无效。copy 不可用于音频拼接,通常应用于转封装场景。

AudioBitrate

int64

音频码率。单位为千比特每秒(kbit/s)。取值范围:[1, 10000]。

AudioSampleRate

int64

音频采样率。单位为赫兹(Hz)。取值范围:8000、12025、12000,16000、22050、24000,32000、44100、48000、64000、88200 和 96000。

说明

不同格式支持的采样率有所不同,mp3 仅支持 48kHz 及以下;opus 支持 8kHz、12kHz、16kHz、24kHz 与 48kHz;ac3 支持 32kHz、44.1kHz 与 48kHz;amr 仅支持 8kHz 与 16kHz。

AudioChannel

int64

音频声道数。取值范围:[1, 8]。

AudioStream

[]int64

需要处理的源文件音频流索引号列表。默认处理第一路音频流,索引号大于 100 表示处理所有音频流。

  • 示例:[0,1]处理索引号为 0 和 1 的音频流;[1]处理索引号为 1 的音频流;[101]处理所有音频流。

说明

只处理索引号存在的音频流,索引号对应的音频流不存在时将忽略该索引号。

开通媒体转码

企业版文件管理服务(阿里云盘企业版)默认已经开通快速转码和离线音频转码能力。

开发版需要您通过官方钉群联系我们开通,开通媒体转码没有费用,但在使用过程中会产生费用,资费标准增值计费项

迁移边转边播到快速转码

相较于快速转码,早期推出的边转边播在部分播放器上进行拖动播放时存在缓冲时间较长的缺点,因此我们提供了无缝迁移边转边播到快速转码的方案。借由迁移,客户不仅可以在复用已有代码的基础上享受快速转码更流畅的播放体验,还可以复用先前边转边播转出来的大部分音视频文件。在进行迁移前,有以下几点限制需要注意:

  1. 迁移完成后转码的计费项将变为边转边播,原先的转码-转码-xxx计费项(如转码-转码264-HD)的计量后续将逐渐减少至归零;

  2. 迁移完成后返回的播放链接,根据链接对应的 m3u8 获取 ts 分片文件时将不支持 Range Get;

  3. 迁移完成后返回的播放链接 query 值中将包含未进行 URL 编码的 { 和 } 符号,例如下文的链接:

http://sample.oss-cn-hangzhou.aliyuncs.com/xxx/media-token-0.ts?x-oss-process=if_status_eq_404{hls/ts,from_dGFyZ2V0L2ZhbmdhbmxhaS92aWRlby8xMDgwcC8xMDgwcDMzLm0zdTg}&x-oss-expires=12345&x-oss-signature-version=OSS2&x-oss-access-key-id=ak&x-oss-signature=sk

对于 IOS 平台,请注意先对返回链接进行解码和编码,避免使用系统 NSURL 库时发生解码错误。相关代码实现可参考:

#import "NSString+URLReEncode.h"

@implementation NSString (URLEncoding)

- (NSString *)urlReEncode {
    NSRange queryStartRange = [self rangeOfString:@"?"];
    if (queryStartRange.location == NSNotFound) {
        return self;
    }
    
    NSString *baseURL = [self substringToIndex:queryStartRange.location];
    NSMutableCharacterSet *allowedCharacterSet = NSCharacterSet.URLQueryAllowedCharacterSet.mutableCopy;
    [allowedCharacterSet removeCharactersInString:@"=&+"];
    
    NSString *query = [self substringFromIndex:queryStartRange.location + 1];
    NSArray *parameters = [query componentsSeparatedByString:@"&"];
    NSMutableArray *encodedParameters = [NSMutableArray arrayWithCapacity:[parameters count]];
    
    for (NSString *parameter in parameters) {
        NSArray *keyValue = [parameter componentsSeparatedByString:@"="];
        if ([keyValue count] == 2) {
            NSString *key = keyValue[0];
            NSString *value = [keyValue[1] stringByRemovingPercentEncoding];
            NSString *encodedValue = [value stringByAddingPercentEncodingWithAllowedCharacters:allowedCharacterSet];
            [encodedParameters addObject:[NSString stringWithFormat:@"%@=%@", key, encodedValue]];
        } else {
            [encodedParameters addObject:parameter];
        }
    }
    
    NSString *encodedQuery = [encodedParameters componentsJoinedByString:@"&"];
    return [NSString stringWithFormat:@"%@?%@", baseURL, encodedQuery];
}

@end

上传音/视频文件

新上传的音/视频或者已经上传的音/视频文件都可以,这个步骤是要拿到原媒体文件的drive_idfile_id,用此信息来获取关联的转码结果。

获取媒体转码信息

调用/v2/file/get_video_preview_play_info接口,设置转码类型为Domain已开通的转码能力类型(比如quick_video),设置参数template_id="模板id"(比如264_480p)即可获取到"模板id"对应的播放信息(为空时会返回所有转码模板的播放信息)。如果转码尚未完成,您会获得一个等待重试的202 VideoPreviewWaitAndRetry 响应,反之则会通过URL字段返回转码结果的预览地址。

请求示例

{
    "drive_id": "1",
    "file_id": "abcd",              // 媒体文件本身
    "category": "quick_video", // 转码类型
    "template_id": "264_480p"       // 需要预览的模板id
}

响应示例

  1. 等待重试的响应结果

{
  "Code": "VideoPreviewWaitAndRetry",
  "Message": "media is transcoding, please wait and retry. xxx"
}

  1. 视频无法转码的响应结果

{
  "Code": "NotFound.VideoPreviewInfo",
  "Message": "ErrVideoPreviewLastErrorExist"
}

  1. 离线视频转码的响应结果

{
    "domain_id": "xxxxx",
    "drive_id": "1",
    "file_id": "abcd",                    // 视频文件本身
    "video_preview_play_info": {
        "category": "offline_video",      // 请求参数中的转码类型
        // 其他不重要信息 ...
        "offline_video_transcoding_list": [
            {
                "template_id": "264_480p",           // 模板ID
                "status": "finished"                 // 转码任务完成
                "url": "https://example.aliyundoc.com/c/d?e=f...", // 预览地址
            }
        ]
    }
}

  1. 离线音频转码的响应结果

{
    "domain_id": "xxxxx",
    "drive_id": "1",
    "file_id": "abcd",                     // 音频文件本身
    "video_preview_play_info": {
        "category": "offline_audio",      // 请求参数中的转码类型
        // 其他不重要信息 ...
        "offline_audio_list": [
            {
                "template_id": "264_480p",           // 模板ID
                "status": "finished"                 // 转码任务完成
                "url": "https://example.aliyundoc.com/c/d?e=f...", // 预览地址
            }
        ]
    }
}

  1. 快速转码的响应结果

{
    "domain_id": "xxxxx",
    "drive_id": "1",
    "file_id": "abcd",                   // 视频文件本身
    "video_preview_play_info": {
        "category": "quick_video",      // 请求参数中的转码类型
        // 其他不重要信息 ...
        "quick_video_list": [
            {
                "template_id": "264_480p",           // 模板ID
                "status": "finished"                 // 播放列表生成完成
                "url": "https://example.aliyundoc.com/c/d?e=f...", // 预览地址
            }
        ]
    }
}