openharmony 鸿蒙 arkts-apis-media-f

2026-08-25 浏览 (1)

Functions

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.

Modules to Import

import { media } from '@kit.MediaKit';

media.createAVPlayer9+

createAVPlayer(callback: AsyncCallback<AVPlayer>): void

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

NOTE

  • You are advised to create a maximum of 16 AVPlayer instances for an application in both audio and video playback scenarios.
  • The actual number of instances that can be created may be different. It depends on the specifications of the device chip in use. For example, in the case of RK3568, you are advised to create a maximum of 6 AVPlayer instances for an application in audio and video playback scenarios.
  • Applications must properly manage AVPlayer instances according to their specific needs, creating and freeing them when necessary. Holding too many AVPlayer instances can lead to high memory usage, and in some cases, the system might terminate applications to free up resources.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Media.AVPlayer

Parameters

NameTypeMandatoryDescription
callbackAsyncCallback<AVPlayer>YesCallback used to return the result. If the operation is successful, an AVPlayer instance is returned; otherwise, null is returned. The instance can be used to play audio and video.

Error codes

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

IDError Message
5400101No memory. Return by callback.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let avPlayer: media.AVPlayer;
media.createAVPlayer((error: BusinessError, video: media.AVPlayer) => {
  if (video) {
    avPlayer = video;
    console.info('Succeeded in creating AVPlayer');
  } else {
    console.error(`Failed to create AVPlayer, error message:${error.message}`);
  }
});

media.createAVPlayer9+

createAVPlayer(): Promise<AVPlayer>

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

NOTE

  • You are advised to create a maximum of 16 AVPlayer instances for an application in both audio and video playback scenarios.
  • The actual number of instances that can be created may be different. It depends on the specifications of the device chip in use. For example, in the case of RK3568, you are advised to create a maximum of 6 AVPlayer instances for an application in audio and video playback scenarios.
  • Applications should reasonably use AVPlayer objects in accordance with actual service requirements, create them on demand, and release them in a timely manner. This avoids excessive memory consumption caused by holding too many AVPlayer instances, which may result in the system terminating the application.

Atomic service API: This API can be used in atomic services since API version 11.

System capability: SystemCapability.Multimedia.Media.AVPlayer

Return value

TypeDescription
Promise<AVPlayer>Promise used to return the result. If the operation is successful, an AVPlayer instance is returned for audio and video playback. Otherwise, null is returned.

Error codes

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

IDError Message
5400101No memory. Return by promise.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let avPlayer: media.AVPlayer;
media.createAVPlayer().then((video: media.AVPlayer) => {
  if (video) {
    avPlayer = video;
    console.info('Succeeded in creating AVPlayer');
  } else {
    console.error('Failed to create AVPlayer');
  }
}).catch((error: BusinessError) => {
  console.error(`Failed to create AVPlayer, error message:${error.message}`);
});

media.createAVRecorder9+

createAVRecorder(callback: AsyncCallback<AVRecorder>): void

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

NOTE

An application can create multiple AVRecorder instances. However, because the device shares a common audio channel, only one instance can record audio at a time. Any attempt to create the second instance for audio recording fails due to audio channel conflicts.

System capability: SystemCapability.Multimedia.Media.AVRecorder

Parameters

NameTypeMandatoryDescription
callbackAsyncCallback<AVRecorder>YesCallback function, which returns an AVRecorder instance for recording audio and video. Otherwise, null is returned.

Error codes

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

IDError Message
5400101No memory. Return by callback.

Example

import { BusinessError } from '@kit.BasicServicesKit';
let avRecorder: media.AVRecorder;

media.createAVRecorder((error: BusinessError, recorder: media.AVRecorder) => {
  if (recorder) {
    avRecorder = recorder;
    console.info('Succeeded in creating AVRecorder');
  } else {
    console.error(`Failed to create AVRecorder, error message:${error.message}`);
  }
});

media.createAVRecorder9+

createAVRecorder(): Promise<AVRecorder>

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

NOTE

An application can create multiple AVRecorder instances. However, because the device shares a common audio channel, only one instance can record audio at a time. Any attempt to create the second instance for audio recording fails due to audio channel conflicts.

Atomic service API: This API can be used in atomic services since API version 12.

System capability: SystemCapability.Multimedia.Media.AVRecorder

Return value

TypeDescription
Promise<AVRecorder>Promise used to return an AVRecorder instance, which can be used to record audio and video. Otherwise, null is returned.

Error codes

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

IDError Message
5400101No memory. Return by promise.

