# 媒体服务
> **说明:**
> 本模块首批接口从API version 6开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
媒体子系统为开发者提供一套简单且易于理解的接口,使得开发者能够方便接入系统并使用系统的媒体资源。
媒体子系统包含了音视频相关媒体业务,提供以下常用功能:
- 音频播放([AudioPlayer](#audioplayer))
- 视频播放([VideoPlayer](#videoplayer8))
- 音频录制([AudioRecorder](#audiorecorder))
- 视频录制([VideoRecorder](#VideoRecorder8+))
后续将提供以下功能:DataSource音视频播放、音视频编解码、容器封装解封装、媒体能力查询等功能。
## 导入模块
```js
import media from '@ohos.multimedia.media';
```
## media.createAudioPlayer
createAudioPlayer(): [AudioPlayer](#audioplayer)
同步方式创建音频播放实例。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
**返回值:**
| 类型 | 说明 |
| --------------------------- | ------------------------------------------------------------ |
| [AudioPlayer](#audioplayer) | 返回AudioPlayer类实例,失败时返回null。可用于音频播放、暂停、停止等操作。 |
**示例:**
```js
let audioPlayer = media.createAudioPlayer();
```
## media.createVideoPlayer8+
createVideoPlayer(callback: AsyncCallback\<[VideoPlayer](#videoplayer8)>): void
异步方式创建视频播放实例,通过注册回调函数获取返回值。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------- | ---- | ------------------------------ |
| callback | AsyncCallback<[VideoPlayer](#videoplayer8)> | 是 | 异步创建视频播放实例回调方法。 |
**示例:**
```js
let videoPlayer
media.createVideoPlayer((error, video) => {
if (typeof(video) != 'undefined') {
videoPlayer = video;
console.info('video createVideoPlayer success');
} else {
console.info(`video createVideoPlayer fail, error:${error.message}`);
}
});
```
## media.createVideoPlayer8+
createVideoPlayer: Promise<[VideoPlayer](#videoplayer8)>
异步方式创建视频播放实例,通过Promise获取返回值。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**返回值:**
| 类型 | 说明 |
| ------------------------------------- | ----------------------------------- |
| Promise<[VideoPlayer](#videoplayer8)> | 异步创建视频播放实例Promise返回值。 |
**示例:**
```js
let videoPlayer
function failureCallback(error) {
console.info(`video failureCallback, error:${error.message}`);
}
function catchCallback(error) {
console.info(`video catchCallback, error:${error.message}`);
}
await media.createVideoPlayer.then((video) => {
if (typeof(video) != 'undefined') {
videoPlayer = video;
console.info('video createVideoPlayer success');
} else {
console.info('video createVideoPlayer fail');
}
}, failureCallback).catch(catchCallback);
```
## media.createAudioRecorder
createAudioRecorder(): AudioRecorder
创建音频录制的实例来控制音频的录制。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder
**返回值:**
| 类型 | 说明 |
| ------------------------------- | ----------------------------------------- |
| [AudioRecorder](#audiorecorder) | 返回AudioRecorder类实例,失败时返回null。 |
**示例:**
```js
let audiorecorder = media.createAudioRecorder();
```
## media.createVideoRecorder8+
createVideoRecorder(callback: AsyncCallback\<[VideoRecorder](#videorecorder8)>): void
异步方式创建视频录制实例。通过注册回调函数获取返回值。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------------------------------------- | ---- | ------------------------------ |
| callback | AsyncCallback<[VideoRecorder](#videorecorder8)> | 是 | 异步创建视频录制实例回调方法。 |
**示例:**
```js
let videoRecorder
media.createVideoRecorder((error, video) => {
if (typeof(video) != 'undefined') {
videoRecorder = video;
console.info('video createVideoRecorder success');
} else {
console.info(`video createVideoRecorder fail, error:${error.message}`);
}
});
```
## media.createVideoRecorder8+
createVideoRecorder: Promise<[VideoRecorder](#videorecorder8)>
异步方式创建视频录制实例。通过Promise获取返回值。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
**返回值:**
| 类型 | 说明 |
| ----------------------------------------- | ----------------------------------- |
| Promise<[VideoRecorder](#videorecorder8)> | 异步创建视频录制实例Promise返回值。 |
**示例:**
```js
let videoRecorder
function failureCallback(error) {
console.info(`video failureCallback, error:${error.message}`);
}
function catchCallback(error) {
console.info(`video catchCallback, error:${error.message}`);
}
await media.createVideoRecorder.then((video) => {
if (typeof(video) != 'undefined') {
videoRecorder = video;
console.info('video createVideoRecorder success');
} else {
console.info('video createVideoRecorder fail');
}
}, failureCallback).catch(catchCallback);
```
## MediaErrorCode8+
媒体服务错误类型枚举。
| 名称 | 值 | 说明 |
| -------------------------- | ---- | ------------------------------------------------------------ |
| MSERR_OK | 0 | 表示操作成功。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| MSERR_NO_MEMORY | 1 | 表示申请内存失败,系统可能无可用内存。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| MSERR_OPERATION_NOT_PERMIT | 2 | 表示无权限执行此操作。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| MSERR_INVALID_VAL | 3 | 表示传入入参无效。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| MSERR_IO | 4 | 表示发生IO错误。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| MSERR_TIMEOUT | 5 | 表示操作超时。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| MSERR_UNKNOWN | 6 | 表示未知错误。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| MSERR_SERVICE_DIED | 7 | 表示服务端失效。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| MSERR_INVALID_STATE | 8 | 表示在当前状态下,不允许执行此操作。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| MSERR_UNSUPPORTED | 9 | 表示在当前版本下,不支持此操作。
**系统能力:** SystemCapability.Multimedia.Media.Core |
## MediaType8+
媒体类型枚举。
| 名称 | 值 | 说明 |
| -------------- | ---- | ------------------------------------------------------------ |
| MEDIA_TYPE_AUD | 0 | 表示音频。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| MEDIA_TYPE_VID | 1 | 表示视频。
**系统能力:** SystemCapability.Multimedia.Media.Core |
## CodecMimeType8+
Codec MIME类型枚举。
| 名称 | 值 | 说明 |
| ------------ | ----------------- | ------------------------------------------------------------ |
| VIDEO_MPEG4 | ”video/mp4v-es“ | 表示视频/mpeg4类型。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| AUDIO_AAC | "audio/mp4a-latm" | 表示音频/mp4a-latm类型。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| AUDIO_VORBIS | "audio/vorbis" | 表示音频/vorbis类型。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| AUDIO_FLAC | "audio/flac" | 表示音频/flac类型。
**系统能力:** SystemCapability.Multimedia.Media.Core |
## MediaDescriptionKey8+
媒体信息描述枚举。
| 名称 | 值 | 说明 |
| ------------------------ | --------------- | ------------------------------------------------------------ |
| MD_KEY_TRACK_INDEX | "track_index" | 表示轨道序号,其对应键值类型为number。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| MD_KEY_TRACK_TYPE | "track_type" | 表示轨道类型,其对应键值类型为number,参考[MediaType](#mediatype8)。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| MD_KEY_CODEC_MIME | "codec_mime" | 表示codec_mime类型,其对应键值类型为string。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| MD_KEY_DURATION | "duration" | 表示媒体时长,其对应键值类型为number,单位为ms。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| MD_KEY_BITRATE | "bitrate" | 表示比特率,其对应键值类型为number,单位为bps。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| MD_KEY_WIDTH | "width" | 表示视频宽度,其对应键值类型为number,单位为像素。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| MD_KEY_HEIGHT | "height" | 表示视频高度,其对应键值类型为number,单位为像素。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| MD_KEY_FRAME_RATE | "frame_rate" | 表示视频帧率,其对应键值类型为number,单位为100fps。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| MD_KEY_AUD_CHANNEL_COUNT | "channel_count" | 表示声道数,其对应键值类型为number。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| MD_KEY_AUD_SAMPLE_RATE | "sample_rate" | 表示采样率,其对应键值类型为number,单位为HZ。
**系统能力:** SystemCapability.Multimedia.Media.Core |
## BufferingInfoType8+
缓存事件类型枚举。
| 名称 | 值 | 说明 |
| ----------------- | ---- | ------------------------------------------------------------ |
| BUFFERING_START | 1 | 表示开始缓存。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| BUFFERING_END | 2 | 表示结束缓存。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| BUFFERING_PERCENT | 3 | 表示缓存百分比。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| CACHED_DURATION | 4 | 表示缓存时长,单位为毫秒。
**系统能力:** SystemCapability.Multimedia.Media.Core |
## AudioPlayer
音频播放管理类,用于管理和播放音频媒体。在调用AudioPlayer的方法前,需要先通过[createAudioPlayer()](#mediacreateaudioplayer)构建一个[AudioPlayer](#audioplayer)实例。
音频播放demo可参考:[音频播放开发指导](../../media/audio-playback.md)
### 属性
| 名称 | 类型 | 可读 | 可写 | 说明 |
| ----------- | ------------------------- | ---- | ---- | ------------------------------------------------------------ |
| src | string | 是 | 是 | 音频媒体URI,支持当前主流的音频格式(mp4、aac、mp3、ogg)。
**支持路径示例**:
1、fd类型播放:fd://xxx
![zh-cn_image_0000001164217678](figures/zh-cn_image_url.png)
2、http网络播放路径:开发中
3、hls网络播放路径:开发中
**注意事项**:
使用媒体素材需要获取读权限,否则无法正常播放。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer |
| loop | boolean | 是 | 是 | 音频循环播放属性,设置为'true'表示循环播放。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer |
| currentTime | number | 是 | 否 | 音频的当前播放位置。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer |
| duration | number | 是 | 否 | 音频时长。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer |
| state | [AudioState](#audiostate) | 是 | 否 | 音频播放的状态。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer |
### play
play(): void
开始播放音频资源,需在[dataLoad](#on('play' | 'pause' | 'stop' | 'reset' | 'dataload' | 'finish' | 'volumechange'))事件成功触发后,才能调用play方法。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
**示例:**
```js
audioPlayer.on('play', () => { //设置'play'事件回调
console.log('audio play success');
});
audioPlayer.play();
```
### pause
pause(): void
暂停播放音频资源。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
**示例:**
```js
audioPlayer.on('pause', () => { //设置'pause'事件回调
console.log('audio pause success');
});
audioPlayer.pause();
```
### stop
stop(): void
停止播放音频资源。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
**示例:**
```js
audioPlayer.on('stop', () => { //设置'stop'事件回调
console.log('audio stop success');
});
audioPlayer.stop();
```
### reset7+
reset(): void
切换播放音频资源。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
**示例:**
```js
audioPlayer.on('reset', () => { //设置'reset'事件回调
console.log('audio reset success');
});
audioPlayer.reset();
```
### seek
seek(timeMs: number): void
跳转到指定播放位置。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------------------------------ |
| timeMs | number | 是 | 指定的跳转时间节点,单位毫秒。 |
**示例:**
```js
audioPlayer.on('timeUpdate', (seekDoneTime) => { //设置'timeUpdate'事件回调
if (typeof (seekDoneTime) == 'undefined') {
console.info('audio seek fail');
return;
}
console.log('audio seek success. seekDoneTime: ' + seekDoneTime);
});
audioPlayer.seek(30000); //seek到30000ms的位置
```
### setVolume
setVolume(vol: number): void
设置音量。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| vol | number | 是 | 指定的相对音量大小,取值范围为[0.00-1.00],1表示最大音量,即100%。 |
**示例:**
```js
audioPlayer.on('volumeChange', () => { //设置'volumeChange'事件回调
console.log('audio volumeChange success');
});
audioPlayer.setVolume(1); //设置音量到100%
```
### release
release(): void
释放音频资源。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
**示例:**
```js
audioPlayer.release();
audioPlayer = undefined;
```
### getTrackDescription8+
getTrackDescription(callback: AsyncCallback>): void
通过回调方式获取音频轨道信息。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------------ | ---- | -------------------------- |
| callback | AsyncCallback> | 是 | 获取音频轨道信息回调方法。 |
**示例:**
```js
function printfDescription(obj) {
for (let item in obj) {
let property = obj[item];
console.info('audio key is ' + item);
console.info('audio value is ' + property);
}
}
audioPlayer.getTrackDescription((error, arrlist) => {
if (typeof (arrlist) != 'undefined') {
for (let i = 0; i < arrlist.length; i++) {
printfDescription(arrlist[i]);
}
} else {
console.log(`audio getTrackDescription fail, error:${error.message}`);
}
});
```
### getTrackDescription8+
getTrackDescription(): Promise>
通过Promise方式获取音频轨道信息。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
**返回值:**
| 类型 | 说明 |
| ------------------------------------------------------ | ------------------------------- |
| Promise> | 获取音频轨道信息Promise返回值。 |
**示例:**
```js
function printfDescription(obj) {
for (let item in obj) {
let property = obj[item];
console.info('audio key is ' + item);
console.info('audio value is ' + property);
}
}
function failureCallback(error) {
console.info(`audio failureCallback, error:${error.message}`);
}
function catchCallback(error) {
console.info(`audio catchCallback, error:${error.message}`);
}
await audioPlayer.getTrackDescription.then((arrlist) => {
if (typeof (arrlist) != 'undefined') {
arrayDescription = arrlist;
} else {
console.log('audio getTrackDescription fail');
}
}, failureCallback).catch(catchCallback);
for (let i = 0; i < arrayDescription.length; i++) {
printfDescription(arrayDescription[i]);
}
```
### on('bufferingUpdate')8+
on(type: 'bufferingUpdate', callback: (infoType: [BufferingInfoType](#bufferinginfotype8), value: number) => void): void
开始订阅音频缓存更新事件。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
| type | string | 是 | 音频缓存事件回调类型,支持的事件:'bufferingUpdate'。 |
| callback | (infoType: [BufferingInfoType](#bufferinginfotype8), value: number) => void | 是 | 音频缓存事件回调方法。
[BufferingInfoType](#bufferinginfotype8)为BUFFERING_PERCENT或CACHED_DURATION时,value值有效,否则固定为0。 |
**示例:**
```js
audioPlayer.on('bufferingUpdate', (infoType, value) => {
console.log('audio bufferingInfo type: ' + infoType);
console.log('audio bufferingInfo value: ' + value);
});
```
### on('play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange')
on(type: 'play' | 'pause' | 'stop' | 'reset' | 'dataLoad' | 'finish' | 'volumeChange', callback: () => void): void
开始订阅音频播放事件。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ---------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 播放事件回调类型,支持的事件包括:'play' \| 'pause' \| 'stop' \| 'reset' \| 'dataLoad' \| 'finish' \| 'volumeChange'。
- 'play':完成[play()](#play)调用,音频开始播放,触发该事件。
- 'pause':完成[pause()](#pause)调用,音频暂停播放,触发该事件。
- 'stop':完成[stop()](#stop)调用,音频停止播放,触发该事件。
- 'reset':完成[reset()](#reset7)调用,播放器重置,触发该事件。
- 'dataLoad':完成音频数据加载后触发该事件,即src属性设置完成后触发该事件。
- 'finish':完成音频播放后触发该事件。
- 'volumeChange':完成[setVolume()](#setvolume)调用,播放音量改变后触发该事件。 |
| callback | () => void | 是 | 播放事件回调方法。 |
**示例:**
```js
let audioPlayer = media.createAudioPlayer(); //创建一个音频播放实例
audioPlayer.on('dataLoad', () => { //设置'dataLoad'事件回调,src属性设置成功后,触发此回调
console.info('audio set source success');
audioPlayer.play(); //开始播放,并触发'play'事件回调
});
audioPlayer.on('play', () => { //设置'play'事件回调
console.info('audio play success');
audioPlayer.seek(30000); //调用seek方法,并触发'timeUpdate'事件回调
});
audioPlayer.on('pause', () => { //设置'pause'事件回调
console.info('audio pause success');
audioPlayer.stop(); //停止播放,并触发'stop'事件回调
});
audioPlayer.on('reset', () => { //设置'reset'事件回调
console.info('audio reset success');
audioPlayer.release(); //释放播放实例资源
audioPlayer = undefined;
});
audioPlayer.on('timeUpdate', (seekDoneTime) => { //设置'timeUpdate'事件回调
if (typeof(seekDoneTime) == "undefined") {
console.info('audio seek fail');
return;
}
console.info('audio seek success, and seek time is ' + seekDoneTime);
audioPlayer.setVolume(0.5); //设置音量为50%,并触发'volumeChange'事件回调
});
audioPlayer.on('volumeChange', () => { //设置'volumeChange'事件回调
console.info('audio volumeChange success');
audioPlayer.pause(); //暂停播放,并触发'pause'事件回调
});
audioPlayer.on('finish', () => { //设置'finish'事件回调
console.info('audio play finish');
audioPlayer.stop(); //停止播放,并触发'stop'事件回调
});
audioPlayer.on('error', (error) => { //设置'error'事件回调
console.info(`audio error called, errName is ${error.name}`);
console.info(`audio error called, errCode is ${error.code}`);
console.info(`audio error called, errMessage is ${error.message}`);
});
// 用户选择视频设置fd(本地播放)
let fdPath = 'fd://'
let path = 'data/accounts/account_0/appdata/ohos.xxx.xxx.xxx/01.mp3';
await fileIO.open(path).then(fdNumber) => {
fdPath = fdPath + '' + fdNumber;
console.info('open fd sucess fd is' + fdPath);
}, (err) => {
console.info('open fd failed err is' + err);
}),catch((err) => {
console.info('open fd failed err is' + err);
});
audioPlayer.src = fdPath; //设置src属性,并触发'dataLoad'事件回调
```
### on('timeUpdate')
on(type: 'timeUpdate', callback: Callback\): void
开始订阅音频播放[seek()](#seek)时间更新事件。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ----------------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 播放事件回调类型,支持的事件包括:'timeUpdate'。
- 'timeUpdate':[seek()](#seek)调用完成,触发该事件。 |
| callback | Callback\ | 是 | 播放事件回调方法。回调方法入参为成功seek的时间。 |
**示例:**
```js
audioPlayer.on('timeUpdate', (seekDoneTime) => { //设置'timeUpdate'事件回调
if (typeof (seekDoneTime) == 'undefined') {
console.info('audio seek fail');
return;
}
console.log('audio seek success. seekDoneTime: ' + seekDoneTime);
});
audioPlayer.seek(30000); //seek到30000ms的位置
```
### on('error')
on(type: 'error', callback: ErrorCallback): void
开始订阅音频播放错误事件。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 播放错误事件回调类型,支持的事件包括:'error'。
- 'error':音频播放中发生错误,触发该事件。 |
| callback | ErrorCallback | 是 | 播放错误事件回调方法。 |
**示例:**
```js
audioPlayer.on('error', (error) => { //设置'error'事件回调
console.info(`audio error called, errName is ${error.name}`); //打印错误类型名称
console.info(`audio error called, errCode is ${error.code}`); //打印错误码
console.info(`audio error called, errMessage is ${error.message}`);//打印错误类型详细描述
});
audioPlayer.setVolume(3); //设置volume为无效值,触发'error'事件
```
## AudioState
音频播放的状态机。可通过state属性获取当前状态。
| 名称 | 类型 | 描述 |
| ------------------ | ------ | ------------------------------------------------------------ |
| idle | string | 音频播放空闲。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer |
| playing | string | 音频正在播放。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer |
| paused | string | 音频暂停播放。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer |
| stopped | string | 音频播放停止。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer |
| error8+ | string | 错误状态。
**系统能力:** SystemCapability.Multimedia.Media.AudioPlayer |
## VideoPlayer8+
视频播放管理类,用于管理和播放视频媒体。在调用VideoPlayer的方法前,需要先通过[createVideoPlayer()](#media.createvideoplayer8)构建一个[VideoPlayer](#videoplayer8)实例。
视频播放demo可参考:[视频播放开发指导](../../media/video-playback.md)
### 属性
| 名称 | 类型 | 可读 | 可写 | 说明 |
| ------------------------ | ---------------------------------- | ---- | ---- | ------------------------------------------------------------ |
| url8+ | string | 是 | 是 | 视频媒体URL,支持当前主流的视频格式(mp4、mpeg-ts、webm、mkv)。
**支持路径示例**:
1. fd类型播放:fd://xxx
![zh-cn_image_0000001164217678](figures/zh-cn_image_url.png)
**注意事项**:
使用媒体素材需要获取读权限,否则无法正常播放。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer |
| loop8+ | boolean | 是 | 是 | 视频循环播放属性,设置为'true'表示循环播放。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer |
| currentTime8+ | number | 是 | 否 | 视频的当前播放位置。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer |
| duration8+ | number | 是 | 否 | 视频时长,返回-1表示直播模式。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer |
| state8+ | [VideoPlayState](#videoplaystate8) | 是 | 否 | 视频播放的状态。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer |
| width8+ | number | 是 | 否 | 视频宽。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer |
| height8+ | number | 是 | 否 | 视频高。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer |
### setDisplaySurface8+
setDisplaySurface(surfaceId: string, callback: AsyncCallback\): void
通过回调方式设置SurfaceId。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| --------- | -------- | ---- | ------------------------- |
| surfaceId | string | 是 | SurfaceId |
| callback | function | 是 | 设置SurfaceId的回调方法。 |
**示例:**
```js
videoPlayer.setDisplaySurface(surfaceId, (err) => {
if (typeof (err) == 'undefined') {
console.info('setDisplaySurface success!');
} else {
console.info('setDisplaySurface fail!');
}
});
```
### setDisplaySurface8+
setDisplaySurface(surfaceId: string): Promise\
通过Promise方式设置SurfaceId。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| --------- | ------ | ---- | --------- |
| surfaceId | string | 是 | SurfaceId |
**返回值:**
| 类型 | 说明 |
| ------------- | ------------------------------ |
| Promise | 设置SurfaceId的Promise返回值。 |
**示例:**
```js
function failureCallback(error) {
console.info(`video failureCallback, error:${error.message}`);
}
function catchCallback(error) {
console.info(`video catchCallback, error:${error.message}`);
}
await videoPlayer.setDisplaySurface(surfaceId).then(() => {
console.info('setDisplaySurface success');
}, failureCallback).catch(catchCallback);
```
### prepare8+
prepare(callback: AsyncCallback\): void
通过回调方式准备播放视频。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | ---- | ------------------------ |
| callback | function | 是 | 准备播放视频的回调方法。 |
**示例:**
```js
videoPlayer.prepare((err) => {
if (typeof (err) == 'undefined') {
console.info('prepare success!');
} else {
console.info('prepare fail!');
}
});
```
### prepare8+
prepare(): Promise\
通过Promise方式准备播放视频。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**返回值:**
| 类型 | 说明 |
| -------------- | ----------------------------- |
| Promise\ | 准备播放视频的Promise返回值。 |
**示例:**
```js
function failureCallback(error) {
console.info(`video failureCallback, error:${error.message}`);
}
function catchCallback(error) {
console.info(`video catchCallback, error:${error.message}`);
}
await videoPlayer.prepare().then(() => {
console.info('prepare success');
}, failureCallback).catch(catchCallback);
```
### play8+
play(callback: AsyncCallback\): void;
通过回调方式开始播放视频。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | ---- | ------------------------ |
| callback | function | 是 | 开始播放视频的回调方法。 |
**示例:**
```js
videoPlayer.play((err) => {
if (typeof (err) == 'undefined') {
console.info('play success!');
} else {
console.info('play fail!');
}
});
```
### play8+
play(): Promise\;
通过Promise方式开始播放视频。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**返回值:**
| 类型 | 说明 |
| -------------- | ----------------------------- |
| Promise\ | 开始播放视频的Promise返回值。 |
**示例:**
```js
function failureCallback(error) {
console.info(`video failureCallback, error:${error.message}`);
}
function catchCallback(error) {
console.info(`video catchCallback, error:${error.message}`);
}
await videoPlayer.play().then(() => {
console.info('play success');
}, failureCallback).catch(catchCallback);
```
### pause8+
pause(callback: AsyncCallback\): void
通过回调方式暂停播放视频。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | ---- | ------------------------ |
| callback | function | 是 | 暂停播放视频的回调方法。 |
**示例:**
```js
videoPlayer.pause((err) => {
if (typeof (err) == 'undefined') {
console.info('pause success!');
} else {
console.info('pause fail!');
}
});
```
### pause8+
pause(): Promise\
通过Promise方式暂停播放视频。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**返回值:**
| 类型 | 说明 |
| -------------- | ----------------------------- |
| Promise\ | 暂停播放视频的Promise返回值。 |
**示例:**
```js
function failureCallback(error) {
console.info(`video failureCallback, error:${error.message}`);
}
function catchCallback(error) {
console.info(`video catchCallback, error:${error.message}`);
}
await videoPlayer.pause().then(() => {
console.info('pause success');
}, failureCallback).catch(catchCallback);
```
### stop8+
stop(callback: AsyncCallback\): void
通过回调方式停止播放视频。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | ---- | ------------------------ |
| callback | function | 是 | 停止播放视频的回调方法。 |
**示例:**
```js
videoPlayer.stop((err) => {
if (typeof (err) == 'undefined') {
console.info('stop success!');
} else {
console.info('stop fail!');
}
});
```
### stop8+
stop(): Promise\
通过Promise方式停止播放视频。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**返回值:**
| 类型 | 说明 |
| -------------- | ----------------------------- |
| Promise\ | 停止播放视频的Promise返回值。 |
**示例:**
```js
function failureCallback(error) {
console.info(`video failureCallback, error:${error.message}`);
}
function catchCallback(error) {
console.info(`video catchCallback, error:${error.message}`);
}
await videoPlayer.stop().then(() => {
console.info('stop success');
}, failureCallback).catch(catchCallback);
```
### reset8+
reset(callback: AsyncCallback\): void
通过回调方式切换播放视频。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | ---- | ------------------------ |
| callback | function | 是 | 切换播放视频的回调方法。 |
**示例:**
```js
videoPlayer.reset((err) => {
if (typeof (err) == 'undefined') {
console.info('reset success!');
} else {
console.info('reset fail!');
}
});
```
### reset8+
reset(): Promise\
通过Promise方式切换播放视频。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**返回值:**
| 类型 | 说明 |
| -------------- | ----------------------------- |
| Promise\ | 切换播放视频的Promise返回值。 |
**示例:**
```js
function failureCallback(error) {
console.info(`video failureCallback, error:${error.message}`);
}
function catchCallback(error) {
console.info(`video catchCallback, error:${error.message}`);
}
await videoPlayer.reset().then(() => {
console.info('reset success');
}, failureCallback).catch(catchCallback);
```
### seek8+
seek(timeMs: number, callback: AsyncCallback\): void
通过回调方式跳转到指定播放位置,默认跳转到指定时间点的下一个关键帧。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | ---- | ------------------------------ |
| timeMs | number | 是 | 指定的跳转时间节点,单位毫秒。 |
| callback | function | 是 | 跳转到指定播放位置的回调方法。 |
**示例:**
```js
videoPlayer.seek((seekTime, err) => {
if (typeof (err) == 'undefined') {
console.info('seek success!');
} else {
console.info('seek fail!');
}
});
```
### seek8+
seek(timeMs: number, mode:SeekMode, callback: AsyncCallback\): void
通过回调方式跳转到指定播放位置。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | ---- | ---------------------------------------- |
| timeMs | number | 是 | 指定的跳转时间节点,单位毫秒。 |
| mode | SeekMode | 是 | 跳转模式,具体见[SeekMode](#seekmode8)。 |
| callback | function | 是 | 跳转到指定播放位置的回调方法。 |
**示例:**
```js
videoPlayer.seek((seekTime, seekMode, err) => {
if (typeof (err) == 'undefined') {
console.info('seek success!');
} else {
console.info('seek fail!');
}
});
```
### seek8+
seek(timeMs: number, mode?:SeekMode): Promise\
通过Promise方式跳转到指定播放位置,如果没有设置mode则跳转到指定时间点的下一个关键帧。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | -------- | ---- | -------------------------------------- |
| timeMs | number | 是 | 指定的跳转时间节点,单位毫秒。 |
| mode | SeekMode | 否 | 跳转模式,具体见[SeekMode](#seekmode8) |
**返回值:**
| 类型 | 说明 |
| -------------- | ----------------------------------- |
| Promise\ | 跳转到指定播放位置的Promise返回值。 |
**示例:**
```js
function failureCallback(error) {
console.info(`video failureCallback, error:${error.message}`);
}
function catchCallback(error) {
console.info(`video catchCallback, error:${error.message}`);
}
await videoPlayer.seek(seekTime).then((seekDoneTime) => { // seekDoneTime表示seek完成后的时间点
console.info('seek success');
}, failureCallback).catch(catchCallback);
await videoPlayer.seek(seekTime, seekMode).then((seekDoneTime) => {
console.info('seek success');
}, failureCallback).catch(catchCallback);
```
### setVolume8+
setVolume(vol: number, callback: AsyncCallback\): void
通过回调方式设置音量。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| vol | number | 是 | 指定的相对音量大小,取值范围为[0.00-1.00],1表示最大音量,即100%。 |
| callback | function | 是 | 设置音量的回调方法。 |
**示例:**
```js
videoPlayer.setVolume((vol, err) => {
if (typeof (err) == 'undefined') {
console.info('setVolume success!');
} else {
console.info('setVolume fail!');
}
});
```
### setVolume8+
setVolume(vol: number): Promise\
通过Promise方式设置音量。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ------------------------------------------------------------ |
| vol | number | 是 | 指定的相对音量大小,取值范围为[0.00-1.00],1表示最大音量,即100%。 |
**返回值:**
| 类型 | 说明 |
| -------------- | ------------------------- |
| Promise\ | 设置音量的Promise返回值。 |
**示例:**
```js
function failureCallback(error) {
console.info(`video failureCallback, error:${error.message}`);
}
function catchCallback(error) {
console.info(`video catchCallback, error:${error.message}`);
}
await videoPlayer.setVolume(vol).then() => {
console.info('setVolume success');
}, failureCallback).catch(catchCallback);
```
### release8+
release(callback: AsyncCallback\): void
通过回调方式释放视频资源。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | ---- | ------------------------ |
| callback | function | 是 | 释放视频资源的回调方法。 |
**示例:**
```js
videoPlayer.release((err) => {
if (typeof (err) == 'undefined') {
console.info('release success!');
} else {
console.info('release fail!');
}
});
```
### release8+
release(): Promise\
通过Promise方式释放视频资源。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**返回值:**
| 类型 | 说明 |
| -------------- | ----------------------------- |
| Promise\ | 释放视频资源的Promise返回值。 |
**示例:**
```js
function failureCallback(error) {
console.info(`video failureCallback, error:${error.message}`);
}
function catchCallback(error) {
console.info(`video catchCallback, error:${error.message}`);
}
await videoPlayer.release().then() => {
console.info('release success');
}, failureCallback).catch(catchCallback);
```
### getTrackDescription8+
getTrackDescription(callback: AsyncCallback>)>>): void
通过回调方式获取视频轨道信息。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | ---- | -------------------------- |
| callback | function | 是 | 获取视频轨道信息回调方法。 |
**示例:**
```js
function printfDescription(obj) {
for (let item in obj) {
let property = obj[item];
console.info('video key is ' + item);
console.info('video value is ' + property);
}
}
videoPlayer.getTrackDescription((error, arrlist) => {
if (typeof (arrlist) != 'undefined') {
for (let i = 0; i < arrlist.length; i++) {
printfDescription(arrlist[i]);
}
} else {
console.log(`video getTrackDescription fail, error:${error.message}`);
}
});
```
### getTrackDescription8+
getTrackDescription(): Promise>)>>
通过Promise方式获取视频轨道信息。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**返回值:**
| 类型 | 说明 |
| -------------------------------------------------------- | ------------------------------- |
| Promise>)>> | 获取视频轨道信息Promise返回值。 |
**示例:**
```js
function printfDescription(obj) {
for (let item in obj) {
let property = obj[item];
console.info('video key is ' + item);
console.info('video value is ' + property);
}
}
function failureCallback(error) {
console.info(`video failureCallback, error:${error.message}`);
}
function catchCallback(error) {
console.info(`video catchCallback, error:${error.message}`);
}
let arrayDescription;
await videoPlayer.getTrackDescription().then((arrlist) => {
if (typeof (arrlist) != 'undefined') {
arrayDescription = arrlist;
} else {
console.log('video getTrackDescription fail');
}
}, failureCallback).catch(catchCallback);
for (let i = 0; i < arrayDescription.length; i++) {
printfDescription(arrayDescription[i]);
}
```
### setSpeed8+
setSpeed(speed:number, callback: AsyncCallback\): void
通过回调方式设置播放速度。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | ---- | ---------------------------------------------------------- |
| speed | number | 是 | 指定播放视频速度,具体见[PlaybackSpeed](#playbackspeed8)。 |
| callback | function | 是 | 设置播放速度的回调方法。 |
**示例:**
```js
videoPlayer.setSpeed((speed:number, err) => {
if (typeof (err) == 'undefined') {
console.info('setSpeed success!');
} else {
console.info('setSpeed fail!');
}
});
```
### setSpeed8+
setSpeed(speed:number): Promise\
通过Promise方式设置播放速度。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------ | ---- | ---------------------------------------------------------- |
| speed | number | 是 | 指定播放视频速度,具体见[PlaybackSpeed](#playbackspeed8)。 |
**示例:**
```js
function failureCallback(error) {
console.info(`video failureCallback, error:${error.message}`);
}
function catchCallback(error) {
console.info(`video catchCallback, error:${error.message}`);
}
await videoPlayer.setSpeed(speed).then() => {
console.info('setSpeed success');
}, failureCallback).catch(catchCallback);
```
### on('playbackCompleted')8+
on(type: 'playbackCompleted', callback: Callback\): void
开始监听视频播放完成事件。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | ---- | ----------------------------------------------------------- |
| type | string | 是 | 视频播放完成事件回调类型,支持的事件:'playbackCompleted'。 |
| callback | function | 是 | 视频播放完成事件回调方法。 |
**示例:**
```js
videoPlayer.on('playbackCompleted', () => {
console.info('playbackCompleted success!');
});
```
### on('bufferingUpdate')8+
on(type: 'bufferingUpdate', callback: (infoType: BufferingInfoType, value: number) => void): void
开始监听视频缓存更新事件。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 视频缓存事件回调类型,支持的事件:'bufferingUpdate'。 |
| callback | function | 是 | 视频缓存事件回调方法。
[BufferingInfoType](#bufferinginfotype8)为BUFFERING_PERCENT或CACHED_DURATION时,value值有效,否则固定为0。 |
**示例:**
```js
videoPlayer.on('bufferingUpdate', (infoType, value) => {
console.log('video bufferingInfo type: ' + infoType);
console.log('video bufferingInfo value: ' + value);
});
```
### on('startRenderFrame')8+
on(type: 'startRenderFrame', callback: Callback\): void
开始监听视频播放首帧送显上报事件。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 视频播放首帧送显上报事件回调类型,支持的事件:'startRenderFrame'。 |
| callback | function | 是 | 视频播放首帧送显上报事件回调方法。 |
**示例:**
```js
videoPlayer.on('startRenderFrame', () => {
console.info('startRenderFrame success!');
});
```
### on('videoSizeChanged')8+
on(type: 'videoSizeChanged', callback: (width: number, height: number) => void): void
开始监听视频播放宽高变化事件。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 视频播放宽高变化事件回调类型,支持的事件:'videoSizeChanged'。 |
| callback | function | 是 | 视频播放宽高变化事件回调方法,width表示宽,height表示高。 |
**示例:**
```js
videoPlayer.on('videoSizeChanged', (width, height) => {
console.log('video width is: ' + width);
console.log('video height is: ' + height);
});
```
### on('error')8+
on(type: 'error', callback: ErrorCallback): void
开始监听视频播放错误事件。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 播放错误事件回调类型,支持的事件包括:'error'。
- 'error':视频播放中发生错误,触发该事件。 |
| callback | function | 是 | 播放错误事件回调方法。 |
**示例:**
```js
videoPlayer.on('error', (error) => { // 设置'error'事件回调
console.info(`video error called, errName is ${error.name}`); // 打印错误类型名称
console.info(`video error called, errCode is ${error.code}`); // 打印错误码
console.info(`video error called, errMessage is ${error.message}`);// 打印错误类型详细描述
});
videoPlayer.setVolume(3); //设置volume为无效值,触发'error'事件
```
## VideoPlayState8+
视频播放的状态机,可通过state属性获取当前状态。
| 名称 | 类型 | 描述 |
| -------- | ------ | ------------------------------------------------------------ |
| idle | string | 视频播放空闲。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer |
| prepared | string | 视频播放准备。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer |
| playing | string | 视频正在播放。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer |
| paused | string | 视频暂停播放。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer |
| stopped | string | 视频播放停止。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer |
| error | string | 错误状态。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer |
## SeekMode8+
视频播放的Seek模式枚举,可通过seek方法作为参数传递下去。
| 名称 | 值 | 描述 |
| -------------- | ---- | ------------------------------------------------------------ |
| SEEK_NEXT_SYNC | 0 | 表示跳转到指定时间点的下一个关键帧,建议向后快进的时候用这个枚举值。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| SEEK_PREV_SYNC | 1 | 表示跳转到指定时间点的上一个关键帧,建议向前快进的时候用这个枚举值。
**系统能力:** SystemCapability.Multimedia.Media.Core |
## PlaybackSpeed8+
视频播放的倍速枚举,可通过setSpeed方法作为参数传递下去。
| 名称 | 值 | 描述 |
| -------------------- | ---- | ------------------------------------------------------------ |
| SPEED_FORWARD_0_75_X | 0 | 表示视频播放正常播速的0.75倍。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer |
| SPEED_FORWARD_1_00_X | 1 | 表示视频播放正常播速。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer |
| SPEED_FORWARD_1_25_X | 2 | 表示视频播放正常播速的1.25倍。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer |
| SPEED_FORWARD_1_75_X | 3 | 表示视频播放正常播速的1.75倍。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer |
| SPEED_FORWARD_2_00_X | 4 | 表示视频播放正常播速的2.00倍。
**系统能力:** SystemCapability.Multimedia.Media.VideoPlayer |
## MediaDescription8+
### [key : string] : any
通过key-value方式获取媒体信息。
| 名称 | 类型 | 说明 |
| ----- | ------ | ------------------------------------------------------------ |
| key | string | 通过key值获取对应的value。key值具体可见[MediaDescriptionKey](#mediadescriptionkey8)。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| value | any | 对应key值得value。其类型可为任意类型,具体key对应value的类型可参考[MediaDescriptionKey](#mediadescriptionkey8)的描述信息。
**系统能力:** SystemCapability.Multimedia.Media.Core |
**示例:**
```js
function printfItemDescription(obj, key) {
let property = obj[key];
console.info('audio key is ' + key);
console.info('audio value is ' + property);
}
audioPlayer.getTrackDescription((error, arrlist) => {
if (typeof (arrlist) != 'undefined') {
for (let i = 0; i < arrlist.length; i++) {
printfItemDescription(arrlist[i], MD_KEY_TRACK_TYPE); //打印出每条轨道MD_KEY_TRACK_TYPE的值
}
} else {
console.log(`audio getTrackDescription fail, error:${error.message}`);
}
});
```
## AudioRecorder
音频录制管理类,用于录制音频媒体。在调用AudioRecorder的方法前,需要先通过[createAudioRecorder()](#media.createaudiorecorder) 构建一个[AudioRecorder](#audiorecorder)实例。
音频录制demo可参考:[音频录制开发指导](../../media/audio-recorder.md)
### prepare
prepare(config: AudioRecorderConfig): void
录音准备。
**需要权限:** ohos.permission.MICROPHONE
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------------------------------------------- | ---- | ------------------------------------------------------------ |
| config | [AudioRecorderConfig](#audiorecorderconfig) | 是 | 配置录音的相关参数,包括音频输出URI、[编码格式](#audioencoder)、采样率、声道数、[输出格式](#audiooutputformat)等。 |
**示例:**
```js
let audioRecorderConfig = {
audioEncoder : media.AudioEncoder.AAC_LC,
audioEncodeBitRate : 22050,
audioSampleRate : 22050,
numberOfChannels : 2,
format : media.AudioOutputFormat.AAC_ADTS,
uri : 'fd://1', // 文件需先由调用者创建,并给予适当的权限
location : { latitude : 30, longitude : 130},
}
audioRecorder.on('prepare', () => { //设置'prepare'事件回调
console.log('prepare success');
});
audioRecorder.prepare(audioRecorderConfig);
```
### start
start(): void
开始录制,需在[prepare](#audiorecorder_on)事件成功触发后,才能调用start方法。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder
**示例:**
```js
audioRecorder.on('start', () => { //设置'start'事件回调
console.log('audio recorder start success');
});
audioRecorder.start();
```
### pause
pause():void
暂停录制,需要在[start](#audiorecorder_on)事件成功触发后,才能调用pause方法。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder
**示例:**
```js
audioRecorder.on('pause', () => { //设置'pause'事件回调
console.log('audio recorder pause success');
});
audioRecorder.pause();
```
### resume
resume():void
暂停录制,需要在[pause](#audiorecorder_on)事件成功触发后,才能调用resume方法。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder
**示例:**
```js
audioRecorder.on('resume', () => { //设置'resume'事件回调
console.log('audio recorder resume success');
});
audioRecorder.resume();
```
### stop
stop(): void
停止录音。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder
**示例:**
```js
audioRecorder.on('stop', () => { //设置'stop'事件回调
console.log('audio recorder stop success');
});
audioRecorder.stop();
```
### release
release(): void
释放录音资源。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder
**示例:**
```js
audioRecorder.on('release', () => { //设置'release'事件回调
console.log('audio recorder release success');
});
audioRecorder.release();
audioRecorder = undefined;
```
### reset
reset(): void
重置录音。
进行重置录音之前,需要先调用[stop()](#audiorecorder_stop)停止录音。重置录音之后,需要调用[prepare()](#audiorecorder_prepare)设置录音参数项,才能再次进行录音。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder
**示例:**
```js
audioRecorder.on('reset', () => { //设置'reset'事件回调
console.log('audio recorder reset success');
});
audioRecorder.reset();
```
### on('prepare' | 'start' | 'pause' | 'resume' | 'stop' | 'release' | 'reset')
on(type: 'prepare' | 'start' | 'pause' | 'resume' | 'stop' | 'release' | 'reset', callback: () => void): void
开始订阅音频录制事件。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 录制事件回调类型,支持的事件包括:'prepare' \| 'start' \| 'pause' \| ’resume‘ \| 'stop' \| 'release' \| 'reset'。
- 'prepare' :完成[prepare](#audiorecorder_prepare)调用,音频录制参数设置完成,触发该事件。
- 'start' :完成[start](#audiorecorder_start)调用,音频录制开始,触发该事件。
- 'pause': 完成[pause](#audiorecorder_pause)调用,音频暂停录制,触发该事件。
- 'resume': 完成[resume](#audiorecorder_resume)调用,音频恢复录制,触发该事件。
- 'stop' :完成[stop](#audiorecorder_stop)调用,音频停止录制,触发该事件。
- 'release' :完成[release](#audiorecorder_release)调用,音频释放录制资源,触发该事件。
- 'reset':完成[reset](#audiorecorder_reset)调用,音频重置为初始状态,触发该事件。 |
| callback | ()=>void | 是 | 录制事件回调方法。 |
**示例:**
```js
let audiorecorder = media.createAudioRecorder(); // 创建一个音频录制实例
let audioRecorderConfig = {
audioEncoder : media.AudioEncoder.AAC_LC, ,
audioEncodeBitRate : 22050,
audioSampleRate : 22050,
numberOfChannels : 2,
format : media.AudioOutputFormat.AAC_ADTS,
uri : 'fd://xx', // 文件需先由调用者创建,并给予适当的权限
location : { latitude : 30, longitude : 130},
}
audioRecorder.on('error', (error) => { // 设置'error'事件回调
console.info(`audio error called, errName is ${error.name}`);
console.info(`audio error called, errCode is ${error.code}`);
console.info(`audio error called, errMessage is ${error.message}`);
});
audioRecorder.on('prepare', () => { // 设置'prepare'事件回调
console.log('prepare success');
audioRecorder.start(); // 开始录制,并触发'start'事件回调
});
audioRecorder.on('start', () => { // 设置'start'事件回调
console.log('audio recorder start success');
});
audioRecorder.on('pause', () => { // 设置'pause'事件回调
console.log('audio recorder pause success');
});
audioRecorder.on('resume', () => { // 设置'resume'事件回调
console.log('audio recorder resume success');
});
audioRecorder.on('stop', () => { // 设置'stop'事件回调
console.log('audio recorder stop success');
});
audioRecorder.on('release', () => { // 设置'release'事件回调
console.log('audio recorder release success');
});
audioRecorder.on('reset', () => { // 设置'reset'事件回调
console.log('audio recorder reset success');
});
audioRecorder.prepare(audioRecorderConfig) // 设置录制参数 ,并触发'prepare'事件回调
```
### on('error')
on(type: 'error', callback: ErrorCallback): void
开始订阅音频录制错误事件。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 录制错误事件回调类型'error'。
- 'error':音频录制过程中发生错误,触发该事件。 |
| callback | ErrorCallback | 是 | 录制错误事件回调方法。 |
**示例:**
```js
audioRecorder.on('error', (error) => { // 设置'error'事件回调
console.info(`audio error called, errName is ${error.name}`); // 打印错误类型名称
console.info(`audio error called, errCode is ${error.code}`); // 打印错误码
console.info(`audio error called, errMessage is ${error.message}`); // 打印错误类型详细描述
});
audioRecorder.prepare(); // prepare不设置参数,触发'error'事件
```
## AudioRecorderConfig
表示音频的录音配置。
| 名称 | 参数类型 | 必填 | 说明 |
| --------------------- | --------------------------------------- | ---- | ------------------------------------------------------------ |
| audioEncoder | [AudioEncoder](#audioencoder) | 否 | 音频编码格式,默认设置为AAC_LC。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder |
| audioEncodeBitRate | number | 否 | 音频编码比特率,默认值为48000。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder |
| audioSampleRate | number | 否 | 音频采集采样率,默认值为48000。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder |
| numberOfChannels | number | 否 | 音频采集声道数,默认值为2。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder |
| format | [AudioOutputFormat](#audiooutputformat) | 否 | 音量输出封装格式,默认设置为MPEG_4。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder |
| location8+ | [Location](#location8) | 否 | 音频采集的地理位置。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder |
| uri | string | 是 | 视频输出URI:fd://xx (fd number)
![zh-cn_image_0000001164217678](figures/zh-cn_image_url.png)
文件需要由调用者创建,并赋予适当的权限。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder |
## AudioEncoder
表示音频编码格式的枚举。
| 名称 | 默认值 | 说明 |
| ------- | ------ | ------------------------------------------------------------ |
| DEFAULT | 0 | Default audio encoding format is AMR_NB。
本接口在OpenHarmony 3.1 Release版本仅为接口定义,暂不支持使用。接口将在OpenHarmony 3.1 MR版本中提供使用支持。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder |
| AMR_NB | 1 | AMR-NB(Adaptive Multi Rate-Narrow Band Speech Codec) 编码格式。
本接口在OpenHarmony 3.1 Release版本仅为接口定义,暂不支持使用。接口将在OpenHarmony 3.1 MR版本中提供使用支持。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder |
| AMR_WB | 2 | AMR-WB(Adaptive Multi Rate-Wide Band Speech Codec) 编码格式。
本接口在OpenHarmony 3.1 Release版本仅为接口定义,暂不支持使用。接口将在OpenHarmony 3.1 MR版本中提供使用支持。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder |
| AAC_LC | 3 | AAC-LC(Advanced Audio Coding Low Complexity)编码格式。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder |
| HE_AAC | 4 | HE_AAC(High-Efficiency Advanced Audio Coding)编码格式。
本接口在OpenHarmony 3.1 Release版本仅为接口定义,暂不支持使用。接口将在OpenHarmony 3.1 MR版本中提供使用支持。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder |
## AudioOutputFormat
表示音频封装格式的枚举。
| 名称 | 默认值 | 说明 |
| -------- | ------ | ------------------------------------------------------------ |
| DEFAULT | 0 | 默认封装格式为MPEG-4。
本接口在OpenHarmony 3.1 Release版本仅为接口定义,暂不支持使用。接口将在OpenHarmony 3.1 MR版本中提供使用支持。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder |
| MPEG_4 | 2 | 封装为MPEG-4格式。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder |
| AMR_NB | 3 | 封装为AMR_NB格式。
本接口在OpenHarmony 3.1 Release版本仅为接口定义,暂不支持使用。接口将在OpenHarmony 3.1 MR版本中提供使用支持。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder |
| AMR_WB | 4 | 封装为AMR_WB格式。
本接口在OpenHarmony 3.1 Release版本仅为接口定义,暂不支持使用。接口将在OpenHarmony 3.1 MR版本中提供使用支持。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder |
| AAC_ADTS | 6 | 封装为ADTS(Audio Data Transport Stream)格式,是AAC音频的传输流格式。
**系统能力:** SystemCapability.Multimedia.Media.AudioRecorder |
## VideoRecorder8+
视频录制管理类,用于录制视频媒体。在调用VideoRecorder的方法前,需要先通过[createVideoRecorder()](#media.createvideorecorder8)构建一个[VideoRecorder](#videorecorder8)实例。
视频录制demo可参考:[视频录制开发指导](../../media/video-recorder.md)
### 属性
| 名称 | 类型 | 可读 | 可写 | 说明 |
| ------------------ | ------------------------------------- | ---- | ---- | ---------------- |
| state8+ | [VideoRecordState](#videorecordstate) | 是 | 否 | 视频录制的状态。 |
### prepare8+
prepare(config: VideoRecorderConfig, callback: AsyncCallback\): void;
异步方式进行视频录制的参数设置。通过注册回调函数获取返回值。
**需要权限:** ohos.permission.MICROPHONE ohos.permission.CAMERA
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------------------------------------- | ---- | ----------------------------------- |
| config | [VideoRecorderConfig](#videorecorderconfig) | 是 | 配置视频录制的相关参数。 |
| callback | AsyncCallback\ | 是 | 异步视频录制prepare方法的回调方法。 |
**示例:**
```js
let videoProfile = {
audioBitrate : 48000,
audioChannels : 2,
audioCodec : 'audio/mp4a-latm',
audioSampleRate : 48000,
fileFormat : 'mp4',
videoBitrate : 48000,
videoCodec : 'video/mp4v-es',
videoFrameWidth : 640,
videoFrameHeight : 480,
videoFrameRate : 30
}
let videoConfig = {
audioSourceType : 1,
videoSourceType : 0,
profile : videoProfile,
url : 'fd://xx', // 文件需先由调用者创建,并给予适当的权限
orientationHint : 0,
location : { latitude : 30, longitude : 130 },
}
// asyncallback
let videoRecorder = null;
let events = require('events');
let eventEmitter = new events.EventEmitter();
eventEmitter.on('prepare', () => {
videoRecorder.prepare(videoConfig, (err) => {
if (typeof (err) == 'undefined') {
console.info('prepare success');
} else {
console.info('prepare failed and error is ' + err.message);
}
});
});
media.createVideoRecorder((err, recorder) => {
if (typeof (err) == 'undefined' && typeof (recorder) != 'undefined') {
videoRecorder = recorder;
console.info('createVideoRecorder success');
eventEmitter.emit('prepare'); // prepare事件触发
} else {
console.info('createVideoRecorder failed and error is ' + err.message);
}
});
```
### prepare8+
prepare(config: VideoRecorderConfig): Promise\;
异步方式进行视频录制的参数设置。通过Promise获取返回值。
**需要权限:** ohos.permission.MICROPHONE ohos.permission.CAMERA
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| ------ | ------------------------------------------- | ---- | ------------------------ |
| config | [VideoRecorderConfig](#videorecorderconfig) | 是 | 配置视频录制的相关参数。 |
**返回值:**
| 类型 | 说明 |
| -------------- | ---------------------------------------- |
| Promise\ | 异步视频录制prepare方法的Promise返回值。 |
**示例:**
```js
let videoProfile = {
audioBitrate : 48000,
audioChannels : 2,
audioCodec : 'audio/mp4a-latm',
audioSampleRate : 48000,
fileFormat : 'mp4',
videoBitrate : 48000,
videoCodec : 'video/mp4v-es',
videoFrameWidth : 640,
videoFrameHeight : 480,
videoFrameRate : 30
}
let videoConfig = {
audioSourceType : 1,
videoSourceType : 0,
profile : videoProfile,
url : 'fd://xx', // 文件需先由调用者创建,并给予适当的权限
orientationHint : 0,
location : { latitude : 30, longitude : 130 },
}
// promise
let videoRecorder = null;
await media.createVideoRecorder().then((recorder) => {
if (typeof (recorder) != 'undefined') {
videoRecorder = recorder;
console.info('createVideoRecorder success');
} else {
console.info('createVideoRecorder failed');
}
}, (err) => {
console.info('error hanppend message is ' + err.message);
}).catch((err) => {
console.info('catch err error message is ' + err.message);
});
await videoRecorder.prepare(videoConfig).then(() => {
console.info('prepare success');
}, (err) => {
console.info('prepare failed and error is ' + err.message);
}).catch((err) => {
console.info('prepare failed and catch error is ' + err.message);
});
```
### getInputSurface8+
getInputSurface(callback: AsyncCallback\): void;
异步方式获得录制需要的surface。此surface提供给调用者,调用者从此surface中获取surfaceBuffer,填入相应的数据。
应当注意,填入的视频数据需要携带时间戳(单位ns),buffersize。时间戳的起始时间请以系统启动时间为基准。
只能在[prepare()](#videorecorder_prepare1)接口调用后调用。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ---------------------- | ---- | --------------------------- |
| callback | AsyncCallback\ | 是 | 异步获得surface的回调方法。 |
**示例:**
```js
// asyncallback
let surfaceID = null; // 传递给外界的surfaceID
videoRecorder.getInputSurface((err, surfaceId) => {
if (typeof (err) == 'undefined') {
console.info('getInputSurface success');
surfaceID = surfaceId;
} else {
console.info('getInputSurface failed and error is ' + err.message);
}
});
```
### getInputSurface8+
getInputSurface(): Promise\;
异步方式获得录制需要的surface。此surface提供给调用者,调用者从此surface中获取surfaceBuffer,填入相应的数据。
应当注意,填入的视频数据需要携带时间戳(单位ns),buffersize。时间戳的起始时间请以系统启动时间为基准。
只能在[prepare()](#videorecorder_prepare1)接口调用后调用。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
**返回值:**
| 类型 | 说明 |
| ---------------- | -------------------------------- |
| Promise\ | 异步获得surface的Promise返回值。 |
**示例:**
```js
// promise
let surfaceID = null; // 传递给外界的surfaceID
await videoRecorder.getInputSurface().then((surfaceId) => {
console.info('getInputSurface success');
surfaceID = surfaceId;
}, (err) => {
console.info('getInputSurface failed and error is ' + err.message);
}).catch((err) => {
console.info('getInputSurface failed and catch error is ' + err.message);
});
```
### start8+
start(callback: AsyncCallback\): void;
异步方式开始视频录制。通过注册回调函数获取返回值。
在[prepare()](#videorecorder_prepare1)和[getInputSurface()](#getinputsurface8)后调用,需要依赖数据源先给surface传递数据。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------- | ---- | ---------------------------- |
| callback | AsyncCallback\ | 是 | 异步开始视频录制的回调方法。 |
**示例:**
```js
// asyncallback
videoRecorder.start((err) => {
if (typeof (err) == 'undefined') {
console.info('start videorecorder success');
} else {
console.info('start videorecorder failed and error is ' + err.message);
}
});
```
### start8+
start(): Promise\;
异步方式开始视频录制。通过Promise获取返回值。
在[prepare()](#videorecorder_prepare1)和[getInputSurface()](#getinputsurface8)后调用,需要依赖数据源先给surface传递数据。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
**返回值:**
| 类型 | 说明 |
| -------------- | ------------------------------------- |
| Promise\ | 异步开始视频录制方法的Promise返回值。 |
**示例:**
```js
// promise
await videoRecorder.start().then(() => {
console.info('start videorecorder success');
}, (err) => {
console.info('start videorecorder failed and error is ' + err.message);
}).catch((err) => {
console.info('start videorecorder failed and catch error is ' + err.message);
});
```
### pause8+
pause(callback: AsyncCallback\): void;
异步方式暂停视频录制。通过注册回调函数获取返回值。
在[start()](#videorecorder_start1)后调用。可以通过调用[resume()](#videorecorder_resume1)接口来恢复录制。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------- | ---- | ---------------------------- |
| callback | AsyncCallback\ | 是 | 异步暂停视频录制的回调方法。 |
**示例:**
```js
// asyncallback
videoRecorder.pause((err) => {
if (typeof (err) == 'undefined') {
console.info('pause videorecorder success');
} else {
console.info('pause videorecorder failed and error is ' + err.message);
}
});
```
### pause8+
pause(): Promise\;
异步方式暂停视频录制。通过Promise获取返回值。
在[start()](#videorecorder_start1)后调用。可以通过调用[resume()](#videorecorder_resume1)接口来恢复录制。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
**返回值:**
| 类型 | 说明 |
| -------------- | ------------------------------------- |
| Promise\ | 异步暂停视频录制方法的Promise返回值。 |
**示例:**
```js
// promise
await videoRecorder.pause().then(() => {
console.info('pause videorecorder success');
}, (err) => {
console.info('pause videorecorder failed and error is ' + err.message);
}).catch((err) => {
console.info('pause videorecorder failed and catch error is ' + err.message);
});
```
### resume8+
resume(callback: AsyncCallback\): void;
异步方式恢复视频录制。通过注册回调函数获取返回值。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------- | ---- | ---------------------------- |
| callback | AsyncCallback\ | 是 | 异步恢复视频录制的回调方法。 |
**示例:**
```js
// asyncallback
videoRecorder.resume((err) => {
if (typeof (err) == 'undefined') {
console.info('resume videorecorder success');
} else {
console.info('resume videorecorder failed and error is ' + err.message);
}
});
```
### resume8+
resume(): Promise\;
异步方式恢复视频录制。通过Promise获取返回值。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
**返回值:**
| 类型 | 说明 |
| -------------- | ------------------------------------- |
| Promise\ | 异步恢复视频录制方法的Promise返回值。 |
**示例:**
```js
// promise
await videoRecorder.resume().then(() => {
console.info('resume videorecorder success');
}, (err) => {
console.info('resume videorecorder failed and error is ' + err.message);
}).catch((err) => {
console.info('resume videorecorder failed and catch error is ' + err.message);
});
```
### stop8+
stop(callback: AsyncCallback\): void;
异步方式停止视频录制。通过注册回调函数获取返回值。
需要重新调用[prepare()](#videorecorder_prepare1)和[getInputSurface()](#getinputsurface8)接口才能重新录制。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------- | ---- | ---------------------------- |
| callback | AsyncCallback\ | 是 | 异步停止视频录制的回调方法。 |
**示例:**
```js
// asyncallback
videoRecorder.stop((err) => {
if (typeof (err) == 'undefined') {
console.info('stop videorecorder success');
} else {
console.info('stop videorecorder failed and error is ' + err.message);
}
});
```
### stop8+
stop(): Promise\;
异步方式停止视频录制。通过Promise获取返回值。
需要重新调用[prepare()](#videorecorder_prepare1)和[getInputSurface()](#getinputsurface8)接口才能重新录制。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
**返回值:**
| 类型 | 说明 |
| -------------- | ------------------------------------- |
| Promise\ | 异步停止视频录制方法的Promise返回值。 |
**示例:**
```js
// promise
await videoRecorder.stop().then(() => {
console.info('stop videorecorder success');
}, (err) => {
console.info('stop videorecorder failed and error is ' + err.message);
}).catch((err) => {
console.info('stop videorecorder failed and catch error is ' + err.message);
});
```
### release8+
release(callback: AsyncCallback\): void;
异步方式释放视频录制资源。通过注册回调函数获取返回值。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------- | ---- | -------------------------------- |
| callback | AsyncCallback\ | 是 | 异步释放视频录制资源的回调方法。 |
**示例:**
```js
// asyncallback
videoRecorder.release((err) => {
if (typeof (err) == 'undefined') {
console.info('release videorecorder success');
} else {
console.info('release videorecorder failed and error is ' + err.message);
}
});
```
### release8+
release(): Promise\;
异步方式释放视频录制资源。通过Promise获取返回值。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
**返回值:**
| 类型 | 说明 |
| -------------- | ----------------------------------------- |
| Promise\ | 异步释放视频录制资源方法的Promise返回值。 |
**示例:**
```js
// promise
await videoRecorder.release().then(() => {
console.info('release videorecorder success');
}, (err) => {
console.info('release videorecorder failed and error is ' + err.message);
}).catch((err) => {
console.info('release videorecorder failed and catch error is ' + err.message);
});
```
### reset8+
reset(callback: AsyncCallback\): void;
异步方式重置视频录制。通过注册回调函数获取返回值。
需要重新调用[prepare()](#videorecorder_prepare1)和[getInputSurface()](#getinputsurface8)接口才能重新录制。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------------------- | ---- | ---------------------------- |
| callback | AsyncCallback\ | 是 | 异步重置视频录制的回调方法。 |
**示例:**
```js
// asyncallback
videoRecorder.reset((err) => {
if (typeof (err) == 'undefined') {
console.info('reset videorecorder success');
} else {
console.info('reset videorecorder failed and error is ' + err.message);
}
});
```
### reset8+
reset(): Promise\;
异步方式重置视频录制。通过Promise获取返回值。
需要重新调用[prepare()](#videorecorder_prepare1)和[getInputSurface()](#getinputsurface8)接口才能重新录制。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
**返回值:**
| 类型 | 说明 |
| -------------- | ------------------------------------- |
| Promise\ | 异步重置视频录制方法的Promise返回值。 |
**示例:**
```js
// promise
await videoRecorder.reset().then(() => {
console.info('reset videorecorder success');
}, (err) => {
console.info('reset videorecorder failed and error is ' + err.message);
}).catch((err) => {
console.info('reset videorecorder failed and catch error is ' + err.message);
});
```
### on('error')8+
on(type: 'error', callback: ErrorCallback): void
开始订阅视频录制错误事件。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder
**参数:**
| 参数名 | 类型 | 必填 | 说明 |
| -------- | ------------- | ---- | ------------------------------------------------------------ |
| type | string | 是 | 录制错误事件回调类型'error'。
- 'error':音频录制过程中发生错误,触发该事件。 |
| callback | ErrorCallback | 是 | 录制错误事件回调方法。 |
**示例:**
```js
videoRecorder.on('error', (error) => { // 设置'error'事件回调
console.info(`audio error called, errName is ${error.name}`); // 打印错误类型名称
console.info(`audio error called, errCode is ${error.code}`); // 打印错误码
console.info(`audio error called, errMessage is ${error.message}`); // 打印错误类型详细描述
});
// 当获取videoRecordState接口出错时通过此订阅事件上报
```
## VideoRecordState8+
视频录制的状态机。可通过state属性获取当前状态。
| 名称 | 类型 | 描述 |
| -------- | ------ | ------------------------------------------------------------ |
| idle | string | 视频录制空闲。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
| prepared | string | 视频录制参数设置完成。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
| playing | string | 视频正在录制。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
| paused | string | 视频暂停录制。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
| stopped | string | 视频录制停止。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
| error | string | 错误状态。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
## VideoRecorderConfig8+
表示视频录制的参数设置。
| 名称 | 参数类型 | 必填 | 说明 |
| --------------- | ---------------------------------------------------------- | ---- | ------------------------------------------------------------ |
| audioSourceType | [AudioSourceType](#audiosourcetype8+) | 是 | 视频录制的音频源类型。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
| videoSourceType | [VideoSourceType](#videosourcetype8+) | 是 | 视频录制的视频源类型。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
| profile | [VideoRecorderProfile](#videorecorderprofile8+) | 是 | 视频录制的profile。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
| orientationHint | number | 否 | 录制视频的旋转角度。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
| location | [Location](#location8) | 否 | 录制视频的地理位置。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
| url | string | 是 | 视频输出URL:fd://xx (fd number)
![zh-cn_image_0000001164217678](figures/zh-cn_image_url.png)
文件需要由调用者创建,并赋予适当的权限。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
## AudioSourceType8+
表示视频录制中音频源类型的枚举。
| 名称 | 值 | 说明 |
| ------------------------- | ---- | ------------------------------------------------------------ |
| AUDIO_SOURCE_TYPE_DEFAULT | 0 | 默认的音频输入源类型。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
| AUDIO_SOURCE_TYPE_MIC | 1 | 表示MIC的音频输入源。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
## VideoSourceType8+
表示视频录制中视频源类型的枚举。
| 名称 | 值 | 说明 |
| ----------------------------- | ---- | ------------------------------------------------------------ |
| VIDEO_SOURCE_TYPE_SURFACE_YUV | 0 | 输入surface中携带的是raw data。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
| VIDEO_SOURCE_TYPE_SURFACE_ES | 1 | 输入surface中携带的是ES data。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
## VideoRecorderProfile8+
视频录制的配置文件。
| 名称 | 参数类型 | 必填 | 说明 |
| ---------------- | -------------------------------------------- | ---- | ------------------------------------------------------------ |
| audioBitrate | number | 是 | 音频编码比特率。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
| audioChannels | number | 是 | 音频采集声道数。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
| audioCodec | [CodecMimeType](#CodecMimeType8) | 是 | 音频编码格式。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
| audioSampleRate | number | 是 | 音频采样率。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
| fileFormat | [ContainerFormatType](#containerformattype8) | 是 | 文件的容器格式。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
| videoCodec | [CodecMimeType](#CodecMimeType8) | 是 | 视频编码格式。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
| videoFrameWidth | number | 是 | 录制视频帧的宽。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
| videoFrameHeight | number | 是 | 录制视频帧的高。
**系统能力:** SystemCapability.Multimedia.Media.VideoRecorder |
## ContainerFormatType8+
表示容器格式类型的枚举,缩写为CFT。
| 名称 | 值 | 说明 |
| ----------- | ----- | ------------------------------------------------------------ |
| CFT_MPEG_4 | "mp4" | 视频的容器格式,MP4。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| CFT_MPEG_4A | "m4a" | 音频的容器格式,M4A。
**系统能力:** SystemCapability.Multimedia.Media.Core |
## Location8+
视频录制的地理位置。
| 名称 | 参数类型 | 必填 | 说明 |
| --------- | -------- | ---- | ------------------------------------------------------------ |
| latitude | number | 是 | 地理位置的纬度。
**系统能力:** SystemCapability.Multimedia.Media.Core |
| longitude | number | 是 | 地理位置的经度。
**系统能力:** SystemCapability.Multimedia.Media.Core |