@ohos.multimedia.media (Media) (System API)

The multimedia subsystem provides a set of simple and easy-to-use APIs for you to access the system and use media resources.

This subsystem offers the following audio and video services:

• Obtaining video thumbnails (AVImageGenerator¹¹⁺)

NOTE

• The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.
• This topic describes only system APIs provided by the module. For details about its public APIs, see @ohos.multimedia.media (Media).

Modules to Import

import media from '@ohos.multimedia.media';

media.createAVImageGenerator¹¹⁺

createAVImageGenerator(callback: AsyncCallback<AVImageGenerator>): void

Creates an AVImageGenerator instance. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.Media.AVImageGenerator

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';

let avImageGenerator: media.AVImageGenerator;
media.createAVImageGenerator((error: BusinessError, generator: media.AVImageGenerator) => {
  if (generator != null) {
    avImageGenerator = generator;
    console.info('createAVImageGenerator success');
  } else {
    console.error(`createAVImageGenerator fail, error message:${error.message}`);
  }
});

media.createAVImageGenerator¹¹⁺

createAVImageGenerator(): Promise<AVImageGenerator>

Creates an AVImageGenerator instance. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Media.AVImageGenerator

System API: This is a system API.

Return value

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';

let avImageGenerator: media.AVImageGenerator;
media.createAVImageGenerator().then((generator: media.AVImageGenerator) => {
  if (generator != null) {
    avImageGenerator = generator;
    console.info('createAVImageGenerator success');
  } else {
    console.error('createAVImageGenerator fail');
  }
}).catch((error: BusinessError) => {
  console.error(`AVImageGenerator catchCallback, error message:${error.message}`);
});

media.createVideoRecorder⁹⁺

createVideoRecorder(callback: AsyncCallback<VideoRecorder>): void

Creates a VideoRecorder instance. This API uses an asynchronous callback to return the result.

Only one VideoRecorder instance can be created per device.

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';

let videoRecorder: media.VideoRecorder;
media.createVideoRecorder((error: BusinessError, video: media.VideoRecorder) => {
  if (video != null) {
    videoRecorder = video;
    console.info('video createVideoRecorder success');
  } else {
    console.error(`video createVideoRecorder fail, error message:${error.message}`);
  }
});

media.createVideoRecorder⁹⁺

createVideoRecorder(): Promise<VideoRecorder>

Creates a VideoRecorder instance. This API uses a promise to return the result.

Only one VideoRecorder instance can be created per device.

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.

Return value

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';

let videoRecorder: media.VideoRecorder;
media.createVideoRecorder().then((video: media.VideoRecorder) => {
  if (video != null) {
    videoRecorder = video;
    console.info('video createVideoRecorder success');
  } else {
    console.error('video createVideoRecorder fail');
  }
}).catch((error: BusinessError) => {
  console.error(`video catchCallback, error message:${error.message}`);
});

AVImageGenerator¹¹⁺

Provides APIs to obtain a thumbnail from a video. Before calling any API of AVImageGenerator, you must use createAVImageGenerator() to create an AVImageGenerator instance.

For details about the demo for obtaining video thumbnails, see Obtaining Video Thumbnails.

Attributes

System capability: SystemCapability.Multimedia.Media.AVImageGenerator

System API: This is a system API.

fetchFrameByTime¹¹⁺

fetchFrameByTime(timeUs: number, options: AVImageQueryOptions, param: PixelMapParams, callback: AsyncCallback<image.PixelMap>): void

Obtains a video thumbnail. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.Media.AVImageGenerator

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';
import media from '@ohos.multimedia.media';
import image from '@ohos.multimedia.image';

let avImageGenerator: media.AVImageGenerator | undefined = undefined;
let pixel_map : image.PixelMap | undefined = undefined;

// Initialize input parameters.
let timeUs: number = 0

let queryOption: media.AVImageQueryOptions = media.AVImageQueryOptions.AV_IMAGE_QUERY_NEXT_SYNC

let param: media.PixelMapParams = {
  width : 300,
  height : 300,
  colorFormat : media.PixelFormat.RGB_565
}

// Obtain the thumbnail.
media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => {
  if(generator != null){
    avImageGenerator = generator;
    console.error(`createAVImageGenerator success`);
    avImageGenerator.fetchFrameByTime(timeUs, queryOption, param, (error: BusinessError, pixelMap) => {
      if (error) {
        console.error(`fetchFrameByTime callback failed, err = ${JSON.stringify(error)}`)
        return
      }
      pixel_map = pixelMap;
    });
  } else {
    console.error(`createAVImageGenerator fail, error message:${err.messag-e}`);
  };
});

fetchFrameByTime¹¹⁺

fetchFrameByTime(timeUs: number, options: AVImageQueryOptions, param: PixelMapParams): Promise<image.PixelMap>