Example

import { BusinessError } from '@kit.BasicServicesKit';
let avRecorder: media.AVRecorder;
media.createAVRecorder().then((recorder: media.AVRecorder) => {
  if (recorder) {
    avRecorder = recorder;
    console.info('Succeeded in creating AVRecorder');
  } else {
    console.error('Failed to create AVRecorder');
  }
}).catch((error: BusinessError) => {
  console.error(`Failed to create AVRecorder, error message:${error.message}`);
});

media.createAVTranscoder12+

createAVTranscoder(): Promise<AVTranscoder>

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

NOTE

A maximum of 2 AVTranscoder instances can be created.

Atomic service API: This API can be used in atomic services since API version 22.

System capability: SystemCapability.Multimedia.Media.AVTranscoder

Return value

TypeDescription
Promise<AVTranscoder>Promise used to return the result. If the operation is successful, an AVTranscoder instance is returned; otherwise, null is returned. The instance can be used for video transcoding.

Error codes

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

IDError Message
5400101No memory. Return by promise.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let avTranscoder: media.AVTranscoder|undefined = undefined;
media.createAVTranscoder().then((transcoder: media.AVTranscoder) => {
  if (transcoder) {
    avTranscoder = transcoder;
    console.info('Succeeded in creating AVTranscoder');
  } else {
    console.error('Failed to create AVTranscoder');
  }
}).catch((error: BusinessError) => {
  console.error(`Failed to create AVTranscoder, error message:${error.message}`);
});

media.createAVMetadataExtractor11+

createAVMetadataExtractor(callback: AsyncCallback<AVMetadataExtractor>): void

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

System capability: SystemCapability.Multimedia.Media.AVMetadataExtractor

Parameters

NameTypeMandatoryDescription
callbackAsyncCallback<AVMetadataExtractor>YesCallback used to return the result. If the operation is successful, err is undefined and data is the AVMetadataExtractor instance created; otherwise, err is an error object.

Error codes

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

IDError Message
5400101No memory. Returned by callback.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let avMetadataExtractor: media.AVMetadataExtractor;
media.createAVMetadataExtractor((error: BusinessError, extractor: media.AVMetadataExtractor) => {
  if (extractor) {
    avMetadataExtractor = extractor;
    console.info('Succeeded in creating AVMetadataExtractor');
  } else {
    console.error(`Failed to create AVMetadataExtractor, error message:${error.message}`);
  }
});

media.createAVMetadataExtractor11+

createAVMetadataExtractor(): Promise<AVMetadataExtractor>

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

System capability: SystemCapability.Multimedia.Media.AVMetadataExtractor

Return value

TypeDescription
Promise<AVMetadataExtractor>Promise used to return the AVMetadataExtractor instance.

Error codes

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

IDError Message
5400101No memory. Returned by promise.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let avMetadataExtractor: media.AVMetadataExtractor;
media.createAVMetadataExtractor().then((extractor: media.AVMetadataExtractor) => {
  if (extractor) {
    avMetadataExtractor = extractor;
    console.info('Succeeded in creating AVMetadataExtractor');
  } else {
    console.error(`Failed to create AVMetadataExtractor`);
  }
}).catch((error: BusinessError) => {
  console.error(`Failed to create AVMetadataExtractor, error message:${error.message}`);
});

media.createSoundPool10+

createSoundPool(maxStreams: number, audioRenderInfo: audio.AudioRendererInfo, callback: AsyncCallback<SoundPool>): void

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

NOTE

  • In versions earlier than API version 18, the bottom layer of the created SoundPool object is in singleton mode. Therefore, an application process can create only one SoundPool instance.
  • In API version 18 and later, the bottom layer of the created SoundPool object is in multiton mode. Therefore, an application process can create a maximum of 128 SoundPool instances.

System capability: SystemCapability.Multimedia.Media.SoundPool

Parameters

NameTypeMandatoryDescription
maxStreamsnumberYesMaximum number of streams that can be played by the SoundPool instance. The value is an integer ranging from 1 to 32.
audioRenderInfoaudio.AudioRendererInfoYesAudio renderer parameters. When the usage parameter in audioRenderInfo is set to STREAM_USAGE_UNKNOWN, STREAM_USAGE_MUSIC, STREAM_USAGE_MOVIE, or STREAM_USAGE_AUDIOBOOK, the SoundPool uses the audio mixing mode when playing a short sound, without interrupting the playback of other audios. SoundPool supports setting rendererFlags to 1 for low-latency playback.
callbackAsyncCallback<SoundPool>YesCallback used to return the result. If the operation is successful, a SoundPool instance is returned; otherwise, null is returned. The instance is used for loading and playback.

