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 /** 49 * @brief Forward declaration of OH_AVDemuxer. 50 * 51 * @since 10 52 */ 53 typedef struct OH_AVDemuxer OH_AVDemuxer; 54 /** 55 * @brief Forward declaration of DRM_MediaKeySystemInfo. 56 * 57 * @since 11 58 */ 59 typedef struct DRM_MediaKeySystemInfo DRM_MediaKeySystemInfo; 60 61 /** 62 * @brief Callback for getting media key system information from media source. 63 * @deprecated since 14 64 * @useinstead Demuxer_MediaKeySystemInfoCallback 65 * @since 11 66 */ 67 typedef void (*DRM_MediaKeySystemInfoCallback)(DRM_MediaKeySystemInfo *mediaKeySystemInfo); 68 69 /** 70 * @brief Call back will be invoked when updating DRM information. 71 * @param demuxer Player OH_AVDemuxer. 72 * @param mediaKeySystemInfo DRM information. 73 * @return DRM_ERR_INVALID_VAL when the params checked failure, return DRM_ERR_OK when function called successfully. 74 * @since 12 75 */ 76 typedef void (*Demuxer_MediaKeySystemInfoCallback)(OH_AVDemuxer *demuxer, DRM_MediaKeySystemInfo *mediaKeySystemInfo); 77 78 /** 79 * @brief Creates an OH_AVDemuxer instance for getting samples from source. 80 * Free the resources of the instance by calling OH_AVDemuxer_Destroy. 81 * @syscap SystemCapability.Multimedia.Media.Spliter 82 * @param source Pointer to an OH_AVSource instance. 83 * @return Returns a pointer to an OH_AVDemuxer instance if the execution is successful, otherwise returns nullptr. 84 * Possible failure causes: 85 * 1. source is invalid. 86 * @since 10 87 */ 88 OH_AVDemuxer *OH_AVDemuxer_CreateWithSource(OH_AVSource *source); 89 90 /** 91 * @brief Destroy the OH_AVDemuxer instance and free the internal resources. 92 * The same instance can only be destroyed once. The destroyed instance 93 * should not be used before it is created again. It is recommended setting 94 * the instance pointer to NULL right after the instance is destroyed successfully. 95 * @syscap SystemCapability.Multimedia.Media.Spliter 96 * @param demuxer Pointer to an OH_AVDemuxer instance. 97 * @return Returns AV_ERR_OK if the execution is successful, 98 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 99 * {@link AV_ERR_INVALID_VAL} demuxer is invalid. 100 * @since 10 101 */ 102 OH_AVErrCode OH_AVDemuxer_Destroy(OH_AVDemuxer *demuxer); 103 104 /** 105 * @brief The specified track is selected and the demuxer will read samples from 106 * this track. Multiple tracks are selected by calling this interface multiple times 107 * with different track indexes. Only the selected tracks are valid when calling 108 * OH_AVDemuxer_ReadSample to read samples. The interface returns AV_ERR_OK and the 109 * track is selected only once if the same track is selected multiple times. 110 * @syscap SystemCapability.Multimedia.Media.Spliter 111 * @param demuxer Pointer to an OH_AVDemuxer instance. 112 * @param trackIndex The index of the selected track. 113 * @return Returns AV_ERR_OK if the execution is successful, 114 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 115 * {@link AV_ERR_INVALID_VAL} demuxer is invalid, demuxer is not properly initialized, 116 * trackIndex is out of range, track is not supported to be read. 117 * @since 10 118 */ 119 OH_AVErrCode OH_AVDemuxer_SelectTrackByID(OH_AVDemuxer *demuxer, uint32_t trackIndex); 120 121 /** 122 * @brief The specified selected track is unselected. The unselected track's sample 123 * can not be read from demuxer. Multiple selected tracks are unselected by calling 124 * this interface multiple times with different track indexes. The interface returns 125 * AV_ERR_OK and the track is unselected only once if the same track is unselected 126 * multiple times. 127 * @syscap SystemCapability.Multimedia.Media.Spliter 128 * @param demuxer Pointer to an OH_AVDemuxer instance. 129 * @param trackIndex The index of the unselected track. 130 * @return Returns AV_ERR_OK if the execution is successful, 131 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 132 * {@link AV_ERR_INVALID_VAL} demuxer is invalid, demuxer is not properly initialized. 133 * @since 10 134 */ 135 OH_AVErrCode OH_AVDemuxer_UnselectTrackByID(OH_AVDemuxer *demuxer, uint32_t trackIndex); 136 137 /** 138 * @brief Get the current encoded sample and sample-related information from the specified 139 * track. The track index must be selected before reading sample. The demuxer will advance 140 * automatically after calling this interface. 141 * @syscap SystemCapability.Multimedia.Media.Spliter 142 * @param demuxer Pointer to an OH_AVDemuxer instance. 143 * @param trackIndex The index of the track from which read an encoded sample. 144 * @param sample The OH_AVMemory handle pointer to the buffer storing the sample data. 145 * @param info The OH_AVCodecBufferAttr handle pointer to the buffer storing sample information. 146 * @return Returns AV_ERR_OK if the execution is successful, 147 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 148 * {@link AV_ERR_INVALID_VAL} demuxer is invalid, demuxer is not properly initialized, sample is invalid, 149 * trackIndex is out of range. 150 * {@link AV_ERR_OPERATE_NOT_PERMIT} trackIndex has not been selected. 151 * {@link AV_ERR_NO_MEMORY} capability of sample is not enough to store all 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 Get the current encoded sample and sample-related information from the specified 162 * track. 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} demuxer is invalid, demuxer is not properly initialized, sample is invalid, 171 * trackIndex is out of range. 172 * {@link AV_ERR_OPERATE_NOT_PERMIT} trackIndex has not been selected. 173 * {@link AV_ERR_NO_MEMORY} capability of sample is not enough to store frame data. 174 * {@link AV_ERR_UNKNOWN} failed to read or parse frame from file. 175 * @since 11 176 */ 177 OH_AVErrCode OH_AVDemuxer_ReadSampleBuffer(OH_AVDemuxer *demuxer, uint32_t trackIndex, 178 OH_AVBuffer *sample); 179 180 /** 181 * @brief All selected tracks seek near to the requested time according to the seek mode. 182 * @syscap SystemCapability.Multimedia.Media.Spliter 183 * @param demuxer Pointer to an OH_AVDemuxer instance. 184 * @param millisecond The millisecond for seeking, the timestamp is the position of 185 * the file relative to the start of the file. 186 * @param mode The mode for seeking. See {@link OH_AVSeekMode}. 187 * @return Returns AV_ERR_OK if the execution is successful, 188 * otherwise returns a specific error code, refer to {@link OH_AVErrCode} 189 * {@link AV_ERR_INVALID_VAL} demuxer is invalid, demuxer is not properly initialized, 190 * millisecond is out of range. 191 * {@link AV_ERR_OPERATE_NOT_PERMIT} trackIndex has not been selected, resource is unseekable. 192 * {@link AV_ERR_UNKNOWN} failed to seek. 193 * @since 10 194 */ 195 OH_AVErrCode OH_AVDemuxer_SeekToTime(OH_AVDemuxer *demuxer, int64_t millisecond, OH_AVSeekMode mode); 196 197 /** 198 * @brief Method to set player media key system info callback. 199 * @syscap SystemCapability.Multimedia.Media.Spliter 200 * @param demuxer Pointer to an OH_AVDemuxer instance 201 * @param callback object pointer. 202 * @return {@link AV_ERR_OK} 0 - Success 203 * {@link AV_ERR_OPERATE_NOT_PERMIT} 2 - If the demuxer engine is not inited or init failed. 204 * {@link AV_ERR_INVALID_VAL} 3 - If the demuxer instance is nullptr or invalid. 205 * @deprecated since 14 206 * @useinstead OH_AVDemuxer_SetDemuxerMediaKeySystemInfoCallback 207 * @since 11 208 */ 209 OH_AVErrCode OH_AVDemuxer_SetMediaKeySystemInfoCallback(OH_AVDemuxer *demuxer, 210 DRM_MediaKeySystemInfoCallback callback); 211 212 /** 213 * @brief Method to set player media key system info callback. 214 * @syscap SystemCapability.Multimedia.Media.Spliter 215 * @param demuxer Pointer to an OH_AVDemuxer instance 216 * @param callback object pointer. 217 * @return {@link AV_ERR_OK} 0 - Success 218 * {@link AV_ERR_OPERATE_NOT_PERMIT} 2 - If the demuxer engine is not inited or init failed. 219 * {@link AV_ERR_INVALID_VAL} 3 - If the demuxer instance is nullptr or invalid. 220 * @since 12 221 */ 222 OH_AVErrCode OH_AVDemuxer_SetDemuxerMediaKeySystemInfoCallback(OH_AVDemuxer *demuxer, 223 Demuxer_MediaKeySystemInfoCallback callback); 224 225 /** 226 * @brief Obtains media key system info to create media key session. 227 * @syscap SystemCapability.Multimedia.Media.Spliter 228 * @param demuxer Pointer to an OH_AVDemuxer instance 229 * @param mediaKeySystemInfo Indicates the media key system info which ram space allocated by callee and 230 * released by caller. 231 * @return {@link AV_ERR_OK} 0 - Success 232 * {@link AV_ERR_OPERATE_NOT_PERMIT} 2 - If the demuxer engine is not inited or init failed. 233 * {@link AV_ERR_INVALID_VAL} 3 - If the demuxer instance is nullptr or invalid 234 * or the mediaKeySystemInfo is nullptr. 235 * @since 11 236 */ 237 OH_AVErrCode OH_AVDemuxer_GetMediaKeySystemInfo(OH_AVDemuxer *demuxer, DRM_MediaKeySystemInfo *mediaKeySystemInfo); 238 239 #ifdef __cplusplus 240 } 241 #endif 242 243 #endif // NATIVE_AVDEMUXER_H 244 /** @} */ 245