Obtains a video thumbnail. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Media.AVImageGenerator

System API: This is a system API.

Parameters

Return value

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';
import media from '@ohos.multimedia.media';
import image from '@ohos.multimedia.image';

let avImageGenerator: media.AVImageGenerator | undefined = undefined;
let pixel_map : image.PixelMap | undefined = undefined;

// Initialize input parameters.
let timeUs: number = 0

let queryOption: media.AVImageQueryOptions = media.AVImageQueryOptions.AV_IMAGE_QUERY_NEXT_SYNC

let param: media.PixelMapParams = {
  width : 300,
  height : 300,
  colorFormat : media.PixelFormat.RGB_565
}

// Obtain the thumbnail.
media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => {
  if(generator != null){
    avImageGenerator = generator;
    console.error(`createAVImageGenerator success`);
    avImageGenerator.fetchFrameByTime(timeUs, queryOption, param).then((pixelMap: image.PixelMap) => {
      pixel_map = pixelMap;
    }).catch((error: BusinessError) => {
      console.error(`fetchFrameByTime catchCallback, error message:${error.message}`);
    });
  } else {
    console.error(`createAVImageGenerator fail, error message:${err.message}`);
  };
});

release¹¹⁺

release(callback: AsyncCallback<void>): void

Releases this AVMetadataExtractor instance. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.Media.AVImageGenerator

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';
import media from '@ohos.multimedia.media';

let avImageGenerator: media.AVImageGenerator | undefined = undefined;

// Release the instance.
media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => {
  if(generator != null){
    avImageGenerator = generator;
    console.error(`createAVImageGenerator success`);
    avImageGenerator.release((error: BusinessError) => {
      if (error) {
        console.error(`release failed, err = ${JSON.stringify(error)}`);
        return;
      }
      console.info(`release success.`);
    });
  } else {
    console.error(`createAVImageGenerator fail, error message:${err.message}`);
  };
});

release¹¹⁺

release(): Promise<void>

Releases this AVMetadataExtractor instance. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Media.AVImageGenerator

System API: This is a system API.

Return value

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';
import media from '@ohos.multimedia.media';

let avImageGenerator: media.AVImageGenerator | undefined = undefined;

// Release the instance.
media.createAVImageGenerator((err: BusinessError, generator: media.AVImageGenerator) => {
  if(generator != null){
    avImageGenerator = generator;
    console.error(`creatAVImageGenerator success`);
    avImageGenerator.release().then(() => {
      console.info(`release success.`);
    }).catch((error: BusinessError) => {
      console.error(`release catchCallback, error message:${error.message}`);
    });
  } else {
    console.error(`creatAVImageGenerator fail, error message:${err.message}`);
  };
});

AVImageQueryOptions¹¹⁺

Enumerates the relationship between the video frame and the time at which the video thumbnail is obtained.

The time passed in for obtaining the thumbnail may be different from the time of the video frame for which the thumbnail is actually obtained. Therefore, you need to specify their relationship.

System capability: SystemCapability.Multimedia.Media.AVImageGenerator

System API: This is a system API.

PixelMapParams¹¹⁺

Defines the format parameters of the video thumbnail to be obtained.

System capability: SystemCapability.Multimedia.Media.AVImageGenerator

System API: This is a system API.

PixelFormat¹¹⁺

Enumerates the color formats supported by the video thumbnail.

System capability: SystemCapability.Multimedia.Media.AVImageGenerator

System API: This is a system API.

VideoRecorder⁹⁺

NOTE This class is deprecated after AVRecorder⁹⁺ is released. You are advised to use AVRecorder instead.

Implements video recording. Before calling any API in the VideoRecorder class, you must use createVideoRecorder() to create a VideoRecorder instance.

Attributes

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.

prepare⁹⁺

prepare(config: VideoRecorderConfig, callback: AsyncCallback<void>): void

Sets video recording parameters. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.MICROPHONE

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';

// Configure the parameters based on those supported by the hardware device.
let videoProfile: media.VideoRecorderProfile = {
  audioBitrate : 48000,
  audioChannels : 2,
  audioCodec : media.CodecMimeType.AUDIO_AAC,
  audioSampleRate : 48000,
  fileFormat : media.ContainerFormatType.CFT_MPEG_4,
  videoBitrate : 2000000,
  videoCodec : media.CodecMimeType.VIDEO_AVC,
  videoFrameWidth : 640,
  videoFrameHeight : 480,
  videoFrameRate : 30
}

let videoConfig: media.VideoRecorderConfig = {
  audioSourceType : media.AudioSourceType.AUDIO_SOURCE_TYPE_MIC,
  videoSourceType : media.VideoSourceType.VIDEO_SOURCE_TYPE_SURFACE_YUV,
  profile : videoProfile,
  url : 'fd://xx', // The file must be created by the caller and granted with proper permissions.
  rotation : 0,
  location : { latitude : 30, longitude : 130 }
}