Error codes

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

IDError Message
5400101No memory. Return by callback.

Example

import { audio } from '@kit.AudioKit';

let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage : audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags : 0
};

media.createSoundPool(5, audioRendererInfo, (error, soundPool_: media.SoundPool) => {
  if (error) {
    console.error(`Failed to createSoundPool`);
    return;
  } else {
    soundPool = soundPool_;
    console.info(`Succeeded in createSoundPool`);
  }
});

media.createSoundPool10+

createSoundPool(maxStreams: number, audioRenderInfo: audio.AudioRendererInfo): Promise<SoundPool>

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

NOTE

  • In versions earlier than API version 18, the bottom layer of the created SoundPool object is in singleton mode. Therefore, an application process can create only one SoundPool instance.
  • In API version 18 and later, the bottom layer of the created SoundPool object is in multiton mode. Therefore, an application process can create a maximum of 128 SoundPool instances.

System capability: SystemCapability.Multimedia.Media.SoundPool

Parameters

NameTypeMandatoryDescription
maxStreamsnumberYesMaximum number of streams that can be played by the SoundPool instance. The value is an integer ranging from 1 to 32.
audioRenderInfoaudio.AudioRendererInfoYesAudio renderer parameters.

Return value

TypeDescription
Promise<SoundPool>Promise used to return the result. If the operation is successful, a SoundPool instance is returned; otherwise, null is returned. The instance is used for loading and playback.

Error codes

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

IDError Message
5400101No memory. Return by promise.

Example

import { audio } from '@kit.AudioKit';
import { BusinessError } from '@kit.BasicServicesKit';

let soundPool: media.SoundPool;
let audioRendererInfo: audio.AudioRendererInfo = {
  usage : audio.StreamUsage.STREAM_USAGE_MUSIC,
  rendererFlags : 0
};

media.createSoundPool(5, audioRendererInfo).then((soundpool_: media.SoundPool) => {
  if (soundpool_) {
    soundPool = soundpool_;
    console.info('Succeeded in creating SoundPool');
  } else {
    console.error('Failed to create SoundPool');
  }
}, (error: BusinessError) => {
  console.error(`soundpool catchCallback, error message:${error.message}`);
});

media.createAVScreenCaptureRecorder12+

createAVScreenCaptureRecorder(): Promise<AVScreenCaptureRecorder>

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

System capability: SystemCapability.Multimedia.Media.AVScreenCapture

Return value

TypeDescription
Promise<AVScreenCaptureRecorder>Promise used to return the result. If the operation is successful, an AVScreenCaptureRecorder instance is returned; otherwise, null is returned. The instance can be used for screen capture.

Error codes

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

IDError Message
5400101No memory. Return by promise.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let avScreenCaptureRecorder: media.AVScreenCaptureRecorder;
media.createAVScreenCaptureRecorder().then((captureRecorder: media.AVScreenCaptureRecorder) => {
  if (captureRecorder) {
    avScreenCaptureRecorder = captureRecorder;
    console.info('Succeeded in createAVScreenCaptureRecorder');
  } else {
    console.error('Failed to createAVScreenCaptureRecorder');
  }
}).catch((error: BusinessError) => {
  console.error(`createAVScreenCaptureRecorder catchCallback, error message:${error.message}`);
});

media.createAVImageGenerator12+

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

Parameters

NameTypeMandatoryDescription
callbackAsyncCallback<AVImageGenerator>YesCallback used to return the result. If the operation is successful, an AVImageGenerator instance is returned; otherwise, null is returned. The API can be used to obtain a video thumbnail.

Error codes

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

IDError Message
5400101No memory. Returned by callback.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let avImageGenerator: media.AVImageGenerator;
media.createAVImageGenerator((error: BusinessError, generator: media.AVImageGenerator) => {
  if (generator) {
    avImageGenerator = generator;
    console.info('Succeeded in creating AVImageGenerator');
  } else {
    console.error(`Failed to create AVImageGenerator, error message:${error.message}`);
  }
});

media.createAVImageGenerator12+

createAVImageGenerator(): Promise<AVImageGenerator>

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

System capability: SystemCapability.Multimedia.Media.AVImageGenerator

Return value

TypeDescription
Promise<AVImageGenerator>Promise used to return the result. If the operation is successful, an AVImageGenerator instance is returned; otherwise, null is returned. The API can be used to obtain a video thumbnail.

