1 /* 2 * Copyright (C) 2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup AVDemuxer 18 * @{ 19 * 20 * @brief The AVDemuxer module provides an interface for extracting samples from media file streams. 21 * 22 * @syscap SystemCapability.Multimedia.Media.Spliter 23 * @since 10 24 */ 25 26 /** 27 * @file native_avdemuxer.h 28 * 29 * @brief Declare the interface for parsing audio and video media data. 30 * 31 * @kit AVCodecKit 32 * @library libnative_media_avdemuxer.so 33 * @syscap SystemCapability.Multimedia.Media.Spliter 34 * @since 10 35 */ 36 37 #ifndef NATIVE_AVDEMUXER_H 38 #define NATIVE_AVDEMUXER_H 39 40 #include <stdint.h> 41 #include "native_avcodec_base.h" 42 #include "native_avsource.h" 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 typedef struct OH_AVDemuxer OH_AVDemuxer; 49 typedef struct DRM_MediaKeySystemInfo DRM_MediaKeySystemInfo; 50 51 /** 52 * @brief Pointer type for media key system information callback function. 53 * @deprecated since 14 54 * @useinstead Demuxer_MediaKeySystemInfoCallback 55 * @since 11 56 */ 57 typedef void (*DRM_MediaKeySystemInfoCallback)(DRM_MediaKeySystemInfo* mediaKeySystemInfo); 58 59 /** 60 * @brief Pointer type for media key system information callback function. 61 * @param demuxer Player OH_AVDemuxer. 62 * @param mediaKeySystemInfo DRM information. 63 * @since 12 64 * @version 1.0 65 */ 66 typedef void (*Demuxer_MediaKeySystemInfoCallback)(OH_AVDemuxer *demuxer, DRM_MediaKeySystemInfo *mediaKeySystemInfo); 67 68 /** 69 * @brief Creates an OH_AVDemuxer instance for getting samples from source. 70 * For the create, destrory, and use of source, please refer to {@link OH_AVSource}. 71 * @syscap SystemCapability.Multimedia.Media.Spliter 72 * @param source Pointer to an OH_AVSource instance. 73 * @return Returns a pointer to an OH_AVDemuxer instance if the execution is successful, otherwise returns NULL. 74 * Possible failure causes: 75 * 1. invalid source, is NULL pointer; 76 * 2. non OH_AVSource instance. 77 * @since 10 78 */ 79 OH_AVDemuxer *OH_AVDemuxer_CreateWithSource(OH_AVSource *source); 80 81 /** 82 * @brief Destroy the OH_AVDemuxer instance and free the internal resources. 83 * The same instance can only be destroyed once. The destroyed instance 84 * should not be used before it is created again. It is recommended setting 85 * the instance pointer to NULL right after the instance is destroyed successfully. 86 * @syscap SystemCapability.Multimedia.Media.Spliter 87 * @param demuxer Pointer to an OH_AVDemuxer instance. 88 * @return Returns AV_ERR_OK if the execution is successful, 89 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 90 * {@link AV_ERR_INVALID_VAL} the input demuxer pointer is non demuxer instance or NULL. 91 * @since 10 92 */ 93 OH_AVErrCode OH_AVDemuxer_Destroy(OH_AVDemuxer *demuxer); 94 95 /** 96 * @brief The specified track is selected and the demuxer will read samples from 97 * this track. Multiple tracks are selected by calling this interface multiple times 98 * with different track indexes. Only the selected tracks are valid when calling 99 * OH_AVDemuxer_ReadSample to read samples. The interface returns AV_ERR_OK and the 100 * track is selected only once if the same track is selected multiple times. 101 * @syscap SystemCapability.Multimedia.Media.Spliter 102 * @param demuxer Pointer to an OH_AVDemuxer instance. 103 * @param trackIndex The index of the selected track. 104 * @return Returns AV_ERR_OK if the execution is successful, 105 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 106 * {@link AV_ERR_OPERATE_NOT_PERMIT} demuxer is not properly initialized. 107 * {@link AV_ERR_INVALID_VAL} 108 * 1. the input demuxer pointer is non demuxer instance or NULL; 109 * 2. trackIndex is out of range; 110 * 3. track is not supported to be read. 111 * @since 10 112 */ 113 OH_AVErrCode OH_AVDemuxer_SelectTrackByID(OH_AVDemuxer *demuxer, uint32_t trackIndex); 114 115 /** 116 * @brief The specified selected track is unselected. The unselected track's sample 117 * can not be read from demuxer. Multiple selected tracks are unselected by calling 118 * this interface multiple times with different track indexes. The interface returns 119 * AV_ERR_OK and the track is unselected only once if the same track is unselected 120 * multiple times. 121 * @syscap SystemCapability.Multimedia.Media.Spliter 122 * @param demuxer Pointer to an OH_AVDemuxer instance. 123 * @param trackIndex The index of the unselected track. 124 * @return Returns AV_ERR_OK if the execution is successful, 125 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 126 * {@link AV_ERR_OPERATE_NOT_PERMIT} demuxer is not properly initialized. 127 * {@link AV_ERR_INVALID_VAL} the input demuxer pointer is non demuxer instance or NULL. 128 * @since 10 129 */ 130 OH_AVErrCode OH_AVDemuxer_UnselectTrackByID(OH_AVDemuxer *demuxer, uint32_t trackIndex); 131 132 /** 133 * @brief Obtain samples and related information for the specified track. 134 * Note that the track index must be selected before reading sample. The demuxer will advance 135 * automatically after calling this interface. 136 * @syscap SystemCapability.Multimedia.Media.Spliter 137 * @param demuxer Pointer to an OH_AVDemuxer instance. 138 * @param trackIndex The index of the track from which read an encoded sample. 139 * @param sample The OH_AVMemory handle pointer to the buffer storing the sample data. 140 * @param info The OH_AVCodecBufferAttr handle pointer to the buffer storing sample information. 141 * @return Returns AV_ERR_OK if the execution is successful, 142 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 143 * {@link AV_ERR_INVALID_VAL} 144 * 1. the input demuxer pointer is non demuxer instance or NULL; 145 * 2. sample is a NULL pointer; 146 * 3. trackIndex is out of range; 147 * 4. the input sample is empty. 148 * {@link AV_ERR_OPERATE_NOT_PERMIT} 149 * 1. trackIndex has not been selected; 150 * 2. demuxer is not properly initialized. 151 * {@link AV_ERR_NO_MEMORY} capability of sample is not enough to store frame data. 152 * {@link AV_ERR_UNKNOWN} failed to read or parse frame from file. 153 * @deprecated since 11 154 * @useinstead OH_AVDemuxer_ReadSampleBuffer 155 * @since 10 156 */ 157 OH_AVErrCode OH_AVDemuxer_ReadSample(OH_AVDemuxer *demuxer, uint32_t trackIndex, 158 OH_AVMemory *sample, OH_AVCodecBufferAttr *info); 159 160 /** 161 * @brief Obtain samples and related information for the specified track. 162 * Note that the track index must be selected before reading sample. The demuxer will advance 163 * automatically after calling this interface. 164 * @syscap SystemCapability.Multimedia.Media.Spliter 165 * @param demuxer Pointer to an OH_AVDemuxer instance. 166 * @param trackIndex The index of the track from which read an encoded sample. 167 * @param sample The OH_AVBuffer handle pointer to the buffer storing the sample data and corresponding attribute. 168 * @return Returns AV_ERR_OK if the execution is successful, 169 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 170 * {@link AV_ERR_INVALID_VAL} 171 * 1. the input demuxer pointer is non demuxer instance or NULL; 172 * 2. sample is a NULL pointer; 173 * 3. trackIndex is out of range; 174 * 4. the input sample is empty. 175 * {@link AV_ERR_OPERATE_NOT_PERMIT} 176 * 1. trackIndex has not been selected; 177 * 2. demuxer is not properly initialized. 178 * {@link AV_ERR_NO_MEMORY} capability of sample is not enough to store frame data. 179 * {@link AV_ERR_UNKNOWN} failed to read or parse frame from file. 180 * @since 11 181 */ 182 OH_AVErrCode OH_AVDemuxer_ReadSampleBuffer(OH_AVDemuxer *demuxer, uint32_t trackIndex, 183 OH_AVBuffer *sample); 184 185 /** 186 * @brief All selected tracks seek near to the requested time according to the seek mode. 187 * @syscap SystemCapability.Multimedia.Media.Spliter 188 * @param demuxer Pointer to an OH_AVDemuxer instance. 189 * @param millisecond The millisecond for seeking, the timestamp is the position of 190 * the file relative to the start of the file. 191 * @param mode The mode for seeking. See {@link OH_AVSeekMode}. 192 * @return Returns AV_ERR_OK if the execution is successful, 193 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 194 * {@link AV_ERR_INVALID_VAL} 195 * 1. the input demuxer pointer is non demuxer instance or NULL; 196 * 2. the millisecond value is out of range. 197 * {@link AV_ERR_OPERATE_NOT_PERMIT} 198 * 1. trackIndex has not been selected; 199 * 2. demuxer is not properly initialized; 200 * 3. resource is unseekable. 201 * {@link AV_ERR_UNKNOWN} 202 * 1. seek failed; 203 * 2. selecting SEEK_MODE_CEXT_SYNC for OH_AVSeekMode and no I-frame after the time point may result in jump failure. 204 * @since 10 205 */ 206 OH_AVErrCode OH_AVDemuxer_SeekToTime(OH_AVDemuxer *demuxer, int64_t millisecond, OH_AVSeekMode mode); 207 208 /** 209 * @brief Set DRM information callback function. 210 * @syscap SystemCapability.Multimedia.Media.Spliter 211 * @param demuxer Pointer to an OH_AVDemuxer instance 212 * @param callback object pointer. 213 * @return 214 * {@link AV_ERR_OK} execution successful. 215 * {@link AV_ERR_OPERATE_NOT_PERMIT} demuxer is not properly initialized. 216 * {@link AV_ERR_INVALID_VAL} the input demuxer pointer is non demuxer instance or NULL. 217 * @since 11 218 * @deprecated since 14 219 * @useinstead OH_AVDemuxer_SetDemuxerMediaKeySystemInfoCallback 220 * @version 1.0 221 */ 222 OH_AVErrCode OH_AVDemuxer_SetMediaKeySystemInfoCallback(OH_AVDemuxer *demuxer, 223 DRM_MediaKeySystemInfoCallback callback); 224 225 /** 226 * @brief Set DRM information callback function. 227 * @syscap SystemCapability.Multimedia.Media.Spliter 228 * @param demuxer Pointer to an OH_AVDemuxer instance 229 * @param callback object pointer. 230 * @return 231 * {@link AV_ERR_OK} execution successful. 232 * {@link AV_ERR_OPERATE_NOT_PERMIT} demuxer is not properly initialized. 233 * {@link AV_ERR_INVALID_VAL} the input demuxer pointer is non demuxer instance or NULL. 234 * @since 12 235 * @version 1.0 236 */ 237 OH_AVErrCode OH_AVDemuxer_SetDemuxerMediaKeySystemInfoCallback(OH_AVDemuxer *demuxer, 238 Demuxer_MediaKeySystemInfoCallback callback); 239 240 /** 241 * @brief Obtain DRM information. After the {@link Demuxer_MediaKeySystemInfoCallback} 242 * or {@link DRM_MediaKeySystemInfoCallback} callback is successful, 243 * this interface can be called to obtain DRM information. 244 * @syscap SystemCapability.Multimedia.Media.Spliter 245 * @param demuxer Pointer to an OH_AVDemuxer instance 246 * @param mediaKeySystemInfo Pointer to DRM information, please refer to {@link DRM_MediaKeySystemInfo} 247 * @return 248 * {@link AV_ERR_OK} execution successful. 249 * {@link AV_ERR_INVALID_VAL} 250 * 1. the input demuxer pointer is non demuxer instance or NULL; 251 * 2. the mediaKeySystemInfo is NULL. 252 * @since 11 253 * @version 1.0 254 */ 255 OH_AVErrCode OH_AVDemuxer_GetMediaKeySystemInfo(OH_AVDemuxer *demuxer, DRM_MediaKeySystemInfo *mediaKeySystemInfo); 256 257 #ifdef __cplusplus 258 } 259 #endif 260 261 #endif // NATIVE_AVDEMUXER_H 262 /** @} */