// asyncallback
videoRecorder.prepare(videoConfig, (err: BusinessError) => {
  if (err == null) {
    console.info('prepare success');
  } else {
    console.error('prepare failed and error is ' + err.message);
  }
})

prepare⁹⁺

prepare(config: VideoRecorderConfig): Promise<void>

Sets video recording parameters. This API uses a promise to return the result.

Required permissions: ohos.permission.MICROPHONE

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.

Parameters

Return value

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';

// Configure the parameters based on those supported by the hardware device.
let videoProfile: media.VideoRecorderProfile = {
  audioBitrate : 48000,
  audioChannels : 2,
  audioCodec : media.CodecMimeType.AUDIO_AAC,
  audioSampleRate : 48000,
  fileFormat : media.ContainerFormatType.CFT_MPEG_4,
  videoBitrate : 2000000,
  videoCodec : media.CodecMimeType.VIDEO_AVC,
  videoFrameWidth : 640,
  videoFrameHeight : 480,
  videoFrameRate : 30
}

let videoConfig: media.VideoRecorderConfig = {
  audioSourceType : media.AudioSourceType.AUDIO_SOURCE_TYPE_MIC,
  videoSourceType : media.VideoSourceType.VIDEO_SOURCE_TYPE_SURFACE_YUV,
  profile : videoProfile,
  url : 'fd://xx', // The file must be created by the caller and granted with proper permissions.
  rotation : 0,
  location : { latitude : 30, longitude : 130 }
}

// promise
videoRecorder.prepare(videoConfig).then(() => {
  console.info('prepare success');
}).catch((err: BusinessError) => {
  console.error('prepare failed and catch error is ' + err.message);
});

getInputSurface⁹⁺

getInputSurface(callback: AsyncCallback<string>): void

Obtains the surface required for recording. This API uses an asynchronous callback to return the result. The caller obtains the surfaceBuffer from this surface and fills in the corresponding data.

Note that the video data must carry the timestamp (in ns) and buffer size, and the start time of the timestamp must be based on the system startup time.

This API can be called only after prepare() is called.

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';

// asyncallback
let surfaceID: string; // Surface ID passed to the external system.
videoRecorder.getInputSurface((err: BusinessError, surfaceId: string) => {
  if (err == null) {
    console.info('getInputSurface success');
    surfaceID = surfaceId;
  } else {
    console.error('getInputSurface failed and error is ' + err.message);
  }
});

getInputSurface⁹⁺

getInputSurface(): Promise<string>;

Obtains the surface required for recording. This API uses a promise to return the result. The caller obtains the surfaceBuffer from this surface and fills in the corresponding data.

Note that the video data must carry the timestamp (in ns) and buffer size, and the start time of the timestamp must be based on the system startup time.

This API can be called only after prepare() is called.

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.

Return value

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';

// promise
let surfaceID: string; // Surface ID passed to the external system.
videoRecorder.getInputSurface().then((surfaceId: string) => {
  console.info('getInputSurface success');
  surfaceID = surfaceId;
}).catch((err: BusinessError) => {
  console.error('getInputSurface failed and catch error is ' + err.message);
});

start⁹⁺

start(callback: AsyncCallback<void>): void

Starts recording. This API uses an asynchronous callback to return the result.

This API can be called only after prepare() and getInputSurface() are called, because the data source must pass data to the surface first.

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';

// asyncallback
videoRecorder.start((err: BusinessError) => {
  if (err == null) {
    console.info('start videorecorder success');
  } else {
    console.error('start videorecorder failed and error is ' + err.message);
  }
});

start⁹⁺

start(): Promise<void>

Starts recording. This API uses a promise to return the result.

This API can be called only after prepare() and getInputSurface() are called, because the data source must pass data to the surface first.

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.

Return value

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';

// promise
videoRecorder.start().then(() => {
  console.info('start videorecorder success');
}).catch((err: BusinessError) => {
  console.error('start videorecorder failed and catch error is ' + err.message);
});

pause⁹⁺

pause(callback: AsyncCallback<void>): void

Pauses recording. This API uses an asynchronous callback to return the result.

This API can be called only after start() is called. You can resume recording by calling resume().

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';

// asyncallback
videoRecorder.pause((err: BusinessError) => {
  if (err == null) {
    console.info('pause videorecorder success');
  } else {
    console.error('pause videorecorder failed and error is ' + err.message);
  }
});

pause⁹⁺

pause(): Promise<void>

Pauses recording. This API uses a promise to return the result.

This API can be called only after start() is called. You can resume recording by calling resume().

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.