Error codes

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

IDError Message
5400101No memory. Returned by promise.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let avImageGenerator: media.AVImageGenerator;
media.createAVImageGenerator().then((generator: media.AVImageGenerator) => {
  if (generator) {
    avImageGenerator = generator;
    console.info('Succeeded in creating AVImageGenerator');
  } else {
    console.error('Failed to create AVImageGenerator');
  }
}).catch((error: BusinessError) => {
  console.error(`Failed to create AVImageGenerator, error message:${error.message}`);
});

media.createMediaSourceWithUrl12+

createMediaSourceWithUrl(url: string, headers?: Record<string, string>): MediaSource

Creates a media source for streaming media to be pre-downloaded.

Atomic service API: This API can be used in atomic services since API version 13.

System capability: SystemCapability.Multimedia.Media.Core

Parameters

NameTypeMandatoryDescription
urlstringYes- URL of the media source. The following streaming media formats are supported: HLS, HTTP-FLV, DASH, and HTTPS.
- FD path of the local M3U8 file.
headersRecord<string, string>NoHTTP header customized for streaming media pre-download. If this parameter is not passed, the default HTTP header of the network request is used.

Return value

TypeDescription
MediaSourceMediaSource instance.

Error codes

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

IDError Message
401Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed.
5400101No memory.

Example 1

let headers: Record<string, string> = {"User-Agent" : "User-Agent-Value"};
let mediaSource : media.MediaSource = media.createMediaSourceWithUrl("http://xxx",  headers);

Example 2

import { media } from "@kit.MediaKit";

async function test(context: Context){
    // this.getUIContext().getHostContext();
    let mgr = context?.resourceManager;
    if (!mgr) {
        return;
    }
    let fileDescriptor = await mgr.getRawFd("xxx.m3u8");

    let fd: string = fileDescriptor.fd.toString();
    let offset: string = fileDescriptor.offset.toString();
    let length: string = fileDescriptor.length.toString();
    let fdUrl: string = "fd://" + fd + "?offset=" + offset + "&size=" + length;

    let mediaSource: media.MediaSource = media.createMediaSourceWithUrl(fdUrl);
}

media.createMediaSourceWithStreamData19+

createMediaSourceWithStreamData(streams: Array<MediaStream>): MediaSource

Creates a multi-bitrate media source for streaming media. Currently, only the HTTP-FLV multi-bitrate media source is supported.

Atomic service API: This API can be used in atomic services since API version 19.

System capability: SystemCapability.Multimedia.Media.Core

Parameters

NameTypeMandatoryDescription
streamsArray<MediaStream>YesArray of MediaStream objects. The supported streaming media format is HTTP-FLV.

Return value

TypeDescription
MediaSourceMediaSource instance.

Example

let streams : Array<media.MediaStream> = [];
streams.push({url: "http://xxx/480p.flv", width: 854, height: 480, bitrate: 800000});
streams.push({url: "http://xxx/720p.flv", width: 1280, height: 720, bitrate: 2000000});
streams.push({url: "http://xxx/1080p.flv", width: 1920, height: 1080, bitrate: 2000000});
let mediaSource : media.MediaSource = media.createMediaSourceWithStreamData(streams);

media.createMediaSourceWithFd

createMediaSourceWithFd(fdSrc: AVFileDescriptor): MediaSource|undefined

Creates a media source using a file descriptor.

Since: 26.0.0

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Multimedia.Media.Core

Parameters

NameTypeMandatoryDescription
fdSrcAVFileDescriptorYesMedia file descriptor.

Return value

TypeDescription
MediaSource |undefinedMediaSource instance.

Example

import { common } from '@kit.AbilityKit';

let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let fdSrc = await context.resourceManager.getRawFd('xxx.mp4');
let mediaSource : media.MediaSource|undefined = media.createMediaSourceWithFd(fdSrc);

media.createMediaSourceWithDataSource

createMediaSourceWithDataSource(dataSrc: AVDataSrcDescriptor): MediaSource|undefined

Creates a media source using the custom data source.

Since: 26.0.0

Atomic service API: This API can be used in atomic services since API version 26.0.0.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Multimedia.Media.Core

Parameters

NameTypeMandatoryDescription
dataSrcAVDataSrcDescriptorYesStreaming media resource descriptor.

Return value

TypeDescription
MediaSource |undefinedMediaSource instance.

Example

import { common } from '@kit.AbilityKit';
import { fileIo as fs, ReadOptions } from '@kit.CoreFileKit';

