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