1 /* 2 * Copyright 2002-2010, Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 */ 5 #ifndef _MEDIA_TRACK_H 6 #define _MEDIA_TRACK_H 7 8 9 #include <MediaFormats.h> 10 11 12 namespace BCodecKit { 13 class BDecoder; 14 class BEncoder; 15 class BMediaExtractor; 16 class BMediaWriter; 17 } 18 19 class BMessage; 20 class BView; 21 class BParameterWeb; 22 23 24 enum media_seek_type { 25 B_MEDIA_SEEK_CLOSEST_FORWARD = 1, 26 B_MEDIA_SEEK_CLOSEST_BACKWARD = 2, 27 B_MEDIA_SEEK_DIRECTION_MASK = 3 28 }; 29 30 31 // BMediaTrack gives access to a particular media track in a media file 32 // (as represented by BMediaFile). 33 // 34 // You always instantiate a BMediaTrack through BMediaFile::TrackAt() 35 // or BMediaFile::CreateTrack(). When a BMediaTrack object is 36 // constructed it finds the necessary decoder or encoder for the type 37 // of data stored in the track. 38 // 39 // Unless you created the BMediaFile() in B_MEDIA_REPLACE_MODE, you 40 // can only access a track for reading or writing, not both. 41 // 42 // If InitCheck() indicates no errors, then the track is ready to be 43 // used to read and write frames using ReadFrames() and WriteFrames(). 44 // For video data you should always only read one frame. 45 // 46 // You can seek a track with SeekToTime() and SeekToFrame(). 47 // 48 // If no codec could be found for the track, it is still possible to 49 // access the encoded data using ReadChunk(). 50 class BMediaTrack { 51 protected: 52 // Use BMediaFile::ReleaseTrack() instead -- or it will go away 53 // on its own when the MediaFile is deleted. 54 virtual ~BMediaTrack(); 55 56 public: 57 58 // for read-only access the BMediaTrack should be instantiated 59 // through BMediaFile::TrackAt() 60 61 // for write-only access the BMediaTrack should be instantiated 62 // through BMediaFile::CreateTrack() 63 64 status_t InitCheck() const; 65 66 // Get information about the codec being used. 67 status_t GetCodecInfo( 68 media_codec_info* _codecInfo) const; 69 70 71 // EncodedFormat returns information about the track's 72 // "native" encoded format. 73 74 status_t EncodedFormat(media_format* _format) const; 75 76 // DecodedFormat is used to negotiate the format that the codec will 77 // use when decoding the track's data. You pass in the format that 78 // that you want; the codec will find and return its "best fit" 79 // format. (inout_format is used as both the input and the returned 80 // format.) The format is typically of the B_MEDIA_RAW_AUDIO or 81 // B_MEDIA_RAW_VIDEO flavor. 82 // The data returned through ReadFrames() will be in the format that's 83 // returned by this function. 84 85 status_t DecodedFormat(media_format* _format, 86 uint32 flags = 0); 87 88 // CountFrames and Duration return the total number of frame and the 89 // total duration (expressed in microseconds) of a track. 90 91 int64 CountFrames() const; 92 bigtime_t Duration() const; 93 94 // Returns in _data hierarchical meta-data about the track. 95 // The fields in the message shall follow a defined naming-scheme, 96 // such that applications can find the same information in different 97 // types of tracks. 98 status_t GetMetaData(BMessage* _data) const; 99 100 // CurrentFrame and CurrentTime return the current position (expressed in 101 // microseconds) within the track, expressed in frame index and time. 102 103 int64 CurrentFrame() const; 104 bigtime_t CurrentTime() const; 105 106 // ReadFrames() fills a buffer with the next frames/samples. For a video 107 // track, it decodes the next frame of video in the passed buffer. For 108 // an audio track, it fills the buffers with the next N samples, as 109 // negotiated by DecodedFormat(). However, if it reaches the end of the 110 // file and was not able to fill the whole buffer, it returns a partial 111 // buffer. Upon return, out_frameCount contains the actual number of 112 // frame/samples returned, and the start time for the frame, expressed 113 // in microseconds, is in the media_header structure. 114 115 status_t ReadFrames(void* buffer, int64* _frameCount, 116 media_header* header = NULL); 117 118 status_t ReadFrames(void* buffer, int64* _frameCount, 119 media_header* header, 120 media_decode_info* info); 121 122 status_t ReplaceFrames(const void* buffer, 123 int64* _frameCount, 124 const media_header* header); 125 126 127 // SeekToTime and SeekToFrame are used for seeking to a particular 128 // position in a track, expressed in either frames or microseconds. 129 // They return whatever position they were able to seek to. For example, 130 // a video codec may not be able to seek to arbitrary frames, but only to 131 // key frames. In this case, it would return the closest key frame before 132 // the specified seek point. 133 // 134 // If you want to explicitly seek to the nearest keyframe _before_ this 135 // frame or _after_ this frame, pass B_MEDIA_SEEK_CLOSEST_FORWARD or 136 // B_MEDIA_SEEK_CLOSEST_BACKWARD as the flags field. 137 138 status_t SeekToTime(bigtime_t* _time, int32 flags = 0); 139 status_t SeekToFrame(int64* _frame, int32 flags = 0); 140 141 status_t FindKeyFrameForTime(bigtime_t* _time, 142 int32 flags = 0) const; 143 status_t FindKeyFrameForFrame(int64* _frame, 144 int32 flags = 0) const; 145 146 // ReadChunk returns, in _buffer, the next _size bytes of 147 // data from the track. The data is not decoded -- it will be 148 // in its native encoded format (as specified by EncodedFormat()). 149 // You can not mix calling ReadChunk() and ReadFrames() -- either 150 // you access the track raw (i.e. with ReadChunk) or you access 151 // it with ReadFrames. 152 153 status_t ReadChunk(char** _buffer, int32* _size, 154 media_header* _header = NULL); 155 156 157 // 158 // Write-only Functions 159 // 160 status_t AddCopyright(const char* copyright); 161 status_t AddTrackInfo(uint32 code, const void* data, 162 size_t size, uint32 flags = 0); 163 164 // Write frameCount of data to the track. This data is passed 165 // through the encoder that was specified when the MediaTrack 166 // was constructed. 167 // Pass B_MEDIA_KEY_FRAME for flags if it is. 168 169 status_t WriteFrames(const void* data, int32 frameCount, 170 int32 flags = 0); 171 status_t WriteFrames(const void* data, int64 frameCount, 172 media_encode_info* info); 173 174 // Write a raw chunk of (presumably already encoded data) to 175 // the file. 176 // Pass B_MEDIA_KEY_FRAME for flags if it is. 177 178 status_t WriteChunk(const void* data, size_t size, 179 uint32 flags = 0); 180 status_t WriteChunk(const void* data, size_t size, 181 media_encode_info* info); 182 183 // Flush all buffered encoded datas to disk. You should call it after 184 // writing the last frame to be sure all datas are flushed at the right 185 // offset into the file. 186 status_t Flush(); 187 188 // These are for controlling the underlying encoder and track parameters 189 // returns a copy of the parameter web 190 status_t GetParameterWeb(BParameterWeb** _web); 191 status_t GetParameterValue(int32 id, void* value, 192 size_t* size); 193 status_t SetParameterValue(int32 id, const void* value, 194 size_t size); 195 BView* GetParameterView(); 196 197 // This is a simplified control API, only one parameter low=0.0, high=1.0 198 // Return B_ERROR if it's not supported by the current encoder. 199 status_t GetQuality(float* _quality); 200 status_t SetQuality(float quality); 201 202 status_t GetEncodeParameters( 203 encode_parameters* parameters) const; 204 status_t SetEncodeParameters( 205 encode_parameters* parameters); 206 207 208 virtual status_t Perform(int32 code, void* data); 209 210 private: 211 friend class BMediaFile; 212 213 // deprecated, but for BeOS R5 compatibility 214 BParameterWeb* Web(); 215 216 // Does nothing, returns B_ERROR, for Zeta compatiblity only 217 status_t ControlCodec(int32 selector, void* _inOutData, 218 size_t size); 219 220 // For read-only access to a BMediaTrack 221 BMediaTrack( 222 BCodecKit::BMediaExtractor* extractor, 223 int32 streamIndex); 224 225 // For write-only access to a BMediaTrack 226 BMediaTrack( 227 BCodecKit::BMediaWriter* writer, 228 int32 streamIndex, media_format* format, 229 const media_codec_info* codecInfo); 230 231 void SetupWorkaround(); 232 bool SetupFormatTranslation( 233 const media_format& from, 234 media_format* _to); 235 236 private: 237 status_t fInitStatus; 238 BCodecKit::BDecoder* fDecoder; 239 BCodecKit::BDecoder* fRawDecoder; 240 BCodecKit::BMediaExtractor* fExtractor; 241 242 int32 fStream; 243 int64 fCurrentFrame; 244 bigtime_t fCurrentTime; 245 246 media_codec_info fCodecInfo; 247 248 BCodecKit::BEncoder* fEncoder; 249 int32 fEncoderID; 250 BCodecKit::BMediaWriter* fWriter; 251 media_format fFormat; 252 253 uint32 fWorkaroundFlags; 254 255 protected: 256 int32 EncoderID() { return fEncoderID; }; 257 258 private: 259 BMediaTrack(); 260 BMediaTrack(const BMediaTrack&); 261 BMediaTrack& operator=(const BMediaTrack&); 262 263 264 double _FrameRate() const; 265 266 // FBC data and virtuals 267 uint32 _reserved_BMediaTrack_[31]; 268 269 virtual status_t _Reserved_BMediaTrack_0(int32 arg, ...); 270 virtual status_t _Reserved_BMediaTrack_1(int32 arg, ...); 271 virtual status_t _Reserved_BMediaTrack_2(int32 arg, ...); 272 virtual status_t _Reserved_BMediaTrack_3(int32 arg, ...); 273 virtual status_t _Reserved_BMediaTrack_4(int32 arg, ...); 274 virtual status_t _Reserved_BMediaTrack_5(int32 arg, ...); 275 virtual status_t _Reserved_BMediaTrack_6(int32 arg, ...); 276 virtual status_t _Reserved_BMediaTrack_7(int32 arg, ...); 277 virtual status_t _Reserved_BMediaTrack_8(int32 arg, ...); 278 virtual status_t _Reserved_BMediaTrack_9(int32 arg, ...); 279 virtual status_t _Reserved_BMediaTrack_10(int32 arg, ...); 280 virtual status_t _Reserved_BMediaTrack_11(int32 arg, ...); 281 virtual status_t _Reserved_BMediaTrack_12(int32 arg, ...); 282 virtual status_t _Reserved_BMediaTrack_13(int32 arg, ...); 283 virtual status_t _Reserved_BMediaTrack_14(int32 arg, ...); 284 virtual status_t _Reserved_BMediaTrack_15(int32 arg, ...); 285 virtual status_t _Reserved_BMediaTrack_16(int32 arg, ...); 286 virtual status_t _Reserved_BMediaTrack_17(int32 arg, ...); 287 virtual status_t _Reserved_BMediaTrack_18(int32 arg, ...); 288 virtual status_t _Reserved_BMediaTrack_19(int32 arg, ...); 289 virtual status_t _Reserved_BMediaTrack_20(int32 arg, ...); 290 virtual status_t _Reserved_BMediaTrack_21(int32 arg, ...); 291 virtual status_t _Reserved_BMediaTrack_22(int32 arg, ...); 292 virtual status_t _Reserved_BMediaTrack_23(int32 arg, ...); 293 virtual status_t _Reserved_BMediaTrack_24(int32 arg, ...); 294 virtual status_t _Reserved_BMediaTrack_25(int32 arg, ...); 295 virtual status_t _Reserved_BMediaTrack_26(int32 arg, ...); 296 virtual status_t _Reserved_BMediaTrack_27(int32 arg, ...); 297 virtual status_t _Reserved_BMediaTrack_28(int32 arg, ...); 298 virtual status_t _Reserved_BMediaTrack_29(int32 arg, ...); 299 virtual status_t _Reserved_BMediaTrack_30(int32 arg, ...); 300 virtual status_t _Reserved_BMediaTrack_31(int32 arg, ...); 301 virtual status_t _Reserved_BMediaTrack_32(int32 arg, ...); 302 virtual status_t _Reserved_BMediaTrack_33(int32 arg, ...); 303 virtual status_t _Reserved_BMediaTrack_34(int32 arg, ...); 304 virtual status_t _Reserved_BMediaTrack_35(int32 arg, ...); 305 virtual status_t _Reserved_BMediaTrack_36(int32 arg, ...); 306 virtual status_t _Reserved_BMediaTrack_37(int32 arg, ...); 307 virtual status_t _Reserved_BMediaTrack_38(int32 arg, ...); 308 virtual status_t _Reserved_BMediaTrack_39(int32 arg, ...); 309 virtual status_t _Reserved_BMediaTrack_40(int32 arg, ...); 310 virtual status_t _Reserved_BMediaTrack_41(int32 arg, ...); 311 virtual status_t _Reserved_BMediaTrack_42(int32 arg, ...); 312 virtual status_t _Reserved_BMediaTrack_43(int32 arg, ...); 313 virtual status_t _Reserved_BMediaTrack_44(int32 arg, ...); 314 virtual status_t _Reserved_BMediaTrack_45(int32 arg, ...); 315 virtual status_t _Reserved_BMediaTrack_46(int32 arg, ...); 316 virtual status_t _Reserved_BMediaTrack_47(int32 arg, ...); 317 }; 318 319 #endif // _MEDIA_TRACK_H 320