let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
let fileDescriptor = await context.resourceManager.getRawFd('xxx.mp4');
let file = fs.openSync("xxx.mp4");
let dataSrc: media.AVDataSrcDescriptor = {
  fileSize: fileDescriptor.length,
  callback: (buf: ArrayBuffer, length: number, pos?: number) => {
    let readLen = 0;
    if (pos) {
      let option: ReadOptions = {
        offset: pos,
        length: length,
      };
      readLen = fs.readSync(file.fd, buf, option);
    }
    return readLen > 0 ? readLen : -1;
  }
}
let mediaSource : media.MediaSource|undefined =  media.createMediaSourceWithDataSource(dataSrc);

media.createAudioPlayer(deprecated)

createAudioPlayer(): AudioPlayer

Creates an AudioPlayer instance in synchronous mode.

NOTE This API is supported since API version 6 and deprecated since API version 9. You are advised to use createAVPlayer instead.

System capability: SystemCapability.Multimedia.Media.AudioPlayer

Return value

TypeDescription
AudioPlayerIf the operation is successful, an AudioPlayer instance is returned; otherwise, null is returned. After the instance is created, you can start, pause, or stop audio playback.

Example

let audioPlayer: media.AudioPlayer = media.createAudioPlayer();

media.createVideoPlayer(deprecated)

createVideoPlayer(callback: AsyncCallback<VideoPlayer>): void

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

NOTE This API is supported since API version 8 and deprecated since API version 9. You are advised to use createAVPlayer instead.

System capability: SystemCapability.Multimedia.Media.VideoPlayer

Parameters

NameTypeMandatoryDescription
callbackAsyncCallback<VideoPlayer>YesCallback used to return the result. If the operation is successful, err is undefined and data is the VideoPlayer instance created; otherwise, err is an error object.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let videoPlayer: media.VideoPlayer;
media.createVideoPlayer((error: BusinessError, video: media.VideoPlayer) => {
  if (video) {
    videoPlayer = video;
    console.info('Succeeded in creating VideoPlayer');
  } else {
    console.error(`Failed to create VideoPlayer, error:${error}`);
  }
});

media.createVideoPlayer(deprecated)

createVideoPlayer(): Promise<VideoPlayer>

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

NOTE This API is supported since API version 8 and deprecated since API version 9. You are advised to use createAVPlayer instead.

System capability: SystemCapability.Multimedia.Media.VideoPlayer

Return value

TypeDescription
Promise<VideoPlayer>Promise used to return the result. If the operation is successful, a VideoPlayer instance is returned; otherwise, null is returned. The instance can be used to manage and play video.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let videoPlayer: media.VideoPlayer;
media.createVideoPlayer().then((video: media.VideoPlayer) => {
  if (video) {
    videoPlayer = video;
    console.info('Succeeded in creating VideoPlayer');
  } else {
    console.error('Failed to create VideoPlayer');
  }
}).catch((error: BusinessError) => {
  console.error(`Failed to create VideoPlayer, error:${error}`);
});

media.createAudioRecorder(deprecated)

createAudioRecorder(): AudioRecorder

Creates an AudioRecorder instance to control audio recording. Only one AudioRecorder instance can be created per device.

NOTE This API is supported since API version 6 and deprecated since API version 9. You are advised to use createAVRecorder instead.

System capability: SystemCapability.Multimedia.Media.AudioRecorder

Return value

TypeDescription
AudioRecorderIf the operation is successful, an AudioRecorder instance is returned; otherwise, null is returned. The instance can be used to record audio.

Example

let audioRecorder: media.AudioRecorder = media.createAudioRecorder();

你可能感兴趣的鸿蒙文章

openharmony 鸿蒙 capi-avrecorder-oh-avrecorder-range

openharmony 鸿蒙 errorcode-media

openharmony 鸿蒙 capi-avplayer

openharmony 鸿蒙 capi-avplayer-base-h

openharmony 鸿蒙 capi-avimage-generator-h

openharmony 鸿蒙 capi-avscreencapture-oh-rect

openharmony 鸿蒙 capi-videoprocessing-videoprocessing-callback

openharmony 鸿蒙 capi-avsinkbase

openharmony 鸿蒙 capi-avmetadataextractor

openharmony 鸿蒙 capi-avscreencapture-oh-multidisplaycapability

  • 所属分类： 后端技术
  • 本文标签： 鸿蒙 软件
  • 版权声明： 本文链接 https://seaxiang.com/blog/bzJXTGdM