diff --git a/zh-cn/application-dev/media/media/avmetadataextractor.md b/zh-cn/application-dev/media/media/avmetadataextractor.md index 4fa246b2bd1d01f10474eac7ee49746b89405101..f22f1edd5747bfd9a89dd7b578b982b401db3fcf 100644 --- a/zh-cn/application-dev/media/media/avmetadataextractor.md +++ b/zh-cn/application-dev/media/media/avmetadataextractor.md @@ -1,8 +1,8 @@ # 使用AVMetadataExtractor提取音视频元数据信息(ArkTS) -使用[AVMetadataExtractor](media-kit-intro.md#avmetadataextractor)可以实现从原始媒体资源中获取元数据，本开发指导将以获取一个音频资源的元数据作为示例，向开发者讲解AVMetadataExtractor元数据相关功能。视频资源的元数据获取流程与音频类似，由于视频没有专辑封面，所以无法获取视频资源的专辑封面。 +使用[AVMetadataExtractor](media-kit-intro.md#avmetadataextractor)可以实现从原始媒体资源中获取元数据。本指南将以获取一个音视频资源的元数据作为示例，向开发者讲解AVMetadataExtractor元数据相关功能。视频资源的元数据获取流程与音频类似，由于视频没有专辑封面，所以无法获取视频资源的专辑封面。 -获取音频资源的元数据的全流程包含：创建AVMetadataExtractor，设置资源，获取元数据，获取专辑封面，销毁资源。 +获取音视频资源的元数据的全流程包含：创建AVMetadataExtractor、设置资源、获取元数据、获取音频资源的专辑封面或获取视频缩略图、销毁资源。 ## 开发步骤及注意事项 @@ -15,7 +15,7 @@ let avMetadataExtractor: media.AVMetadataExtractor = await media.createAVMetadataExtractor(); ``` -2. 设置资源：用户可以根据需要选择设置属性fdSrc（表示文件描述符）, 或者设置属性dataSrc（表示dataSource描述符）。 +2. 设置资源：用户可以根据需要选择设置属性fdSrc（表示文件描述符）和属性dataSrc（表示dataSource描述符）或者调用setUrlSource设置在线媒体链接。 > **说明：** > > 开发者需根据实际情况，确认资源有效性并设置（只能设置其中一种）： @@ -24,9 +24,12 @@ > > - 如果设置dataSrc，必须正确设置dataSrc中的callback属性，确保callback被调用时能正确读取到对应资源，使用应用沙箱路径访问对应资源，参考[获取应用文件路径](../../application-models/application-context-stage.md#获取应用文件路径)。应用沙箱的介绍及如何向应用沙箱推送文件，请参考[文件管理](../../file-management/app-sandbox-directory.md)。 > + > - 如果设置[setUrlSource](../../reference/apis-media-kit/arkts-apis-media-AVMetadataExtractor.md#seturlsource20)，必须正确设置setUrlSource中的url和headers属性，确保正确访问url。 + > > - 不同AVMetadataExtractor或者[AVImageGenerator](../../reference/apis-media-kit/arkts-apis-media-AVImageGenerator.md)实例，如果需要操作同一资源，需要多次打开文件描述符，不要共用同一文件描述符。 ```ts + import { BusinessError } from '@kit.BasicServicesKit'; import { common } from '@kit.AbilityKit'; import { fileIo as fs, ReadOptions } from '@kit.CoreFileKit'; // 获取rawfile目录下资源文件描述符，设置fdSrc属性。 @@ -67,6 +70,16 @@ }; // 设置dataSrc。 avMetadataExtractor.dataSrc = dataSrc; + + // 调用setUrlSource设置网络点播媒体资源URL，用来获取在线音视频元数据和在线视频缩略图。 + let url: string = 'http://xx.mp4'; + let headers: Record = { + "User-Agent" : "User-Agent-Value" + }; + await avMetadataExtractor.setUrlSource(url, headers).then(() => { + }).catch((error: BusinessError) => { + console.error(`Failed to setUrlSource, code: ${error.code} message: ${error.message}`); + }); ``` 3. 获取元数据：调用fetchMetadata()，可以获取到一个AVMetadata对象，通过访问该对象的各个属性，可以获取到元数据。 @@ -101,7 +114,22 @@ this.pixelMap = await avMetadataExtractor.fetchAlbumCover(); ``` -5. 释放资源：调用release()销毁实例，释放资源。 +5. （可选）获取视频缩略图：调用fetchFrameByTime，可以获取到视频缩略图。 + ```ts + import { image } from '@kit.ImageKit'; + // pixelMap对象声明，用于图片显示。 + @State pixelMap: image.PixelMap | undefined = undefined; + // 接口入参声明。 + let timeUs: number = 0; + let queryOption: media.AVImageQueryOptions = media.AVImageQueryOptions.AV_IMAGE_QUERY_PREVIOUS_SYNC; + let param: media.PixelMapParams = { + width : 300, + height : 300 + } + // 获取视频缩略图（promise模式）。 + this.pixelMap = await avMetadataExtractor.fetchFrameByTime(timeUs, queryOption, param); + +6. 释放资源：调用release()销毁实例，释放资源。 ```ts // 释放资源（callback模式）。 avMetadataExtractor.release((error) => { diff --git a/zh-cn/application-dev/reference/apis-media-kit/arkts-apis-media-AVMetadataExtractor.md b/zh-cn/application-dev/reference/apis-media-kit/arkts-apis-media-AVMetadataExtractor.md index d3f43114b45a838558cef99f9645102d8eef136b..23410699fd289c437ee6503d63ca88ab7a56e61b 100644 --- a/zh-cn/application-dev/reference/apis-media-kit/arkts-apis-media-AVMetadataExtractor.md +++ b/zh-cn/application-dev/reference/apis-media-kit/arkts-apis-media-AVMetadataExtractor.md @@ -3,9 +3,9 @@ > **说明：** > 本模块首批接口从API version 11开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 -元数据获取类，用于从媒体资源中获取元数据。在调用AVMetadataExtractor的方法前，需要先通过[createAVMetadataExtractor()](arkts-apis-media-f.md#mediacreateavmetadataextractor11)构建一个AVMetadataExtractor实例。 +元数据获取类，用于从媒体资源中获取元数据、缩略图。在调用AVMetadataExtractor的方法前，需要先通过[media.createAVMetadataExtractor](arkts-apis-media-f.md#mediacreateavmetadataextractor11)构建一个AVMetadataExtractor实例。 -获取音频或视频元数据的demo可参考：[获取音视频元数据开发指导](../../media/media/avmetadataextractor.md)。 +获取音频或视频元数据、视频缩略图的demo可参考：[使用AVMetadataExtractor提取音视频元数据信息(ArkTS)](../../media/media/avmetadataextractor.md)。 ## 属性 @@ -16,6 +16,130 @@ | fdSrc11+ | [AVFileDescriptor](arkts-apis-media-i.md#avfiledescriptor9) | 是 | 是 | 媒体文件描述，通过该属性设置数据源。在获取元数据之前，必须设置数据源属性，只能设置fdSrc和dataSrc的其中一个。
**使用示例**：
假设一个连续存储的媒体文件，地址偏移:0，字节长度:100。其文件描述为 AVFileDescriptor { fd = 资源句柄; offset = 0; length = 100; }。
**说明：**
- 将资源句柄（fd）传递给 AVMetadataExtractor 实例之后，请不要通过该资源句柄做其他读写操作，包括但不限于将同一个资源句柄传递给多个 AVPlayer / AVMetadataExtractor / AVImageGenerator / AVTranscoder。同一时间通过同一个资源句柄读写文件时存在竞争关系，将导致音视频元数据获取异常。 | | dataSrc11+ | [AVDataSrcDescriptor](arkts-apis-media-i.md#avdatasrcdescriptor10) | 是 | 是 | 流式媒体资源描述，通过该属性设置数据源。在获取元数据之前，必须设置数据源属性，只能设置fdSrc和dataSrc的其中一个。
当应用从远端获取音视频媒体文件，在应用未下载完整音视频资源时，可以设置dataSrc提前获取该资源的元数据。| +### setUrlSource20+ + +setUrlSource(url: string, headers?: Record\): Promise\ + +网络点播资源地址描述，通过该接口设置数据源。使用Promise异步回调。只支持获取网络[fetchMetadata](#fetchmetadata11)（元数据）、[fetchFrameByTime](#fetchframebytime20)（缩略图），在获取之前，必须设置媒体资源URL。 + +**需要权限：** ohos.permission.INTERNET + +**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------------------- | ---- | ----------------------------------- | +| url | string | 是 | 媒体资源URL。
1. 支持的视频格式包括：mp4、mpeg-ts、mkv。
2. 支持的音频格式包括：m4a、aac、mp3、ogg、wav、flac、amr。
**支持路径示例**：
1. http网络播放：http\://xx。
2. https网络播放：https\://xx。
**说明：**
- 不支持设置hls/dash、直播资源。
- 设置网络资源路径，需[声明权限](../../security/AccessToken/declare-permissions.md)：[ohos.permission.INTERNET](../../security/AccessToken/permissions-for-all.md#ohospermissioninternet)，相关错误码: [201](../errorcode-universal.md)。| +| headers | Record\ | 否 | 支持访问网络资源HttpHeader自定义。默认为空。| + +**返回值：** + +| 类型 | 说明 | +| -------------- | ---------------------------------------- | +| Promise\ | Promise对象，无返回结果。 | + +**错误码：** + +以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[媒体错误码](errorcode-media.md)。 + +| 错误码ID | 错误信息 | +| -------- | ----------------------------------------- | +| 201 | Permission denied, requires internet access permission. Returned by promise. | +| 5400102 | Operation not allowed,Returned by promise.the URL source has already been set and cannot be modified. Returned by promise. | +| 5400108 | Parameter check failed. Returned by promise. | + +**示例：** + +```ts +import { BusinessError } from '@kit.BasicServicesKit'; +import { media } from '@kit.MediaKit'; + +let avMetadataExtractor: media.AVMetadataExtractor | undefined = undefined; + +media.createAVMetadataExtractor(async (error: BusinessError, extractor: media.AVMetadataExtractor) => { + if (extractor != null) { + avMetadataExtractor = extractor; + console.info('Succeeded in creating AVMetadataExtractor'); + let url = "http://xx"; + let headers: Record = { + "User-Agent" : "User-Agent-Value" + }; + await avMetadataExtractor.setUrlSource(url, headers).then(() => { + }).catch((error: BusinessError) => { + console.error(`Failed to setUrlSource, code: ${error.code} message: ${error.message}`); + }); + } else { + console.error(`Failed to create AVMetadataExtractor, error message:${error.message}`); + } +}); +``` + +### fetchFrameByTime20+ + +fetchFrameByTime(timeUs: number, options: AVImageQueryOptions, param: PixelMapParams): Promise\ + +获取视频缩略图。使用Promise异步回调。 + +**系统能力：** SystemCapability.Multimedia.Media.AVMetadataExtractor + +**参数：** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -------------------------------------------- | ---- | ----------------------------------- | +| timeUs | number | 是 | 需要获取的缩略图在视频中的时间点，单位为微秒（μs）。 | +| options | [AVImageQueryOptions](arkts-apis-media-e.md#avimagequeryoptions12) | 是 | 需要获取的缩略图时间点与视频帧的对应关系。 | +| param | [PixelMapParams](arkts-apis-media-i.md#pixelmapparams12) | 是 | 需要获取的缩略图的格式参数。 | + +**返回值：** + +| 类型 | 说明 | +| -------------- | ---------------------------------------- | +| Promise\<[image.PixelMap](../apis-image-kit/js-apis-image.md#pixelmap7)> | Promise对象，返回视频缩略图对象。 | + +**错误码：** + +以下错误码的详细介绍请参见[媒体错误码](errorcode-media.md) + +| 错误码ID | 错误信息 | +| -------- | ----------------------------------------- | +| 5400102 | Operation not allowed. Returned by promise. | +| 5400106 | Unsupported format. Returned by promise. | +| 5400108 | Parameter check failed. Returned by promise. | + +**示例：** + +```ts +import { BusinessError } from '@kit.BasicServicesKit'; +import { image } from '@kit.ImageKit'; +import { media } from '@kit.MediaKit'; + +let avMetadataExtractor: media.AVMetadataExtractor | undefined = undefined; +let pixel_map : image.PixelMap | undefined = undefined; + +// 初始化入参。 +let timeUs: number = 0; +let queryOption: media.AVImageQueryOptions = media.AVImageQueryOptions.AV_IMAGE_QUERY_PREVIOUS_SYNC; +let param: media.PixelMapParams = { + width : 300, + height : 300 +}; +// 获取缩略图。 +media.createAVMetadataExtractor((error: BusinessError, extractor: media.AVMetadataExtractor) => { + if (extractor != null) { + avMetadataExtractor = extractor; + console.info('Succeeded in creating AVMetadataExtractor'); + avMetadataExtractor.fetchFrameByTime(timeUs, queryOption, param).then((pixelMap: image.PixelMap) => { + pixel_map = pixelMap; + }).catch((error: BusinessError) => { + console.error(`Failed to fetch FrameByTime, error message:${error.message}`); + }); + } else { + console.error(`Failed to create AVMetadataExtractor, error message:${error.message}`); + } +}); +``` + ## fetchMetadata11+ fetchMetadata(callback: AsyncCallback\): void