Return value

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';

// promise
videoRecorder.pause().then(() => {
  console.info('pause videorecorder success');
}).catch((err: BusinessError) => {
  console.error('pause videorecorder failed and catch error is ' + err.message);
});

resume⁹⁺

resume(callback: AsyncCallback<void>): void

Resumes recording. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';

// asyncallback
videoRecorder.resume((err: BusinessError) => {
  if (err == null) {
    console.info('resume videorecorder success');
  } else {
    console.error('resume videorecorder failed and error is ' + err.message);
  }
});

resume⁹⁺

resume(): Promise<void>

Resumes recording. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.

Return value

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';

// promise
videoRecorder.resume().then(() => {
  console.info('resume videorecorder success');
}).catch((err: BusinessError) => {
  console.error('resume videorecorder failed and catch error is ' + err.message);
});

stop⁹⁺

stop(callback: AsyncCallback<void>): void

Stops recording. This API uses an asynchronous callback to return the result.

To start another recording, you must call prepare() and getInputSurface() again.

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';

// asyncallback
videoRecorder.stop((err: BusinessError) => {
  if (err == null) {
    console.info('stop videorecorder success');
  } else {
    console.error('stop videorecorder failed and error is ' + err.message);
  }
});

stop⁹⁺

stop(): Promise<void>

Stops recording. This API uses a promise to return the result.

To start another recording, you must call prepare() and getInputSurface() again.

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.

Return value

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';

// promise
videoRecorder.stop().then(() => {
  console.info('stop videorecorder success');
}).catch((err: BusinessError) => {
  console.error('stop videorecorder failed and catch error is ' + err.message);
});

release⁹⁺

release(callback: AsyncCallback<void>): void

Releases the video recording resources. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';

// asyncallback
videoRecorder.release((err: BusinessError) => {
  if (err == null) {
    console.info('release videorecorder success');
  } else {
    console.error('release videorecorder failed and error is ' + err.message);
  }
});

release⁹⁺

release(): Promise<void>

Releases the video recording resources. This API uses a promise to return the result.

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.

Return value

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';

// promise
videoRecorder.release().then(() => {
  console.info('release videorecorder success');
}).catch((err: BusinessError) => {
  console.error('release videorecorder failed and catch error is ' + err.message);
});

reset⁹⁺

reset(callback: AsyncCallback<void>): void

Resets video recording. This API uses an asynchronous callback to return the result.

To start another recording, you must call prepare() and getInputSurface() again.

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';

// asyncallback
videoRecorder.reset((err: BusinessError) => {
  if (err == null) {
    console.info('reset videorecorder success');
  } else {
    console.error('reset videorecorder failed and error is ' + err.message);
  }
});

reset⁹⁺

reset(): Promise<void>

Resets video recording. This API uses a promise to return the result.

To start another recording, you must call prepare() and getInputSurface() again.

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.

Return value

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';

// promise
videoRecorder.reset().then(() => {
  console.info('reset videorecorder success');
}).catch((err: BusinessError) => {
  console.error('reset videorecorder failed and catch error is ' + err.message);
});

on('error')⁹⁺

on(type: 'error', callback: ErrorCallback): void

Subscribes to video recording error events. After an error event is reported, you must handle the event and exit the recording.

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.

Parameters

Error codes

For details about the error codes, see Media Error Codes.

Example

import { BusinessError } from '@ohos.base';

// This event is reported when an error occurs during the retrieval of videoRecordState.
videoRecorder.on('error', (error: BusinessError) => { // Set the 'error' event callback.
  console.error(`audio error called, error: ${error}`);
})

VideoRecordState⁹⁺

Enumerates the video recording states. You can obtain the state through the state attribute.

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.

VideoRecorderConfig⁹⁺

Describes the video recording parameters.

The audioSourceType and videoSourceType parameters are used to distinguish video-only recording from audio and video recording. (For audio-only recording, use AVRecorder or AudioRecorder.) For video-only recording, set only videoSourceType. For audio and video recording, set both audioSourceType and videoSourceType.

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.

Name	Type	Mandatory	Description
audioSourceType	AudioSourceType	No	Type of the audio source for video recording. This parameter is mandatory for audio recording.
videoSourceType	VideoSourceType	Yes	Type of the video source for video recording.
profile	VideoRecorderProfile	Yes	Video recording profile.
rotation	number	No	Rotation angle of the recorded video. The value can only be 0 (default), 90, 180, or 270.
location	Location	No	Geographical location of the recorded video. By default, the geographical location information is not recorded.
url	string	Yes	Video output URL. Supported: fd://xx (fd number)

VideoRecorderProfile⁹⁺

Describes the video recording profile.

System capability: SystemCapability.Multimedia.Media.VideoRecorder

System API: This is a system API.