1# AVSource 2 3 4## Overview 5 6The AVSource module provides the functions for constructing media resource objects. 7 8**System capability**: SystemCapability.Multimedia.Media.Spliter 9 10**Sample**: [AVCodec](https://gitcode.com/openharmony/applications_app_samples/tree/master/code/BasicFeature/Media/AVCodec) 11 12**Since**: 10 13 14 15## Summary 16 17 18### Files 19 20| Name| Description| 21| -------- | -------- | 22| [native_avsource.h](native__avsource_8h.md) | Declares the APIs for parsing audio and video media data. | 23 24 25### Types 26 27| Name| Description| 28| -------- | -------- | 29| typedef struct [OH_AVSource](#oh_avsource) [OH_AVSource](#oh_avsource) | Defines a struct that describes a native object for the media resource interface. | 30 31 32### Functions 33 34| Name| Description| 35| -------- | -------- | 36| [OH_AVSource](#oh_avsource) \* [OH_AVSource_CreateWithDataSource](#oh_avsource_createwithdatasource) ([OH_AVDataSource](_o_h___a_v_data_source.md) \*dataSource) | Creates an OH_AVSource instance with a user-defined data source. You can release the instance by calling **OH_AVSource_Destroy**. | 37| [OH_AVSource](#oh_avsource) \* [OH_AVSource_CreateWithDataSourceExt](#oh_avsource_createwithdatasourceext) ([OH_AVDataSourceExt](_o_h___a_v_data_source_ext.md) \*dataSource, void *userData) | Creates an OH_AVSource instance with a user-defined data source. You can release the instance by calling **OH_AVSource_Destroy**. User-defined data can be passed to its callback functions through the **userData** parameter. | 38| [OH_AVSource](#oh_avsource) \* [OH_AVSource_CreateWithURI](#oh_avsource_createwithuri) (char \*uri) | Creates an OH_AVSource instance based on a URI. | 39| [OH_AVSource](#oh_avsource) \* [OH_AVSource_CreateWithFD](#oh_avsource_createwithfd) (int32_t fd, int64_t offset, int64_t size) | Creates an OH_AVSource instance based on a file descriptor (FD). | 40| [OH_AVErrCode](_core.md#oh_averrcode) [OH_AVSource_Destroy](#oh_avsource_destroy) ([OH_AVSource](#oh_avsource) \*source) | Destroys an OH_AVSource instance and clears internal resources. | 41| [OH_AVFormat](_core.md#oh_avformat) \* [OH_AVSource_GetSourceFormat](#oh_avsource_getsourceformat) ([OH_AVSource](#oh_avsource) \*source) | Obtains the basic information about a media resource file. | 42| [OH_AVFormat](_core.md#oh_avformat) \* [OH_AVSource_GetTrackFormat](#oh_avsource_gettrackformat) ([OH_AVSource](#oh_avsource) \*source, uint32_t trackIndex) | Obtains the basic information about a track. | 43| [OH_AVFormat](_core.md#oh_avformat) \* [OH_AVSource_GetCustomMetadataFormat](#oh_avsource_getcustommetadataformat) ([OH_AVSource](#oh_avsource) \*source) | Obtains the basic information about custom metadata.| 44 45 46## Type Description 47 48 49### OH_AVSource 50 51``` 52typedef struct OH_AVSource OH_AVSource 53``` 54 55**Description** 56 57Defines a struct that describes a native object for the media resource interface. 58 59**Since**: 10 60 61 62## Function Description 63 64 65### OH_AVSource_CreateWithDataSource() 66 67``` 68OH_AVSource* OH_AVSource_CreateWithDataSource (OH_AVDataSource * dataSource) 69``` 70 71**Description** 72 73Creates an OH_AVSource instance with a user-defined data source. You can release the instance by calling **OH_AVSource_Destroy**. 74 75**System capability**: SystemCapability.Multimedia.Media.Spliter 76 77**Since**: 12 78 79**Parameters** 80 81| Name| Description| 82| -------- | -------- | 83| dataSource | Pointer to user-defined data source. | 84 85**Returns** 86 87Pointer to the OH_AVSource instance created. If the operation fails, NULL is returned. 88 89The possible causes of an operation failure are as follows: 901. The value of **dataSource** is nullptr. 912. The size of the data source is 0. 923. Setting the data source fails. 934. The memory is insufficient. 945. The decoder engine is nullptr. 956. dataSource->readAt == nullptr. 96 97 98### OH_AVSource_CreateWithDataSourceExt() 99 100``` 101OH_AVSource *OH_AVSource_CreateWithDataSourceExt(OH_AVDataSourceExt *dataSource, void *userData) 102``` 103 104**Description** 105 106Creates an OH_AVSource instance with a user-defined data source. You can release the instance by calling **OH_AVSource_Destroy**. User-defined data can be passed to its callback functions through the **userData** parameter. 107 108**System capability**: SystemCapability.Multimedia.Media.Spliter 109 110**Since**: 20 111 112**Parameters** 113 114| Name| Description| 115| -------- | -------- | 116| dataSource | Pointer to the data source struct, which is used to obtain the input data.| 117| userData | Pointer to user-defined data.| 118 119**Returns** 120 121Pointer to the OH_AVSource instance created. If the operation fails, NULL is returned. 122 123The possible causes of an operation failure are as follows: 1241. The value of **dataSource** is nullptr. 1252. The size of the data source is 0. 1263. Setting the data source fails. 1274. The memory is insufficient. 1285. The decoder engine is nullptr. 1296. dataSource->readAt == nullptr. 130 131 132### OH_AVSource_CreateWithFD() 133 134``` 135OH_AVSource* OH_AVSource_CreateWithFD (int32_t fd, int64_t offset, int64_t size) 136``` 137 138**Description** 139 140Creates an OH_AVSource instance based on an FD. You can release the instance by calling **OH_AVSource_Destroy**. 141 142If **offset** is not the start position of the file or **size** is not the file size, undefined errors such as creation failure and demultiplexing failure may occur due to incomplete data obtained. 143 144**System capability**: SystemCapability.Multimedia.Media.Spliter 145 146**Since**: 10 147 148**Parameters** 149 150| Name| Description| 151| -------- | -------- | 152| fd | FD of a media resource file. | 153| offset | Position from which data is to read. | 154| size | File size, in bytes. | 155 156**Returns** 157 158Pointer to the OH_AVSource instance created. If the operation fails, NULL is returned. 159 160The possible causes of an operation failure are as follows: 161 1621. The FD is invalid. 1632. The offset is not the start position of the file. 1643. The size is incorrect. 1654. The resource is invalid. 1665. The file format is not supported. 167 168 169### OH_AVSource_CreateWithURI() 170 171``` 172OH_AVSource* OH_AVSource_CreateWithURI (char *uri) 173``` 174 175**Description** 176 177Creates an OH_AVSource instance based on a URI. You can release the instance by calling **OH_AVSource_Destroy**. 178 179**System capability**: SystemCapability.Multimedia.Media.Spliter 180 181**Since**: 10 182 183**Parameters** 184 185| Name| Description| 186| -------- | -------- | 187| uri | URI of the media resource. | 188 189**Returns** 190 191Pointer to the OH_AVSource instance created. If the operation fails, NULL is returned. 192 193The possible causes of an operation failure are as follows: 194 1951. The network is abnormal. 1962. The resource is invalid. 1973. The file format is not supported. 198 199 200### OH_AVSource_Destroy() 201 202``` 203OH_AVErrCode OH_AVSource_Destroy (OH_AVSource *source) 204``` 205 206**Description** 207 208Destroys an OH_AVSource instance and clears internal resources. An instance can be destroyed only once. The destroyed instance cannot be used until it is re-created. You are advised to set the pointer to NULL after the instance is destroyed. 209 210**System capability**: SystemCapability.Multimedia.Media.Spliter 211 212**Since**: 10 213 214**Parameters** 215 216| Name| Description| 217| -------- | -------- | 218| source | Pointer to an OH_AVSource instance. | 219 220**Returns** 221 222One of the following result codes: 223 224**AV_ERR_OK**: The operation is successful. 225 226**AV_ERR_INVALID_VAL**: The operation fails. 227 228 1. The source pointer is invalid. 229 2. The pointer is null or does not point to an OH_AVSource instance. 230 231 232### OH_AVSource_GetCustomMetadataFormat() 233 234``` 235OH_AVFormat *OH_AVSource_GetCustomMetadataFormat(OH_AVSource *source) 236``` 237 238**Description** 239 240Obtains the basic information about custom metadata. 241 242You must call [OH_AVFormat_Destroy](_core.md#oh_avformat_destroy) to release the OH_AVFormat instance when its lifecycle ends. 243 244**System capability**: SystemCapability.Multimedia.Media.Spliter 245 246**Since**: 18 247 248**Parameters** 249 250| Name| Description| 251| -------- | -------- | 252| source | Pointer to an OH_AVSource instance.| 253 254**Returns** 255 256Basic information about the metadata. If the operation fails, NULL is returned. 257 258The possible causes of an operation failure are as follows: 259 2601. The source pointer is invalid. 2612. The pointer is null or does not point to an OH_AVSource instance. 2623. The source is not initialized. 263 264 265### OH_AVSource_GetSourceFormat() 266 267``` 268OH_AVFormat* OH_AVSource_GetSourceFormat (OH_AVSource *source) 269``` 270 271**Description** 272 273Obtains the basic information about a media resource file. 274 275You must call [OH_AVFormat_Destroy](_core.md#oh_avformat_destroy) to release the OH_AVFormat instance when its lifecycle ends. 276 277**System capability**: SystemCapability.Multimedia.Media.Spliter 278 279**Since**: 10 280 281**Parameters** 282 283| Name| Description| 284| -------- | -------- | 285| source | Pointer to an OH_AVSource instance. | 286 287**Returns** 288 289Basic information about the file. If the operation fails, NULL is returned. 290 291The possible causes of an operation failure are as follows: 292 2931. The source pointer is invalid. 2942. The pointer is null or does not point to an OH_AVSource instance. 2953. The source is not initialized. 296 297 298### OH_AVSource_GetTrackFormat() 299 300``` 301OH_AVFormat* OH_AVSource_GetTrackFormat (OH_AVSource *source, uint32_t trackIndex) 302``` 303 304**Description** 305 306Obtains the basic information about a track. 307 308You must call [OH_AVFormat_Destroy](_core.md#oh_avformat_destroy) to release the OH_AVFormat instance when its lifecycle ends. 309 310**System capability**: SystemCapability.Multimedia.Media.Spliter 311 312**Since**: 10 313 314**Parameters** 315 316| Name| Description| 317| -------- | -------- | 318| source | Pointer to an OH_AVSource instance. | 319| trackIndex | Index of the track whose information is to be obtained. | 320 321**Returns** 322 323Basic information about the track. If the operation fails, NULL is returned. 324 325The possible causes of an operation failure are as follows: 326 3271. The value of **source** is invalid (either a null pointer or a pointer to a non-OH_AVSource instance). 3282. The track index is out of range. 3293. The source is not initialized. 330