1 /* 2 * GPAC - Multimedia Framework C SDK 3 * 4 * Authors: Jean Le Feuvre 5 * Copyright (c) Telecom ParisTech 2000-2019 6 * All rights reserved 7 * 8 * This file is part of GPAC / ISO Media File Format sub-project 9 * 10 * GPAC is free software; you can redistribute it and/or modify 11 * it under the terms of the GNU Lesser General Public License as published by 12 * the Free Software Foundation; either version 2, or (at your option) 13 * any later version. 14 * 15 * GPAC is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 * GNU Lesser General Public License for more details. 19 * 20 * You should have received a copy of the GNU Lesser General Public 21 * License along with this library; see the file COPYING. If not, write to 22 * the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. 23 * 24 */ 25 26 27 28 #ifndef _GF_ISOMEDIA_H_ 29 #define _GF_ISOMEDIA_H_ 30 31 32 #ifdef __cplusplus 33 extern "C" { 34 #endif 35 36 /*! 37 \file <gpac/isomedia.h> 38 \brief ISOBMFF parsing and writing library. 39 */ 40 41 /*! 42 \addtogroup iso_grp ISO Base Media File 43 \brief ISOBMF, 3GPP, AVC and HEVC file format utilities. 44 45 This section documents the reading and writing of ISOBMF (MP4, 3GPP, AVC, HEVC HEIF ...) 46 The library supports: 47 - regular movie read 48 - regular movie write 49 - fragmented movie and movie segments read 50 - fragmented movie and movie segments write 51 - QT support 52 - Sample descriptions for most common media found in such files (audio, video, text and subtitles) 53 - Meta and HEIF read 54 - Meta and HEIF write 55 - Common Encryption ISMA E&A and OMA DRM support 56 - MPEG-4 Systems extensions 57 58 59 All the READ function in this API can be used in EDIT/WRITE mode. 60 However, some unexpected errors or values may happen in that case, depending 61 on how much modifications you made (timing, track with 0 samples, ...). 62 On the other hand, none of the EDIT/WRITE functions will work in READ mode. 63 64 The output structure of a edited file will sometimes be different 65 from the original file, but the media-data and meta-data will be identical. 66 The only change happens in the file media-data container(s) during edition 67 68 When editing the file, you MUST set the final name of the modified file 69 to something different. This API doesn't allow file overwriting. 70 71 @{ 72 */ 73 74 #include <gpac/tools.h> 75 76 77 /*! Track reference types 78 79 Some track may depend on other tracks for several reasons. They reference these tracks through the following Reference Types 80 */ 81 enum 82 { 83 /*! ref type for the OD track dependencies*/ 84 GF_ISOM_REF_OD = GF_4CC( 'm', 'p', 'o', 'd' ), 85 /*! ref type for stream dependencies*/ 86 GF_ISOM_REF_DECODE = GF_4CC( 'd', 'p', 'n', 'd' ), 87 /*! ref type for OCR (Object Clock Reference) dependencies*/ 88 GF_ISOM_REF_OCR = GF_4CC( 's', 'y', 'n', 'c' ), 89 /*! ref type for IPI (Intellectual Property Information) dependencies*/ 90 GF_ISOM_REF_IPI = GF_4CC( 'i', 'p', 'i', 'r' ), 91 /*! this track describes the referenced tr*/ 92 GF_ISOM_REF_META = GF_4CC( 'c', 'd', 's', 'c' ), 93 /*! ref type for Hint tracks*/ 94 GF_ISOM_REF_HINT = GF_4CC( 'h', 'i', 'n', 't' ), 95 /*! ref type for QT Chapter tracks*/ 96 GF_ISOM_REF_CHAP = GF_4CC( 'c', 'h', 'a', 'p' ), 97 /*! ref type for the SVC and SHVC base tracks*/ 98 GF_ISOM_REF_BASE = GF_4CC( 's', 'b', 'a', 's' ), 99 /*! ref type for the SVC and SHVC extractor reference tracks*/ 100 GF_ISOM_REF_SCAL = GF_4CC( 's', 'c', 'a', 'l' ), 101 /*! ref type for the SHVC tile base tracks*/ 102 GF_ISOM_REF_TBAS = GF_4CC( 't', 'b', 'a', 's' ), 103 /*! ref type for the SHVC tile tracks*/ 104 GF_ISOM_REF_SABT = GF_4CC( 's', 'a', 'b', 't' ), 105 /*! ref type for the SHVC oinf track*/ 106 GF_ISOM_REF_OREF = GF_4CC( 'o', 'r', 'e', 'f' ), 107 /*! this track uses fonts carried/defined in the referenced track*/ 108 GF_ISOM_REF_FONT = GF_4CC( 'f', 'o', 'n', 't' ), 109 /*! this track depends on the referenced hint track, i.e., it should only be used if the referenced hint track is used.*/ 110 GF_ISOM_REF_HIND = GF_4CC( 'h', 'i', 'n', 'd' ), 111 /*! this track contains auxiliary depth video information for the referenced video track*/ 112 GF_ISOM_REF_VDEP = GF_4CC( 'v', 'd', 'e', 'p' ), 113 /*! this track contains auxiliary parallax video information for the referenced video track*/ 114 GF_ISOM_REF_VPLX = GF_4CC( 'v', 'p', 'l', 'x' ), 115 /*! this track contains subtitle, timed text or overlay graphical information for the referenced track or any track in the alternate group to which the track belongs, if any*/ 116 GF_ISOM_REF_SUBT = GF_4CC( 's', 'u', 'b', 't' ), 117 /*! thumbnail track*/ 118 GF_ISOM_REF_THUMB = GF_4CC( 't', 'h', 'm', 'b' ), 119 /*DRC*/ 120 /*! additional audio track*/ 121 GF_ISOM_REF_ADDA = GF_4CC( 'a', 'd', 'd', 'a' ), 122 /*! DRC metadata*/ 123 GF_ISOM_REF_ADRC = GF_4CC( 'a', 'd', 'r', 'c' ), 124 /*! item->track location*/ 125 GF_ISOM_REF_ILOC = GF_4CC( 'i', 'l', 'o', 'c' ), 126 /*! AVC dep stream*/ 127 GF_ISOM_REF_AVCP = GF_4CC( 'a', 'v', 'c', 'p' ), 128 /*! AVC switch to*/ 129 GF_ISOM_REF_SWTO = GF_4CC( 's', 'w', 't', 'o' ), 130 /*! AVC switch from*/ 131 GF_ISOM_REF_SWFR = GF_4CC( 's', 'w', 'f', 'r' ), 132 133 /*! Time code*/ 134 GF_ISOM_REF_TMCD = GF_4CC( 't', 'm', 'c', 'd' ), 135 /*! Structural dependency*/ 136 GF_ISOM_REF_CDEP = GF_4CC( 'c', 'd', 'e', 'p' ), 137 /*! transcript*/ 138 GF_ISOM_REF_SCPT = GF_4CC( 's', 'c', 'p', 't' ), 139 /*! nonprimary source description*/ 140 GF_ISOM_REF_SSRC = GF_4CC( 's', 's', 'r', 'c' ), 141 /*! layer audio track dependency*/ 142 GF_ISOM_REF_LYRA = GF_4CC( 'l', 'y', 'r', 'a' ), 143 /*! File Delivery Item Information Extension */ 144 GF_ISOM_REF_FDEL = GF_4CC( 'f', 'd', 'e', 'l' ), 145 /*! Track fragment inherit */ 146 GF_ISOM_REF_TRIN = GF_4CC( 't', 'r', 'i', 'n' ), 147 }; 148 149 /*! Track Edit list type*/ 150 typedef enum { 151 /*! empty segment in the track (no media for this segment)*/ 152 GF_ISOM_EDIT_EMPTY = 0x00, 153 /*! dwelled segment in the track (one media sample for this segment)*/ 154 GF_ISOM_EDIT_DWELL = 0x01, 155 /*! normal segment in the track*/ 156 GF_ISOM_EDIT_NORMAL = 0x02 157 } GF_ISOEditType; 158 159 /*! Generic Media Types (YOU HAVE TO USE ONE OF THESE TYPES FOR COMPLIANT ISO MEDIA FILES)*/ 160 enum 161 { 162 /*base media types*/ 163 GF_ISOM_MEDIA_VISUAL = GF_4CC( 'v', 'i', 'd', 'e' ), 164 GF_ISOM_MEDIA_AUXV = GF_4CC( 'a', 'u', 'x', 'v' ), 165 GF_ISOM_MEDIA_PICT = GF_4CC( 'p', 'i', 'c', 't' ), 166 GF_ISOM_MEDIA_AUDIO = GF_4CC( 's', 'o', 'u', 'n' ), 167 GF_ISOM_MEDIA_HINT = GF_4CC( 'h', 'i', 'n', 't' ), 168 GF_ISOM_MEDIA_META = GF_4CC( 'm', 'e', 't', 'a' ), 169 GF_ISOM_MEDIA_TEXT = GF_4CC( 't', 'e', 'x', 't' ), 170 /*subtitle code point used on ipod - same as text*/ 171 GF_ISOM_MEDIA_SUBT = GF_4CC( 's', 'b', 't', 'l' ), 172 GF_ISOM_MEDIA_SUBPIC = GF_4CC( 's', 'u', 'b', 'p' ), 173 GF_ISOM_MEDIA_MPEG_SUBT = GF_4CC( 's', 'u', 'b', 't' ), 174 /*closed caption track types for QT/ProRes*/ 175 GF_ISOM_MEDIA_CLOSED_CAPTION = GF_4CC( 'c', 'l', 'c', 'p' ), 176 /*timecode metadata for QT/ProRes*/ 177 GF_ISOM_MEDIA_TIMECODE = GF_4CC( 't', 'm', 'c', 'd' ), 178 /*MPEG-4 media types*/ 179 GF_ISOM_MEDIA_OD = GF_4CC( 'o', 'd', 's', 'm' ), 180 GF_ISOM_MEDIA_OCR = GF_4CC( 'c', 'r', 's', 'm' ), 181 GF_ISOM_MEDIA_SCENE = GF_4CC( 's', 'd', 's', 'm' ), 182 GF_ISOM_MEDIA_MPEG7 = GF_4CC( 'm', '7', 's', 'm' ), 183 GF_ISOM_MEDIA_OCI = GF_4CC( 'o', 'c', 's', 'm' ), 184 GF_ISOM_MEDIA_IPMP = GF_4CC( 'i', 'p', 's', 'm' ), 185 GF_ISOM_MEDIA_MPEGJ = GF_4CC( 'm', 'j', 's', 'm' ), 186 /*GPAC-defined, for any track using MPEG-4 systems signaling but with undefined streaml types*/ 187 GF_ISOM_MEDIA_ESM = GF_4CC( 'g', 'e', 's', 'm' ), 188 /*DIMS media type (same as scene but with a different mediaInfo)*/ 189 GF_ISOM_MEDIA_DIMS = GF_4CC( 'd', 'i', 'm', 's' ), 190 /*SWF file embedded in media track*/ 191 GF_ISOM_MEDIA_FLASH = GF_4CC( 'f', 'l', 's', 'h' ), 192 /*QTVR track*/ 193 GF_ISOM_MEDIA_QTVR = GF_4CC( 'q', 't', 'v', 'r' ), 194 GF_ISOM_MEDIA_JPEG = GF_4CC( 'j', 'p', 'e', 'g' ), 195 GF_ISOM_MEDIA_JP2 = GF_4CC( 'j', 'p', '2', ' ' ), 196 GF_ISOM_MEDIA_PNG = GF_4CC( 'p', 'n', 'g', ' ' ), 197 GF_ISOM_MEDIA_TMCD = GF_4CC( 't', 'm', 'c', 'd' ), 198 }; 199 200 201 /*! specific media sub-types - you shall make sure the media sub type is what you expect*/ 202 enum 203 { 204 /*reserved, internal use in the lib. Indicates the track complies to MPEG-4 system 205 specification, and the usual OD framework tools may be used*/ 206 GF_ISOM_SUBTYPE_MPEG4 = GF_4CC( 'M', 'P', 'E', 'G' ), 207 208 /*reserved, internal use in the lib. Indicates the track is of GF_ISOM_SUBTYPE_MPEG4 209 but it is encrypted.*/ 210 GF_ISOM_SUBTYPE_MPEG4_CRYP = GF_4CC( 'E', 'N', 'C', 'M' ), 211 212 /*AVC/H264 media type - not listed as an MPEG-4 type, ALTHOUGH this library automatically remaps 213 GF_AVCConfig to MPEG-4 ESD*/ 214 GF_ISOM_SUBTYPE_AVC_H264 = GF_4CC( 'a', 'v', 'c', '1' ), 215 GF_ISOM_SUBTYPE_AVC2_H264 = GF_4CC( 'a', 'v', 'c', '2' ), 216 GF_ISOM_SUBTYPE_AVC3_H264 = GF_4CC( 'a', 'v', 'c', '3' ), 217 GF_ISOM_SUBTYPE_AVC4_H264 = GF_4CC( 'a', 'v', 'c', '4' ), 218 GF_ISOM_SUBTYPE_SVC_H264 = GF_4CC( 's', 'v', 'c', '1' ), 219 GF_ISOM_SUBTYPE_MVC_H264 = GF_4CC( 'm', 'v', 'c', '1' ), 220 221 /*HEVC media type*/ 222 GF_ISOM_SUBTYPE_HVC1 = GF_4CC( 'h', 'v', 'c', '1' ), 223 GF_ISOM_SUBTYPE_HEV1 = GF_4CC( 'h', 'e', 'v', '1' ), 224 GF_ISOM_SUBTYPE_HVC2 = GF_4CC( 'h', 'v', 'c', '2' ), 225 GF_ISOM_SUBTYPE_HEV2 = GF_4CC( 'h', 'e', 'v', '2' ), 226 GF_ISOM_SUBTYPE_LHV1 = GF_4CC( 'l', 'h', 'v', '1' ), 227 GF_ISOM_SUBTYPE_LHE1 = GF_4CC( 'l', 'h', 'e', '1' ), 228 GF_ISOM_SUBTYPE_HVT1 = GF_4CC( 'h', 'v', 't', '1' ), 229 230 /*AV1 media type*/ 231 GF_ISOM_SUBTYPE_AV01 = GF_4CC('a', 'v', '0', '1'), 232 233 /*Opus media type*/ 234 GF_ISOM_SUBTYPE_OPUS = GF_4CC('O', 'p', 'u', 's'), 235 GF_ISOM_SUBTYPE_FLAC = GF_4CC( 'f', 'L', 'a', 'C' ), 236 237 /* VP */ 238 GF_ISOM_SUBTYPE_VP08 = GF_4CC('v', 'p', '0', '8'), 239 GF_ISOM_SUBTYPE_VP09 = GF_4CC('v', 'p', '0', '9'), 240 GF_ISOM_SUBTYPE_VP10 = GF_4CC('v', 'p', '1', '0'), 241 242 /* Dolby Vision */ 243 GF_ISOM_SUBTYPE_DVHE = GF_4CC('d', 'v', 'h', 'e'), 244 245 /*3GPP(2) extension subtypes*/ 246 GF_ISOM_SUBTYPE_3GP_H263 = GF_4CC( 's', '2', '6', '3' ), 247 GF_ISOM_SUBTYPE_3GP_AMR = GF_4CC( 's', 'a', 'm', 'r' ), 248 GF_ISOM_SUBTYPE_3GP_AMR_WB = GF_4CC( 's', 'a', 'w', 'b' ), 249 GF_ISOM_SUBTYPE_3GP_EVRC = GF_4CC( 's', 'e', 'v', 'c' ), 250 GF_ISOM_SUBTYPE_3GP_QCELP = GF_4CC( 's', 'q', 'c', 'p' ), 251 GF_ISOM_SUBTYPE_3GP_SMV = GF_4CC( 's', 's', 'm', 'v' ), 252 253 /*3GPP DIMS*/ 254 GF_ISOM_SUBTYPE_3GP_DIMS = GF_4CC( 'd', 'i', 'm', 's' ), 255 256 GF_ISOM_SUBTYPE_AC3 = GF_4CC( 'a', 'c', '-', '3' ), 257 GF_ISOM_SUBTYPE_EC3 = GF_4CC( 'e', 'c', '-', '3' ), 258 GF_ISOM_SUBTYPE_MP3 = GF_4CC( '.', 'm', 'p', '3' ), 259 GF_ISOM_SUBTYPE_MP4A = GF_4CC( 'm', 'p', '4', 'a' ), 260 GF_ISOM_SUBTYPE_MP4S = GF_4CC( 'm', 'p', '4', 's' ), 261 262 GF_ISOM_SUBTYPE_LSR1 = GF_4CC( 'l', 's', 'r', '1' ), 263 GF_ISOM_SUBTYPE_WVTT = GF_4CC( 'w', 'v', 't', 't' ), 264 GF_ISOM_SUBTYPE_STXT = GF_4CC( 's', 't', 'x', 't' ), 265 GF_ISOM_SUBTYPE_STPP = GF_4CC( 's', 't', 'p', 'p' ), 266 GF_ISOM_SUBTYPE_SBTT = GF_4CC( 's', 'b', 't', 't' ), 267 GF_ISOM_SUBTYPE_METT = GF_4CC( 'm', 'e', 't', 't' ), 268 GF_ISOM_SUBTYPE_METX = GF_4CC( 'm', 'e', 't', 'x' ), 269 GF_ISOM_SUBTYPE_TX3G = GF_4CC( 't', 'x', '3', 'g' ), 270 GF_ISOM_SUBTYPE_TEXT = GF_4CC( 't', 'e', 'x', 't' ), 271 272 273 GF_ISOM_SUBTYPE_RTP = GF_4CC( 'r', 't', 'p', ' ' ), 274 GF_ISOM_SUBTYPE_SRTP = GF_4CC( 's', 'r', 't', 'p' ), 275 GF_ISOM_SUBTYPE_RRTP = GF_4CC( 'r', 'r', 't', 'p' ), 276 GF_ISOM_SUBTYPE_RTCP = GF_4CC( 'r', 't', 'c', 'p' ), 277 GF_ISOM_SUBTYPE_FLUTE = GF_4CC( 'f', 'd', 'p', ' ' ), 278 279 /* Apple XDCAM */ 280 GF_ISOM_SUBTYPE_XDVB = GF_4CC( 'x', 'd', 'v', 'b' ), 281 282 GF_ISOM_SUBTYPE_H263 = GF_4CC( 'h', '2', '6', '3' ), 283 284 GF_ISOM_SUBTYPE_JPEG = GF_4CC( 'j', 'p', 'e', 'g' ), 285 GF_ISOM_SUBTYPE_PNG = GF_4CC( 'p', 'n', 'g', ' ' ), 286 GF_ISOM_SUBTYPE_MJP2 = GF_4CC( 'm', 'j', 'p', '2' ), 287 GF_ISOM_SUBTYPE_JP2K = GF_4CC('j','p','2','k'), 288 289 GF_ISOM_SUBTYPE_MH3D_MHA1 = GF_4CC( 'm', 'h', 'a', '1' ), 290 GF_ISOM_SUBTYPE_MH3D_MHA2 = GF_4CC( 'm', 'h', 'a', '2' ), 291 GF_ISOM_SUBTYPE_MH3D_MHM1 = GF_4CC( 'm', 'h', 'm', '1' ), 292 GF_ISOM_SUBTYPE_MH3D_MHM2 = GF_4CC( 'm', 'h', 'm', '2' ), 293 294 GF_ISOM_SUBTYPE_IPCM = GF_4CC( 'i', 'p', 'c', 'm' ), 295 GF_ISOM_SUBTYPE_FPCM = GF_4CC( 'f', 'p', 'c', 'm' ), 296 297 /* on-screen colours */ 298 GF_ISOM_SUBTYPE_NCLX = GF_4CC( 'n', 'c', 'l', 'x' ), 299 GF_ISOM_SUBTYPE_NCLC = GF_4CC( 'n', 'c', 'l', 'c' ), 300 GF_ISOM_SUBTYPE_PROF = GF_4CC( 'p', 'r', 'o', 'f' ), 301 GF_ISOM_SUBTYPE_RICC = GF_4CC( 'r', 'I', 'C', 'C' ), 302 303 /* QT audio codecs */ 304 GF_QT_SUBTYPE_RAW = GF_4CC('r','a','w',' '), 305 GF_QT_SUBTYPE_TWOS = GF_4CC('t','w','o','s'), 306 GF_QT_SUBTYPE_SOWT = GF_4CC('s','o','w','t'), 307 GF_QT_SUBTYPE_FL32 = GF_4CC('f','l','3','2'), 308 GF_QT_SUBTYPE_FL64 = GF_4CC('f','l','6','4'), 309 GF_QT_SUBTYPE_IN24 = GF_4CC('i','n','2','4'), 310 GF_QT_SUBTYPE_IN32 = GF_4CC('i','n','3','2'), 311 GF_QT_SUBTYPE_ULAW = GF_4CC('u','l','a','w'), 312 GF_QT_SUBTYPE_ALAW = GF_4CC('a','l','a','w'), 313 GF_QT_SUBTYPE_ADPCM = GF_4CC(0x6D,0x73,0x00,0x02), 314 GF_QT_SUBTYPE_IMA_ADPCM = GF_4CC(0x6D,0x73,0x00,0x11), 315 GF_QT_SUBTYPE_DVCA = GF_4CC('d','v','c','a'), 316 GF_QT_SUBTYPE_QDMC = GF_4CC('Q','D','M','C'), 317 GF_QT_SUBTYPE_QDMC2 = GF_4CC('Q','D','M','2'), 318 GF_QT_SUBTYPE_QCELP = GF_4CC('Q','c','l','p'), 319 GF_QT_SUBTYPE_kMP3 = GF_4CC(0x6D,0x73,0x00,0x55), 320 321 /* QT video codecs */ 322 GF_QT_SUBTYPE_C608 = GF_4CC( 'c', '6', '0', '8' ), 323 GF_QT_SUBTYPE_APCH = GF_4CC( 'a', 'p', 'c', 'h' ), 324 GF_QT_SUBTYPE_APCO = GF_4CC( 'a', 'p', 'c', 'o' ), 325 GF_QT_SUBTYPE_APCN = GF_4CC( 'a', 'p', 'c', 'n' ), 326 GF_QT_SUBTYPE_APCS = GF_4CC( 'a', 'p', 'c', 's' ), 327 GF_QT_SUBTYPE_AP4X = GF_4CC( 'a', 'p', '4', 'x' ), 328 GF_QT_SUBTYPE_AP4H = GF_4CC( 'a', 'p', '4', 'h' ), 329 GF_QT_SUBTYPE_YUV422 = GF_4CC('y','u','v','2'), 330 // GF_QT_SUBTYPE_YUV422 = GF_4CC('2','v','u','Y'), 331 GF_QT_SUBTYPE_YUV444 = GF_4CC('v','3','0','8'), 332 GF_QT_SUBTYPE_YUV422_10 = GF_4CC('v','2','1','0'), 333 GF_QT_SUBTYPE_YUV444_10 = GF_4CC('v','4','1','0'), 334 }; 335 336 337 338 339 /*! direction for sample search (including SyncSamples search) 340 Function using search allways specify the desired time in composition (presentation) time 341 (Sample N-1) DesiredTime (Sample N) 342 */ 343 typedef enum 344 { 345 /*! FORWARD: will give the next sample given the desired time (eg, N)*/ 346 GF_ISOM_SEARCH_FORWARD = 1, 347 /*! BACKWARD: will give the previous sample given the desired time (eg, N-1)*/ 348 GF_ISOM_SEARCH_BACKWARD = 2, 349 /*! SYNCFORWARD: will search from the desired point in time for a sync sample if any. If no sync info, behaves as FORWARD*/ 350 GF_ISOM_SEARCH_SYNC_FORWARD = 3, 351 /*! SYNCBACKWARD: will search till the desired point in time for a sync sample if any. If no sync info, behaves as BACKWARD*/ 352 GF_ISOM_SEARCH_SYNC_BACKWARD = 4, 353 /*! SYNCSHADOW: use the sync shadow information to retrieve the sample. If no SyncShadow info, behave as SYNCBACKWARD 354 \warning deprecated in ISOBMFF*/ 355 GF_ISOM_SEARCH_SYNC_SHADOW = 5 356 } GF_ISOSearchMode; 357 358 /*! Predefined File Brand codes (MPEG-4 and JPEG2000)*/ 359 enum 360 { 361 /*file complying to the generic ISO Media File (base specification ISO/IEC 14496-12) 362 this is the default brand when creating a new movie*/ 363 GF_ISOM_BRAND_ISOM = GF_4CC( 'i', 's', 'o', 'm' ), 364 /*file complying to the generic ISO Media File (base specification ISO/IEC 14496-12) + Meta extensions*/ 365 GF_ISOM_BRAND_ISO2 = GF_4CC( 'i', 's', 'o', '2' ), 366 /*file complying to ISO/IEC 14496-1 2001 edition. A .mp4 file without a brand 367 is equivalent to a file compatible with this brand*/ 368 GF_ISOM_BRAND_MP41 = GF_4CC( 'm', 'p', '4', '1' ), 369 /*file complying to ISO/IEC 14496-14 (MP4 spec)*/ 370 GF_ISOM_BRAND_MP42 = GF_4CC( 'm', 'p', '4', '2' ), 371 /*file complying to ISO/IEC 15444-3 (JPEG2000) without profile restriction*/ 372 GF_ISOM_BRAND_MJP2 = GF_4CC( 'm', 'j', 'p', '2' ), 373 /*file complying to ISO/IEC 15444-3 (JPEG2000) with simple profile restriction*/ 374 GF_ISOM_BRAND_MJ2S = GF_4CC( 'm', 'j', '2', 's' ), 375 /*old versions of 3GPP spec (without timed text)*/ 376 GF_ISOM_BRAND_3GP4 = GF_4CC('3', 'g', 'p', '4'), 377 GF_ISOM_BRAND_3GP5 = GF_4CC('3', 'g', 'p', '5'), 378 /*final version of 3GPP file spec*/ 379 GF_ISOM_BRAND_3GP6 = GF_4CC('3', 'g', 'p', '6'), 380 /*generci 3GPP file (several audio tracks, etc..)*/ 381 GF_ISOM_BRAND_3GG5 = GF_4CC('3', 'g', 'g', '5'), 382 GF_ISOM_BRAND_3GG6 = GF_4CC('3', 'g', 'g', '6'), 383 /*3GPP2 file spec*/ 384 GF_ISOM_BRAND_3G2A = GF_4CC('3', 'g', '2', 'a'), 385 /*AVC file spec*/ 386 GF_ISOM_BRAND_AVC1 = GF_4CC('a', 'v', 'c', '1'), 387 /* file complying to ISO/IEC 21000-9:2005 (MPEG-21 spec)*/ 388 GF_ISOM_BRAND_MP21 = GF_4CC('m', 'p', '2', '1'), 389 /*file complying to the generic ISO Media File (base specification ISO/IEC 14496-12) + support for version 1*/ 390 GF_ISOM_BRAND_ISO4 = GF_4CC( 'i', 's', 'o', '4' ), 391 /* Image File Format */ 392 GF_ISOM_BRAND_MIF1 = GF_4CC('m', 'i', 'f', '1'), 393 GF_ISOM_BRAND_HEIC = GF_4CC('h', 'e', 'i', 'c'), 394 GF_ISOM_BRAND_HEIM = GF_4CC('h', 'e', 'i', 'm'), 395 GF_ISOM_BRAND_AVIF = GF_4CC('a', 'v', 'i', 'f'), 396 GF_ISOM_BRAND_AVCI = GF_4CC('a', 'v', 'c', 'i'), 397 /*other iso media brands */ 398 GF_ISOM_BRAND_ISO1 = GF_4CC( 'i', 's', 'o', '1' ), 399 GF_ISOM_BRAND_ISO3 = GF_4CC( 'i', 's', 'o', '3' ), 400 GF_ISOM_BRAND_ISO5 = GF_4CC( 'i', 's', 'o', '5' ), 401 GF_ISOM_BRAND_ISO6 = GF_4CC( 'i', 's', 'o', '6' ), 402 GF_ISOM_BRAND_ISO7 = GF_4CC( 'i', 's', 'o', '7' ), 403 GF_ISOM_BRAND_ISO8 = GF_4CC( 'i', 's', 'o', '8' ), 404 GF_ISOM_BRAND_ISO9 = GF_4CC( 'i', 's', 'o', '9' ), 405 GF_ISOM_BRAND_ISOA = GF_4CC( 'i', 's', 'o', 'a' ), 406 407 /* QT brand*/ 408 GF_ISOM_BRAND_QT = GF_4CC( 'q', 't', ' ', ' ' ), 409 410 /* JPEG 2000 Image (.JP2) [ISO 15444-1] */ 411 GF_ISOM_BRAND_JP2 = GF_4CC( 'j', 'p', '2', ' ' ), 412 413 /* MPEG-4 (.MP4) for SonyPSP */ 414 GF_ISOM_BRAND_MSNV = GF_4CC( 'M', 'S', 'N', 'V' ), 415 /* Apple iTunes AAC-LC (.M4A) Audio */ 416 GF_ISOM_BRAND_M4A = GF_4CC( 'M', '4', 'A', ' ' ), 417 /* Apple iTunes Video (.M4V) Video */ 418 GF_ISOM_BRAND_M4V = GF_4CC( 'M', '4', 'V', ' ' ), 419 420 GF_ISOM_BRAND_HVCE = GF_4CC( 'h', 'v', 'c', 'e' ), 421 GF_ISOM_BRAND_HVCI = GF_4CC( 'h', 'v', 'c', 'i' ), 422 GF_ISOM_BRAND_HVTI = GF_4CC( 'h', 'v', 't', 'i' ), 423 424 425 GF_ISOM_BRAND_AV01 = GF_4CC( 'a', 'v', '0', '1'), 426 427 GF_ISOM_BRAND_OPUS = GF_4CC( 'O', 'p', 'u', 's'), 428 429 GF_ISOM_BRAND_ISMA = GF_4CC( 'I', 'S', 'M', 'A' ), 430 431 /* dash related brands (ISO/IEC 23009-1) */ 432 GF_ISOM_BRAND_DASH = GF_4CC('d','a','s','h'), 433 /* Media Segment conforming to the DASH Self-Initializing Media Segment format type */ 434 GF_ISOM_BRAND_DSMS = GF_4CC('d','s','m','s'), 435 /* Media Segment conforming to the general format type */ 436 GF_ISOM_BRAND_MSDH = GF_4CC('m','s','d','h'), 437 /* Media Segment conforming to the Indexed Media Segment format type */ 438 GF_ISOM_BRAND_MSIX = GF_4CC('m','s','i','x'), 439 /* Representation Index Segment used to index MPEG-2 TS based Media Segments */ 440 GF_ISOM_BRAND_RISX = GF_4CC('r','i','s','x'), 441 /* last Media Segment indicator for ISO base media file format */ 442 GF_ISOM_BRAND_LMSG = GF_4CC('l','m','s','g'), 443 /* Single Index Segment used to index MPEG-2 TS based Media Segments */ 444 GF_ISOM_BRAND_SISX = GF_4CC('s','i','s','x'), 445 /* Subsegment Index Segment used to index MPEG-2 TS based Media Segments */ 446 GF_ISOM_BRAND_SSSS = GF_4CC('s','s','s','s'), 447 448 449 /* from ismacryp.c */ 450 /* OMA DCF DRM Format 2.0 (OMA-TS-DRM-DCF-V2_0-20060303-A) */ 451 GF_ISOM_BRAND_ODCF = GF_4CC('o','d','c','f'), 452 /* OMA PDCF DRM Format 2.1 (OMA-TS-DRM-DCF-V2_1-20070724-C) */ 453 GF_ISOM_BRAND_OPF2 = GF_4CC('o','p','f','2'), 454 455 }; 456 457 #ifndef GPAC_DISABLE_ISOM 458 459 #include <gpac/mpeg4_odf.h> 460 461 /*! isomedia file*/ 462 typedef struct __tag_isom GF_ISOFile; 463 464 /*! a track ID value - just a 32 bit value but typedefed for API safety*/ 465 typedef u32 GF_ISOTrackID; 466 467 /*! @} */ 468 469 /*! 470 \addtogroup isosample_grp ISO Sample 471 \ingroup iso_grp 472 473 Media sample for ISOBMFF API. 474 @{ 475 */ 476 477 /*! Random Access Point flag*/ 478 typedef enum { 479 /*! redundant sync shadow - only set when reading sample*/ 480 RAP_REDUNDANT = -1, 481 /*! not rap*/ 482 RAP_NO = 0, 483 /*! sync point (IDR)*/ 484 RAP = 1, 485 /*! sync point (IDR)*/ 486 SAP_TYPE_1 = 1, 487 /*! sync point (IDR)*/ 488 SAP_TYPE_2 = 2, 489 /*! RAP, OpenGOP*/ 490 SAP_TYPE_3 = 3, 491 /*! RAP, roll info (GDR or audio preroll)*/ 492 SAP_TYPE_4 = 4, 493 } GF_ISOSAPType; 494 495 /*! media sample object*/ 496 typedef struct 497 { 498 /*! data size*/ 499 u32 dataLength; 500 /*! data with padding if requested*/ 501 u8 *data; 502 /*! decoding time*/ 503 u64 DTS; 504 /*! relative offset for composition if needed*/ 505 s32 CTS_Offset; 506 /*! SAP type*/ 507 GF_ISOSAPType IsRAP; 508 /*! allocated data size - used only when using static sample in \ref gf_isom_get_sample_ex*/ 509 u32 alloc_size; 510 511 /*! number of packed samples in this sample. If 0 or 1, only 1 sample is present 512 only used for constant size and constant duration samples*/ 513 u32 nb_pack; 514 } GF_ISOSample; 515 516 517 /*! creates a new empty sample 518 \return the newly allocated ISO sample*/ 519 GF_ISOSample *gf_isom_sample_new(); 520 521 /*! delete a sample. NOTE:the buffer content will be destroyed by default. 522 if you wish to keep the buffer, set dataLength to 0 in the sample 523 before deleting it 524 the pointer is set to NULL after deletion 525 \param samp pointer to the target ISO sample 526 */ 527 void gf_isom_sample_del(GF_ISOSample **samp); 528 529 530 /*! @} */ 531 532 /*! 533 \addtogroup isogen_grp Generic API 534 \ingroup iso_grp 535 536 Generic API functions 537 @{ 538 */ 539 540 /*! Movie file opening modes */ 541 typedef enum 542 { 543 /*! Opens file for dumping: same as read-only but keeps all movie fragments info untouched*/ 544 GF_ISOM_OPEN_READ_DUMP = 0, 545 /*! Opens a file in READ ONLY mode*/ 546 GF_ISOM_OPEN_READ, 547 /*! Opens a file in WRITE ONLY mode. Media Data is captured on the fly and storage mode is always flat (moov at end). 548 In this mode, the editing functions are disabled.*/ 549 GF_ISOM_OPEN_WRITE, 550 /*! Opens an existing file in EDIT mode*/ 551 GF_ISOM_OPEN_EDIT, 552 /*! Creates a new file in EDIT mode*/ 553 GF_ISOM_WRITE_EDIT, 554 /*! Opens an existing file and keep fragment information*/ 555 GF_ISOM_OPEN_KEEP_FRAGMENTS, 556 } GF_ISOOpenMode; 557 558 /*! indicates if target file is an IsoMedia file 559 \param fileName the target local file name or path to probe, gmem:// or gfio:// resource 560 \return 1 if it is a non-special file, 2 if an init segment, 3 if a media segment, 0 otherwise 561 */ 562 u32 gf_isom_probe_file(const char *fileName); 563 564 /*! indicates if target file is an IsoMedia file 565 \param fileName the target local file name or path to probe, gmem:// or gfio:// resource 566 \param start_range the offset in the file to start probing from 567 \param end_range the offset in the file at which probing shall stop 568 \return 1 if it is a non-special file, 2 if an init segment, 3 if a media segment, 4 if empty or no file, 0 otherwise 569 */ 570 u32 gf_isom_probe_file_range(const char *fileName, u64 start_range, u64 end_range); 571 572 /*! indicates if target file is an IsoMedia file 573 \param inBuf the buffer to probe 574 \param inSize the sizeo of the buffer to probe 575 \returns 1 if it is a non-special file, 2 if an init segment, 3 if a media segment, 0 otherwise (non recognized or too short) 576 */ 577 u32 gf_isom_probe_data(const u8*inBuf, u32 inSize); 578 579 /*! opens an isoMedia File. 580 If fileName is NULL data will be written in memory ; write with gf_isom_write() ; use gf_isom_get_bs() to get the data ; use gf_isom_delete() to delete the internal data. 581 \param fileName name of the file to open, , gmem:// or gfio:// resource. The special name "_gpac_isobmff_redirect" is used to indicate that segment shall be written to a memory buffer passed to callback function set through \ref gf_isom_set_write_callback. 582 \param OpenMode file opening mode 583 \param tmp_dir for the 2 edit modes only, specifies a location for temp file. If NULL, the library will use the default 584 OS temporary file management schemes. 585 \return the created ISO file if no error 586 */ 587 GF_ISOFile *gf_isom_open(const char *fileName, GF_ISOOpenMode OpenMode, const char *tmp_dir); 588 589 /*! closes the file, write it if new/edited - equivalent to gf_isom_write()+gf_isom_delete() 590 \param isom_file the target ISO file 591 \return error if any 592 */ 593 GF_Err gf_isom_close(GF_ISOFile *isom_file); 594 595 /*! deletes the movie without saving it 596 \param isom_file the target ISO file 597 */ 598 void gf_isom_delete(GF_ISOFile *isom_file); 599 600 /*! gets the last fatal error that occured in the file 601 ANY FUNCTION OF THIS API WON'T BE PROCESSED IF THE FILE HAS AN ERROR 602 Note: some function may return an error while the movie has no error 603 the last error is a FatalError, and is not always set if a bad 604 param is specified... 605 \param isom_file the target ISO file 606 \return error if any 607 */ 608 GF_Err gf_isom_last_error(GF_ISOFile *isom_file); 609 610 /*! gets the mode of an open file 611 \param isom_file the target ISO file 612 \return open mode of the file 613 */ 614 u8 gf_isom_get_mode(GF_ISOFile *isom_file); 615 616 /*! checks if file is J2K image 617 \param isom_file the target ISO file 618 \return GF_TRUE if file is a j2k image, GF_FALSE otherwise 619 */ 620 Bool gf_isom_is_JPEG2000(GF_ISOFile *isom_file); 621 622 /*! gets file size of an ISO file 623 \param isom_file the target ISO file 624 \return the file size in bytes 625 */ 626 u64 gf_isom_get_file_size(GF_ISOFile *isom_file); 627 628 /*! checks if a given four character code matches a known video handler type (vide, auxv, pict, ...) 629 \param mtype the four character code to check 630 \return GF_TRUE if the type is a video media type*/ 631 Bool gf_isom_is_video_handler_type(u32 mtype); 632 633 /*! gets number of implemented boxes in (including the internal unknown box wrapper). 634 \note There can be several times the same type returned due to variation of the box (versions or flags) 635 \return number of implemented boxes 636 */ 637 u32 gf_isom_get_num_supported_boxes(); 638 639 /*! gets four character code of box given its index. Index 0 is GPAC internal unknown box handler 640 \param idx 0-based index of the box 641 \return four character code of the box 642 */ 643 u32 gf_isom_get_supported_box_type(u32 idx); 644 645 #ifndef GPAC_DISABLE_ISOM_DUMP 646 647 /*! prints default box syntax of box given its index. Index 0 is GPAC internal unknown box handler 648 \param idx 0-based index of the box 649 \param trace the file object to dump to 650 \return error if any 651 */ 652 GF_Err gf_isom_dump_supported_box(u32 idx, FILE * trace); 653 654 #endif 655 656 /*! @} */ 657 658 /*! 659 \addtogroup isoread_grp ISOBMFF Reading 660 \ingroup iso_grp 661 662 ISOBMF file reading 663 @{ 664 */ 665 666 /*! checks if moov box is before any mdat box 667 \param isom_file the target ISO file 668 \return GF_TRUE if if moov box is before any mdat box, GF_FALSE otherwise 669 */ 670 Bool gf_isom_moov_first(GF_ISOFile *isom_file); 671 672 /*! when reading a file, indicates that file data is missing the indicated bytes 673 \param isom_file the target ISO file 674 \param byte_offset number of bytes not present at the begining of the file 675 \return error if any 676 */ 677 GF_Err gf_isom_set_byte_offset(GF_ISOFile *isom_file, s64 byte_offset); 678 679 680 /*! opens a movie that can be uncomplete in READ_ONLY mode 681 to use for http streaming & co 682 683 start_range and end_range restricts the media byte range in the URL (used by DASH) 684 if 0 or end_range<=start_range, the entire URL is used when parsing 685 686 If the url indicates a gfio or gmem resource, the file can be played from the associated underlying buffer. For gmem, you must call \ref gf_isom_refresh_fragmented and gf_isom_set_removed_bytes whenever the underlying buffer is modified. 687 688 \param fileName the name of the local file or cache to open, gmem:// or gfio:// 689 \param start_range only loads starting from indicated byte range 690 \param end_range loading stops at indicated byte range 691 \param enable_frag_templates loads fragment and segment boundaries in an internal table 692 \param isom_file pointer set to the opened file if success 693 \param BytesMissing is set to the predicted number of bytes missing for the file to be loaded 694 Note that if the file is not optimized for streaming, this number is not accurate 695 If the movie is successfully loaded (isom_file non-NULL), BytesMissing is zero 696 \return error if any 697 */ 698 GF_Err gf_isom_open_progressive(const char *fileName, u64 start_range, u64 end_range, Bool enable_frag_templates, GF_ISOFile **isom_file, u64 *BytesMissing); 699 700 701 /*! same as \ref gf_isom_open_progressive but allows fetching the incomplete box type 702 703 \param fileName the name of the local file or cache to open 704 \param start_range only loads starting from indicated byte range 705 \param end_range loading stops at indicated byte range 706 \param enable_frag_templates loads fragment and segment boundaries in an internal table 707 \param isom_file pointer set to the opened file if success 708 \param BytesMissing is set to the predicted number of bytes missing for the file to be loaded 709 \param topBoxType is set to the 4CC of the incomplete top-level box found - may be NULL 710 Note that if the file is not optimized for streaming, this number is not accurate 711 If the movie is successfully loaded (isom_file non-NULL), BytesMissing is zero 712 \return error if any 713 */ 714 GF_Err gf_isom_open_progressive_ex(const char *fileName, u64 start_range, u64 end_range, Bool enable_frag_templates, GF_ISOFile **isom_file, u64 *BytesMissing, u32 *topBoxType); 715 716 /*! retrieves number of bytes missing. 717 if requesting a sample fails with error GF_ISOM_INCOMPLETE_FILE, use this function 718 to get the number of bytes missing to retrieve the sample 719 \param isom_file the target ISO file 720 \param trackNumber the desired track to query 721 \return the number of bytes missing to fetch the sample 722 */ 723 u64 gf_isom_get_missing_bytes(GF_ISOFile *isom_file, u32 trackNumber); 724 725 /*! checks if a file has movie info (moov box with tracks & dynamic media). Some files may just use 726 the base IsoMedia structure without "moov" container 727 \param isom_file the target ISO file 728 \return GF_TRUE if the file has a movie, GF_FALSE otherwise 729 */ 730 Bool gf_isom_has_movie(GF_ISOFile *isom_file); 731 732 /*! gets number of tracks 733 \param isom_file the target ISO file 734 \return the number of tracks in the movie, or -1 if error*/ 735 u32 gf_isom_get_track_count(GF_ISOFile *isom_file); 736 737 /*! gets the movie timescale 738 \param isom_file the target ISO file 739 \return the timescale of the movie, 0 if error*/ 740 u32 gf_isom_get_timescale(GF_ISOFile *isom_file); 741 742 /*! gets the movie duration computed based on media samples and edit lists 743 \param isom_file the target ISO file 744 \return the computed duration of the movie, 0 if error*/ 745 u64 gf_isom_get_duration(GF_ISOFile *isom_file); 746 747 /*! gets the original movie duration as written in the file, regardless of the media data 748 \param isom_file the target ISO file 749 \return the duration of the movie*/ 750 u64 gf_isom_get_original_duration(GF_ISOFile *isom_file); 751 752 /*! gets the creation info of the movie 753 \param isom_file the target ISO file 754 \param creationTime set to the creation time of the movie 755 \param modificationTime set to the modification time of the movie 756 \return error if any 757 */ 758 GF_Err gf_isom_get_creation_time(GF_ISOFile *isom_file, u64 *creationTime, u64 *modificationTime); 759 760 /*! gets the ID of a track 761 \param isom_file the target ISO file 762 \param trackNumber the target track 763 \return the trackID of the track, or 0 if error*/ 764 GF_ISOTrackID gf_isom_get_track_id(GF_ISOFile *isom_file, u32 trackNumber); 765 766 /*! gets a track number by its ID 767 \param isom_file the target ISO file 768 \param trackID the target track ID 769 \return the track number of the track, or 0 if error*/ 770 u32 gf_isom_get_track_by_id(GF_ISOFile *isom_file, GF_ISOTrackID trackID); 771 772 /*! gets the track original ID (before cloning from another file) 773 \param isom_file the target ISO file 774 \param trackNumber the target track 775 \return the original trackID of the track, or 0 if error*/ 776 GF_ISOTrackID gf_isom_get_track_original_id(GF_ISOFile *isom_file, u32 trackNumber); 777 778 /*! gets the enable flag of a track 779 \param isom_file the target ISO file 780 \param trackNumber the target track 781 \return 0: not enabled, 1: enabled, 2: error 782 */ 783 u8 gf_isom_is_track_enabled(GF_ISOFile *isom_file, u32 trackNumber); 784 785 /*! gets track flags 786 \param isom_file the target ISO file 787 \param trackNumber the target track 788 \return the track flags 789 */ 790 u32 gf_isom_get_track_flags(GF_ISOFile *isom_file, u32 trackNumber); 791 792 /*! gets the track duration 793 \param isom_file the target ISO file 794 \param trackNumber the target track 795 \return the track duration in movie timescale, or 0 if error*/ 796 u64 gf_isom_get_track_duration(GF_ISOFile *isom_file, u32 trackNumber); 797 798 /*! gets the media type (audio, video, etc) of a track 799 \param isom_file the target ISO file 800 \param trackNumber the target track 801 \return the media type four character code of the media*/ 802 u32 gf_isom_get_media_type(GF_ISOFile *isom_file, u32 trackNumber); 803 804 /*! gets media subtype of a sample description entry 805 \param isom_file the target ISO file 806 \param trackNumber the target track 807 \param sampleDescriptionIndex the target sample description index (1-based) 808 \return the media type four character code of the given sample description*/ 809 u32 gf_isom_get_media_subtype(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 810 811 /*! gets the composition time (media time) given the absolute time in the Movie 812 \param isom_file the target ISO file 813 \param trackNumber the target track 814 \param movieTime desired time in movie timescale 815 \param mediaTime is set to 0 if the media is not playing at that time (empty time segment) 816 \return error if any*/ 817 GF_Err gf_isom_get_media_time(GF_ISOFile *isom_file, u32 trackNumber, u32 movieTime, u64 *mediaTime); 818 819 /*! gets the number of sample descriptions in the media - a media can have several stream descriptions (eg different codec configurations, different protetcions, different visual sizes). 820 \param isom_file the target ISO file 821 \param trackNumber the target track 822 \return the number of sample descriptions 823 */ 824 u32 gf_isom_get_sample_description_count(GF_ISOFile *isom_file, u32 trackNumber); 825 826 /*! gets the stream description index for a given time in media time 827 \param isom_file the target ISO file 828 \param trackNumber the target track 829 \param for_time the desired time in media timescale 830 \return the sample description index, or 0 if error or if empty*/ 831 u32 gf_isom_get_sample_description_index(GF_ISOFile *isom_file, u32 trackNumber, u64 for_time); 832 833 /*! checks if a sample stream descritpion is self-contained (samples located in the file) 834 \param isom_file the target ISO file 835 \param trackNumber the target track 836 \param sampleDescriptionIndex the target sample description index (1-based) 837 \return GF_TRUE if samples refering to the given stream description are present in the file, GF_FALSE otherwise*/ 838 Bool gf_isom_is_self_contained(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 839 840 /*! gets the media duration (without edit) based on sample table 841 \param isom_file the target ISO file 842 \param trackNumber the target track 843 \return the media duration, 0 if no samples 844 */ 845 u64 gf_isom_get_media_duration(GF_ISOFile *isom_file, u32 trackNumber); 846 847 /*! gets the original media duration (without edit) as indicated in the file 848 \param isom_file the target ISO file 849 \param trackNumber the target track 850 \return the media duration 851 */ 852 u64 gf_isom_get_media_original_duration(GF_ISOFile *isom_file, u32 trackNumber); 853 854 /*! gets the media timescale 855 \param isom_file the target ISO file 856 \param trackNumber the target track 857 \return the timeScale of the media 858 */ 859 u32 gf_isom_get_media_timescale(GF_ISOFile *isom_file, u32 trackNumber); 860 861 /*! gets media chunking information for non-fragmented files 862 \param isom_file the target ISO file 863 \param trackNumber the target track 864 \param dur_min set to minimum chunk duration in media timescale (optional, can be NULL) 865 \param dur_avg set to average chunk duration in media timescale (optional, can be NULL) 866 \param dur_max set to maximum chunk duration in media timescale (optional, can be NULL) 867 \param size_min set to smallest chunk size in bytes (optional, can be NULL) 868 \param size_avg set to average chunk size in bytes (optional, can be NULL) 869 \param size_max set to largest chunk size in bytes (optional, can be NULL) 870 \return error if any 871 */ 872 GF_Err gf_isom_get_chunks_infos(GF_ISOFile *isom_file, u32 trackNumber, u32 *dur_min, u32 *dur_avg, u32 *dur_max, u32 *size_min, u32 *size_avg, u32 *size_max); 873 874 /*! gets the handler name. The outName must be: 875 \param isom_file the target ISO file 876 \param trackNumber the target track 877 \param outName set to the handler name (must be non NULL) 878 \return error if any 879 */ 880 GF_Err gf_isom_get_handler_name(GF_ISOFile *isom_file, u32 trackNumber, const char **outName); 881 882 /*! checks if the data reference for the given track and sample description is valid and supported 883 (a data Reference allows to construct a file without integrating the media data, however this library only handles local storage external data references) 884 \param isom_file the target ISO file 885 \param trackNumber the target track 886 \param sampleDescriptionIndex the target sample description index (1-based) 887 \return error if any 888 */ 889 GF_Err gf_isom_check_data_reference(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 890 891 /*! gets the location of the data. If both outURL and outURN are set to NULL, the data is in this file 892 \param isom_file the target ISO file 893 \param trackNumber the target track 894 \param sampleDescriptionIndex the target sample description index (1-based) 895 \param outURL set to URL value of the data reference 896 \param outURN set to URN value of the data reference 897 \return error if any 898 */ 899 GF_Err gf_isom_get_data_reference(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, const char **outURL, const char **outURN); 900 901 /*! gets the number of samples in a track 902 \param isom_file the target ISO file 903 \param trackNumber the target track 904 \return the number of samples, or 0 if error*/ 905 u32 gf_isom_get_sample_count(GF_ISOFile *isom_file, u32 trackNumber); 906 907 /*! gets the constant sample size for samples of a track 908 \param isom_file the target ISO file 909 \param trackNumber the target track 910 \return constant size of samples or 0 if size not constant 911 */ 912 u32 gf_isom_get_constant_sample_size(GF_ISOFile *isom_file, u32 trackNumber); 913 914 /*! gets the constant sample duration for samples of a track 915 \param isom_file the target ISO file 916 \param trackNumber the target track 917 \return constant duration of samples, or 0 if duration not constant*/ 918 u32 gf_isom_get_constant_sample_duration(GF_ISOFile *isom_file, u32 trackNumber); 919 920 /*! sets max audio sample packing in a single ISOSample. 921 This is mostly used when processing raw audio tracks, for which extracting samples per samples would be too time consuming 922 \param isom_file the target ISO file 923 \param trackNumber the target track 924 \param pack_num_samples the target number of samples to pack in one ISOSample 925 \return GF_TRUE if packing was successfull, GF_FALSE otherwise (non constant size and non constant duration) 926 */ 927 Bool gf_isom_enable_raw_pack(GF_ISOFile *isom_file, u32 trackNumber, u32 pack_num_samples); 928 929 /*! gets the total media data size of a track (whether in the file or not) 930 \param isom_file the target ISO file 931 \param trackNumber the target track 932 \return total amount of media bytes in track 933 */ 934 u64 gf_isom_get_media_data_size(GF_ISOFile *isom_file, u32 trackNumber); 935 936 /*! sets sample padding bytes when reading a sample 937 It may be desired to fetch samples with a bigger allocated buffer than their real size, in case the decoder 938 reads more data than available. This sets the amount of extra bytes to allocate when reading samples from this track 939 NOTE: the dataLength of the sample does NOT include padding 940 \param isom_file the target ISO file 941 \param trackNumber the target track 942 \param padding_bytes the amount of bytes to add at the end of a sample data buffer 943 \return error if any 944 */ 945 GF_Err gf_isom_set_sample_padding(GF_ISOFile *isom_file, u32 trackNumber, u32 padding_bytes); 946 947 /*! fetches a sample from a track. The sample must be destroyed using \ref gf_isom_sample_del 948 \param isom_file the target ISO file 949 \param trackNumber the target track 950 \param sampleNumber the desired sample number (1-based index) 951 \param sampleDescriptionIndex set to the sample description index corresponding to this sample 952 \return the ISO sample or NULL if not found or end of stream or incomplete file. Use \ref gf_isom_last_error to check the error code 953 */ 954 GF_ISOSample *gf_isom_get_sample(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber, u32 *sampleDescriptionIndex); 955 956 /*! fetches a sample from a track without allocating a new sample. 957 This function is the same as \ref gf_isom_get_sample except that it fills in the static_sample passed as argument, potentially reallocating buffers 958 959 \param isom_file the target ISO file 960 \param trackNumber the target track 961 \param sampleNumber the desired sample number (1-based index) 962 \param sampleDescriptionIndex set to the sample description index corresponding to this sample 963 \param static_sample a caller-allocated ISO sample to use as the returned sample 964 \param data_offset set to data offset in file / current bitstream - may be NULL 965 \return the ISO sample or NULL if not found or end of stream or incomplete file. Use \ref gf_isom_last_error to check the error code 966 \note If the function returns NULL, the static_sample and its associated data are NOT destroyed 967 */ 968 GF_ISOSample *gf_isom_get_sample_ex(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber, u32 *sampleDescriptionIndex, GF_ISOSample *static_sample, u64 *data_offset); 969 970 /*! gets sample information. This is the same as \ref gf_isom_get_sample but doesn't fetch media data 971 972 \param isom_file the target ISO file 973 \param trackNumber the target track 974 \param sampleNumber the desired sample number (1-based index) 975 \param sampleDescriptionIndex set to the sample description index corresponding to this sample (optional, can be NULL) 976 \param data_offset set to the sample start offset in file (optional, can be NULL) 977 \note: when both sampleDescriptionIndex and data_offset are NULL, only DTS, CTS_Offset and RAP indications are retrieved (faster) 978 \return the ISO sample without data or NULL if not found or end of stream or incomplete file. Use \ref gf_isom_last_error to check the error code 979 */ 980 GF_ISOSample *gf_isom_get_sample_info(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber, u32 *sampleDescriptionIndex, u64 *data_offset); 981 982 /*! gets sample information with a user-allocated sample. This is the same as \ref gf_isom_get_sample_info but uses a static allocated sample as input 983 \param isom_file the target ISO file 984 \param trackNumber the target track 985 \param sampleNumber the desired sample number (1-based index) 986 \param sampleDescriptionIndex set to the sample description index corresponding to this sample (optional, can be NULL) 987 \param data_offset set to the sample start offset in file (optional, can be NULL) 988 \note: when both sampleDescriptionIndex and data_offset are NULL, only DTS, CTS_Offset and RAP indications are retrieved (faster) 989 \param static_sample a caller-allocated ISO sample to use as the returned sample 990 \return the ISO sample without data or NULL if not found or end of stream or incomplete file. Use \ref gf_isom_last_error to check the error code 991 \note If the function returns NULL, the static_sample and its associated data if any are NOT destroyed 992 */ 993 GF_ISOSample *gf_isom_get_sample_info_ex(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber, u32 *sampleDescriptionIndex, u64 *data_offset, GF_ISOSample *static_sample); 994 995 /*! get sample decoding time 996 \param isom_file the target ISO file 997 \param trackNumber the target track 998 \param sampleNumber the desired sample number (1-based index) 999 \return decoding time in media timescale 1000 */ 1001 u64 gf_isom_get_sample_dts(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber); 1002 1003 /*! gets sample duration 1004 \param isom_file the target ISO file 1005 \param trackNumber the target track 1006 \param sampleNumber the desired sample number (1-based index) 1007 \return sample duration in media timescale*/ 1008 u32 gf_isom_get_sample_duration(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber); 1009 1010 /*! gets sample size 1011 \param isom_file the target ISO file 1012 \param trackNumber the target track 1013 \param sampleNumber the desired sample number (1-based index) 1014 \return sample size in bytes*/ 1015 u32 gf_isom_get_sample_size(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber); 1016 1017 /*! gets maximum sample size in track 1018 \param isom_file the target ISO file 1019 \param trackNumber the target track 1020 \return max size of any sample in track*/ 1021 u32 gf_isom_get_max_sample_size(GF_ISOFile *isom_file, u32 trackNumber); 1022 1023 /*! gets average sample size in a track 1024 \param isom_file the target ISO file 1025 \param trackNumber the target track 1026 \return average size of sample in track 1027 */ 1028 u32 gf_isom_get_avg_sample_size(GF_ISOFile *isom_file, u32 trackNumber); 1029 1030 /*! gets maximum sample duration in track 1031 \param isom_file the target ISO file 1032 \param trackNumber the target track 1033 \return max sample delta in media timescale 1034 */ 1035 u32 gf_isom_get_max_sample_delta(GF_ISOFile *isom_file, u32 trackNumber); 1036 1037 /*! gets max sample CTS offset (CTS-DTS) in track 1038 \param isom_file the target ISO file 1039 \param trackNumber the target track 1040 \return max sample cts offset in media timescale*/ 1041 u32 gf_isom_get_max_sample_cts_offset(GF_ISOFile *isom_file, u32 trackNumber); 1042 1043 /*! gets sample sync flag. This does not check other sample groups ('rap ' or 'sap ') 1044 \param isom_file the target ISO file 1045 \param trackNumber the target track 1046 \param sampleNumber the desired sample number (1-based index) 1047 \return GF_TRUE if sample is sync, GF_FALSE otherwise*/ 1048 Bool gf_isom_get_sample_sync(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber); 1049 1050 /*! gets sample dependency flags - see ISO/IEC 14496-12 and \ref gf_filter_pck_set_dependency_flags 1051 \param isom_file the target ISO file 1052 \param trackNumber the target track 1053 \param sampleNumber the desired sample number (1-based index) 1054 \param is_leading set to 1 if sample is a leading picture 1055 \param dependsOn set to the depends_on flag 1056 \param dependedOn set to the depended_on flag 1057 \param redundant set to the redundant flag 1058 \return error if any 1059 */ 1060 GF_Err gf_isom_get_sample_flags(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber, u32 *is_leading, u32 *dependsOn, u32 *dependedOn, u32 *redundant); 1061 1062 /*! gets a sample given a desired decoding time and set the sampleDescriptionIndex of this sample 1063 1064 WARNING: the sample may not be sync even though the sync was requested (depends on the media and the editList) 1065 the SampleNum is optional. If non-NULL, will contain the sampleNumber 1066 1067 \param isom_file the target ISO file 1068 \param trackNumber the target track 1069 \param desiredTime the desired time in media timescale 1070 \param sampleDescriptionIndex set to the sample description index corresponding to this sample (optional, can be NULL) 1071 \param SearchMode the search direction mode 1072 \param sample set to the fetched sample if any. If NULL, sample is not fetched (optional, can be NULL) 1073 \param sample_number set to the fetched sample number if any, set to 0 otherwise (optional, can be NULL) 1074 \param data_offset set to the sample start offset in file (optional, can be NULL) 1075 1076 \return GF_EOS if the desired time exceeds the media duration or error if any 1077 */ 1078 GF_Err gf_isom_get_sample_for_media_time(GF_ISOFile *isom_file, u32 trackNumber, u64 desiredTime, u32 *sampleDescriptionIndex, GF_ISOSearchMode SearchMode, GF_ISOSample **sample, u32 *sample_number, u64 *data_offset); 1079 1080 /*! gets sample number for a given decode time 1081 \param isom_file the target ISO file 1082 \param trackNumber the target track 1083 \param dts the desired decode time in media timescale 1084 \return the sample number or 0 if not found 1085 */ 1086 u32 gf_isom_get_sample_from_dts(GF_ISOFile *isom_file, u32 trackNumber, u64 dts); 1087 1088 /*! get the number of track references of a track for a given ReferenceType 1089 \param isom_file the target ISO file 1090 \param trackNumber the target track 1091 \param referenceType the four character code of the reference to query 1092 \return -1 if error or the number of references*/ 1093 s32 gf_isom_get_reference_count(GF_ISOFile *isom_file, u32 trackNumber, u32 referenceType); 1094 1095 /*! get the referenced track number for a track and a given ReferenceType and Index 1096 \param isom_file the target ISO file 1097 \param trackNumber the target track 1098 \param referenceType the four character code of the reference to query 1099 \param referenceIndex the 1-based index of the reference to query (see \ref gf_isom_get_reference_count) 1100 \param refTrack set to the track number of the referenced track 1101 \return error if any 1102 */ 1103 GF_Err gf_isom_get_reference(GF_ISOFile *isom_file, u32 trackNumber, u32 referenceType, u32 referenceIndex, u32 *refTrack); 1104 1105 /*! get the referenced track ID for a track and a given ReferenceType and Index 1106 \param isom_file the target ISO file 1107 \param trackNumber the target track 1108 \param referenceType the four character code of the reference to query 1109 \param referenceIndex the 1-based index of the reference to query (see \ref gf_isom_get_reference_count) 1110 \param refTrackID set to the track ID of the referenced track 1111 \return error if any 1112 */ 1113 GF_Err gf_isom_get_reference_ID(GF_ISOFile *isom_file, u32 trackNumber, u32 referenceType, u32 referenceIndex, GF_ISOTrackID *refTrackID); 1114 1115 /*! checks if a track has a reference of given type to another track 1116 \param isom_file the target ISO file 1117 \param trackNumber the target track 1118 \param referenceType the four character code of the reference to query 1119 \param refTrackID set to the track number of the referenced track 1120 \return the reference index if the given track has a reference of type referenceType to refTreckID, 0 otherwise*/ 1121 u32 gf_isom_has_track_reference(GF_ISOFile *isom_file, u32 trackNumber, u32 referenceType, GF_ISOTrackID refTrackID); 1122 1123 /*! fetches a sample for a given movie time, handling possible track edit lists. 1124 1125 if no sample is playing, an empty sample is returned with no data and a DTS set to MovieTime when searching in sync modes 1126 if no sample is playing, the closest sample in the edit time-line is returned when searching in regular modes 1127 1128 WARNING: the sample may not be sync even though the sync was requested (depends on the media and the editList) 1129 1130 Note: this function will handle re-timestamping the sample according to the mapping of the media time-line 1131 on the track time-line. The sample TSs (DTS / CTS offset) are expressed in MEDIA TIME SCALE 1132 (to match the media stream TS resolution as indicated in media header / SLConfig) 1133 1134 1135 \param isom_file the target ISO file 1136 \param trackNumber the target track 1137 \param movieTime the desired movie time in media timescale 1138 \param sampleDescriptionIndex set to the sample description index corresponding to this sample (optional, can be NULL) 1139 \param SearchMode the search direction mode 1140 \param sample set to the fetched sample if any. If NULL, sample is not fetched (optional, can be NULL) 1141 \param sample_number set to the fetched sample number if any, set to 0 otherwise (optional, can be NULL) 1142 \param data_offset set to the sample start offset in file (optional, can be NULL) 1143 \return error if any 1144 */ 1145 GF_Err gf_isom_get_sample_for_movie_time(GF_ISOFile *isom_file, u32 trackNumber, u64 movieTime, u32 *sampleDescriptionIndex, GF_ISOSearchMode SearchMode, GF_ISOSample **sample, u32 *sample_number, u64 *data_offset); 1146 1147 /*! gets edit list type 1148 \param isom_file the target ISO file 1149 \param trackNumber the target track 1150 \param mediaOffset set to the media offset of the edit for time-shifting edits 1151 \return GF_TRUE if complex edit list, GF_FALSE if no edit list or time-shifting only edit list, in which case mediaOffset is set to the CTS of the first sample to present at presentation time 0 1152 A negative value implies that the samples with CTS between 0 and mediaOffset should not be presented (skip) 1153 A positive value value implies that there is nothing to present between 0 and CTS (hold) 1154 */ 1155 Bool gf_isom_get_edit_list_type(GF_ISOFile *isom_file, u32 trackNumber, s64 *mediaOffset); 1156 1157 /*! gets the number of edits in an edit list 1158 \param isom_file the target ISO file 1159 \param trackNumber the target track 1160 \return number of edits 1161 */ 1162 u32 gf_isom_get_edits_count(GF_ISOFile *isom_file, u32 trackNumber); 1163 1164 /*! gets the desired edit information 1165 \param isom_file the target ISO file 1166 \param trackNumber the target track 1167 \param EditIndex index of the edit to query (1-based index) 1168 \param EditTime set to the edit time in movie timescale 1169 \param SegmentDuration set to the edit duration in movie timescale 1170 \param MediaTime set to the edit media start time in media timescale 1171 \param EditMode set to the mode of the edit 1172 \return error if any 1173 */ 1174 GF_Err gf_isom_get_edit(GF_ISOFile *isom_file, u32 trackNumber, u32 EditIndex, u64 *EditTime, u64 *SegmentDuration, u64 *MediaTime, GF_ISOEditType *EditMode); 1175 1176 /*! gets the number of languages for the copyright 1177 \param isom_file the target ISO file 1178 \return number of languages, 0 if no copyright*/ 1179 u32 gf_isom_get_copyright_count(GF_ISOFile *isom_file); 1180 1181 /*! gets a copyright and its language code 1182 \param isom_file the target ISO file 1183 \param Index the 1-based index of the copyright notice to query 1184 \param threeCharCodes set to the copyright language code 1185 \param notice set to the copyright notice 1186 \return error if any 1187 */ 1188 GF_Err gf_isom_get_copyright(GF_ISOFile *isom_file, u32 Index, const char **threeCharCodes, const char **notice); 1189 1190 /*! gets the number of chapter for movie or track (chapters can be assigned to tracks or to movies) 1191 \param isom_file the target ISO file 1192 \param trackNumber the target track to queryy. If 0, looks for chapter at the movie level 1193 \return number of chapters 1194 */ 1195 u32 gf_isom_get_chapter_count(GF_ISOFile *isom_file, u32 trackNumber); 1196 1197 /*! gets the given chapter time and name for a movie or track 1198 \param isom_file the target ISO file 1199 \param trackNumber the target track to queryy. If 0, looks for chapter at the movie level 1200 \param Index the index of the ckhapter to queryy 1201 \param chapter_time set to chapter start time in milliseconds (optional, may be NULL) 1202 \param name set to chapter name (optional, may be NULL) 1203 \return error if any 1204 */ 1205 GF_Err gf_isom_get_chapter(GF_ISOFile *isom_file, u32 trackNumber, u32 Index, u64 *chapter_time, const char **name); 1206 1207 /*! checks if a media has sync points 1208 \param isom_file the target ISO file 1209 \param trackNumber the target track 1210 \return 0 if the media has no sync point info (eg, all samples are RAPs), 1 if the media has sync points (eg some samples are RAPs), 2 if the media has empty sync point info (no samples are RAPs - this will likely only happen 1211 in scalable context) 1212 */ 1213 u8 gf_isom_has_sync_points(GF_ISOFile *isom_file, u32 trackNumber); 1214 1215 /*! gets the number of sync points in a media 1216 \param isom_file the target ISO file 1217 \param trackNumber the target track 1218 \return number of sync points*/ 1219 u32 gf_isom_get_sync_point_count(GF_ISOFile *isom_file, u32 trackNumber); 1220 1221 /*! checks if a media track hhas composition time offset 1222 \param isom_file the target ISO file 1223 \param trackNumber the target track 1224 \return 1 if the track uses unsigned compositionTime offsets (B-frames or similar), 2 if the track uses signed compositionTime offsets (B-frames or similar), 0 if the track does not use compositionTime offsets (CTS == DTS) 1225 */ 1226 u32 gf_isom_has_time_offset(GF_ISOFile *isom_file, u32 trackNumber); 1227 1228 /*! gets cts to dts shift value if defined. 1229 This shift is defined only in cases of negative CTS offset (ctts version 1) and not always present in files! 1230 Adding shift to CTS guarantees that the shifted CTS is always greater than the DTS for any sample 1231 \param isom_file the target ISO file 1232 \param trackNumber the target track 1233 \return the shift from composition time to decode time for that track if indicated, or 0 if not found 1234 */ 1235 s64 gf_isom_get_cts_to_dts_shift(GF_ISOFile *isom_file, u32 trackNumber); 1236 1237 /*! checks if a track has sync shadow samples (RAP samples replacing non RAP ones) 1238 \param isom_file the target ISO file 1239 \param trackNumber the target track 1240 \return GF_TRUE if the track has sync shadow samples*/ 1241 Bool gf_isom_has_sync_shadows(GF_ISOFile *isom_file, u32 trackNumber); 1242 1243 /*! checks if a track has sample dependencoes indicated 1244 \param isom_file the target ISO file 1245 \param trackNumber the target track 1246 \return GF_TRUE if the track has sample dep indications*/ 1247 Bool gf_isom_has_sample_dependency(GF_ISOFile *isom_file, u32 trackNumber); 1248 1249 /*! gets a rough estimation of file size. This only works for completely self-contained files and without fragmentation 1250 for the current time 1251 \param isom_file the target ISO file 1252 \return estimated file size in bytes*/ 1253 u64 gf_isom_estimate_size(GF_ISOFile *isom_file); 1254 1255 /*! gets next alternate group ID available 1256 \param isom_file the target ISO file 1257 \return next available ID for alternate groups 1258 */ 1259 u32 gf_isom_get_next_alternate_group_id(GF_ISOFile *isom_file); 1260 1261 1262 /*! gets file name of an opened ISO file 1263 \param isom_file the target ISO file 1264 \return the file name*/ 1265 const char *gf_isom_get_filename(GF_ISOFile *isom_file); 1266 1267 1268 /*! gets file brand information 1269 The brand is used to 1270 - differenciate MP4, MJPEG2000 and QT while indicating compatibilities 1271 - identify tools that shall be supported for correct parsing of the file 1272 1273 The function will set brand, minorVersion and AlternateBrandsCount to 0 if no brand indication is found in the file 1274 1275 \param isom_file the target ISO file 1276 \param brand set to the four character code of the brand 1277 \param minorVersion set to an informative integer for the minor version of the major brand (optional, can be NULL) 1278 \param AlternateBrandsCount set to the number of compatible brands (optional, can be NULL). 1279 \return error if any*/ 1280 GF_Err gf_isom_get_brand_info(GF_ISOFile *isom_file, u32 *brand, u32 *minorVersion, u32 *AlternateBrandsCount); 1281 1282 /*! gets an alternate brand indication 1283 \note the Major brand should always be indicated in the alternate brands 1284 \param isom_file the target ISO file 1285 \param BrandIndex 1-based index of alternate brand to query (cf \ref gf_isom_get_brand_info) 1286 \param brand set to the four character code of the brand 1287 \return error if any*/ 1288 GF_Err gf_isom_get_alternate_brand(GF_ISOFile *isom_file, u32 BrandIndex, u32 *brand); 1289 1290 /*! gets the internal list of brands 1291 \param isom_file the target ISO file 1292 \return the internal list of brands. DO NOT MODIFY the content 1293 */ 1294 const u32 *gf_isom_get_brands(GF_ISOFile *isom_file); 1295 1296 /*! gets the number of padding bits at the end of a given sample if any 1297 \param isom_file the target ISO file 1298 \param trackNumber the target track 1299 \param sampleNumber the desired sample number (1-based index) 1300 \param NbBits set to the number of padded bits at the end of the sample 1301 \return error if any*/ 1302 GF_Err gf_isom_get_sample_padding_bits(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber, u8 *NbBits); 1303 1304 /*! checks if a track samples use padding bits or not 1305 \param isom_file the target ISO file 1306 \param trackNumber the target track 1307 \return GF_TRUE if samples have padding bits information, GF_FALSE otherwise*/ 1308 Bool gf_isom_has_padding_bits(GF_ISOFile *isom_file, u32 trackNumber); 1309 1310 /*! gets information of a visual track for a given sample description 1311 \param isom_file the target ISO file 1312 \param trackNumber the target track 1313 \param sampleDescriptionIndex the target sample description index (1-based) 1314 \param Width set to the width of the sample description in pixels 1315 \param Height set to the height of the sample description in pixels 1316 \return error if any*/ 1317 GF_Err gf_isom_get_visual_info(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 *Width, u32 *Height); 1318 1319 /*! gets bit depth of a sample description of a visual track (for uncompressed media usually) 1320 \param isom_file the target ISO file 1321 \param trackNumber the target track number 1322 \param sampleDescriptionIndex the target sample description index 1323 \param bitDepth the bit depth of each pixel (eg 24 for RGB, 32 for RGBA) 1324 \return error if any 1325 */ 1326 GF_Err gf_isom_get_visual_bit_depth(GF_ISOFile* isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u16 *bitDepth); 1327 1328 /*! gets information of an audio track for a given sample description 1329 \param isom_file the target ISO file 1330 \param trackNumber the target track 1331 \param sampleDescriptionIndex the target sample description index (1-based) 1332 \param SampleRate set to the audio sample rate of the sample description 1333 \param Channels set to the audio channel count of the sample description 1334 \param bitsPerSample set to the audio bits per sample for raw audio of the sample description 1335 \return error if any*/ 1336 GF_Err gf_isom_get_audio_info(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 *SampleRate, u32 *Channels, u32 *bitsPerSample); 1337 1338 /*! Audio channel layout description, ISOBMFF style*/ 1339 typedef struct 1340 { 1341 /*! stream structure flags, 1: has channel layout, 2: has objects*/ 1342 u8 stream_structure; 1343 1344 /*! defined CICP channel layout*/ 1345 u8 definedLayout; 1346 1347 /*! number of channels*/ 1348 u32 channels_count; 1349 struct { 1350 /*! speaker position*/ 1351 u8 position; 1352 /*! speaker elevation if position==126*/ 1353 s8 elevation; 1354 /*! speaker azimuth if position==126*/ 1355 s16 azimuth; 1356 } layouts[64]; 1357 /*! bit-map of omitted channels using bit positions defined in CICP - only valid if definedLayout is not 0*/ 1358 u64 omittedChannelsMap; 1359 /*! number of objects in the stream*/ 1360 u8 object_count; 1361 } GF_AudioChannelLayout; 1362 1363 /*! get channel layout info for an audio track, ISOBMFF style 1364 \param isom_file the target ISO file 1365 \param trackNumber the target track 1366 \param sampleDescriptionIndex the target sample description index (1-based) 1367 \param layout set to the channel/object layout info for this track 1368 \return GF_NOT_FOUND if not set in file, or other error if any*/ 1369 GF_Err gf_isom_get_audio_layout(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, GF_AudioChannelLayout *layout); 1370 1371 1372 /*! gets visual track layout information 1373 \param isom_file the target ISO file 1374 \param trackNumber the target track 1375 \param width set to the width of the track in pixels 1376 \param height set to the height of the track in pixels 1377 \param translation_x set to the horizontal translation of the track in pixels 1378 \param translation_y set to the vertical translation of the track in pixels 1379 \param layer set to the z-order of the track 1380 \return error if any*/ 1381 GF_Err gf_isom_get_track_layout_info(GF_ISOFile *isom_file, u32 trackNumber, u32 *width, u32 *height, s32 *translation_x, s32 *translation_y, s16 *layer); 1382 1383 /*! gets matrix of a visual track 1384 \param isom_file the target ISO file 1385 \param trackNumber the target track 1386 \param matrix set to the track matrix - all coord values are expressed as 16.16 fixed point floats 1387 \return error if any*/ 1388 GF_Err gf_isom_get_track_matrix(GF_ISOFile *isom_file, u32 trackNumber, u32 matrix[9]); 1389 1390 /*! gets sample (pixel) aspect ratio information of a visual track for a given sample description 1391 The aspect ratio is hSpacing divided by vSpacing 1392 \param isom_file the target ISO file 1393 \param trackNumber the target track 1394 \param sampleDescriptionIndex the target sample description index (1-based) 1395 \param hSpacing horizontal spacing 1396 \param vSpacing vertical spacing 1397 \return error if any*/ 1398 GF_Err gf_isom_get_pixel_aspect_ratio(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 *hSpacing, u32 *vSpacing); 1399 1400 /*! gets color information of a visual track for a given sample description 1401 \param isom_file the target ISO file 1402 \param trackNumber the target track 1403 \param sampleDescriptionIndex the target sample description index (1-based) 1404 \param colour_type set to the four character code of the colour type mode used (nclx, nclc, prof or ricc currently defined) 1405 \param colour_primaries set to the colour primaries for nclc/nclx as defined in ISO/IEC 23001-8 1406 \param transfer_characteristics set to the colour primaries for nclc/nclx as defined in ISO/IEC 23001-8 1407 \param matrix_coefficients set to the colour primaries for nclc/nclx as defined in ISO/IEC 23001-8 1408 \param full_range_flag set to the colour primaries for nclc as defined in ISO/IEC 23001-8 1409 \return error if any*/ 1410 GF_Err gf_isom_get_color_info(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 *colour_type, u16 *colour_primaries, u16 *transfer_characteristics, u16 *matrix_coefficients, Bool *full_range_flag); 1411 1412 /*! gets the media language code of a track 1413 \param isom_file the target ISO file 1414 \param trackNumber the target track 1415 \param lang set to a newly allocated string containg 3 chars (if old files) or longer form (BCP-47) - shall be freed by caller 1416 \return error if any*/ 1417 GF_Err gf_isom_get_media_language(GF_ISOFile *isom_file, u32 trackNumber, char **lang); 1418 1419 /*! gets the number of kind (media role) for a given track 1420 \param isom_file the target ISO file 1421 \param trackNumber the target track 1422 \return number of kind defined 1423 */ 1424 u32 gf_isom_get_track_kind_count(GF_ISOFile *isom_file, u32 trackNumber); 1425 1426 /*! gets a given kind (media role) information for a given track 1427 \param isom_file the target ISO file 1428 \param trackNumber the target track 1429 \param index the 1-based index of the kind to retrieve 1430 \param scheme set to the scheme of the kind information - shall be freed by caller 1431 \param value set to the value of the kind information - shall be freed by caller 1432 \return error if any*/ 1433 GF_Err gf_isom_get_track_kind(GF_ISOFile *isom_file, u32 trackNumber, u32 index, char **scheme, char **value); 1434 1435 /*! gets the magic number associated with a track. The magic number is usually set by a file muxer, and is not serialized to file 1436 \param isom_file the target ISO file 1437 \param trackNumber the target track 1438 \return the magic number (0 by default) 1439 */ 1440 u64 gf_isom_get_track_magic(GF_ISOFile *isom_file, u32 trackNumber); 1441 1442 /*! checks if file is a single AV file with max one audio, one video, one text and basic od/bifs 1443 \param isom_file the target ISO file 1444 \return GF_TRUE if file is single AV, GF_FALSE otherwise 1445 */ 1446 Bool gf_isom_is_single_av(GF_ISOFile *isom_file); 1447 1448 /*! guesses which specification this file refers to. 1449 \param isom_file the target ISO file 1450 \return possible values are: 1451 GF_ISOM_BRAND_ISOM: unrecognized std 1452 GF_ISOM_BRAND_3GP5: 3GP file (max 1 audio, 1 video) without text track 1453 GF_ISOM_BRAND_3GP6: 3GP file (max 1 audio, 1 video) with text track 1454 GF_ISOM_BRAND_3GG6: 3GP file multitrack file 1455 GF_ISOM_BRAND_3G2A: 3GP2 file 1456 GF_ISOM_BRAND_AVC1: AVC file 1457 FCC("ISMA"): ISMA file (may overlap with 3GP) 1458 GF_ISOM_BRAND_MP42: any generic MP4 file (eg with BIFS/OD/MPEG-4 systems stuff) 1459 1460 for files without movie, returns the file meta handler type 1461 */ 1462 u32 gf_isom_guess_specification(GF_ISOFile *isom_file); 1463 1464 1465 /*! gets the nalu_length_field size used for this sample description if NALU-based (AVC/HEVC/...) 1466 \param isom_file the target ISO file 1467 \param trackNumber the target track 1468 \param sampleDescriptionIndex the target sample description index (1-based) 1469 \return number of bytes used to code the NALU size, or 0 if not NALU-based*/ 1470 u32 gf_isom_get_nalu_length_field(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 1471 1472 /*! gets max/average rate information as indicated in ESDS or BTRT boxes. If not found all values are set to 0 1473 if sampleDescriptionIndex is 0, gather for all sample descriptions 1474 1475 \param isom_file the target ISO file 1476 \param trackNumber the target track 1477 \param sampleDescriptionIndex the target sample description index (1-based) 1478 \param average_bitrate set to the average bitrate in bits per second of the media 1479 \param max_bitrate set to the maximum bitrate in bits per second of the media 1480 \param decode_buffer_size set to the decoder buffer size in bytes of the media 1481 \return error if any*/ 1482 GF_Err gf_isom_get_bitrate(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 *average_bitrate, u32 *max_bitrate, u32 *decode_buffer_size); 1483 1484 1485 /*! gets the track template of a track. This serializes track box without serializing sample tables nor sample description info 1486 \param isom_file the destination ISO file 1487 \param trackNumber the destination track 1488 \param output will be set to a newly allocated buffer containing the serialized box - caller shall free it 1489 \param output_size will be set to the size of the allocated buffer 1490 \return error if any 1491 */ 1492 GF_Err gf_isom_get_track_template(GF_ISOFile *isom_file, u32 trackNumber, u8 **output, u32 *output_size); 1493 1494 /*! gets the trex template of a track. This serializes trex box 1495 \param isom_file the destination ISO file 1496 \param trackNumber the destination track 1497 \param output will be set to a newly allocated buffer containing the serialized box - caller shall free it 1498 \param output_size will be set to the size of the allocated buffer 1499 \return error if any 1500 */ 1501 GF_Err gf_isom_get_trex_template(GF_ISOFile *isom_file, u32 trackNumber, u8 **output, u32 *output_size); 1502 1503 /*! sets the number of removed bytes form the input bitstream when using gmem:// url 1504 The number of bytes shall be the total number since the opening of the movie 1505 \param isom_file the target ISO file 1506 \param bytes_removed number of bytes removed 1507 \return error if any 1508 */ 1509 GF_Err gf_isom_set_removed_bytes(GF_ISOFile *isom_file, u64 bytes_removed); 1510 1511 /*! gets the current file offset of the current incomplete top level box not parsed 1512 This shall be checked to avoid discarding bytes at or after the current top box header 1513 \param isom_file the target ISO file 1514 \param current_top_box_offset set to the offset from file first byte 1515 \return error if any 1516 */ 1517 GF_Err gf_isom_get_current_top_box_offset(GF_ISOFile *isom_file, u64 *current_top_box_offset); 1518 1519 /*! purges the given number of samples, starting from the first sample, from a track of a fragmented file. 1520 This avoids having sample tables growing in size when reading a fragmented file in pure streaming mode (no seek). 1521 You should always keep one sample in the track 1522 \param isom_file the target ISO file 1523 \param trackNumber the desired track to purge 1524 \param nb_samples the number of samples to remove 1525 \return error if any 1526 */ 1527 GF_Err gf_isom_purge_samples(GF_ISOFile *isom_file, u32 trackNumber, u32 nb_samples); 1528 1529 1530 #ifndef GPAC_DISABLE_ISOM_DUMP 1531 1532 /*! dumps file structures into XML trace file 1533 \param isom_file the target ISO file 1534 \param trace the file object to dump to 1535 \param skip_init does not dump init segment structure 1536 \return error if any 1537 */ 1538 GF_Err gf_isom_dump(GF_ISOFile *isom_file, FILE *trace, Bool skip_init, Bool skip_samples); 1539 1540 #endif /*GPAC_DISABLE_ISOM_DUMP*/ 1541 1542 1543 /*! @} */ 1544 1545 1546 #ifndef GPAC_DISABLE_ISOM_WRITE 1547 1548 /*! 1549 \addtogroup isowrite_grp ISOBMFF Writing 1550 \ingroup iso_grp 1551 1552 ISOBMF file writing 1553 @{ 1554 */ 1555 1556 /*! Movie Storage modes*/ 1557 typedef enum 1558 { 1559 /*! FLAT: the MediaData is stored at the beginning of the file*/ 1560 GF_ISOM_STORE_FLAT = 1, 1561 /*! STREAMABLE: the MetaData (File Info) is stored at the beginning of the file 1562 for fast access during download*/ 1563 GF_ISOM_STORE_STREAMABLE, 1564 /*! INTERLEAVED: Same as STREAMABLE, plus the media data is mixed by chunk of fixed duration*/ 1565 GF_ISOM_STORE_INTERLEAVED, 1566 /*! INTERLEAVED +DRIFT: Same as INTERLEAVED, and adds time drift control to avoid creating too long chunks*/ 1567 GF_ISOM_STORE_DRIFT_INTERLEAVED, 1568 /*! tightly interleaves samples based on their DTS, therefore allowing better placement of samples in the file. 1569 This is used for both http interleaving and Hinting optimizations*/ 1570 GF_ISOM_STORE_TIGHT, 1571 /*! FASTSTART: same as FLAT but moves moov before mdat at the end*/ 1572 GF_ISOM_STORE_FASTSTART, 1573 } GF_ISOStorageMode; 1574 1575 /*! writes the file without deleting (see \ref gf_isom_delete) 1576 \param isom_file the target ISO file 1577 \return error if any 1578 */ 1579 GF_Err gf_isom_write(GF_ISOFile *isom_file); 1580 1581 /*! freezes order of the current box tree in the file. 1582 By default the library always reorder boxes in the recommended order in the various specifications implemented. 1583 New created tracks or meta items will not have a frozen order of boxes, but the function can be called several time 1584 \param isom_file the target ISO file 1585 \return error if any 1586 */ 1587 GF_Err gf_isom_freeze_order(GF_ISOFile *isom_file); 1588 1589 /*! keeps UTC edit times when storing 1590 \param isom_file the target ISO file 1591 \param keep_utc if GF_TRUE, do not edit times 1592 */ 1593 void gf_isom_keep_utc_times(GF_ISOFile *isom_file, Bool keep_utc); 1594 1595 /*! sets the timescale of the movie. This rescales times expressed in movie timescale in edit lists and mvex boxes 1596 \param isom_file the target ISO file 1597 \param timeScale the target timescale 1598 \return error if any 1599 */ 1600 GF_Err gf_isom_set_timescale(GF_ISOFile *isom_file, u32 timeScale); 1601 1602 /*! loads a set of top-level boxes in moov udta and child boxes. UDTA will be replaced if already present 1603 \param isom_file the target ISO file 1604 \param moov_boxes a serialized array of boxes to add 1605 \param moov_boxes_size the size of the serialized array of boxes 1606 \param udta_only only replace/inject udta box and entries 1607 \return error if any 1608 */ 1609 GF_Err gf_isom_load_extra_boxes(GF_ISOFile *isom_file, u8 *moov_boxes, u32 moov_boxes_size, Bool udta_only); 1610 1611 /*! creates a new track 1612 \param isom_file the target ISO file 1613 \param trackID the ID of the track - if 0, the track ID is chosen by the API 1614 \param MediaType the handler type (four character code) of the media 1615 \param TimeScale the time scale of the media 1616 \return the track number or 0 if error*/ 1617 u32 gf_isom_new_track(GF_ISOFile *isom_file, GF_ISOTrackID trackID, u32 MediaType, u32 TimeScale); 1618 1619 /*! creates a new track from an encoded trak box. 1620 \param isom_file the target ISO file 1621 \param trackID the ID of the track - if 0, the track ID is chosen by the API 1622 \param MediaType the handler type (four character code) of the media 1623 \param TimeScale the time scale of the media 1624 \param tk_box a serialized trak box to use as template 1625 \param tk_box_size the size of the serialized trak box 1626 \param udta_only only replace/inject udta box and entries 1627 \return the track number or 0 if error*/ 1628 u32 gf_isom_new_track_from_template(GF_ISOFile *isom_file, GF_ISOTrackID trackID, u32 MediaType, u32 TimeScale, u8 *tk_box, u32 tk_box_size, Bool udta_only); 1629 1630 /*! removes a track - internal cross dependencies will be updated. 1631 WARNING: any OD streams with references to this track through ODUpdate, ESDUpdate, ESDRemove commands 1632 will be rewritten 1633 \param isom_file the target ISO file 1634 \param trackNumber the target track to remove file 1635 \return error if any 1636 */ 1637 GF_Err gf_isom_remove_track(GF_ISOFile *isom_file, u32 trackNumber); 1638 1639 /*! sets the enable flag of a track 1640 \param isom_file the target ISO file 1641 \param trackNumber the target track 1642 \param enableTrack if GF_TRUE, track is enabled, otherwise disabled 1643 \return error if any 1644 */ 1645 GF_Err gf_isom_set_track_enabled(GF_ISOFile *isom_file, u32 trackNumber, Bool enableTrack); 1646 1647 /*! Track header flags operation type*/ 1648 typedef enum 1649 { 1650 /*! set flags, erasing previous value*/ 1651 GF_ISOM_TKFLAGS_SET = 0, 1652 /*! add flags*/ 1653 GF_ISOM_TKFLAGS_REM, 1654 /*! remove flags*/ 1655 GF_ISOM_TKFLAGS_ADD, 1656 } GF_ISOMTrackFlagOp; 1657 1658 /*! toggles track flags on or off 1659 \param isom_file the target ISO file 1660 \param trackNumber the target track 1661 \param flags flags to modify 1662 \param op flag operation mode 1663 \return error if any 1664 */ 1665 GF_Err gf_isom_set_track_flags(GF_ISOFile *isom_file, u32 trackNumber, u32 flags, GF_ISOMTrackFlagOp op); 1666 1667 /*! sets creationTime and modificationTime of the movie to the specified date 1668 \param isom_file the target ISO file 1669 \param time the new time 1670 \return error if any 1671 */ 1672 GF_Err gf_isom_set_creation_time(GF_ISOFile *isom_file, u64 time); 1673 1674 /*! sets creationTime and modificationTime of the track to the specified date 1675 \param isom_file the target ISO file 1676 \param trackNumber the target track 1677 \param time the new time 1678 \return error if any 1679 */ 1680 GF_Err gf_isom_set_track_creation_time(GF_ISOFile *isom_file,u32 trackNumber, u64 time); 1681 1682 /*! changes the ID of a track - all track references present in the file are updated 1683 \param isom_file the target ISO file 1684 \param trackNumber the target track 1685 \param trackID the new track ID 1686 \return error if trackID is already in used in the file*/ 1687 GF_Err gf_isom_set_track_id(GF_ISOFile *isom_file, u32 trackNumber, GF_ISOTrackID trackID); 1688 1689 /*! forces to rewrite all dependencies when track ID changes. Used to check if track references are broken during import of a single track 1690 \param isom_file the target ISO file 1691 \param trackNumber the target track 1692 \return error if any 1693 */ 1694 GF_Err gf_isom_rewrite_track_dependencies(GF_ISOFile *isom_file, u32 trackNumber); 1695 1696 /*! adds a sample to a track 1697 \param isom_file the target ISO file 1698 \param trackNumber the target track 1699 \param sampleDescriptionIndex the target sample description index associated with the sample 1700 \param sample the target sample to add 1701 \return error if any 1702 */ 1703 GF_Err gf_isom_add_sample(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, const GF_ISOSample *sample); 1704 1705 /*! copies all sample dependency, subSample and sample group information from the given sampleNumber in source file to the last added sample in dest file 1706 \param dst the destination ISO file 1707 \param dst_track the destination track 1708 \param src the source ISO file 1709 \param src_track the source track 1710 \param sampleNumber the source sample number 1711 \return error if any 1712 */ 1713 GF_Err gf_isom_copy_sample_info(GF_ISOFile *dst, u32 dst_track, GF_ISOFile *src, u32 src_track, u32 sampleNumber); 1714 1715 /*! adds a sync shadow sample to a track. 1716 - There must be a regular sample with the same DTS. 1717 - Sync Shadow samples MUST be RAP and can only use the same sample description as the sample they shadow 1718 - Currently, adding sync shadow must be done in order (no sample insertion) 1719 1720 \param isom_file the target ISO file 1721 \param trackNumber the target track 1722 \param sample the target shadow sample to add 1723 \return error if any 1724 */ 1725 GF_Err gf_isom_add_sample_shadow(GF_ISOFile *isom_file, u32 trackNumber, GF_ISOSample *sample); 1726 1727 /*! adds data to current sample in the track. This will update the data size. 1728 CANNOT be used with OD media type 1729 There shall not be any other 1730 \param isom_file the target ISO file 1731 \param trackNumber the target track 1732 \param data the data to append to the sample 1733 \param data_size the size of the data to append 1734 \return error if any 1735 */ 1736 GF_Err gf_isom_append_sample_data(GF_ISOFile *isom_file, u32 trackNumber, u8 *data, u32 data_size); 1737 1738 /*! adds sample references to a track 1739 \param isom_file the target ISO file 1740 \param trackNumber the target track 1741 \param sampleDescriptionIndex the target sample description index associated with the sample 1742 \param sample the target sample to add 1743 \param dataOffset is the offset in bytes of the data in the referenced file. 1744 \return error if any 1745 */ 1746 GF_Err gf_isom_add_sample_reference(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, GF_ISOSample *sample, u64 dataOffset); 1747 1748 /*! sets the duration of the last media sample. If not set, the duration of the last sample is the 1749 duration of the previous one if any, or media TimeScale (default value). This does not modify the edit list if any, 1750 you must modify this using \ref gf_isom_set_edit 1751 \param isom_file the target ISO file 1752 \param trackNumber the target track 1753 \param duration duration of last sample in media timescale 1754 \return error if any 1755 */ 1756 GF_Err gf_isom_set_last_sample_duration(GF_ISOFile *isom_file, u32 trackNumber, u32 duration); 1757 1758 /*! sets the duration of the last media sample. If not set, the duration of the last sample is the 1759 duration of the previous one if any, or media TimeScale (default value). This does not modify the edit list if any, 1760 you must modify this using \ref gf_isom_set_edit. 1761 If both dur_num and dur_den are both zero, forces last sample duration to be the same as previous sample 1762 \param isom_file the target ISO file 1763 \param trackNumber the target track 1764 \param dur_num duration num value 1765 \param dur_den duration num value 1766 \return error if any 1767 */ 1768 GF_Err gf_isom_set_last_sample_duration_ex(GF_ISOFile *isom_file, u32 trackNumber, u32 dur_num, u32 dur_den); 1769 1770 /*! patches last stts entry to make sure the cumulated duration equals the given next_dts value 1771 \param isom_file the target ISO file 1772 \param trackNumber the target track 1773 \param next_dts target decode time of next sample 1774 \return error if any 1775 */ 1776 GF_Err gf_isom_patch_last_sample_duration(GF_ISOFile *isom_file, u32 trackNumber, u64 next_dts); 1777 1778 /*! adds a track reference to another track 1779 \param isom_file the target ISO file 1780 \param trackNumber the target track 1781 \param referenceType the four character code of the reference 1782 \param ReferencedTrackID the ID of the track refered to 1783 \return error if any 1784 */ 1785 GF_Err gf_isom_set_track_reference(GF_ISOFile *isom_file, u32 trackNumber, u32 referenceType, GF_ISOTrackID ReferencedTrackID); 1786 1787 /*! removes all track references 1788 \param isom_file the target ISO file 1789 \param trackNumber the target track 1790 \return error if any 1791 */ 1792 GF_Err gf_isom_remove_track_references(GF_ISOFile *isom_file, u32 trackNumber); 1793 1794 /*! sets track handler name. 1795 \param isom_file the target ISO file 1796 \param trackNumber the target track 1797 \param nameUTF8 the handler name; either NULL (reset), a UTF-8 formatted string or a UTF8 file resource in the form "file://path/to/file_utf8" 1798 \return error if any 1799 */ 1800 GF_Err gf_isom_set_handler_name(GF_ISOFile *isom_file, u32 trackNumber, const char *nameUTF8); 1801 1802 /*! updates the sample size table - this is needed when using \ref gf_isom_append_sample_data in case the resulting samples 1803 are of same sizes (typically in 3GP speech tracks) 1804 \param isom_file the target ISO file 1805 \param trackNumber the target track 1806 \return error if any 1807 */ 1808 GF_Err gf_isom_refresh_size_info(GF_ISOFile *isom_file, u32 trackNumber); 1809 1810 /*! updates the duration of the movie 1811 \param isom_file the target ISO file 1812 \return error if any 1813 */ 1814 GF_Err gf_isom_update_duration(GF_ISOFile *isom_file); 1815 1816 1817 /*! updates a given sample of the media. This function updates both media data of sample and sample properties (DTS, CTS, SAP type) 1818 \param isom_file the target ISO file 1819 \param trackNumber the target track 1820 \param sampleNumber the number of the sample to update 1821 \param sample the new sample 1822 \param data_only if set to GF_TRUE, only the sample data is updated, not other info 1823 \return error if any 1824 */ 1825 GF_Err gf_isom_update_sample(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber, GF_ISOSample *sample, Bool data_only); 1826 1827 /*! updates a sample reference in the media. Note that the sample MUST exists, and that sample->data MUST be NULL and sample->dataLength must be NON NULL. 1828 \param isom_file the target ISO file 1829 \param trackNumber the target track 1830 \param sampleNumber the number of the sample to update 1831 \param sample the new sample 1832 \param data_offset new offset of sample in referenced file 1833 \return error if any 1834 */ 1835 GF_Err gf_isom_update_sample_reference(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber, GF_ISOSample *sample, u64 data_offset); 1836 1837 /*! removes a given sample 1838 \param isom_file the target ISO file 1839 \param trackNumber the target track 1840 \param sampleNumber the number of the sample to update 1841 \return error if any 1842 */ 1843 GF_Err gf_isom_remove_sample(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber); 1844 1845 /*! changes media time scale 1846 1847 \param isom_file the target ISO file 1848 \param trackNumber the target track 1849 \param new_timescale the new timescale to set 1850 \param new_tsinc if not 0, changes sample duration and composition offsets to new_tsinc/new_timescale. If non-constant sample dur is used, uses the samllest sample dur in the track. Otherwise, only changes the timescale 1851 \param force_rescale if set to GF_TRUE, only the media timescale is changed but media times are not updated. Ignored if new_tsinc is not 0. 1852 \return GF_EOS if no action taken (same config), or error if any 1853 */ 1854 GF_Err gf_isom_set_media_timescale(GF_ISOFile *isom_file, u32 trackNumber, u32 new_timescale, u32 new_tsinc, Bool force_rescale); 1855 1856 /*! sets the save file name of the (edited) movie. 1857 If the movie is edited, the default fileName is the open name suffixed with an internally defined extension "%p_isotmp")" 1858 \note you cannot save an edited file under the same name (overwrite not allowed) 1859 If the movie is created (WRITE mode), the default filename is $OPEN_NAME 1860 1861 \param isom_file the target ISO file 1862 \param filename the new final filename 1863 \return error if any 1864 */ 1865 GF_Err gf_isom_set_final_name(GF_ISOFile *isom_file, char *filename); 1866 1867 /*! sets the storage mode of a file (FLAT, STREAMABLE, INTERLEAVED) 1868 \param isom_file the target ISO file 1869 \param storage_mode the target storage mode 1870 \return error if any 1871 */ 1872 GF_Err gf_isom_set_storage_mode(GF_ISOFile *isom_file, GF_ISOStorageMode storage_mode); 1873 1874 /*! sets the interleaving time of media data (INTERLEAVED mode only) 1875 \param isom_file the target ISO file 1876 \param InterleaveTime the target interleaving time in movie timescale 1877 \return error if any 1878 */ 1879 GF_Err gf_isom_set_interleave_time(GF_ISOFile *isom_file, u32 InterleaveTime); 1880 1881 /*! forces usage of 64 bit chunk offsets 1882 \param isom_file the target ISO file 1883 \param set_on if GF_TRUE, 64 bit chunk offsets are always used; otherwise, they are used only for large files 1884 \return error if any 1885 */ 1886 GF_Err gf_isom_force_64bit_chunk_offset(GF_ISOFile *isom_file, Bool set_on); 1887 1888 /*! compression mode of top-level boxes*/ 1889 typedef enum 1890 { 1891 /*! no compression is used*/ 1892 GF_ISO_COMP_NONE=0, 1893 /*! only moov box is compressed*/ 1894 GF_ISO_COMP_MOOV, 1895 /*! only moof boxes are compressed*/ 1896 GF_ISO_COMP_MOOF, 1897 /*! only moof and sidx boxes are compressed*/ 1898 GF_ISO_COMP_MOOF_SIDX, 1899 /*! only moof, sidx and ssix boxes are compressed*/ 1900 GF_ISO_COMP_MOOF_SSIX, 1901 /*! all (moov, moof, sidx and ssix) boxes are compressed*/ 1902 GF_ISO_COMP_ALL, 1903 } GF_ISOCompressMode; 1904 1905 /*! sets compression mode of file 1906 \param isom_file the target ISO file 1907 \param compress_mode the desired compress mode 1908 \param force_compress forces compressed box even if compress size is larger than uncompressed size 1909 \return error if any 1910 */ 1911 GF_Err gf_isom_enable_compression(GF_ISOFile *isom_file, GF_ISOCompressMode compress_mode, Bool force_compress); 1912 1913 /*! sets the copyright in one language 1914 \param isom_file the target ISO file 1915 \param threeCharCode the ISO three character language code for copyright 1916 \param notice the copyright notice to add 1917 \return error if any 1918 */ 1919 GF_Err gf_isom_set_copyright(GF_ISOFile *isom_file, const char *threeCharCode, char *notice); 1920 1921 /*! adds a kind type to a track 1922 \param isom_file the target ISO file 1923 \param trackNumber the target track 1924 \param schemeURI the scheme URI of the added kind 1925 \param value the value of the added kind 1926 \return error if any 1927 */ 1928 GF_Err gf_isom_add_track_kind(GF_ISOFile *isom_file, u32 trackNumber, const char *schemeURI, const char *value); 1929 1930 /*! removes a kind type to the track, all if NULL params 1931 \param isom_file the target ISO file 1932 \param trackNumber the target track 1933 \param schemeURI the scheme URI of the removed kind 1934 \param value the value of the removed kind 1935 \return error if any 1936 */ 1937 GF_Err gf_isom_remove_track_kind(GF_ISOFile *isom_file, u32 trackNumber, const char *schemeURI, const char *value); 1938 1939 /*! changes the handler type of the media 1940 \warning this may completely breaks the parsing of the media track 1941 \param isom_file the target ISO file 1942 \param trackNumber the target track 1943 \param new_type the new handler four character type 1944 \return error if any 1945 */ 1946 GF_Err gf_isom_set_media_type(GF_ISOFile *isom_file, u32 trackNumber, u32 new_type); 1947 1948 /*! changes the type of the sampleDescriptionBox 1949 \warning this may completely breaks the parsing of the media track 1950 \param isom_file the target ISO file 1951 \param trackNumber the target track 1952 \param sampleDescriptionIndex the target sample description index 1953 \param new_type the new four character code type of the smaple description 1954 \return error if any 1955 */ 1956 GF_Err gf_isom_set_media_subtype(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 new_type); 1957 1958 /*! sets a track in an alternate group 1959 \param isom_file the target ISO file 1960 \param trackNumber the target track 1961 \param groupId the alternate group ID 1962 \return error if any 1963 */ 1964 GF_Err gf_isom_set_alternate_group_id(GF_ISOFile *isom_file, u32 trackNumber, u32 groupId); 1965 1966 /*! adds chapter info: 1967 1968 \param isom_file the target ISO file 1969 \param trackNumber the target track. If 0, the chapter info is added to the movie, otherwise to the track 1970 \param timestamp the chapter start time in milliseconds. Chapters are added in order to the file. If a chapter with same timestamp 1971 is found, its name is updated but no entry is created. 1972 \param name the chapter name. If NULL, defaults to 'Chapter N' 1973 \return error if any 1974 */ 1975 GF_Err gf_isom_add_chapter(GF_ISOFile *isom_file, u32 trackNumber, u64 timestamp, char *name); 1976 1977 /*! deletes copyright 1978 \param isom_file the target ISO file 1979 \param trackNumber the target track 1980 \param index the 1-based index of the copyright notice to remove, or 0 to remove all copyrights 1981 \return error if any 1982 */ 1983 GF_Err gf_isom_remove_chapter(GF_ISOFile *isom_file, u32 trackNumber, u32 index); 1984 1985 /*! updates or inserts a new edit in the track time line. Edits are used to modify 1986 the media normal timing. EditTime and EditDuration are expressed in movie timescale 1987 \note If a segment with EditTime already exists, it is erase 1988 \note If there is a segment before this new one, its duration is adjust to match EditTime of the new segment 1989 \warning The first segment always have an EditTime of 0. You should insert an empty or dwelled segment first 1990 1991 \param isom_file the target ISO file 1992 \param trackNumber the target track 1993 \param EditTime the start of the edit in movie timescale 1994 \param EditDuration the duration of the edit in movie timecale 1995 \param MediaTime the corresponding media time of the start of the edit, in media timescale. -1 for empty edits 1996 \param EditMode the edit mode 1997 \return error if any 1998 */ 1999 GF_Err gf_isom_set_edit(GF_ISOFile *isom_file, u32 trackNumber, u64 EditTime, u64 EditDuration, u64 MediaTime, GF_ISOEditType EditMode); 2000 2001 /*! same as \ref gf_isom_set_edit except only modifies duration type and mediaType 2002 \param isom_file the target ISO file 2003 \param trackNumber the target track 2004 \param edit_index the 1-based index of the edit to update 2005 \param EditDuration duration of the edit in movie timescale 2006 \param MediaTime the corresponding media time of the start of the edit, in media timescale. -1 for empty edits 2007 \param EditMode the edit mode 2008 \return error if any 2009 */ 2010 GF_Err gf_isom_modify_edit(GF_ISOFile *isom_file, u32 trackNumber, u32 edit_index, u64 EditDuration, u64 MediaTime, GF_ISOEditType EditMode); 2011 2012 /*! same as \ref gf_isom_modify_edit except only appends new segment 2013 \param isom_file the target ISO file 2014 \param trackNumber the target track 2015 \param EditDuration duration of the edit in movie timescale 2016 \param MediaTime the corresponding media time of the start of the edit, in media timescale. -1 for empty edits 2017 \param EditMode the edit mode 2018 \return error if any 2019 */ 2020 GF_Err gf_isom_append_edit(GF_ISOFile *isom_file, u32 trackNumber, u64 EditDuration, u64 MediaTime, GF_ISOEditType EditMode); 2021 2022 /*! removes all edits in the track 2023 \param isom_file the target ISO file 2024 \param trackNumber the target track 2025 \return error if any 2026 */ 2027 GF_Err gf_isom_remove_edits(GF_ISOFile *isom_file, u32 trackNumber); 2028 2029 /*! removes the given edit. If this is not the last segment, the next segment duration is updated to maintain a continous timeline 2030 \param isom_file the target ISO file 2031 \param trackNumber the target track 2032 \param edit_index the 1-based index of the edit to update 2033 \return error if any 2034 */ 2035 GF_Err gf_isom_remove_edit(GF_ISOFile *isom_file, u32 trackNumber, u32 edit_index); 2036 2037 /*! updates edit list after track edition. All edit entries with a duration or media starttime larger than the media duration are clamped to media duration 2038 \param isom_file the target ISO file 2039 \param trackNumber the target track 2040 \return error if any 2041 */ 2042 GF_Err gf_isom_update_edit_list_duration(GF_ISOFile *isom_file, u32 trackNumber); 2043 2044 2045 /*! remove track, moov or file-level UUID box of matching type 2046 \param isom_file the target ISO file 2047 \param trackNumber the target track for the UUID box; if 0, removes from movie; if 0xFFFFFFFF, removes from file 2048 \param UUID the UUID of the box to remove 2049 \return error if any 2050 */ 2051 GF_Err gf_isom_remove_uuid(GF_ISOFile *isom_file, u32 trackNumber, bin128 UUID); 2052 2053 /*! adds track, moov or file-level UUID box 2054 \param isom_file the target ISO file 2055 \param trackNumber the target track for the UUID box; if 0, removes from movie; if 0xFFFFFFFF, removes from file 2056 \param UUID the UUID of the box to remove 2057 \param data the data to add, may be NULL 2058 \param size the size of the data to add, shall be 0 when data is NULL 2059 \return error if any 2060 */ 2061 GF_Err gf_isom_add_uuid(GF_ISOFile *isom_file, u32 trackNumber, bin128 UUID, const u8 *data, u32 size); 2062 2063 /*! uses a compact track version for sample size. This is not usually recommended 2064 except for speech codecs where the track has a lot of small samples 2065 compaction is done automatically while writing based on the track's sample sizes 2066 \param isom_file the target ISO file 2067 \param trackNumber the target track for the udta box; if 0, add the udta to the movie; 2068 \param CompactionOn if set to GF_TRUE, compact size tables are used; otherwise regular size tables are used 2069 \return error if any 2070 */ 2071 GF_Err gf_isom_use_compact_size(GF_ISOFile *isom_file, u32 trackNumber, Bool CompactionOn); 2072 2073 /*! sets the brand of the movie 2074 \note this automatically adds the major brand to the set of alternate brands if not present 2075 \param isom_file the target ISO file 2076 \param MajorBrand four character code of the major brand to set 2077 \param MinorVersion version of the brand 2078 \return error if any 2079 */ 2080 GF_Err gf_isom_set_brand_info(GF_ISOFile *isom_file, u32 MajorBrand, u32 MinorVersion); 2081 2082 /*! adds or removes an alternate brand for the movie. 2083 \note When removing an alternate brand equal to the major brand, the major brand is updated with the first alternate brand remaining, or 'isom' otherwise 2084 \param isom_file the target ISO file 2085 \param Brand four character code of the brand to add or remove 2086 \param AddIt if set to GF_TRUE, the brand is added, otherwise it is removed 2087 \return error if any 2088 */ 2089 GF_Err gf_isom_modify_alternate_brand(GF_ISOFile *isom_file, u32 Brand, Bool AddIt); 2090 2091 /*! removes all alternate brands except major brand 2092 \param isom_file the target ISO file 2093 \return error if any 2094 */ 2095 GF_Err gf_isom_reset_alt_brands(GF_ISOFile *isom_file); 2096 2097 /*! set sample dependency flags - see ISO/IEC 14496-12 and \ref gf_filter_pck_set_dependency_flags 2098 \param isom_file the target ISO file 2099 \param trackNumber the target track number 2100 \param sampleNumber the target sample number 2101 \param isLeading indicates that the sample is a leading picture 2102 \param dependsOn indicates the sample dependency towards other samples 2103 \param dependedOn indicates the sample dependency from other samples 2104 \param redundant indicates that the sample contains redundant coding 2105 \return error if any 2106 */ 2107 GF_Err gf_isom_set_sample_flags(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber, u32 isLeading, u32 dependsOn, u32 dependedOn, u32 redundant); 2108 2109 /*! sets size information of a sample description of a visual track 2110 \param isom_file the target ISO file 2111 \param trackNumber the target track number 2112 \param sampleDescriptionIndex the target sample description index 2113 \param Width the width in pixels 2114 \param Height the height in pixels 2115 \return error if any 2116 */ 2117 GF_Err gf_isom_set_visual_info(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 Width, u32 Height); 2118 2119 /*! sets bit depth of a sample description of a visual track (for uncompressed media usually) 2120 \param isom_file the target ISO file 2121 \param trackNumber the target track number 2122 \param sampleDescriptionIndex the target sample description index 2123 \param bitDepth the bit depth of each pixel (eg 24 for RGB, 32 for RGBA) 2124 \return error if any 2125 */ 2126 GF_Err gf_isom_set_visual_bit_depth(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u16 bitDepth); 2127 2128 /*! sets a visual track layout info 2129 \param isom_file the target ISO file 2130 \param trackNumber the target track number 2131 \param width the track width in pixels 2132 \param height the track height in pixels 2133 \param translation_x the horizontal translation (from the left) of the track in the movie canvas, expressed as 16.16 fixed point float 2134 \param translation_y the vertical translation (from the top) of the track in the movie canvas, expressed as 16.16 fixed point float 2135 \param layer z order of the track on the canvas 2136 \return error if any 2137 */ 2138 GF_Err gf_isom_set_track_layout_info(GF_ISOFile *isom_file, u32 trackNumber, u32 width, u32 height, s32 translation_x, s32 translation_y, s16 layer); 2139 2140 /*! sets track matrix 2141 \param isom_file the target ISO file 2142 \param trackNumber the target track number 2143 \param matrix the transformation matrix of the track on the movie canvas; all coeficients are expressed as 16.16 floating points 2144 \return error if any 2145 */ 2146 GF_Err gf_isom_set_track_matrix(GF_ISOFile *isom_file, u32 trackNumber, s32 matrix[9]); 2147 2148 /*! sets the pixel aspect ratio for a sample description 2149 \note the aspect ratio is expressed as hSpacing divided by vSpacing; 2:1 means pixel is twice as wide as it is high 2150 \param isom_file the target ISO file 2151 \param trackNumber the target track number 2152 \param sampleDescriptionIndex the target sample description index 2153 \param hSpacing horizontal spacing of the aspect ratio; a value of 0 removes PAR; negative value means 1 2154 \param vSpacing vertical spacing of the aspect ratio; a value of 0 removes PAR; negative value means 1 2155 \param force_par if set, forces PAR to 1:1 when hSpacing=vSpacing; otherwise removes PAR when hSpacing=vSpacing 2156 \return error if any 2157 */ 2158 GF_Err gf_isom_set_pixel_aspect_ratio(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, s32 hSpacing, s32 vSpacing, Bool force_par); 2159 2160 /*! sets clean apperture (crop window, see ISO/IEC 14496-12) for a sample description 2161 \param isom_file the target ISO file 2162 \param trackNumber the target track number 2163 \param sampleDescriptionIndex the target sample description index 2164 \param cleanApertureWidthN nominator of clean apperture horizontal size 2165 \param cleanApertureWidthD denominator of clean apperture horizontal size 2166 \param cleanApertureHeightN nominator of clean apperture vertical size 2167 \param cleanApertureHeightD denominator of clean apperture vertical size 2168 \param horizOffN nominator of horizontal offset of clean apperture center minus (width-1)/2 (eg 0 sets center to center of video) 2169 \param horizOffD denominator of horizontal offset of clean apperture center minus (width-1)/2 (eg 0 sets center to center of video) 2170 \param vertOffN nominator of vertical offset of clean apperture center minus (height-1)/2 (eg 0 sets center to center of video) 2171 \param vertOffD denominator of vertical offset of clean apperture center minus (height-1)/2 (eg 0 sets center to center of video) 2172 \return error if any 2173 */ 2174 GF_Err gf_isom_set_clean_aperture(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 cleanApertureWidthN, u32 cleanApertureWidthD, u32 cleanApertureHeightN, u32 cleanApertureHeightD, u32 horizOffN, u32 horizOffD, u32 vertOffN, u32 vertOffD); 2175 2176 /*! updates track aperture information for QT/ProRes 2177 \param isom_file the target ISO file 2178 \param trackNumber the target track number 2179 \param remove if GF_TRUE, remove track aperture information, otherwise updates it 2180 \return error if any 2181 */ 2182 GF_Err gf_isom_update_aperture_info(GF_ISOFile *isom_file, u32 trackNumber, Bool remove); 2183 2184 /*! content light level info*/ 2185 typedef struct { 2186 /*! max content ligth level*/ 2187 u16 max_content_light_level; 2188 /*! max picture average ligth level*/ 2189 u16 max_pic_average_light_level; 2190 } GF_ContentLightLevelInfo; 2191 2192 /*! mastering display colour volume info*/ 2193 typedef struct { 2194 /*! display primaries*/ 2195 struct { 2196 u16 x; 2197 u16 y; 2198 } display_primaries[3]; 2199 /*! X white point*/ 2200 u16 white_point_x; 2201 /*! Y white point*/ 2202 u16 white_point_y; 2203 u32 max_display_mastering_luminance; 2204 /*! min display mastering luminance*/ 2205 u32 min_display_mastering_luminance; 2206 } GF_MasteringDisplayColourVolumeInfo; 2207 2208 2209 /*! sets high dynamic range information for a sample description 2210 \param isom_file the target ISO file 2211 \param trackNumber the target track number 2212 \param sampleDescriptionIndex the target sample description index 2213 \param mdcv the mastering display colour volume to set 2214 \param clli the content light level to set 2215 \return error if any 2216 */ 2217 GF_Err gf_isom_set_high_dynamic_range_info(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, GF_MasteringDisplayColourVolumeInfo *mdcv, GF_ContentLightLevelInfo *clli); 2218 2219 /*! force Dolby Vision profile: mainly used when the bitstream doesn't contain all the necessary information 2220 \param isom_file the target ISO file 2221 \param trackNumber the target track number 2222 \param sampleDescriptionIndex the target sample description index 2223 \param dv_profile the Dolby Vision profile 2224 \return error if any 2225 */ 2226 GF_Err gf_isom_set_dolby_vision_profile(GF_ISOFile* isom_file, u32 trackNumber, u32 StreamDescriptionIndex, u32 dv_profile); 2227 2228 2229 /*! sets image sequence coding constraints (mostly used for HEIF image files) 2230 \param isom_file the target ISO file 2231 \param trackNumber the target track number 2232 \param sampleDescriptionIndex the target sample description index 2233 \param remove if set to GF_TRUE, removes coding constraints 2234 \param all_ref_pics_intra indicates if all reference pictures are intra frames 2235 \param intra_pred_used indicates if intra prediction is used 2236 \param max_ref_per_pic indicates the max number of reference images per picture 2237 \return error if any 2238 */ 2239 GF_Err gf_isom_set_image_sequence_coding_constraints(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, Bool remove, Bool all_ref_pics_intra, Bool intra_pred_used, u32 max_ref_per_pic); 2240 2241 /*! sets image sequence alpha flag (mostly used for HEIF image files). The alpha flag indicates the image sequence is an alpha plane 2242 or has an alpha channel 2243 \param isom_file the target ISO file 2244 \param trackNumber the target track number 2245 \param sampleDescriptionIndex the target sample description index 2246 \param remove if set to GF_TRUE, removes coding constraints 2247 \return error if any 2248 */ 2249 GF_Err gf_isom_set_image_sequence_alpha(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, Bool remove); 2250 2251 /*! sets colour information for a sample description 2252 \param isom_file the target ISO file 2253 \param trackNumber the target track number 2254 \param sampleDescriptionIndex the target sample description index 2255 \param colour_type the four character code of the colour type to set (nclc, nclx, prof, ricc); if 0, removes all color info 2256 \param colour_primaries the colour primaries for nclc/nclx as defined in ISO/IEC 23001-8 2257 \param transfer_characteristics the colour primaries for nclc/nclx as defined in ISO/IEC 23001-8 2258 \param matrix_coefficients the colour primaries for nclc/nclx as defined in ISO/IEC 23001-8 2259 \param full_range_flag the colour primaries for nclc as defined in ISO/IEC 23001-8 2260 \param icc_data the icc data pto set for prof and ricc types 2261 \param icc_size the size of the icc data 2262 \return error if any 2263 */ 2264 GF_Err gf_isom_set_visual_color_info(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 colour_type, u16 colour_primaries, u16 transfer_characteristics, u16 matrix_coefficients, Bool full_range_flag, u8 *icc_data, u32 icc_size); 2265 2266 2267 /*! Audio Sample Description signaling mode*/ 2268 typedef enum { 2269 /*! use ISOBMF sample entry v0*/ 2270 GF_IMPORT_AUDIO_SAMPLE_ENTRY_NOT_SET = 0, 2271 /*! use ISOBMF sample entry v0*/ 2272 GF_IMPORT_AUDIO_SAMPLE_ENTRY_v0_BS, 2273 /*! use ISOBMF sample entry v0 and forces channel count to 2*/ 2274 GF_IMPORT_AUDIO_SAMPLE_ENTRY_v0_2, 2275 /*! use ISOBMF sample entry v1*/ 2276 GF_IMPORT_AUDIO_SAMPLE_ENTRY_v1_MPEG, 2277 /*! use QTFF sample entry v1*/ 2278 GF_IMPORT_AUDIO_SAMPLE_ENTRY_v1_QTFF 2279 } GF_AudioSampleEntryImportMode; 2280 2281 2282 /*! sets audio format information for a sample description 2283 \param isom_file the target ISO file 2284 \param trackNumber the target track number 2285 \param sampleDescriptionIndex the target sample description index 2286 \param sampleRate the audio sample rate 2287 \param nbChannels the number of audio channels 2288 \param bitsPerSample the number of bits per sample, mostly used for raw audio 2289 \param asemode type of audio entry signaling desired 2290 \return error if any 2291 */ 2292 GF_Err gf_isom_set_audio_info(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 sampleRate, u32 nbChannels, u8 bitsPerSample, GF_AudioSampleEntryImportMode asemode); 2293 2294 2295 /*! sets audio channel and object layout information for a sample description, ISOBMFF style 2296 \param isom_file the target ISO file 2297 \param trackNumber the target track number 2298 \param sampleDescriptionIndex the target sample description index 2299 \param layout the layout information 2300 \return error if any 2301 */ 2302 GF_Err gf_isom_set_audio_layout(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, GF_AudioChannelLayout *layout); 2303 2304 /*! sets CTS unpack mode (used for B-frames & like): in unpack mode, each sample uses one entry in CTTS tables 2305 2306 \param isom_file the target ISO file 2307 \param trackNumber the target track number 2308 \param unpack if GF_TRUE, sets unpack on, creating a ctts table if none found; if GF_FALSE, sets unpack off and repacks all table info 2309 \return error if any 2310 */ 2311 GF_Err gf_isom_set_cts_packing(GF_ISOFile *isom_file, u32 trackNumber, Bool unpack); 2312 2313 /*! shifts all CTS with the given offset. This MUST be called in unpack mode only 2314 \param isom_file the target ISO file 2315 \param trackNumber the target track number 2316 \param offset_shift CTS offset shift in media timescale 2317 \return error if any 2318 */ 2319 GF_Err gf_isom_shift_cts_offset(GF_ISOFile *isom_file, u32 trackNumber, s32 offset_shift); 2320 2321 /*! enables negative composition offset in track 2322 \note this will compute the composition to decode time information 2323 \param isom_file the target ISO file 2324 \param trackNumber the target track 2325 \param use_negative_offsets if GF_TRUE, negative offsets are used, otherwise they are disabled 2326 \return error if any 2327 */ 2328 GF_Err gf_isom_set_composition_offset_mode(GF_ISOFile *isom_file, u32 trackNumber, Bool use_negative_offsets); 2329 2330 /*! enables negative composition offset in track and shift offsets 2331 2332 \param isom_file the target ISO file 2333 \param trackNumber the target track 2334 \param ctts_shift shif CTS offsets by the given time in media timescale if positive offsets only are used 2335 \return error if any 2336 */ 2337 GF_Err gf_isom_set_ctts_v1(GF_ISOFile *isom_file, u32 trackNumber, u32 ctts_shift); 2338 2339 2340 /*! sets language for a track 2341 \param isom_file the target ISO file 2342 \param trackNumber the target track number 2343 \param code 3-character code or BCP-47 code media language 2344 \return error if any 2345 */ 2346 GF_Err gf_isom_set_media_language(GF_ISOFile *isom_file, u32 trackNumber, char *code); 2347 2348 /*! gets the ID of the last created track 2349 \param isom_file the target ISO file 2350 \return the last created track ID 2351 */ 2352 GF_ISOTrackID gf_isom_get_last_created_track_id(GF_ISOFile *isom_file); 2353 2354 /*! applies a box patch to the file. See examples in gpac test suite, media/boxpatch/ 2355 \param isom_file the target ISO file 2356 \param trackID the ID of the track to patch, in case one of the box patch applies to a track 2357 \param box_patch_filename the name of the file containing the box patches 2358 \param for_fragments indicates if the patch targets movie fragments or regular moov 2359 \return error if any 2360 */ 2361 GF_Err gf_isom_apply_box_patch(GF_ISOFile *isom_file, GF_ISOTrackID trackID, const char *box_patch_filename, Bool for_fragments); 2362 2363 /*! sets track magic number 2364 \param isom_file the target ISO file 2365 \param trackNumber the target track 2366 \param magic the magic number to set; magic number is not written to file 2367 \return error if any 2368 */ 2369 GF_Err gf_isom_set_track_magic(GF_ISOFile *isom_file, u32 trackNumber, u64 magic); 2370 2371 /*! sets track index in moov 2372 \param isom_file the target ISO file 2373 \param trackNumber the target track 2374 \param index the 1-based index to set. Tracks will be reordered after this! 2375 \param track_num_changed callback function used to notify track changes during the call to this function 2376 \param udta opaque user data for the callback function 2377 \return error if any 2378 */ 2379 GF_Err gf_isom_set_track_index(GF_ISOFile *isom_file, u32 trackNumber, u32 index, void (*track_num_changed)(void *udta, u32 old_track_num, u32 new_track_num), void *udta); 2380 2381 /*! removes a sample description with the given index 2382 \warning This does not remove any added samples for that stream description, nor rewrite the sample to chunk and other boxes referencing the sample description index ! 2383 \param isom_file the target ISO file 2384 \param trackNumber the target track number 2385 \param sampleDescriptionIndex the target sample description to remove 2386 \return error if any 2387 */ 2388 GF_Err gf_isom_remove_stream_description(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 2389 2390 /*! updates average and max bitrate of a sample description 2391 if both average_bitrate and max_bitrate are 0, this removes any bitrate information 2392 \param isom_file the target ISO file 2393 \param trackNumber the target track number 2394 \param sampleDescriptionIndex the target sample description 2395 \param average_bitrate the average bitrate of the media for that sample description 2396 \param max_bitrate the maximum bitrate of the media for that sample description 2397 \param decode_buffer_size the decoder buffer size in bytes for that sample description 2398 \return error if any 2399 */ 2400 GF_Err gf_isom_update_bitrate(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 average_bitrate, u32 max_bitrate, u32 decode_buffer_size); 2401 2402 2403 /*! track clone flags*/ 2404 typedef enum 2405 { 2406 /*! set this flag to keep data reference entries while cloning track*/ 2407 GF_ISOM_CLONE_TRACK_KEEP_DREF = 1, 2408 /*! set this flag to avoid cloning track as a QT track while cloning track*/ 2409 GF_ISOM_CLONE_TRACK_NO_QT = 1<<1 2410 } GF_ISOTrackCloneFlags; 2411 2412 /*! clones a track. This clones everything except media data and sample info (DTS, CTS, RAPs, etc...), and also clones sample descriptions 2413 \param orig_file the source ISO file 2414 \param orig_track the source track 2415 \param dest_file the destination ISO file 2416 \param flags flags to use during clone 2417 \param dest_track set to the track number of cloned track 2418 \return error if any 2419 */ 2420 GF_Err gf_isom_clone_track(GF_ISOFile *orig_file, u32 orig_track, GF_ISOFile *dest_file, GF_ISOTrackCloneFlags flags, u32 *dest_track); 2421 2422 2423 /*! sets the GroupID of a track (only used for optimized interleaving). By setting GroupIDs 2424 you can specify the storage order for media data of a group of streams. This is useful 2425 for BIFS presentation so that static resources of the scene can be downloaded before BIFS 2426 2427 \param isom_file the target ISO file 2428 \param trackNumber the target track 2429 \param GroupID the desired group ID 2430 \return error if any 2431 */ 2432 GF_Err gf_isom_set_track_interleaving_group(GF_ISOFile *isom_file, u32 trackNumber, u32 GroupID); 2433 2434 /*! sets the priority of a track within a Group (used for optimized interleaving and hinting). 2435 This allows tracks to be stored before other within a same group, for instance the 2436 hint track data can be stored just before the media data, reducing disk seeking 2437 2438 \param isom_file the target ISO file 2439 \param trackNumber the target track 2440 \param InversePriority the desired priority. For a same time, within a group of tracks, the track with the lowest InversePriority will 2441 be written first 2442 \return error if any 2443 */ 2444 GF_Err gf_isom_set_track_priority_in_group(GF_ISOFile *isom_file, u32 trackNumber, u32 InversePriority); 2445 2446 /*! sets the maximum chunk size for a track 2447 \param isom_file the target ISO file 2448 \param trackNumber the target track 2449 \param maxChunkSize the maximum chunk size in bytes 2450 \return error if any 2451 */ 2452 GF_Err gf_isom_hint_max_chunk_size(GF_ISOFile *isom_file, u32 trackNumber, u32 maxChunkSize); 2453 2454 /*! sets up interleaving for storage (shortcut for storeage mode + interleave_time) 2455 \param isom_file the target ISO file 2456 \param TimeInSec the desired interleaving time in seconds 2457 \return error if any 2458 */ 2459 GF_Err gf_isom_make_interleave(GF_ISOFile *isom_file, Double TimeInSec); 2460 2461 /*! sets progress callback when writing a file 2462 \param isom_file the target ISO file 2463 \param progress_cbk the progress callback function 2464 \param progress_cbk_udta opaque data passed to the progress callback function 2465 */ 2466 void gf_isom_set_progress_callback(GF_ISOFile *isom_file, void (*progress_cbk)(void *udta, u64 nb_done, u64 nb_total), void *progress_cbk_udta); 2467 2468 /*! sets write callback functions for in-memory file writing 2469 \param isom_file the target ISO file 2470 \param on_block_out the block write callback function 2471 \param on_block_patch the block patch callback function 2472 \param usr_data opaque user data passed to callback functions 2473 \param block_size desired block size in bytes 2474 \return error if any 2475 */ 2476 GF_Err gf_isom_set_write_callback(GF_ISOFile *isom_file, 2477 GF_Err (*on_block_out)(void *cbk, u8 *data, u32 block_size), 2478 GF_Err (*on_block_patch)(void *usr_data, u8 *block, u32 block_size, u64 block_offset, Bool is_insert), 2479 void *usr_data, 2480 u32 block_size); 2481 2482 /*! @} */ 2483 2484 #endif // GPAC_DISABLE_ISOM_WRITE 2485 2486 /*! 2487 \addtogroup isomp4sys_grp ISOBMFF MPEG-4 Systems 2488 \ingroup iso_grp 2489 2490 MPEG-4 Systems extensions 2491 @{ 2492 */ 2493 2494 2495 /*! MPEG-4 ProfileAndLevel codes*/ 2496 typedef enum 2497 { 2498 /*! Audio PL*/ 2499 GF_ISOM_PL_AUDIO, 2500 /*! Visual PL*/ 2501 GF_ISOM_PL_VISUAL, 2502 /*! Graphics PL*/ 2503 GF_ISOM_PL_GRAPHICS, 2504 /*! Scene PL*/ 2505 GF_ISOM_PL_SCENE, 2506 /*! OD PL*/ 2507 GF_ISOM_PL_OD, 2508 /*! MPEG-J PL*/ 2509 GF_ISOM_PL_MPEGJ, 2510 /*! not a profile, just set/unset inlineFlag*/ 2511 GF_ISOM_PL_INLINE, 2512 } GF_ISOProfileLevelType; 2513 2514 /*! gets MPEG-4 subtype of a sample description entry (eg, mp4a, mp4v, enca, encv, resv, etc...) 2515 \param isom_file the target ISO file 2516 \param trackNumber the target track 2517 \param sampleDescriptionIndex the target sample description index (1-based) 2518 \return the media type FOUR CHAR code type of an MPEG4 media, or 0 if not MPEG-4 subtype 2519 */ 2520 u32 gf_isom_get_mpeg4_subtype(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 2521 2522 /*! checks if files has root OD/IOD or not 2523 \param isom_file the target ISO file 2524 \return GF_TRUE if the file has a root OD or IOD */ 2525 Bool gf_isom_has_root_od(GF_ISOFile *isom_file); 2526 2527 /*! fetches the root OD of a file (can be NULL, OD or IOD, you have to check its tag) 2528 \param isom_file the target ISO file 2529 \return the OD/IOD if any. Caller must destroy the descriptor 2530 */ 2531 GF_Descriptor *gf_isom_get_root_od(GF_ISOFile *isom_file); 2532 2533 /*! disable OD conversion from ISOM internal to regular OD tags 2534 \param isom_file the target ISO file 2535 \param disable if TRUE, ODs and ESDs will not be converted 2536 */ 2537 void gf_isom_disable_odf_conversion(GF_ISOFile *movie, Bool disable); 2538 2539 /*! checks the presence of a track in rood OD/IOD 2540 \param isom_file the target ISO file 2541 \param trackNumber the target track 2542 \return 0: NO, 1: YES, 2: ERROR*/ 2543 u8 gf_isom_is_track_in_root_od(GF_ISOFile *isom_file, u32 trackNumber); 2544 2545 /*! gets the GF_ESD given the sampleDescriptionIndex 2546 \param isom_file the target ISO file 2547 \param trackNumber the target track 2548 \param sampleDescriptionIndex the target sample description index (1-based) 2549 \return the ESD associated to the sample description index, or NULL if error or not supported. Caller must destroy the ESD*/ 2550 GF_ESD *gf_isom_get_esd(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 2551 2552 /*! gets the decoderConfigDescriptor given the sampleDescriptionIndex 2553 \param isom_file the target ISO file 2554 \param trackNumber the target track 2555 \param sampleDescriptionIndex the target sample description index (1-based) 2556 \return the decoder configuration descriptor associated to the sample description index, or NULL if error or not supported. Caller must destroy the descriptor 2557 */ 2558 GF_DecoderConfig *gf_isom_get_decoder_config(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 2559 2560 /*! sets default TrackID (or ES_ID) for clock references. 2561 \param isom_file the target ISO file 2562 \param trackNumber the target track to set as a clock reference. If 0, default sync track ID is reseted and will be reassigned at next ESD fetch*/ 2563 void gf_isom_set_default_sync_track(GF_ISOFile *isom_file, u32 trackNumber); 2564 2565 /*! gets the profile and level value for MPEG-4 streams 2566 \param isom_file the target ISO file 2567 \param PL_Code the target profile to query file 2568 \return the profile and level value, 0xFF if not defined 2569 */ 2570 u8 gf_isom_get_pl_indication(GF_ISOFile *isom_file, GF_ISOProfileLevelType PL_Code); 2571 2572 /*! finds the first ObjectDescriptor using the given track by inspecting all OD tracks 2573 \param isom_file the target ISO file 2574 \param trackNumber the target track 2575 \return the OD ID if dound, 0 otherwise*/ 2576 u32 gf_isom_find_od_id_for_track(GF_ISOFile *isom_file, u32 trackNumber); 2577 2578 /*! sets a profile and level indication for the movie iod (created if needed) 2579 \note Use for MPEG-4 Systems only 2580 if the flag is ProfileLevel is 0 this means the movie doesn't require 2581 the specific codec (equivalent to 0xFF value in MPEG profiles) 2582 \param isom_file the target ISO file 2583 \param PL_Code the profile and level code to set 2584 \param ProfileLevel the profile and level value to set 2585 \return error if any 2586 */ 2587 GF_Err gf_isom_set_pl_indication(GF_ISOFile *isom_file, u8 PL_Code, GF_ISOProfileLevelType ProfileLevel); 2588 2589 #ifndef GPAC_DISABLE_ISOM_WRITE 2590 /*! sets the rootOD ID of the movie if you need it. By default, movies are created without root ODs 2591 \note Use for MPEG-4 Systems only 2592 \param isom_file the target ISO file 2593 \param OD_ID ID to assign to the root OD/IOD 2594 \return error if any 2595 */ 2596 GF_Err gf_isom_set_root_od_id(GF_ISOFile *isom_file, u32 OD_ID); 2597 2598 /*! sets the rootOD URL of the movie if you need it (only needed to create an empty file pointing 2599 to external ressource) 2600 \note Use for MPEG-4 Systems only 2601 \param isom_file the target ISO file 2602 \param url_string the URL to assign to the root OD/IOD 2603 \return error if any 2604 */ 2605 GF_Err gf_isom_set_root_od_url(GF_ISOFile *isom_file, const char *url_string); 2606 2607 /*! removes the root OD 2608 \note Use for MPEG-4 Systems only 2609 \param isom_file the target ISO file 2610 \return error if any 2611 */ 2612 GF_Err gf_isom_remove_root_od(GF_ISOFile *isom_file); 2613 2614 /*! adds a system descriptor to the OD of the movie 2615 \note Use for MPEG-4 Systems only 2616 \param isom_file the target ISO file 2617 \param theDesc the descriptor to add 2618 \return error if any 2619 */ 2620 GF_Err gf_isom_add_desc_to_root_od(GF_ISOFile *isom_file, const GF_Descriptor *theDesc); 2621 2622 /*! adds a track to the root OD 2623 \note Use for MPEG-4 Systems only 2624 \param isom_file the target ISO file 2625 \param trackNumber the track to add to the root OD 2626 \return error if any 2627 */ 2628 GF_Err gf_isom_add_track_to_root_od(GF_ISOFile *isom_file, u32 trackNumber); 2629 2630 /*! removes a track to the root OD 2631 \note Use for MPEG-4 Systems only 2632 \param isom_file the target ISO file 2633 \param trackNumber the track to remove from the root OD 2634 \return error if any 2635 */ 2636 GF_Err gf_isom_remove_track_from_root_od(GF_ISOFile *isom_file, u32 trackNumber); 2637 2638 2639 /*! creates a new MPEG-4 sample description in a track 2640 2641 \note Used for MPEG-4 Systems, AAC and MPEG-4 Visual (part 2) 2642 2643 \param isom_file the target ISO file 2644 \param trackNumber the target track number 2645 \param esd the ESD to use for that sample description 2646 \param URLname URL value of the data reference, NULL if no data reference (media in the file) 2647 \param URNname URN value of the data reference, NULL if no data reference (media in the file) 2648 \param outDescriptionIndex set to index of the new sample description 2649 \return error if any 2650 */ 2651 GF_Err gf_isom_new_mpeg4_description(GF_ISOFile *isom_file, u32 trackNumber, const GF_ESD *esd, const char *URLname, const char *URNname, u32 *outDescriptionIndex); 2652 2653 /*! changes an MPEG-4 sample description 2654 \note Used for MPEG-4 Systems, AAC and MPEG-4 Visual (part 2) 2655 \warning This will replace the whole ESD 2656 \param isom_file the target ISO file 2657 \param trackNumber the target track number 2658 \param sampleDescriptionIndex the target sample description 2659 \param newESD the new ESD to use for that sample description 2660 \return error if any 2661 */ 2662 GF_Err gf_isom_change_mpeg4_description(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, const GF_ESD *newESD); 2663 2664 /*! adds an MPEG-4 systems descriptor to the ESD of a sample description 2665 \note Used for MPEG-4 Systems, AAC and MPEG-4 Visual (part 2) 2666 \warning This will replace the whole ESD 2667 \param isom_file the target ISO file 2668 \param trackNumber the target track number 2669 \param sampleDescriptionIndex the target sample description 2670 \param theDesc the descriptor to add to the ESD of the sample description 2671 \return error if any 2672 */ 2673 GF_Err gf_isom_add_desc_to_description(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, const GF_Descriptor *theDesc); 2674 2675 /*! clones IOD PLs from orig to dest if any 2676 \param orig_file the source ISO file 2677 \param dest_file the destination ISO file 2678 \return error if any 2679 */ 2680 GF_Err gf_isom_clone_pl_indications(GF_ISOFile *orig_file, GF_ISOFile *dest_file); 2681 2682 /*deletes chapter (1-based index, index 0 for all)*/ 2683 GF_Err gf_isom_remove_chapter(GF_ISOFile *the_file, u32 trackNumber, u32 index); 2684 2685 /*! associates a given SL config with a given ESD while extracting the OD information 2686 This is useful while reading the IOD / OD stream of an MP4 file. Note however that 2687 only full AUs are extracted, therefore the calling application must SL-packetize the streams 2688 2689 \param isom_file the target ISO file 2690 \param trackNumber the target track 2691 \param sampleDescriptionIndex set to the sample description index corresponding to this sample (optional, can be NULL) 2692 \param slConfig the SL configuration descriptor to set. The descriptor is copied by the API for further use. A NULL pointer will result 2693 in using the default SLConfig (predefined = 2) remapped to predefined = 0 2694 \return error if any 2695 */ 2696 GF_Err gf_isom_set_extraction_slc(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, const GF_SLConfig *slConfig); 2697 2698 #endif //GPAC_DISABLE_ISOM_WRITE 2699 2700 2701 /*! @} */ 2702 2703 /*! 2704 \addtogroup isostsd_grp ISOBMFF Sample Descriptions 2705 \ingroup iso_grp 2706 2707 Sample Description functions are used to query and set codec parameters of a track 2708 2709 @{ 2710 */ 2711 2712 /*! Unknown sample description*/ 2713 typedef struct 2714 { 2715 /*! codec tag is the containing box's tag, 0 if UUID is used*/ 2716 u32 codec_tag; 2717 /*! entry UUID if no tag is used*/ 2718 bin128 UUID; 2719 /*! codec version*/ 2720 u16 version; 2721 /*! codec revision*/ 2722 u16 revision; 2723 /*! vendor four character code*/ 2724 u32 vendor_code; 2725 2726 /*! temporal quality, video codecs only*/ 2727 u32 temporal_quality; 2728 /*! spatial quality, video codecs only*/ 2729 u32 spatial_quality; 2730 /*! width in pixels, video codecs only*/ 2731 u16 width; 2732 /*! height in pixels, video codecs only*/ 2733 u16 height; 2734 /*! horizontal resolution as 16.16 fixed point, video codecs only*/ 2735 u32 h_res; 2736 /*! vertical resolution as 16.16 fixed point, video codecs only*/ 2737 u32 v_res; 2738 /*! bit depth resolution in bits, video codecs only*/ 2739 u16 depth; 2740 /*! color table, video codecs only*/ 2741 u16 color_table_index; 2742 /*! compressor name, video codecs only*/ 2743 char compressor_name[33]; 2744 2745 /*! sample rate, audio codecs only*/ 2746 u32 samplerate; 2747 /*! number of channels, audio codecs only*/ 2748 u16 nb_channels; 2749 /*! bits per sample, audio codecs only*/ 2750 u16 bits_per_sample; 2751 /*! indicates if QTFF signaling should be used, audio codecs only*/ 2752 Bool is_qtff; 2753 2754 /*optional, sample description specific configuration*/ 2755 u8 *extension_buf; 2756 /*optional, sample description specific size*/ 2757 u32 extension_buf_size; 2758 } GF_GenericSampleDescription; 2759 2760 /*! gets an unknown sample description 2761 \param isom_file the target ISO file 2762 \param trackNumber the target track 2763 \param sampleDescriptionIndex the target sample description index (1-based) 2764 \return generic sample description information, or NULL if error 2765 */ 2766 GF_GenericSampleDescription *gf_isom_get_generic_sample_description(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 2767 2768 /*! gets the decoder configuration of a JP2 file 2769 \param isom_file the target ISO file 2770 \param trackNumber the target track 2771 \param sampleDescriptionIndex the target sample description index (1-based) 2772 \param out_dsi set to the decoder configuration - shall be freed by user 2773 \param out_size set to the decoder configuration size 2774 \return error if any 2775 */ 2776 GF_Err gf_isom_get_jp2_config(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u8 **out_dsi, u32 *out_size); 2777 2778 2779 2780 /*! gets RVC (Reconvigurable Video Coding) config of a track for a given sample description 2781 \param isom_file the target ISO file 2782 \param trackNumber the target track 2783 \param sampleDescriptionIndex the target sample description index (1-based) 2784 \param rvc_predefined set to a predefined value of RVC 2785 \param data set to the RVC config buffer if not predefined, NULL otherwise 2786 \param size set to the RVC config buffer size 2787 \param mime set to the associated mime type of the stream 2788 \return error if any*/ 2789 GF_Err gf_isom_get_rvc_config(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u16 *rvc_predefined, u8 **data, u32 *size, const char **mime); 2790 2791 #ifndef GPAC_DISABLE_ISOM_WRITE 2792 /*! sets the RVC config for the given track sample description 2793 \param isom_file the target ISO file 2794 \param trackNumber the target track number 2795 \param sampleDescriptionIndex the target sample description index 2796 \param rvc_predefined the predefined RVC configuration code, 0 if not predefined 2797 \param mime the associated mime type of the video 2798 \param data the RVC configuration data; ignored if rvc_predefined is not 0 2799 \param size the size of the RVC configuration data; ignored if rvc_predefined is not 0 2800 \return error if any 2801 */ 2802 GF_Err gf_isom_set_rvc_config(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u16 rvc_predefined, char *mime, u8 *data, u32 size); 2803 2804 2805 /*! updates fields of given visual sample description - these fields are reserved in ISOBMFF, this should only be used for QT, see QTFF 2806 \param isom_file the target ISO file 2807 \param trackNumber the target track number 2808 \param sampleDescriptionIndex the target sample description 2809 \param revision revision of the sample description format 2810 \param vendor four character code of the vendor 2811 \param temporalQ temporal quality 2812 \param spatialQ spatial quality 2813 \param horiz_res horizontal resolution as 16.16 fixed point number 2814 \param vert_res vertical resolution as 16.16 fixed point number 2815 \param frames_per_sample number of frames per media samples 2816 \param compressor_name human readable name for the compressor 2817 \param color_table_index color table index, use -1 if no color table (most common case) 2818 \return error if any 2819 */ 2820 GF_Err gf_isom_update_video_sample_entry_fields(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u16 revision, u32 vendor, u32 temporalQ, u32 spatialQ, u32 horiz_res, u32 vert_res, u16 frames_per_sample, const char *compressor_name, s16 color_table_index); 2821 2822 /*! updates a sample description from a serialized sample description box. Only child boxes are removed in the process 2823 \param isom_file the target ISO file 2824 \param trackNumber the target track number 2825 \param sampleDescriptionIndex the target sample description 2826 \param data a serialized sample description box 2827 \param size size of the serialized sample description 2828 \return error if any 2829 */ 2830 GF_Err gf_isom_update_sample_description_from_template(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u8 *data, u32 size); 2831 2832 2833 /*! creates a new unknown StreamDescription in the file. 2834 \note use this to store media not currently supported by the ISO media format or media types not implemented in this library 2835 \param isom_file the target ISO file 2836 \param trackNumber the target track 2837 \param URLname URL value of the data reference, NULL if no data reference (media in the file) 2838 \param URNname URN value of the data reference, NULL if no data reference (media in the file) 2839 \param udesc generic sample description information to use 2840 \param outDescriptionIndex set to index of the new sample description 2841 \return error if any 2842 */ 2843 GF_Err gf_isom_new_generic_sample_description(GF_ISOFile *isom_file, u32 trackNumber, const char *URLname, const char *URNname, GF_GenericSampleDescription *udesc, u32 *outDescriptionIndex); 2844 2845 /*! clones a sample description without inspecting media types 2846 \param isom_file the destination ISO file 2847 \param trackNumber the destination track 2848 \param orig_file the source ISO file 2849 \param orig_track the source track 2850 \param orig_desc_index the source sample description to clone 2851 \param URLname URL value of the data reference, NULL if no data reference (media in the file) 2852 \param URNname URN value of the data reference, NULL if no data reference (media in the file) 2853 \param outDescriptionIndex set to index of the new sample description 2854 \return error if any 2855 */ 2856 GF_Err gf_isom_clone_sample_description(GF_ISOFile *isom_file, u32 trackNumber, GF_ISOFile *orig_file, u32 orig_track, u32 orig_desc_index, const char *URLname, const char *URNname, u32 *outDescriptionIndex); 2857 2858 /*! gets the sample description template of a track. This serializes sample description box 2859 \param isom_file the destination ISO file 2860 \param trackNumber the destination track 2861 \param sampleDescriptionIndex the target sample description 2862 \param output will be set to a newly allocated buffer containing the serialized box - caller shall free it 2863 \param output_size will be set to the size of the allocated buffer 2864 \return error if any 2865 */ 2866 GF_Err gf_isom_get_stsd_template(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u8 **output, u32 *output_size); 2867 2868 #endif // GPAC_DISABLE_ISOM_WRITE 2869 2870 /*! checks if sample descriptions are the same. This does include self-contained checking and reserved flags. The specific media cfg (DSI & co) is not analysed, only a memory comparaison is done 2871 \param f1 the first ISO file 2872 \param tk1 the first track 2873 \param sdesc_index1 the first sample description 2874 \param f2 the second ISO file 2875 \param tk2 the second track 2876 \param sdesc_index2 the second sample description 2877 \return GF_TRUE if sample descriptions match, GF_FALSE otherwise 2878 */ 2879 Bool gf_isom_is_same_sample_description(GF_ISOFile *f1, u32 tk1, u32 sdesc_index1, GF_ISOFile *f2, u32 tk2, u32 sdesc_index2); 2880 2881 2882 /*! Generic 3GP/3GP2 config record*/ 2883 typedef struct 2884 { 2885 /*GF_4CC record type, one fo the above GF_ISOM_SUBTYPE_3GP_ * subtypes*/ 2886 u32 type; 2887 /*4CC vendor name*/ 2888 u32 vendor; 2889 /*codec version*/ 2890 u8 decoder_version; 2891 /*number of sound frames per IsoMedia sample, >0 and <=15. The very last sample may contain less frames. */ 2892 u8 frames_per_sample; 2893 /*H263 ONLY - Level*/ 2894 u8 H263_level; 2895 /*H263 Profile*/ 2896 u8 H263_profile; 2897 /*AMR(WB) ONLY - num of mode for the codec*/ 2898 u16 AMR_mode_set; 2899 /*AMR(WB) ONLY - changes in codec mode per sample*/ 2900 u8 AMR_mode_change_period; 2901 } GF_3GPConfig; 2902 2903 2904 /*! gets a 3GPP sample description 2905 \param isom_file the target ISO file 2906 \param trackNumber the target track 2907 \param sampleDescriptionIndex the target sample description index 2908 \return the 3GP config for this sample description, NULL if not a 3GPP track 2909 */ 2910 GF_3GPConfig *gf_isom_3gp_config_get(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 2911 #ifndef GPAC_DISABLE_ISOM_WRITE 2912 /*! creates a 3GPP sample description 2913 \param isom_file the target ISO file 2914 \param trackNumber the target track 2915 \param config the 3GP config for this sample description 2916 \param URLname URL value of the data reference, NULL if no data reference (media in the file) 2917 \param URNname URN value of the data reference, NULL if no data reference (media in the file) 2918 \param outDescriptionIndex set to the index of the created sample description 2919 \return error if any 2920 */ 2921 GF_Err gf_isom_3gp_config_new(GF_ISOFile *isom_file, u32 trackNumber, GF_3GPConfig *config, const char *URLname, const char *URNname, u32 *outDescriptionIndex); 2922 /*! updates the 3GPP config - subtypes shall NOT differ 2923 \param isom_file the target ISO file 2924 \param trackNumber the target track 2925 \param config the 3GP config for this sample description 2926 \param sampleDescriptionIndex the target sample description index 2927 \return error if any 2928 */ 2929 GF_Err gf_isom_3gp_config_update(GF_ISOFile *isom_file, u32 trackNumber, GF_3GPConfig *config, u32 sampleDescriptionIndex); 2930 #endif /*GPAC_DISABLE_ISOM_WRITE*/ 2931 2932 2933 /*! gets AVC config for a sample description 2934 \param isom_file the target ISO file 2935 \param trackNumber the target track 2936 \param sampleDescriptionIndex the target sample description index 2937 \return the AVC config - user is responsible for deleting it 2938 */ 2939 GF_AVCConfig *gf_isom_avc_config_get(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 2940 /*! gets SVC config for a sample description 2941 \param isom_file the target ISO file 2942 \param trackNumber the target track 2943 \param sampleDescriptionIndex the target sample description index 2944 \return the SVC config - user is responsible for deleting it 2945 */ 2946 GF_AVCConfig *gf_isom_svc_config_get(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 2947 /*! gets MVC config for a sample description 2948 \param isom_file the target ISO file 2949 \param trackNumber the target track 2950 \param sampleDescriptionIndex the target sample description index 2951 \return the SVC config - user is responsible for deleting it 2952 */ 2953 GF_AVCConfig *gf_isom_mvc_config_get(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 2954 2955 /*! AVC familiy type*/ 2956 typedef enum 2957 { 2958 /*! not an AVC codec*/ 2959 GF_ISOM_AVCTYPE_NONE=0, 2960 /*! AVC only*/ 2961 GF_ISOM_AVCTYPE_AVC_ONLY, 2962 /*! AVC+SVC in same track*/ 2963 GF_ISOM_AVCTYPE_AVC_SVC, 2964 /*! SVC only*/ 2965 GF_ISOM_AVCTYPE_SVC_ONLY, 2966 /*! AVC+MVC in same track*/ 2967 GF_ISOM_AVCTYPE_AVC_MVC, 2968 /*! SVC only*/ 2969 GF_ISOM_AVCTYPE_MVC_ONLY, 2970 } GF_ISOMAVCType; 2971 2972 /*! gets the AVC family type for a sample description 2973 \param isom_file the target ISO file 2974 \param trackNumber the target hint track 2975 \param sampleDescriptionIndex the target sample description index 2976 \return the type of AVC media 2977 */ 2978 GF_ISOMAVCType gf_isom_get_avc_svc_type(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 2979 2980 /*! HEVC family type*/ 2981 typedef enum 2982 { 2983 /*! not an HEVC codec*/ 2984 GF_ISOM_HEVCTYPE_NONE=0, 2985 /*! HEVC only*/ 2986 GF_ISOM_HEVCTYPE_HEVC_ONLY, 2987 /*! HEVC+LHVC in same track*/ 2988 GF_ISOM_HEVCTYPE_HEVC_LHVC, 2989 /*! LHVC only*/ 2990 GF_ISOM_HEVCTYPE_LHVC_ONLY, 2991 } GF_ISOMHEVCType; 2992 2993 /*! gets the HEVC family type for a sample description 2994 \param isom_file the target ISO file 2995 \param trackNumber the target track 2996 \param sampleDescriptionIndex the target sample description index 2997 \return the type of HEVC media 2998 */ 2999 GF_ISOMHEVCType gf_isom_get_hevc_lhvc_type(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 3000 3001 /*! gets HEVC config for a sample description 3002 \param isom_file the target ISO file 3003 \param trackNumber the target track 3004 \param sampleDescriptionIndex the target sample description index 3005 \return the HEVC config - user is responsible for deleting it 3006 */ 3007 GF_HEVCConfig *gf_isom_hevc_config_get(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 3008 /*! gets LHVC config for a sample description 3009 \param isom_file the target ISO file 3010 \param trackNumber the target track 3011 \param sampleDescriptionIndex the target sample description index 3012 \return the LHVC config - user is responsible for deleting it 3013 */ 3014 GF_HEVCConfig *gf_isom_lhvc_config_get(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 3015 3016 /*! gets AV1 config for a sample description 3017 \param isom_file the target ISO file 3018 \param trackNumber the target track 3019 \param sampleDescriptionIndex the target sample description index 3020 \return the AV1 config - user is responsible for deleting it 3021 */ 3022 GF_AV1Config *gf_isom_av1_config_get(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 3023 3024 /*! gets VP8/9 config for a sample description 3025 \param isom_file the target ISO file 3026 \param trackNumber the target track 3027 \param sampleDescriptionIndex the target sample description index 3028 \return the VP8/9 config - user is responsible for deleting it 3029 */ 3030 GF_VPConfig *gf_isom_vp_config_get(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 3031 3032 /*! gets DOVI config for a sample description 3033 \param isom_file the target ISO file 3034 \param trackNumber the target track 3035 \param sampleDescriptionIndex the target sample description index 3036 \return the DOVI config - user is responsible for deleting it 3037 */ 3038 GF_DOVIDecoderConfigurationRecord* gf_isom_dovi_config_get(GF_ISOFile* isom_file, u32 trackNumber, u32 DescriptionIndex); 3039 3040 /*! checks if some tracks in file needs layer reconstruction 3041 \param isom_file the target ISO file 3042 \return GF_TRUE if track dependencies implying extractors or implicit reconstruction are found, GF_FALSE otherwise 3043 */ 3044 Bool gf_isom_needs_layer_reconstruction(GF_ISOFile *isom_file); 3045 3046 /*! NALU extract modes and flags*/ 3047 typedef enum 3048 { 3049 /*! all extractors are rewritten*/ 3050 GF_ISOM_NALU_EXTRACT_DEFAULT = 0, 3051 /*! all extractors are skipped but NALU data from this track is kept*/ 3052 GF_ISOM_NALU_EXTRACT_LAYER_ONLY, 3053 /*! all extractors are kept (untouched sample) - used for dumping modes*/ 3054 GF_ISOM_NALU_EXTRACT_INSPECT, 3055 /*! above mode is applied and PPS/SPS/... are appended in the front of every IDR*/ 3056 GF_ISOM_NALU_EXTRACT_INBAND_PS_FLAG = 1<<16, 3057 /*! above mode is applied and all start codes are rewritten (xPS inband as well)*/ 3058 GF_ISOM_NALU_EXTRACT_ANNEXB_FLAG = 2<<17, 3059 /*! above mode is applied and VDRD NAL unit is inserted before SVC slice*/ 3060 GF_ISOM_NALU_EXTRACT_VDRD_FLAG = 1<<18, 3061 /*! all extractors are skipped and only tile track data is kept*/ 3062 GF_ISOM_NALU_EXTRACT_TILE_ONLY = 1<<19 3063 } GF_ISONaluExtractMode; 3064 3065 /*! sets the NALU extraction mode for this track 3066 \param isom_file the target ISO file 3067 \param trackNumber the target track 3068 \param nalu_extract_mode the NALU extraction mode to set 3069 \return error if any 3070 */ 3071 GF_Err gf_isom_set_nalu_extract_mode(GF_ISOFile *isom_file, u32 trackNumber, GF_ISONaluExtractMode nalu_extract_mode); 3072 /*! gets the NALU extraction mode for this track 3073 \param isom_file the target ISO file 3074 \param trackNumber the target track 3075 \return the NALU extraction mode used 3076 */ 3077 GF_ISONaluExtractMode gf_isom_get_nalu_extract_mode(GF_ISOFile *isom_file, u32 trackNumber); 3078 3079 3080 #ifndef GPAC_DISABLE_ISOM_WRITE 3081 /*! creates a new AVC sample description 3082 \param isom_file the target ISO file 3083 \param trackNumber the target track 3084 \param cfg the AVC config for this sample description 3085 \param URLname URL value of the data reference, NULL if no data reference (media in the file) 3086 \param URNname URN value of the data reference, NULL if no data reference (media in the file) 3087 \param outDescriptionIndex set to the index of the created sample description 3088 \return error if any 3089 */ 3090 GF_Err gf_isom_avc_config_new(GF_ISOFile *isom_file, u32 trackNumber, GF_AVCConfig *cfg, const char *URLname, const char *URNname, u32 *outDescriptionIndex); 3091 /*! updates an AVC sample description 3092 \param isom_file the target ISO file 3093 \param trackNumber the target track 3094 \param sampleDescriptionIndex the target sample description index to update 3095 \param cfg the AVC config for this sample description 3096 \return error if any 3097 */ 3098 GF_Err gf_isom_avc_config_update(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, GF_AVCConfig *cfg); 3099 3100 /*! creates a new SVC sample description 3101 \param isom_file the target ISO file 3102 \param trackNumber the target track 3103 \param cfg the SVC config for this sample description 3104 \param URLname URL value of the data reference, NULL if no data reference (media in the file) 3105 \param URNname URN value of the data reference, NULL if no data reference (media in the file) 3106 \param outDescriptionIndex set to the index of the created sample description 3107 \return error if any 3108 */ 3109 GF_Err gf_isom_svc_config_new(GF_ISOFile *isom_file, u32 trackNumber, GF_AVCConfig *cfg, const char *URLname, const char *URNname, u32 *outDescriptionIndex); 3110 /*! updates an SVC sample description 3111 \param isom_file the target ISO file 3112 \param trackNumber the target track 3113 \param sampleDescriptionIndex the target sample description index to update 3114 \param cfg the AVC config for this sample description 3115 \param is_additional if set, the SVCConfig will be added to the AVC sample description, otherwise the sample description will be SVC-only 3116 \return error if any 3117 */ 3118 GF_Err gf_isom_svc_config_update(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, GF_AVCConfig *cfg, Bool is_additional); 3119 /*! deletes an SVC sample description 3120 \warning associated samples if any are NOT deleted 3121 \param isom_file the target ISO file 3122 \param trackNumber the target track 3123 \param sampleDescriptionIndex the target sample description index to delete 3124 \return error if any 3125 */ 3126 GF_Err gf_isom_svc_config_del(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 3127 3128 /*! creates a new MVC sample description 3129 \param isom_file the target ISO file 3130 \param trackNumber the target track 3131 \param cfg the SVC config for this sample description 3132 \param URLname URL value of the data reference, NULL if no data reference (media in the file) 3133 \param URNname URN value of the data reference, NULL if no data reference (media in the file) 3134 \param outDescriptionIndex set to the index of the created sample description 3135 \return error if any 3136 */ 3137 GF_Err gf_isom_mvc_config_new(GF_ISOFile *isom_file, u32 trackNumber, GF_AVCConfig *cfg, const char *URLname, const char *URNname, u32 *outDescriptionIndex); 3138 3139 /*! updates an MVC sample description 3140 \param isom_file the target ISO file 3141 \param trackNumber the target track 3142 \param sampleDescriptionIndex the target sample description index to update 3143 \param cfg the AVC config for this sample description 3144 \param is_additional if set, the MVCConfig will be added to the AVC sample description, otherwise the sample description will be MVC-only 3145 \return error if any 3146 */ 3147 GF_Err gf_isom_mvc_config_update(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, GF_AVCConfig *cfg, Bool is_additional); 3148 3149 /*! deletes an MVC sample description 3150 \warning associated samples if any are NOT deleted 3151 \param isom_file the target ISO file 3152 \param trackNumber the target track 3153 \param sampleDescriptionIndex the target sample description index to delete 3154 \return error if any 3155 */ 3156 GF_Err gf_isom_mvc_config_del(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 3157 3158 /*! sets avc3 entry type (inband SPS/PPS) instead of avc1 (SPS/PPS in avcC box) 3159 \param isom_file the target ISO file 3160 \param trackNumber the target track 3161 \param sampleDescriptionIndex the target sample description index 3162 \param keep_xps if set to GF_TRUE, keeps parameter set in the configuration record otherwise removes them 3163 \return error if any 3164 */ 3165 GF_Err gf_isom_avc_set_inband_config(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, Bool keep_xps); 3166 3167 /*! sets hev1 entry type (inband SPS/PPS) instead of hvc1 (SPS/PPS in hvcC box) 3168 \param isom_file the target ISO file 3169 \param trackNumber the target track 3170 \param sampleDescriptionIndex the target sample description index 3171 \param keep_xps if set to GF_TRUE, keeps parameter set in the configuration record otherwise removes them 3172 \return error if any 3173 */ 3174 GF_Err gf_isom_hevc_set_inband_config(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, Bool keep_xps); 3175 3176 /*! sets lhe1 entry type instead of lhc1 but keep lhcC box intact 3177 \param isom_file the target ISO file 3178 \param trackNumber the target track 3179 \param sampleDescriptionIndex the target sample description index 3180 \return error if any 3181 */ 3182 GF_Err gf_isom_lhvc_force_inband_config(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 3183 3184 /*! sets hvt1 entry type (tile track) or hev2/hvc2 type if is_base_track is set. It is the use responsability to set the tbas track reference to the base hevc track 3185 \param isom_file the target ISO file 3186 \param trackNumber the target track 3187 \param sampleDescriptionIndex the target sample description index 3188 \param cfg may be set to the tile track configuration to indicate sub-profile of the tile, or NULL 3189 \param is_base_track if set to GF_TRUE, indicates this is a tile base track, otherwise this is a tile track 3190 \return error if any 3191 */ 3192 GF_Err gf_isom_hevc_set_tile_config(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, GF_HEVCConfig *cfg, Bool is_base_track); 3193 3194 /*! creates a new HEVC sample description 3195 \param isom_file the target ISO file 3196 \param trackNumber the target track 3197 \param cfg the HEVC config for this sample description 3198 \param URLname URL value of the data reference, NULL if no data reference (media in the file) 3199 \param URNname URN value of the data reference, NULL if no data reference (media in the file) 3200 \param outDescriptionIndex set to the index of the created sample description 3201 \return error if any 3202 */ 3203 GF_Err gf_isom_hevc_config_new(GF_ISOFile *isom_file, u32 trackNumber, GF_HEVCConfig *cfg, const char *URLname, const char *URNname, u32 *outDescriptionIndex); 3204 3205 /*! updates an HEVC sample description 3206 \param isom_file the target ISO file 3207 \param trackNumber the target track 3208 \param sampleDescriptionIndex the target sample description index to update 3209 \param cfg the HEVC config for this sample description 3210 \return error if any 3211 */ 3212 GF_Err gf_isom_hevc_config_update(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, GF_HEVCConfig *cfg); 3213 3214 /*! Updates L-HHVC config*/ 3215 typedef enum { 3216 //! changes track type to LHV1/LHE1: no base nor extractors in track, just enhancement layers 3217 GF_ISOM_LEHVC_ONLY = 0, 3218 //! changes track type to HVC2/HEV2: base and extractors/enh. in track 3219 GF_ISOM_LEHVC_WITH_BASE, 3220 //! changes track type to HVC1/HEV1 with additional cfg: base and enh. in track no extractors 3221 GF_ISOM_LEHVC_WITH_BASE_BACKWARD, 3222 //! changes track type to HVC2/HEV2 for tile base tracks 3223 GF_ISOM_HEVC_TILE_BASE, 3224 } GF_ISOMLHEVCTrackType; 3225 3226 /*! updates an HEVC sample description 3227 \param isom_file the target ISO file 3228 \param trackNumber the target track 3229 \param sampleDescriptionIndex the target sample description index to update 3230 \param cfg the LHVC config for this sample description 3231 \param track_type indicates the LHVC track type to set 3232 \return error if any 3233 */ 3234 GF_Err gf_isom_lhvc_config_update(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, GF_HEVCConfig *cfg, GF_ISOMLHEVCTrackType track_type); 3235 3236 /*! sets nalu size length 3237 \warning any previously added samples must be rewritten by the caller 3238 \param isom_file the target ISO file 3239 \param trackNumber the target track 3240 \param sampleDescriptionIndex the target sample description index to update 3241 \param nalu_size_length the new NALU size length in bytes 3242 \return error if any 3243 */ 3244 GF_Err gf_isom_set_nalu_length_field(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 nalu_size_length); 3245 3246 /*! creates new VPx config 3247 \param isom_file the target ISO file 3248 \param trackNumber the target track 3249 \param cfg the VPx config for this sample description 3250 \param URLname URL value of the data reference, NULL if no data reference (media in the file) 3251 \param URNname URN value of the data reference, NULL if no data reference (media in the file) 3252 \param outDescriptionIndex set to the index of the created sample description 3253 \param vpx_type four character code of entry ('vp08', 'vp09' or 'vp10') 3254 \return error if any 3255 */ 3256 GF_Err gf_isom_vp_config_new(GF_ISOFile *isom_file, u32 trackNumber, GF_VPConfig *cfg, const char *URLname, const char *URNname, u32 *outDescriptionIndex, u32 vpx_type); 3257 3258 3259 /*! creates new AV1 config 3260 \param isom_file the target ISO file 3261 \param trackNumber the target track 3262 \param cfg the AV1 config for this sample description 3263 \param URLname URL value of the data reference, NULL if no data reference (media in the file) 3264 \param URNname URN value of the data reference, NULL if no data reference (media in the file) 3265 \param outDescriptionIndex set to the index of the created sample description 3266 \return error if any 3267 */ 3268 GF_Err gf_isom_av1_config_new(GF_ISOFile *isom_file, u32 trackNumber, GF_AV1Config *cfg, const char *URLname, const char *URNname, u32 *outDescriptionIndex); 3269 3270 3271 #endif /*GPAC_DISABLE_ISOM_WRITE*/ 3272 3273 3274 /*! Sample entry description for 3GPP DIMS*/ 3275 typedef struct 3276 { 3277 /*! profile*/ 3278 u8 profile; 3279 /*! level*/ 3280 u8 level; 3281 /*! number of components in path*/ 3282 u8 pathComponents; 3283 /*! full request*/ 3284 Bool fullRequestHost; 3285 /*! stream type*/ 3286 Bool streamType; 3287 /*! has redundant sample (carousel)*/ 3288 u8 containsRedundant; 3289 /*! text encoding string*/ 3290 const char *textEncoding; 3291 /*! content encoding string*/ 3292 const char *contentEncoding; 3293 /*! script string*/ 3294 const char *content_script_types; 3295 /*! mime type string*/ 3296 const char *mime_type; 3297 /*! xml schema location string*/ 3298 const char *xml_schema_loc; 3299 } GF_DIMSDescription; 3300 3301 /*! gets a DIMS sample description 3302 \param isom_file the target ISO file 3303 \param trackNumber the target track 3304 \param sampleDescriptionIndex the target sample description index 3305 \param desc set to the DIMS description 3306 \return error if any 3307 */ 3308 GF_Err gf_isom_get_dims_description(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, GF_DIMSDescription *desc); 3309 3310 #ifndef GPAC_DISABLE_ISOM_WRITE 3311 /*! creates a DIMS sample description 3312 \param isom_file the target ISO file 3313 \param trackNumber the target track 3314 \param desc the DIMS config for this sample description 3315 \param URLname URL value of the data reference, NULL if no data reference (media in the file) 3316 \param URNname URN value of the data reference, NULL if no data reference (media in the file) 3317 \param outDescriptionIndex set to the index of the created sample description 3318 \return error if any 3319 */ 3320 GF_Err gf_isom_new_dims_description(GF_ISOFile *isom_file, u32 trackNumber, GF_DIMSDescription *desc, const char *URLname, const char *URNname, u32 *outDescriptionIndex); 3321 #endif /*GPAC_DISABLE_ISOM_WRITE*/ 3322 3323 /*! AC-3 config record extension for EAC-3 - see dolby specs*/ 3324 struct __ec3_stream 3325 { 3326 /*! AC3 fs code*/ 3327 u8 fscod; 3328 /*! AC3 bsid code*/ 3329 u8 bsid; 3330 /*! AC3 bs mode*/ 3331 u8 bsmod; 3332 /*! AC3 ac mode*/ 3333 u8 acmod; 3334 /*! LF on*/ 3335 u8 lfon; 3336 /*! asvc mode, only for EC3*/ 3337 u8 asvc; 3338 /*! deps, only for EC3*/ 3339 u8 nb_dep_sub; 3340 /*! channel loc, only for EC3*/ 3341 u8 chan_loc; 3342 }; 3343 3344 /*! AC3 config record*/ 3345 typedef struct 3346 { 3347 /*! indicates if ec3*/ 3348 u8 is_ec3; 3349 /*! number of streams : 3350 1 for AC3 3351 max 8 for EC3, main stream is included 3352 */ 3353 u8 nb_streams; 3354 /*! if AC3 this is the bitrate code, otherwise cumulated data rate of EC3 streams*/ 3355 u16 brcode; 3356 struct __ec3_stream streams[8]; 3357 } GF_AC3Config; 3358 3359 /*! gets an AC3 sample description 3360 \param isom_file the target ISO file 3361 \param trackNumber the target track 3362 \param sampleDescriptionIndex the target sample description index 3363 \return AC-3 config 3364 */ 3365 GF_AC3Config *gf_isom_ac3_config_get(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 3366 3367 /*! parses an AC3/EC3 sample description 3368 \param dsi the encoded config 3369 \param dsi_len the encoded config size 3370 \param is_ec3 indicates that the encoded config is for an EC3 track 3371 \param cfg the AC3/EC3 confgi to fill 3372 \return Error if any 3373 */ 3374 GF_Err gf_isom_ac3_config_parse(u8 *dsi, u32 dsi_len, Bool is_ec3, GF_AC3Config *cfg); 3375 3376 #ifndef GPAC_DISABLE_ISOM_WRITE 3377 /*! creates an AC3 sample description 3378 \param isom_file the target ISO file 3379 \param trackNumber the target track 3380 \param cfg the AC3 config for this sample description 3381 \param URLname URL value of the data reference, NULL if no data reference (media in the file) 3382 \param URNname URN value of the data reference, NULL if no data reference (media in the file) 3383 \param outDescriptionIndex set to the index of the created sample description 3384 \return error if any 3385 */ 3386 GF_Err gf_isom_ac3_config_new(GF_ISOFile *isom_file, u32 trackNumber, GF_AC3Config *cfg, const char *URLname, const char *URNname, u32 *outDescriptionIndex); 3387 #endif /*GPAC_DISABLE_ISOM_WRITE*/ 3388 3389 /*! gets a FLAC sample description 3390 \param isom_file the target ISO file 3391 \param trackNumber the target track 3392 \param sampleDescriptionIndex the target sample description index 3393 \param dsi set to the flac decoder config - shall be freeed by caller 3394 \param dsi_size set to the size of the flac decoder config 3395 \return error if any 3396 */ 3397 GF_Err gf_isom_flac_config_get(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u8 **dsi, u32 *dsi_size); 3398 3399 #ifndef GPAC_DISABLE_ISOM_WRITE 3400 /*! creates a FLAC sample description 3401 \param isom_file the target ISO file 3402 \param trackNumber the target track 3403 \param metadata the flac decoder config buffer 3404 \param metadata_size the size of flac decoder config 3405 \param URLname URL value of the data reference, NULL if no data reference (media in the file) 3406 \param URNname URN value of the data reference, NULL if no data reference (media in the file) 3407 \param outDescriptionIndex set to the index of the created sample description 3408 \return error if any 3409 */ 3410 GF_Err gf_isom_flac_config_new(GF_ISOFile *isom_file, u32 trackNumber, u8 *metadata, u32 metadata_size, const char *URLname, const char *URNname, u32 *outDescriptionIndex); 3411 #endif /*GPAC_DISABLE_ISOM_WRITE*/ 3412 3413 /*! gets a OPUS sample description 3414 \param isom_file the target ISO file 3415 \param trackNumber the target track 3416 \param sampleDescriptionIndex the target sample description index 3417 \param dsi set to the OPUS decoder config - shall be freeed by caller 3418 \param dsi_size set to the size of the OPUS decoder config 3419 \return error if any 3420 */ 3421 GF_Err gf_isom_opus_config_get(GF_ISOFile *the_file, u32 trackNumber, u32 StreamDescriptionIndex, u8 **dsi, u32 *dsi_size); 3422 3423 #ifndef GPAC_DISABLE_ISOM_WRITE 3424 3425 /*! creates a motion jpeg 2000 sample description 3426 \param isom_file the target ISO file 3427 \param trackNumber the target track 3428 \param URLname URL value of the data reference, NULL if no data reference (media in the file) 3429 \param URNname URN value of the data reference, NULL if no data reference (media in the file) 3430 \param outDescriptionIndex set to the index of the created sample description 3431 \param dsi the jpeg2000 decoder config buffer 3432 \param dsi_len the size of jpeg2000 decoder config 3433 \return error if any 3434 */ 3435 GF_Err gf_isom_new_mj2k_description(GF_ISOFile *isom_file, u32 trackNumber, const char *URLname, const char *URNname, u32 *outDescriptionIndex, u8 *dsi, u32 dsi_len); 3436 #endif /*GPAC_DISABLE_ISOM_WRITE*/ 3437 3438 #ifndef GPAC_DISABLE_ISOM_WRITE 3439 3440 /*! creates a time code metadata sample description 3441 \note frames_per_counter_tick<0 disables counter flag but signals frames_per_tick 3442 \param isom_file the target ISO file 3443 \param trackNumber the target track 3444 \param fps_num the frame rate numerator 3445 \param fps_den the frame rate denumerator (frame rate numerator will be track media timescale) 3446 \param frames_per_counter_tick if not 0, enables counter mode (sample data is an counter) and use this value as number of frames per counter tick. Otherwise, disables counter mode (sample data write h,m,s,frames) 3447 \param is_drop indicates that the time code in samples is a drop timecode 3448 \param is_counter indicates that the counter flag should be set 3449 \param outDescriptionIndex set to the index of the created sample description 3450 \return error if any 3451 */ 3452 GF_Err gf_isom_tmcd_config_new(GF_ISOFile *isom_file, u32 trackNumber, u32 fps_num, u32 fps_den, s32 frames_per_counter_tick, Bool is_drop, Bool is_counter, u32 *outDescriptionIndex); 3453 3454 #endif /*GPAC_DISABLE_ISOM_WRITE*/ 3455 3456 /*! gets information of a time code metadata sample description 3457 \param isom_file the target ISO file 3458 \param trackNumber the target track 3459 \param sampleDescriptionIndex the target sample description index 3460 \param tmcd_flags set to the timecode description flags 3461 \param tmcd_fps_num set to fps numerator of timecode description 3462 \param tmcd_fps_den set to fps denominator of timecode description 3463 \param tmcd_fpt set to the ticks per second for counter mode (tmcd_flags & 0x1) 3464 \return error if any 3465 */ 3466 GF_Err gf_isom_get_tmcd_config(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 *tmcd_flags, u32 *tmcd_fps_num, u32 *tmcd_fps_den, u32 *tmcd_fpt); 3467 3468 /*! gets information of a raw PCM sample description, ISOBMFF style 3469 \param isom_file the target ISO file 3470 \param trackNumber the target track 3471 \param sampleDescriptionIndex the target sample description index 3472 \param flags set to the pcm config flags (0: big endian, 1: little endian) 3473 \param pcm_size set to PCM sample size (per channel, 16, 24, 32, 64 3474 \return error if any 3475 */ 3476 GF_Err gf_isom_get_pcm_config(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 *flags, u32 *pcm_size); 3477 3478 /*! @} */ 3479 3480 3481 #ifndef GPAC_DISABLE_ISOM_FRAGMENTS 3482 /*! 3483 \addtogroup isofragred_grp Fragmented ISOBMFF Read 3484 \ingroup iso_grp 3485 3486 This describes function specific to fragmented ISOBMF files 3487 3488 @{ 3489 */ 3490 3491 /*! checks if a movie file is fragmented 3492 \param isom_file the target ISO file 3493 \return GF_FALSE if movie isn't fragmented, GF_TRUE otherwise 3494 */ 3495 Bool gf_isom_is_fragmented(GF_ISOFile *isom_file); 3496 /*! checks if a movie file is fragmented 3497 \param isom_file the target ISO file 3498 \param TrackID the target track 3499 \return GF_FALSE if track isn't fragmented, GF_TRUE otherwise*/ 3500 Bool gf_isom_is_track_fragmented(GF_ISOFile *isom_file, GF_ISOTrackID TrackID); 3501 3502 /*! checks if a file has a top styp box 3503 \param isom_file the target ISO file 3504 \param brand set to the major brand of the styp box 3505 \param version set to version of the styp box 3506 \return GF_TRUE of the file has a styp box, GF_FALSE otherwise 3507 */ 3508 Bool gf_isom_has_segment(GF_ISOFile *isom_file, u32 *brand, u32 *version); 3509 /*! gets number of movie fragments in the file 3510 \param isom_file the target ISO file 3511 \returns number of movie fragments in the file, 0 if none 3512 */ 3513 u32 gf_isom_segment_get_fragment_count(GF_ISOFile *isom_file); 3514 /*! gets number of track fragments in the indicated movie fragment 3515 \param isom_file the target ISO file 3516 \param moof_index the target movie fragment (1-based index) 3517 \return number of track fragments, 0 if none 3518 */ 3519 u32 gf_isom_segment_get_track_fragment_count(GF_ISOFile *isom_file, u32 moof_index); 3520 /*! get the track fragment decode time of a track fragment 3521 \param isom_file the target ISO file 3522 \param moof_index the target movie fragment (1-based index) 3523 \param traf_index the target track fragment (1-based index) 3524 \param decode_time set to the track fragment decode time if present, 0 otherwise 3525 \return the track ID of the track fragment 3526 */ 3527 u32 gf_isom_segment_get_track_fragment_decode_time(GF_ISOFile *isom_file, u32 moof_index, u32 traf_index, u64 *decode_time); 3528 3529 /*! enables single moof mode. In single moof mode, file is parsed only one moof/mdat at a time 3530 in order to proceed to next moof, \ref gf_isom_reset_data_offset must be called to parse the next moof 3531 \param isom_file the target ISO file 3532 \param mode if GF_TRUE, enables single moof mode; otherwise disables it 3533 */ 3534 void gf_isom_set_single_moof_mode(GF_ISOFile *isom_file, Bool mode); 3535 3536 GF_Err gf_isom_get_file_offset_for_time(GF_ISOFile *movie, Double start_time, u64 *max_offset); 3537 GF_Err gf_isom_get_sidx_duration(GF_ISOFile *movie, u64 *sidx_dur, u32 *sidx_timescale); 3538 3539 3540 /*! refreshes a fragmented file 3541 A file being downloaded may be a fragmented file. In this case only partial info 3542 is available once the file is successfully open (gf_isom_open_progressive), and since there is 3543 no information wrt number fragments (which could actually be generated on the fly 3544 at the sender side), you must call this function on regular basis in order to 3545 load newly downloaded fragments. Note this may result in Track/Movie duration changes 3546 and SampleCount change too ... 3547 3548 This function should also be called when using memory read (gmem://) to refresh the underlying bitstream after appendin data to your blob. 3549 In the case where the file is not fragmented, no further box parsing will be done. 3550 3551 \param isom_file the target ISO file 3552 \param MissingBytes set to the number of missing bytes to parse the last incomplete top-level box found 3553 \param new_location if set, the previous bitstream is changed to this new location, otherwise it is refreshed (disk flush) 3554 \return error if any 3555 */ 3556 GF_Err gf_isom_refresh_fragmented(GF_ISOFile *isom_file, u64 *MissingBytes, const char *new_location); 3557 3558 /*! gets the current track fragment decode time of the track (the one of the last fragment parsed). 3559 \param isom_file the target ISO file 3560 \param trackNumber the target track 3561 \return the track fragment decode time in media timescale 3562 */ 3563 u64 gf_isom_get_current_tfdt(GF_ISOFile *isom_file, u32 trackNumber); 3564 3565 /*! checks if the movie is a smooth streaming recomputed initial movie 3566 \param isom_file the target ISO file 3567 \return GF_TRUE if the file init segment (moov) was generated from external meta-data (smooth streaming) 3568 */ 3569 Bool gf_isom_is_smooth_streaming_moov(GF_ISOFile *isom_file); 3570 3571 3572 /*! gets default values of samples in a track to use for track fragments default. Each variable is optional and 3573 if set will contain the default value for this track samples 3574 3575 \param isom_file the target ISO file 3576 \param trackNumber the target track 3577 \param defaultDuration set to the default duration of samples, 0 if not computable 3578 \param defaultSize set to the default size of samples, 0 if not computable 3579 \param defaultDescriptionIndex set to the default sample description index of samples, 0 if not computable 3580 \param defaultRandomAccess set to the default sync flag of samples, 0 if not computable 3581 \param defaultPadding set to the default padding bits of samples, 0 if not computable 3582 \param defaultDegradationPriority set to the default degradation priority of samples, 0 if not computable 3583 \return error if any*/ 3584 GF_Err gf_isom_get_fragment_defaults(GF_ISOFile *isom_file, u32 trackNumber, 3585 u32 *defaultDuration, u32 *defaultSize, u32 *defaultDescriptionIndex, 3586 u32 *defaultRandomAccess, u8 *defaultPadding, u16 *defaultDegradationPriority); 3587 3588 3589 3590 /*! gets last UTC/timestamp values indicated for the reference track in the file if any (pfrt box) 3591 \param isom_file the target ISO file 3592 \param refTrackID set to the ID of the reference track used by the pfrt box 3593 \param ntp set to the NTP timestamp found 3594 \param timestamp set to the corresponding media timestamp in refTrackID timescale 3595 \param reset_info if GF_TRUE, discards current NTP mapping info; this will trigger parsing of the next prft box found. If not set, subsequent pfrt boxes will not be parsed until the function is called with reset_info=GF_TRUE 3596 \return GF_FALSE if no info found, GF_TRUE if OK 3597 */ 3598 Bool gf_isom_get_last_producer_time_box(GF_ISOFile *isom_file, GF_ISOTrackID *refTrackID, u64 *ntp, u64 *timestamp, Bool reset_info); 3599 3600 #ifndef GPAC_DISABLE_ISOM_WRITE 3601 /*! enables storage of traf templates (serialized sidx/moof/traf without trun/senc) at segment boundaries 3602 This is mostly used to recreate identical segment information when refragmenting a file 3603 \param isom_file the target ISO file 3604 */ 3605 void gf_isom_enable_traf_map_templates(GF_ISOFile *isom_file); 3606 3607 /*! Segment boundary information*/ 3608 typedef struct 3609 { 3610 /*! fragment start offset*/ 3611 u64 frag_start; 3612 /*! mdat end offset*/ 3613 u64 mdat_end; 3614 /*segment start offset plus one: 3615 0 if regular fragment, 1 if dash sedment, offset indicates start of segment (styp or sidx) 3616 if sidx, it is writtent in the moof_template 3617 */ 3618 u64 seg_start_plus_one; 3619 3620 /*! serialized array of styp (if present) sidx (if present) and moof with only the current traf*/ 3621 const u8 *moof_template; 3622 /*! size of serialized buffer*/ 3623 u32 moof_template_size; 3624 /*! sidx start, 0 if absent*/ 3625 u64 sidx_start; 3626 /*! sidx end, 0 if absent*/ 3627 u64 sidx_end; 3628 } GF_ISOFragmentBoundaryInfo; 3629 3630 /*! checks if a sample is a fragment start 3631 Only use this function if \ref gf_isom_enable_traf_map_templates has been called 3632 \param isom_file the target ISO file 3633 \param trackNumber the target track 3634 \param sampleNum the target sample number 3635 \param frag_info filled with information on fragment boundaries (optional - can be NULL) 3636 \return GF_TRUE if this sample was the first sample of a traf in the fragmented source file, GF_FALSE otherwise*/ 3637 Bool gf_isom_sample_is_fragment_start(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNum, GF_ISOFragmentBoundaryInfo *frag_info); 3638 #endif //GPAC_DISABLE_ISOM_WRITE 3639 3640 /*! resets sample information for all tracks setup. This allows keeping the memory footprint low when playing DASH/CMAF segments 3641 \note seeking in the file is then no longer possible 3642 \param isom_file the target ISO file 3643 \param reset_sample_count if GF_TRUE, sets sample count of all tracks back to 0 3644 \return error if any 3645 */ 3646 GF_Err gf_isom_reset_tables(GF_ISOFile *isom_file, Bool reset_sample_count); 3647 3648 /*! sets the offset for parsing from the input buffer to 0 (used to reclaim input buffer) 3649 \param isom_file the target ISO file 3650 \param top_box_start set to the byte offset in the source buffer of the first top level box 3651 \return error if any 3652 */ 3653 GF_Err gf_isom_reset_data_offset(GF_ISOFile *isom_file, u64 *top_box_start); 3654 3655 3656 /*! releases current movie segment. This closes the associated file IO object. 3657 \note seeking in the file is no longer possible when tables are rested 3658 \warning the sample count is not reseted after the release of tables. use \ref gf_isom_reset_tables for this 3659 3660 \param isom_file the target ISO file 3661 \param reset_tables if set, sample information for all tracks setup as segment are destroyed, along with all PSSH boxes. This allows keeping the memory footprint low when playing segments. 3662 \return error if any 3663 */ 3664 GF_Err gf_isom_release_segment(GF_ISOFile *isom_file, Bool reset_tables); 3665 3666 /*! Flags for gf_isom_open_segment*/ 3667 typedef enum 3668 { 3669 /*! do not check for movie fragment sequence number*/ 3670 GF_ISOM_SEGMENT_NO_ORDER_FLAG = 1, 3671 /*! the segment contains a scalable layer of the last opened segment*/ 3672 GF_ISOM_SEGMENT_SCALABLE_FLAG = 1<<1, 3673 } GF_ISOSegOpenMode; 3674 3675 /*! opens a new segment file. Access to samples in previous segments is no longer possible 3676 if end_range>start_range, restricts the URL to the given byterange when parsing 3677 3678 \param isom_file the target ISO file 3679 \param fileName the file name of the new segment to open 3680 \param start_range the start offset in bytes in the file of the segment data 3681 \param end_range the end offset in bytes in the file of the segment data 3682 \param flags flags to use when opening the segment 3683 \return error if any 3684 */ 3685 GF_Err gf_isom_open_segment(GF_ISOFile *isom_file, const char *fileName, u64 start_range, u64 end_range, GF_ISOSegOpenMode flags); 3686 3687 /*! returns the track ID of the track containing the highest enhancement layer for the given base track 3688 \param isom_file the target ISO file 3689 \param for_base_track the number of the base track 3690 \return the track ID of the highest enahnacement track 3691 */ 3692 GF_ISOTrackID gf_isom_get_highest_track_in_scalable_segment(GF_ISOFile *isom_file, u32 for_base_track); 3693 3694 /*! resets internal info (track fragement decode time, number of samples, next moof number)used with fragments and segment. 3695 \note This should be called when seeking (with keep_sample_count=0) or when loading a media segments with the same timing as the previously loaded segment 3696 \param isom_file the target ISO file 3697 \param keep_sample_count if GF_TRUE, does not reset the sample count on tracks 3698 */ 3699 void gf_isom_reset_fragment_info(GF_ISOFile *isom_file, Bool keep_sample_count); 3700 3701 /*! resets sample count to 0 and next moof number to 0. When doing scalable media, should be called before opening the segment containing 3702 the base layer in order to make sure the sample count base number is always the same (ie 1) on all tracks 3703 \param isom_file the target ISO file 3704 */ 3705 void gf_isom_reset_sample_count(GF_ISOFile *isom_file); 3706 /*! resets moof sequence number to 0 3707 \param isom_file the target ISO file 3708 */ 3709 void gf_isom_reset_seq_num(GF_ISOFile *isom_file); 3710 3711 /*! gets the duration of movie+fragments 3712 \param isom_file the target ISO file 3713 \return the duration in movie timescale, 0 if unknown or if error*/ 3714 u64 gf_isom_get_fragmented_duration(GF_ISOFile *isom_file); 3715 3716 /*! gets the number of fragments or segments when the file is opened in \ref GF_ISOM_OPEN_READ_DUMP mode 3717 \param isom_file the target ISO file 3718 \param segments_only if set to GF_TRUE, counts segments (sidx), otherwise counts fragments 3719 \return the number of segments or fragments 3720 */ 3721 u32 gf_isom_get_fragments_count(GF_ISOFile *isom_file, Bool segments_only); 3722 3723 /*! gets total sample number and duration when the file is opened in \ref GF_ISOM_OPEN_READ_DUMP mode 3724 \param isom_file the target ISO file 3725 \param trackID the ID of the target track 3726 \param nb_samples set to the number of samples in the track 3727 \param duration set to the total duration in media timescale 3728 \return error if any 3729 */ 3730 GF_Err gf_isom_get_fragmented_samples_info(GF_ISOFile *isom_file, GF_ISOTrackID trackID, u32 *nb_samples, u64 *duration); 3731 3732 /*! gets the number of the next moof to be produced 3733 \param isom_file the target ISO file 3734 \return number of the next moof 3735 */ 3736 u32 gf_isom_get_next_moof_number(GF_ISOFile *isom_file); 3737 3738 /*! @} */ 3739 #endif //GPAC_DISABLE_ISOM_FRAGMENTS 3740 3741 3742 /*! 3743 \addtogroup isoudta_grp ISOBMFF UserData Manipulation 3744 \ingroup iso_grp 3745 3746 User Data Manipulation 3747 3748 You can add specific typed data to either a track or the movie: the UserData 3749 The type must be formated as a FourCC if you have a registered 4CC type 3750 but the usual is to set a UUID (128 bit ID for box type) which never conflict 3751 with existing structures in the format 3752 To manipulate a UUID user data set the UserDataType to 0 and specify a valid UUID. 3753 Otherwise the UUID parameter is ignored 3754 Several items with the same ID or UUID can be added (this allows you to store any 3755 kind/number of private information under a unique ID / UUID) 3756 3757 @{ 3758 */ 3759 3760 /*! gets number of udta (user data) entries of a movie or track 3761 \param isom_file the target ISO file 3762 \param trackNumber the target track if not 0; if 0, the movie udta is checked 3763 \return the number of entries in UDTA*/ 3764 u32 gf_isom_get_udta_count(GF_ISOFile *isom_file, u32 trackNumber); 3765 3766 /*! checks type of a given udta entry 3767 \param isom_file the target ISO file 3768 \param trackNumber the target track if not 0; if 0, the movie udta is checked 3769 \param udta_idx 1-based index of the user data to query 3770 \param UserDataType set to the four character code of the user data entry (optional, can be NULL) 3771 \param UUID set to the UUID of the user data entry (optional, can be NULL) 3772 \return error if any*/ 3773 GF_Err gf_isom_get_udta_type(GF_ISOFile *isom_file, u32 trackNumber, u32 udta_idx, u32 *UserDataType, bin128 *UUID); 3774 3775 /*! gets the number of UserDataItems with the same ID / UUID in the desired track or movie 3776 \param isom_file the target ISO file 3777 \param trackNumber the target track if not 0; if 0, the movie udta is checked 3778 \param UserDataType the four character code of the user data entry to query 3779 \param UUID the UUID of the user data entry 3780 \return number of UDTA entries with the given type*/ 3781 u32 gf_isom_get_user_data_count(GF_ISOFile *isom_file, u32 trackNumber, u32 UserDataType, bin128 UUID); 3782 3783 /*! gets the UserData for the specified item from the track or the movie 3784 \param isom_file the target ISO file 3785 \param trackNumber the target track if not 0; if 0, the movie udta is checked 3786 \param UserDataType the four character code of the user data entry to query 3787 \param UUID the UUID of the user data entry 3788 \param UserDataIndex 1-based index of the user data of the given type to fetch. If 0, all boxes with type==UserDataType will be serialized (including box header and size) in the output buffer 3789 \param userData set to a newly allocated buffer containing the serialized data - shall be freed by caller, you must pass (userData != NULL && *userData=NULL) 3790 \param userDataSize set to the size of the allocated buffer 3791 \return error if any*/ 3792 GF_Err gf_isom_get_user_data(GF_ISOFile *isom_file, u32 trackNumber, u32 UserDataType, bin128 UUID, u32 UserDataIndex, u8 **userData, u32 *userDataSize); 3793 3794 #ifndef GPAC_DISABLE_ISOM_WRITE 3795 3796 /*! adds a user data item in the desired track or in the movie 3797 \param isom_file the target ISO file 3798 \param trackNumber the target track for the user data; if 0, adds user data to the movie 3799 \param UserDataType the user data four character code type 3800 \param UUID the user data UUID 3801 \param data the data to add, may be NULL 3802 \param size the size of the data to add, shall be 0 when data is NULL 3803 \return error if any 3804 */ 3805 GF_Err gf_isom_add_user_data(GF_ISOFile *isom_file, u32 trackNumber, u32 UserDataType, bin128 UUID, u8 *data, u32 size); 3806 3807 /*! removes all user data items from a track or movie 3808 \param isom_file the target ISO file 3809 \param trackNumber the target track for the user data; if 0, adds user data to the movie 3810 \param UserDataType the user data four character code type 3811 \param UUID the user data UUID 3812 \return error if any 3813 */ 3814 GF_Err gf_isom_remove_user_data(GF_ISOFile *isom_file, u32 trackNumber, u32 UserDataType, bin128 UUID); 3815 3816 /*! removes a user data item from a track or movie 3817 use the UDAT read functions to get the item index 3818 \param isom_file the target ISO file 3819 \param trackNumber the target track for the user data; if 0, adds user data to the movie 3820 \param UserDataType the user data four character code type 3821 \param UUID the user data UUID 3822 \param UserDataIndex the 1-based index of the user data item to remove - see \ref gf_isom_get_user_data_count 3823 \return error if any 3824 */ 3825 GF_Err gf_isom_remove_user_data_item(GF_ISOFile *isom_file, u32 trackNumber, u32 UserDataType, bin128 UUID, u32 UserDataIndex); 3826 3827 /*! adds a user data item in a track or movie using a serialzed buffer of ISOBMFF boxes 3828 \param isom_file the target ISO file 3829 \param trackNumber the target track for the udta box; if 0, add the udta to the movie; 3830 \param data the serialized udta box to add, shall not be NULL 3831 \param size the size of the data to add 3832 \return error if any 3833 */ 3834 GF_Err gf_isom_add_user_data_boxes(GF_ISOFile *isom_file, u32 trackNumber, u8 *data, u32 size); 3835 3836 /*! gets serialized user data box of a movie 3837 \param isom_file the destination ISO file 3838 \param output will be set to a newly allocated buffer containing the serialized box - caller shall free it 3839 \param output_size will be set to the size of the allocated buffer 3840 \return error if any 3841 */ 3842 GF_Err gf_isom_get_raw_user_data(GF_ISOFile *isom_file, u8 **output, u32 *output_size); 3843 3844 #endif //GPAC_DISABLE_ISOM_WRITE 3845 3846 /*! @} */ 3847 3848 3849 #if !defined(GPAC_DISABLE_ISOM_FRAGMENTS) && !defined(GPAC_DISABLE_ISOM_WRITE) 3850 3851 /*! 3852 \addtogroup isofragwrite_grp Fragmented ISOBMFF Writing 3853 \ingroup iso_grp 3854 3855 Movie Fragments Writing API 3856 Movie Fragments is a feature of ISO media files for fragmentation 3857 of a presentation meta-data and interleaving with its media data. 3858 This enables faster http fast start for big movies, and also reduces the risk 3859 of data loss in case of a recording crash, because meta data and media data 3860 can be written to disk at regular times 3861 This API provides simple function calls to setup such a movie and write it 3862 The process implies: 3863 1- creating a movie in the usual way (track, stream descriptions, (IOD setup 3864 copyright, ...) 3865 2- possibly add some samples in the regular fashion 3866 3- setup track fragments for all track that will be written in a fragmented way 3867 (note that you can create/write a track that has no fragmentation at all) 3868 4- finalize the movie for fragmentation (this will flush all meta-data and 3869 any media-data added to disk, ensuring all vital information for the presentation 3870 is stored on file and not lost in case of crash/poweroff) 3871 3872 then 5-6 as often as desired 3873 5- start a new movie fragment 3874 6- add samples to each setup track 3875 3876 3877 IMPORTANT NOTES: 3878 * Movie Fragments can only be used in GF_ISOM_OPEN_WRITE mode (capturing) 3879 and no editing functionalities can be used 3880 * the fragmented movie API uses TrackID and not TrackNumber 3881 3882 @{ 3883 */ 3884 3885 /*! sets up a track for fragmentation by specifying some default values for storage efficiency 3886 \note If all the defaults are 0, traf flags will always be used to signal them. 3887 \param isom_file the target ISO file 3888 \param TrackID ID of the target track 3889 \param DefaultSampleDescriptionIndex the default description used by samples in this track 3890 \param DefaultSampleDuration default duration of samples in this track 3891 \param DefaultSampleSize default size of samples in this track (0 if unknown) 3892 \param DefaultSampleIsSync default key-flag (RAP) of samples in this track 3893 \param DefaultSamplePadding default padding bits for samples in this track 3894 \param DefaultDegradationPriority default degradation priority for samples in this track 3895 \param force_traf_flags if GF_TRUE, will ignore these default in each traf but will still write them in moov 3896 \return error if any 3897 */ 3898 GF_Err gf_isom_setup_track_fragment(GF_ISOFile *isom_file, GF_ISOTrackID TrackID, 3899 u32 DefaultSampleDescriptionIndex, 3900 u32 DefaultSampleDuration, 3901 u32 DefaultSampleSize, 3902 u8 DefaultSampleIsSync, 3903 u8 DefaultSamplePadding, 3904 u16 DefaultDegradationPriority, 3905 Bool force_traf_flags); 3906 3907 /*! changes the default parameters of an existing trak fragment 3908 \warning should not be used if samples have already been added 3909 3910 \param isom_file the target ISO file 3911 \param TrackID ID of the target track 3912 \param DefaultSampleDescriptionIndex the default description used by samples in this track 3913 \param DefaultSampleDuration default duration of samples in this track 3914 \param DefaultSampleSize default size of samples in this track (0 if unknown) 3915 \param DefaultSampleIsSync default key-flag (RAP) of samples in this track 3916 \param DefaultSamplePadding default padding bits for samples in this track 3917 \param DefaultDegradationPriority default degradation priority for samples in this track 3918 \param force_traf_flags if GF_TRUE, will ignore these default in each traf but will still write them in moov 3919 \return error if any 3920 */ 3921 GF_Err gf_isom_change_track_fragment_defaults(GF_ISOFile *isom_file, GF_ISOTrackID TrackID, 3922 u32 DefaultSampleDescriptionIndex, 3923 u32 DefaultSampleDuration, 3924 u32 DefaultSampleSize, 3925 u8 DefaultSampleIsSync, 3926 u8 DefaultSamplePadding, 3927 u16 DefaultDegradationPriority, 3928 u8 force_traf_flags); 3929 3930 /*! flushes data to disk and prepare movie fragmentation 3931 \param isom_file the target ISO file 3932 \param media_segment_type 0 if no segments, 1 if regular segment, 2 if single segment 3933 \param mvex_after_tracks forces writing mvex box after track boxes 3934 \return error if any 3935 */ 3936 GF_Err gf_isom_finalize_for_fragment(GF_ISOFile *isom_file, u32 media_segment_type, Bool mvex_after_tracks); 3937 3938 /*! sets the duration of the movie in case of movie fragments 3939 \param isom_file the target ISO file 3940 \param duration the complete duration (movie and all fragments) in movie timescale 3941 \return error if any 3942 */ 3943 GF_Err gf_isom_set_movie_duration(GF_ISOFile *isom_file, u64 duration); 3944 3945 /*! fragment creatio option*/ 3946 typedef enum 3947 { 3948 /*! moof is stored before mdat - will require temporary storage of data in memory*/ 3949 GF_ISOM_FRAG_MOOF_FIRST = 1, 3950 #ifdef GF_ENABLE_CTRN 3951 /*! use compact fragment syntax*/ 3952 GF_ISOM_FRAG_USE_COMPACT = 1<<1, 3953 #endif 3954 } GF_ISOStartFragmentFlags; 3955 /*! starts a new movie fragment 3956 \param isom_file the target ISO file 3957 \param moof_first if GF_TRUE, the moof will be written before the mdat 3958 \return error if any 3959 */ 3960 GF_Err gf_isom_start_fragment(GF_ISOFile *isom_file, GF_ISOStartFragmentFlags moof_first); 3961 3962 /*! starts a new segment in the file 3963 \param isom_file the target ISO file 3964 \param SegName if not NULL, the output will be written in the SegName file. If NULL, segment will be created in same file as movie. The special name "_gpac_isobmff_redirect" is used to indicate that segment shall be written to a memory buffer passed to callback function set through \ref gf_isom_set_write_callback 3965 \param memory_mode if set, all samples writing is done in memory rather than on disk. Ignored in callback mode 3966 \return error if any 3967 */ 3968 GF_Err gf_isom_start_segment(GF_ISOFile *isom_file, const char *SegName, Bool memory_mode); 3969 3970 /*! sets the baseMediaDecodeTime of the first sample of the given track 3971 \param isom_file the target ISO file 3972 \param TrackID ID of the target track 3973 \param decode_time the decode time in media timescale 3974 \return error if any 3975 */ 3976 GF_Err gf_isom_set_traf_base_media_decode_time(GF_ISOFile *isom_file, GF_ISOTrackID TrackID, u64 decode_time); 3977 3978 /*! enables mfra (movie fragment random access computing) when writing movie fragments 3979 \note this should only be used when generating segments in a single file 3980 \param isom_file the target ISO file 3981 \return error if any 3982 */ 3983 GF_Err gf_isom_enable_mfra(GF_ISOFile *isom_file); 3984 3985 /*! sets Microsoft Smooth Streaming traf 'tfxd' box info, written at the end of each traf 3986 \param isom_file the target ISO file 3987 \param reference_track_ID ID of the reference track giving the media timescale 3988 \param decode_traf_time decode time of the first sample in the segment in media timescale (hardcoded to 10MHz in Smooth) 3989 \param traf_duration duration of all samples in the traf in media timescale (hardcoded to 10MHz in Smooth) 3990 \return error if any 3991 */ 3992 GF_Err gf_isom_set_traf_mss_timeext(GF_ISOFile *isom_file, GF_ISOTrackID reference_track_ID, u64 decode_traf_time, u64 traf_duration); 3993 3994 /*! closes current segment, producing a segment index box if desired 3995 \param isom_file the target ISO file 3996 \param subsegs_per_sidx number of subsegments per sidx box; a negative value disables sidx, 0 forces a single sidx for the segment (or subsegment) 3997 \param referenceTrackID the ID of the track used as a reference for the segment index box 3998 \param ref_track_decode_time the decode time fo the first sample in the reference track for this segment 3999 \param timestamp_shift the constant difference between media time and presentation time (derived from edit list) 4000 \param ref_track_next_cts the CTS of the first sample in the reference track in the next segment 4001 \param daisy_chain_sidx if GF_TRUE, indicates chained sidx shall be used. Otherwise, an array of indexes is used 4002 \param use_ssix if GF_TRUE, produces an ssix box using I-frames as first level and all other frames as second level 4003 \param last_segment indicates if this is the last segment of the session 4004 \param close_segment_handle if set to GF_TRUE, the associated file if any will be closed 4005 \param segment_marker_4cc a four character code used to insert an empty box at the end of the saegment with the given type. If 0, no such box is inserted 4006 \param index_start_range set to the start offset in bytes of the segment in the media file 4007 \param index_end_range set to the end offset in bytes of the segment in the media file 4008 \param out_seg_size set to the segment size in bytes (optional, can be NULL) 4009 \return error if any 4010 */ 4011 GF_Err gf_isom_close_segment(GF_ISOFile *isom_file, s32 subsegs_per_sidx, GF_ISOTrackID referenceTrackID, u64 ref_track_decode_time, s32 timestamp_shift, u64 ref_track_next_cts, Bool daisy_chain_sidx, Bool use_ssix, Bool last_segment, Bool close_segment_handle, u32 segment_marker_4cc, u64 *index_start_range, u64 *index_end_range, u64 *out_seg_size); 4012 4013 /*! writes any pending fragment to file for low-latency output. 4014 \warning This shall only be used if no SIDX is used: subsegs_per_sidx<0 or flushing all fragments before calling \ref gf_isom_close_segment 4015 4016 \param isom_file the target ISO file 4017 \param last_segment indicates if this is the last segment of the session 4018 \return error if any 4019 */ 4020 GF_Err gf_isom_flush_fragments(GF_ISOFile *isom_file, Bool last_segment); 4021 4022 /*! gets name of current segment (or last segment if called between close_segment and start_segment) 4023 \param isom_file the target ISO file 4024 \return associated file name of the segment 4025 */ 4026 const char *gf_isom_get_segment_name(GF_ISOFile *isom_file); 4027 4028 /*! sets fragment prft box info, written just before the moof 4029 \param isom_file the target ISO file 4030 \param reference_track_ID the ID of the track used as a reference for media timestamps 4031 \param ntp absolute NTP time 4032 \param timestamp media time corresponding to the NTP time, in reference track media timescale 4033 \return error if any 4034 */ 4035 GF_Err gf_isom_set_fragment_reference_time(GF_ISOFile *isom_file, GF_ISOTrackID reference_track_ID, u64 ntp, u64 timestamp); 4036 4037 /*! writes an empty sidx in the current movie. 4038 4039 The SIDX will be forced to have nb_segs entries, and nb_segs shall match the number of calls to 4040 \ref gf_isom_close_segment that will follow. 4041 This avoids wasting time and disk space moving data around. Once \ref gf_isom_close_segment has then been called nb_segs times, 4042 the pre-allocated SIDX is destroyed and successive calls to \ref gf_isom_close_segment will create their own sidx, unless gf_isom_allocate_sidx is called again. 4043 4044 \param isom_file the target ISO file 4045 \param subsegs_per_sidx reserved to 0, currently ignored 4046 \param daisy_chain_sidx reserved to 0, currently ignored 4047 \param nb_segs number of entries in the segment index 4048 \param frags_per_segment reserved, currently ignored 4049 \param start_range set to the start offset in bytes of the segment index box 4050 \param end_range set to the end offset in bytes of the segment index box 4051 \param use_ssix if GF_TRUE, produces an ssix box using I-frames as first level and all other frames as second level 4052 \return error if any 4053 */ 4054 GF_Err gf_isom_allocate_sidx(GF_ISOFile *isom_file, s32 subsegs_per_sidx, Bool daisy_chain_sidx, u32 nb_segs, u32 *frags_per_segment, u32 *start_range, u32 *end_range, Bool use_ssix); 4055 4056 /*! sets up track fragment defaults using the given template. The template shall be a serialized array of one or more trex boxes 4057 4058 \param isom_file the target ISO file 4059 \param TrackID ID of the target track 4060 \param boxes serialized array of trex boxes 4061 \param boxes_size size of the serialized array 4062 \param force_traf_flags if GF_TRUE, will ignore these default in each traf but will still write them in moov 4063 \return error if any 4064 */ 4065 GF_Err gf_isom_setup_track_fragment_template(GF_ISOFile *isom_file, GF_ISOTrackID TrackID, u8 *boxes, u32 boxes_size, u8 force_traf_flags); 4066 4067 /*! enables track fragment inheriting from a given traf. 4068 This shall only be set when the inherited traf shares exactly the same syntax except the sample sizes, this library does not compute which 4069 sample values can be inherited 4070 4071 \param isom_file the target ISO file 4072 \param TrackID ID of the target track 4073 \param BaseTrackID ID of the track from which sample values are inherited in track fragments 4074 \return error if any 4075 */ 4076 GF_Err gf_isom_enable_traf_inherit(GF_ISOFile *isom_file, GF_ISOTrackID TrackID, GF_ISOTrackID BaseTrackID); 4077 4078 /*! Track fragment options*/ 4079 typedef enum 4080 { 4081 /*! indicates that the track fragment has no samples but still has a duration 4082 (silence-detection in audio codecs, ...). 4083 param: indicates duration*/ 4084 GF_ISOM_TRAF_EMPTY, 4085 /*! I-Frame detection: this can reduce file size by detecting I-frames and 4086 optimizing sample flags (padding, priority, ..) 4087 param: on/off (0/1)*/ 4088 GF_ISOM_TRAF_RANDOM_ACCESS, 4089 /*! activate data cache on track fragment. This is useful when writing interleaved 4090 media from a live source (typically audio-video), and greatly reduces file size 4091 param: Number of samples (> 1) to cache before disk flushing. You shouldn't try 4092 to cache too many samples since this will load your memory. base that on FPS/SR*/ 4093 GF_ISOM_TRAF_DATA_CACHE, 4094 /*! forces moof base offsets when traf based offsets would be chosen 4095 param: on/off (0/1)*/ 4096 GF_ISOM_TFHD_FORCE_MOOF_BASE_OFFSET, 4097 /*! use sdtp box in traf rather than storing sample deps in trun entry. param values are: 4098 0: disables sdtp 4099 1: enables sdtp and disables sample dependency flags in trun 4100 2: enables sdtp and also use sample dependency flags in trun 4101 */ 4102 GF_ISOM_TRAF_USE_SAMPLE_DEPS_BOX, 4103 /*! forces new trun at next sample add 4104 param: ignored*/ 4105 GF_ISOM_TRUN_FORCE, 4106 /*! sets interleave group ID of the next sample add. Samples with lower interleave ID will be stored first, creating new trun whenever a new group is detected 4107 This will enable data cache 4108 param: interleave ID*/ 4109 GF_ISOM_TRUN_SET_INTERLEAVE_ID, 4110 } GF_ISOTrackFragmentOption; 4111 4112 /*! sets a track fragment option. Options can be set at the beginning of each new fragment only, and for the 4113 lifetime of the fragment 4114 \param isom_file the target ISO file 4115 \param TrackID ID of the target track 4116 \param Code the option type to set 4117 \param param the option value 4118 \return error if any 4119 */ 4120 GF_Err gf_isom_set_fragment_option(GF_ISOFile *isom_file, GF_ISOTrackID TrackID, GF_ISOTrackFragmentOption Code, u32 param); 4121 4122 /*! adds a sample to a fragmented track 4123 4124 \param isom_file the target ISO file 4125 \param TrackID destination track 4126 \param sample sample to add 4127 \param sampleDescriptionIndex sample description for this sample. If 0, the default one 4128 is used 4129 \param Duration sample duration; the sample duration MUST be provided at least for the last sample (for intermediate samples, it is recomputed internally by the lib) 4130 \param PaddingBits padding bits for the sample, or 0 4131 \param DegradationPriority for the sample, or 0 4132 \param redundantCoding indicates this is samples acts as a sync shadow point 4133 \return error if any 4134 */ 4135 GF_Err gf_isom_fragment_add_sample(GF_ISOFile *isom_file, GF_ISOTrackID TrackID, const GF_ISOSample *sample, 4136 u32 sampleDescriptionIndex, 4137 u32 Duration, u8 PaddingBits, u16 DegradationPriority, Bool redundantCoding); 4138 4139 /*! appends data into last sample of track for video fragments/other media 4140 \warning this shall not be used with OD tracks 4141 \param isom_file the target ISO file 4142 \param TrackID destination track 4143 \param data the data to append 4144 \param data_size the size of the data to append 4145 \param PaddingBits padding bits for the sample, or 0 4146 \return error if any 4147 */ 4148 GF_Err gf_isom_fragment_append_data(GF_ISOFile *isom_file, GF_ISOTrackID TrackID, u8 *data, u32 data_size, u8 PaddingBits); 4149 4150 4151 /*! sets side information for common encryption for the last added sample 4152 \param isom_file the target ISO file 4153 \param trackID the ID of the target track 4154 \param IV_size the size of the init vector (8 or 16 bytes) 4155 \param sai_b buffer containing the SAI information of the sample 4156 \param sai_b_size size of the SAI buffer. If sai_b is NULL, this indicates the original sample size, and an SAI will be created describing the proper byte ranges if use_subsample is set 4157 \param use_subsample indicates if the media uses CENC subsamples 4158 \param use_saio_32bit indicates if 32-bit saio shall be used 4159 \return error if any 4160 */ 4161 GF_Err gf_isom_fragment_set_cenc_sai(GF_ISOFile *isom_file, GF_ISOTrackID trackID, u32 IV_size, u8 *sai_b, u32 sai_b_size, Bool use_subsample, Bool use_saio_32bit); 4162 /*! clones PSSH data between two files 4163 \param dst_file the target ISO file 4164 \param src_file the source ISO file 4165 \param in_moof if GF_TRUE, indicates the pssh should be cloned in current moof box 4166 \return error if any 4167 */ 4168 GF_Err gf_isom_clone_pssh(GF_ISOFile *dst_file, GF_ISOFile *src_file, Bool in_moof); 4169 /*! sets roll information for a sample in a track fragment 4170 \param isom_file the target ISO file 4171 \param trackID the ID of the target track 4172 \param sample_number the sample number of the last sample 4173 \param is_roll set to GF_TRUE to indicate the sample is a roll sample, GF_FALSE otherwise 4174 \param roll_distance set to the roll distance for a roll sample 4175 \return error if any 4176 */ 4177 GF_Err gf_isom_fragment_set_sample_roll_group(GF_ISOFile *isom_file, GF_ISOTrackID trackID, u32 sample_number, Bool is_roll, s16 roll_distance); 4178 4179 /*! sets rap information for a sample in a track fragment 4180 \param isom_file the target ISO file 4181 \param trackID the ID of the target track 4182 \param sample_number_in_frag the sample number of the sample in the traf 4183 \param is_rap set to GF_TRUE to indicate the sample is a RAP sample (open-GOP), GF_FALSE otherwise 4184 \param num_leading_samples set to the number of leading pictures for a RAP sample 4185 \return error if any 4186 */ 4187 GF_Err gf_isom_fragment_set_sample_rap_group(GF_ISOFile *isom_file, GF_ISOTrackID trackID, u32 sample_number_in_frag, Bool is_rap, u32 num_leading_samples); 4188 4189 /*! sets sample dependency flags in a track fragment - see ISO/IEC 14496-12 and \ref gf_filter_pck_set_dependency_flags 4190 \param isom_file the target ISO file 4191 \param trackID the ID of the target track 4192 \param is_leading indicates that the sample is a leading picture 4193 \param dependsOn indicates the sample dependency towards other samples 4194 \param dependedOn indicates the sample dependency from other samples 4195 \param redundant indicates that the sample contains redundant coding 4196 \return error if any 4197 */ 4198 GF_Err gf_isom_fragment_set_sample_flags(GF_ISOFile *isom_file, GF_ISOTrackID trackID, u32 is_leading, u32 dependsOn, u32 dependedOn, u32 redundant); 4199 4200 4201 /*! sets the number of the next moof to be produced 4202 \param isom_file the target ISO file 4203 \param value the number of the next moof 4204 */ 4205 void gf_isom_set_next_moof_number(GF_ISOFile *isom_file, u32 value); 4206 4207 4208 /*! @} */ 4209 #endif// !defined(GPAC_DISABLE_ISOM_FRAGMENTS) && !defined(GPAC_DISABLE_ISOM_WRITE) 4210 4211 4212 /*! 4213 \addtogroup isortp_grp ISOBMFF RTP Hinting 4214 \ingroup iso_grp 4215 4216 @{ 4217 */ 4218 4219 /*! supported hint formats - ONLY RTP now*/ 4220 typedef enum 4221 { 4222 /*! RTP hint type*/ 4223 GF_ISOM_HINT_RTP = GF_4CC('r', 't', 'p', ' '), 4224 } GF_ISOHintFormat; 4225 4226 #if !defined(GPAC_DISABLE_ISOM_WRITE) && !defined(GPAC_DISABLE_ISOM_HINTING) 4227 4228 /*! sets up a hint track based on the hint format 4229 \warning This function MUST be called after creating a new hint track and before any other calls on this track 4230 \param isom_file the target ISO file 4231 \param trackNumber the target hint track 4232 \param HintType the desired hint type 4233 \return error if any 4234 */ 4235 GF_Err gf_isom_setup_hint_track(GF_ISOFile *isom_file, u32 trackNumber, GF_ISOHintFormat HintType); 4236 4237 /*! creates a HintDescription for the HintTrack 4238 \param isom_file the target ISO file 4239 \param trackNumber the target hint track 4240 \param HintTrackVersion version of hint track 4241 \param LastCompatibleVersion last compatible version of hint track 4242 \param Rely flag indicating whether a reliable transport protocol is desired/required 4243 for data transport 4244 0: not desired (UDP/IP). NB: most RTP streaming servers only support UDP/IP for data 4245 1: preferable (TCP/IP if possible or UDP/IP) 4246 2: required (TCP/IP only) 4247 \param HintDescriptionIndex is set to the newly created hint sample description index 4248 \return error if any 4249 */ 4250 GF_Err gf_isom_new_hint_description(GF_ISOFile *isom_file, u32 trackNumber, s32 HintTrackVersion, s32 LastCompatibleVersion, u8 Rely, u32 *HintDescriptionIndex); 4251 4252 /*! starts a new sample for the hint track. A sample is just a collection of packets 4253 the transmissionTime is indicated in the media timeScale of the hint track 4254 \param isom_file the target ISO file 4255 \param trackNumber the target hint track 4256 \param HintDescriptionIndex the target hint sample description index 4257 \param TransmissionTime the target transmission time in hint media timescale 4258 \return error if any 4259 */ 4260 GF_Err gf_isom_begin_hint_sample(GF_ISOFile *isom_file, u32 trackNumber, u32 HintDescriptionIndex, u32 TransmissionTime); 4261 4262 /*! ends an hint sample once all your packets for this sample are done 4263 \param isom_file the target ISO file 4264 \param trackNumber the target hint track 4265 \param IsRandomAccessPoint set to GF_TRUE if you want to indicate that this is a random access point in the stream 4266 \return error if any 4267 */ 4268 GF_Err gf_isom_end_hint_sample(GF_ISOFile *isom_file, u32 trackNumber, u8 IsRandomAccessPoint); 4269 4270 4271 /*! 4272 PacketHandling functions 4273 Data can be added at the end or at the beginning of the current packet 4274 by setting AtBegin to 1 the data will be added at the beginning 4275 This allows constructing the packet payload before any meta-data 4276 */ 4277 4278 /*! adds a blank chunk of data in the sample that is skipped while streaming 4279 \param isom_file the target ISO file 4280 \param trackNumber the target hint track 4281 \param AtBegin indicates if the blank chunk should be at the end or at the begining of the hint packet 4282 \return error if any 4283 */ 4284 GF_Err gf_isom_hint_blank_data(GF_ISOFile *isom_file, u32 trackNumber, u8 AtBegin); 4285 4286 /*! adds a chunk of data in the packet that is directly copied while streaming 4287 NOTE: dataLength MUST BE <= 14 bytes, and you should only use this function 4288 to add small blocks of data (encrypted parts, specific headers, ...) 4289 \param isom_file the target ISO file 4290 \param trackNumber the target hint track 4291 \param data buffer to add to the RTP packet 4292 \param dataLength size of buffer to add to the RTP packet 4293 \param AtBegin indicates if the blank chunk should be at the end or at the begining of the hint packet 4294 \return error if any 4295 */ 4296 GF_Err gf_isom_hint_direct_data(GF_ISOFile *isom_file, u32 trackNumber, u8 *data, u32 dataLength, u8 AtBegin); 4297 4298 /*! adds a reference to some sample data in the packet 4299 \note if you want to reference a previous HintSample in the hintTrack, you will have to parse the sample yourself ... 4300 4301 \param isom_file the target ISO file 4302 \param trackNumber the target hint track 4303 \param SourceTrackID the ID of the track where the referenced sample is 4304 \param SampleNumber the sample number containing the data to be added 4305 \param DataLength the length of bytes to copy in the packet 4306 \param offsetInSample the offset in bytes in the sample at which to begin copying data 4307 \param extra_data only used when the sample is actually the sample that will contain this packet 4308 (useful to store en encrypted version of a packet only available while streaming) 4309 In this case, set SourceTrackID to the HintTrack ID and SampleNumber to 0 4310 In this case, the DataOffset MUST BE NULL and length will indicate the extra_data size 4311 \param AtBegin indicates if the blank chunk should be at the end or at the begining of the hint packet 4312 \return error if any 4313 */ 4314 GF_Err gf_isom_hint_sample_data(GF_ISOFile *isom_file, u32 trackNumber, GF_ISOTrackID SourceTrackID, u32 SampleNumber, u16 DataLength, u32 offsetInSample, u8 *extra_data, u8 AtBegin); 4315 4316 4317 /*! adds a reference to some stream description data in the packet (headers, ...) 4318 4319 \param isom_file the target ISO file 4320 \param trackNumber the target hint track 4321 \param SourceTrackID the ID of the track where the referenced sample is 4322 \param sampleDescriptionIndex the index of the stream description in the desired track 4323 \param DataLength the length of bytes to copy in the packet 4324 \param offsetInDescription the offset in bytes in the description at which to begin copying data. Since it is far from being obvious / interoperable what this offset is, we recommend not using this function and injecting the data instead using \ref gf_isom_hint_direct_data. 4325 \param AtBegin indicates if the blank chunk should be at the end or at the begining of the hint packet 4326 \return error if any 4327 */ 4328 GF_Err gf_isom_hint_sample_description_data(GF_ISOFile *isom_file, u32 trackNumber, GF_ISOTrackID SourceTrackID, u32 sampleDescriptionIndex, u16 DataLength, u32 offsetInDescription, u8 AtBegin); 4329 4330 4331 /*! creates a new RTP packet in the HintSample. If a previous packet was created, 4332 it is stored in the hint sample and a new packet is created. 4333 4334 \param isom_file the target ISO file 4335 \param trackNumber the target hint track 4336 \param relativeTime RTP time offset of this packet in the HintSample if any - in hint track 4337 time scale. Used for data smoothing by servers. 4338 \param PackingBit the 'P' bit of the RTP packet header 4339 \param eXtensionBit the'X' bit of the RTP packet header 4340 \param MarkerBit the 'M' bit of the RTP packet header 4341 \param PayloadType the payload type, on 7 bits, format 0x0XXXXXXX 4342 \param disposable_packet indicates if this packet can be skipped by a server 4343 \param IsRepeatedPacket indicates if this is a duplicate packet of a previous one and can be skipped by a server 4344 \param SequenceNumber the RTP base sequence number of the packet. Because of support for repeated packets, you have to set the sequence number yourself. 4345 \return error if any 4346 */ 4347 GF_Err gf_isom_rtp_packet_begin(GF_ISOFile *isom_file, u32 trackNumber, s32 relativeTime, u8 PackingBit, u8 eXtensionBit, u8 MarkerBit, u8 PayloadType, u8 disposable_packet, u8 IsRepeatedPacket, u16 SequenceNumber); 4348 4349 /*! sets the flags of the RTP packet 4350 \param isom_file the target ISO file 4351 \param trackNumber the target hint track 4352 \param PackingBit the 'P' bit of the RTP packet header 4353 \param eXtensionBit the'X' bit of the RTP packet header 4354 \param MarkerBit the 'M' bit of the RTP packet header 4355 \param disposable_packet indicates if this packet can be skipped by a server 4356 \param IsRepeatedPacket indicates if this is a duplicate packet of a previous one and can be skipped by a server 4357 \return error if any*/ 4358 GF_Err gf_isom_rtp_packet_set_flags(GF_ISOFile *isom_file, u32 trackNumber, u8 PackingBit, u8 eXtensionBit, u8 MarkerBit, u8 disposable_packet, u8 IsRepeatedPacket); 4359 4360 /*! sets the time offset of this packet. This enables packets to be placed in the hint track 4361 in decoding order, but have their presentation time-stamp in the transmitted 4362 packet in a different order. Typically used for MPEG video with B-frames 4363 \param isom_file the target ISO file 4364 \param trackNumber the target hint track 4365 \param timeOffset time offset in RTP media timescale 4366 \return error if any 4367 */ 4368 GF_Err gf_isom_rtp_packet_set_offset(GF_ISOFile *isom_file, u32 trackNumber, s32 timeOffset); 4369 4370 4371 /*! sets the RTP TimeScale that the server use to send packets 4372 some RTP payloads may need a specific timeScale that is not the timeScale in the file format 4373 the default timeScale choosen by the API is the MediaTimeScale of the hint track 4374 \param isom_file the target ISO file 4375 \param trackNumber the target hint track 4376 \param HintDescriptionIndex the target hint sample description index 4377 \param TimeScale the RTP timescale to use 4378 \return error if any 4379 */ 4380 GF_Err gf_isom_rtp_set_timescale(GF_ISOFile *isom_file, u32 trackNumber, u32 HintDescriptionIndex, u32 TimeScale); 4381 4382 /*! sets the RTP TimeOffset that the server will add to the packets 4383 if not set, the server adds a random offset 4384 \param isom_file the target ISO file 4385 \param trackNumber the target hint track 4386 \param HintDescriptionIndex the target hint sample description index 4387 \param TimeOffset the time offset in RTP timescale 4388 \return error if any 4389 */ 4390 GF_Err gf_isom_rtp_set_time_offset(GF_ISOFile *isom_file, u32 trackNumber, u32 HintDescriptionIndex, u32 TimeOffset); 4391 4392 /*! sets the RTP SequenceNumber Offset that the server will add to the packets 4393 if not set, the server adds a random offset 4394 \param isom_file the target ISO file 4395 \param trackNumber the target hint track 4396 \param HintDescriptionIndex the target hint sample description index 4397 \param SequenceNumberOffset the sequence number offset 4398 \return error if any 4399 */ 4400 GF_Err gf_isom_rtp_set_time_sequence_offset(GF_ISOFile *isom_file, u32 trackNumber, u32 HintDescriptionIndex, u32 SequenceNumberOffset); 4401 4402 /*! adds an SDP line to the SDP container at the track level (media-specific SDP info) 4403 \note the CRLF end of line for SDP is automatically inserted 4404 \param isom_file the target ISO file 4405 \param trackNumber the target hint track 4406 \param text the SDP text to add the target hint track 4407 \return error if any 4408 */ 4409 GF_Err gf_isom_sdp_add_track_line(GF_ISOFile *isom_file, u32 trackNumber, const char *text); 4410 /*! removes all SDP info at the track level 4411 \param isom_file the target ISO file 4412 \param trackNumber the target hint track 4413 \return error if any 4414 */ 4415 GF_Err gf_isom_sdp_clean_track(GF_ISOFile *isom_file, u32 trackNumber); 4416 4417 /*! adds an SDP line to the SDP container at the movie level (presentation SDP info) 4418 NOTE: the CRLF end of line for SDP is automatically inserted 4419 \param isom_file the target ISO file 4420 \param text the SDP text to add the target hint track 4421 \return error if any 4422 */ 4423 GF_Err gf_isom_sdp_add_line(GF_ISOFile *isom_file, const char *text); 4424 /*! removes all SDP info at the movie level 4425 \param isom_file the target ISO file 4426 \return error if any 4427 */ 4428 GF_Err gf_isom_sdp_clean(GF_ISOFile *isom_file); 4429 4430 #endif// !defined(GPAC_DISABLE_ISOM_WRITE) && !defined(GPAC_DISABLE_ISOM_HINTING) 4431 4432 4433 #ifndef GPAC_DISABLE_ISOM_HINTING 4434 4435 #ifndef GPAC_DISABLE_ISOM_DUMP 4436 /*! dumps RTP hint samples structure into XML trace file 4437 \param isom_file the target ISO file 4438 \param trackNumber the target track 4439 \param SampleNum the target sample number 4440 \param trace the file object to dump to 4441 \return error if any 4442 */ 4443 GF_Err gf_isom_dump_hint_sample(GF_ISOFile *isom_file, u32 trackNumber, u32 SampleNum, FILE * trace); 4444 #endif 4445 4446 /*! gets SDP info at the movie level 4447 \param isom_file the target ISO file 4448 \param sdp set to the sdp text - do not modify 4449 \param length set to the sdp length 4450 \return error if any 4451 */ 4452 GF_Err gf_isom_sdp_get(GF_ISOFile *isom_file, const char **sdp, u32 *length); 4453 /*! gets SDP info at the track level 4454 \param isom_file the target ISO file 4455 \param trackNumber the target track 4456 \param sdp set to the sdp text - do not modify 4457 \param length set to the sdp length 4458 \return error if any 4459 */ 4460 GF_Err gf_isom_sdp_track_get(GF_ISOFile *isom_file, u32 trackNumber, const char **sdp, u32 *length); 4461 /*! gets number of payload type defines for an RTP hint track 4462 \param isom_file the target ISO file 4463 \param trackNumber the target track 4464 \return the number of payload types defined 4465 */ 4466 u32 gf_isom_get_payt_count(GF_ISOFile *isom_file, u32 trackNumber); 4467 /*! gets payload type information for an RTP hint track 4468 \param isom_file the target ISO file 4469 \param trackNumber the target track 4470 \param index the payload type 1_based index 4471 \param payID set to the ID of the payload type 4472 \return the sdp fmtp attribute describing the payload 4473 */ 4474 const char *gf_isom_get_payt_info(GF_ISOFile *isom_file, u32 trackNumber, u32 index, u32 *payID); 4475 4476 4477 #endif /*GPAC_DISABLE_ISOM_HINTING*/ 4478 4479 4480 /*! @} */ 4481 4482 /*! 4483 \addtogroup isotxt_grp Subtitles and Timed Text 4484 \ingroup iso_grp 4485 4486 @{ 4487 */ 4488 4489 4490 /*! sets streaming text reading mode (MPEG-4 text vs 3GPP) 4491 \param isom_file the target ISO file 4492 \param do_convert is set, all text samples will be retrieved as TTUs and ESD will be emulated for text tracks 4493 \return error if any 4494 */ 4495 GF_Err gf_isom_text_set_streaming_mode(GF_ISOFile *isom_file, Bool do_convert); 4496 4497 4498 #ifndef GPAC_DISABLE_ISOM_DUMP 4499 /*! text track export type*/ 4500 typedef enum { 4501 /*! dump as TTXT XML*/ 4502 GF_TEXTDUMPTYPE_TTXT = 0, 4503 /*! dump as TTXT XML with box */ 4504 GF_TEXTDUMPTYPE_TTXT_BOXES = 1, 4505 /*! dump as SRT*/ 4506 GF_TEXTDUMPTYPE_SRT = 2, 4507 /*! dump as SVG*/ 4508 GF_TEXTDUMPTYPE_SVG = 3, 4509 } GF_TextDumpType; 4510 /*! dumps a text track to a file 4511 \param isom_file the target ISO file 4512 \param trackNumber the target track 4513 \param dump the file object to write to (binary open mode) 4514 \param dump_type the dump type mode 4515 \return error if any 4516 */ 4517 GF_Err gf_isom_text_dump(GF_ISOFile *isom_file, u32 trackNumber, FILE *dump, GF_TextDumpType dump_type); 4518 #endif 4519 4520 /*! gets encoded TX3G box (text sample description for 3GPP text streams) as needed by RTP or other standards: 4521 \param isom_file the target ISO file 4522 \param trackNumber the target track 4523 \param sampleDescriptionIndex the sample description index 4524 \param sidx_offset if 0, the sidx will NOT be written before the encoded TX3G. If not 0, the sidx will be written before the encoded TX3G, with the given offset. Offset sshould be at least 128 for most commmon usage of TX3G (RTP, MPEG-4 timed text, etc) 4525 \param tx3g set to a newly allocated buffer containing the encoded tx3g - to be freed by caller 4526 \param tx3g_size set to the size of the encoded config 4527 \return error if any 4528 */ 4529 GF_Err gf_isom_text_get_encoded_tx3g(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 sidx_offset, u8 **tx3g, u32 *tx3g_size); 4530 4531 /*! text sample formatting*/ 4532 typedef struct _3gpp_text_sample GF_TextSample; 4533 /*! creates text sample handle 4534 \return a newly allocated text sample 4535 */ 4536 GF_TextSample *gf_isom_new_text_sample(); 4537 /*! destroys text sample handle 4538 \param tx_samp the target text sample 4539 */ 4540 void gf_isom_delete_text_sample(GF_TextSample *tx_samp); 4541 4542 /*! generic subtitle sample formatting*/ 4543 typedef struct _generic_subtitle_sample GF_GenericSubtitleSample; 4544 /*! creates generic subtitle sample handle 4545 \return a newly allocated generic subtitle sample 4546 */ 4547 GF_GenericSubtitleSample *gf_isom_new_generic_subtitle_sample(); 4548 /*! destroys generic subtitle sample handle 4549 \param generic_subtitle_samp the target generic subtitle sample 4550 */ 4551 void gf_isom_delete_generic_subtitle_sample(GF_GenericSubtitleSample *generic_subtitle_samp); 4552 4553 #ifndef GPAC_DISABLE_VTT 4554 /*! creates new WebVTT config 4555 \param isom_file the target ISO file 4556 \param trackNumber the target track 4557 \param URLname URL value of the data reference, NULL if no data reference (media in the file) 4558 \param URNname URN value of the data reference, NULL if no data reference (media in the file) 4559 \param outDescriptionIndex set to the index of the created sample description 4560 \param config the WebVTT configuration string 4561 \return error if any 4562 */ 4563 GF_Err gf_isom_new_webvtt_description(GF_ISOFile *isom_file, u32 trackNumber, const char *URLname, const char *URNname, u32 *outDescriptionIndex, const char *config); 4564 /*! updates a WebVTT sample description 4565 \param isom_file the target ISO file 4566 \param trackNumber the target track 4567 \param sampleDescriptionIndex the target sample description index to update 4568 \param config the WebVTT configuration string 4569 \return error if any 4570 */ 4571 GF_Err gf_isom_update_webvtt_description(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, const char *config); 4572 #endif 4573 4574 /*! gets WebVTT config for a sample description 4575 \param isom_file the target ISO file 4576 \param trackNumber the target track 4577 \param sampleDescriptionIndex the target sample description index 4578 \return the WebVTT configuration string 4579 */ 4580 const char *gf_isom_get_webvtt_config(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 4581 4582 /*! gets simple streaming text config for a sample description 4583 \param isom_file the target ISO file 4584 \param trackNumber the target track 4585 \param sampleDescriptionIndex the target sample description index 4586 \param mime set to the mime type (optional, can be NULL) 4587 \param encoding set to the text encoding type (optional, can be NULL) 4588 \param config set to the WebVTT configuration string (optional, can be NULL) 4589 \return error if any 4590 */ 4591 GF_Err gf_isom_stxt_get_description(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, const char **mime, const char **encoding, const char **config); 4592 4593 #ifndef GPAC_DISABLE_ISOM_WRITE 4594 /*! creates new simple streaming text config 4595 \param isom_file the target ISO file 4596 \param trackNumber the target track 4597 \param type the four character code of the simple text sample description (sbtt, stxt, mett) 4598 \param mime the mime type 4599 \param encoding the text encoding, if any 4600 \param config the configuration string, if any 4601 \param outDescriptionIndex set to the index of the created sample description 4602 \return error if any 4603 */ 4604 GF_Err gf_isom_new_stxt_description(GF_ISOFile *isom_file, u32 trackNumber, u32 type, const char *mime, const char *encoding, const char *config, u32 *outDescriptionIndex); 4605 4606 /*! updates simple streaming text config 4607 \param isom_file the target ISO file 4608 \param trackNumber the target track 4609 \param encoding the text encoding, if any 4610 \param config the configuration string, if any 4611 \param sampleDescriptionIndex the target sample description index 4612 \return error if any 4613 */ 4614 GF_Err gf_isom_update_stxt_description(GF_ISOFile *isom_file, u32 trackNumber, const char *encoding, const char *config, u32 sampleDescriptionIndex); 4615 #endif // GPAC_DISABLE_ISOM_WRITE 4616 4617 /*! gets XML streaming text config for a sample description 4618 \param isom_file the target ISO file 4619 \param trackNumber the target track 4620 \param sampleDescriptionIndex the target sample description index 4621 \param xmlnamespace set to the XML namespace (optional, can be NULL) 4622 \param xml_schema_loc set to the XML schema location (optional, can be NULL) 4623 \param mimes set to the associated mime(s) types (optional, can be NULL) 4624 \return error if any 4625 */ 4626 GF_Err gf_isom_xml_subtitle_get_description(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, 4627 const char **xmlnamespace, const char **xml_schema_loc, const char **mimes); 4628 4629 #ifndef GPAC_DISABLE_ISOM_WRITE 4630 /*! creates a new XML streaming text config 4631 \param isom_file the target ISO file 4632 \param trackNumber the target track 4633 \param xmlnamespace the XML namespace 4634 \param xml_schema_loc the XML schema location (optional, can be NULL) 4635 \param auxiliary_mimes the associated mime(s) types (optional, can be NULL) 4636 \param outDescriptionIndex set to the index of the created sample description 4637 \return error if any 4638 */ 4639 GF_Err gf_isom_new_xml_subtitle_description(GF_ISOFile *isom_file, u32 trackNumber, 4640 const char *xmlnamespace, const char *xml_schema_loc, const char *auxiliary_mimes, 4641 u32 *outDescriptionIndex); 4642 #endif // GPAC_DISABLE_ISOM_WRITE 4643 4644 4645 /*! gets XML metadata for a sample description 4646 \param isom_file the target ISO file 4647 \param trackNumber the target track 4648 \param sampleDescriptionIndex the target sample description index 4649 \param xmlnamespace set to the XML namespace (optional, can be NULL) 4650 \param schema_loc set to the XML schema location (optional, can be NULL) 4651 \param content_encoding set to the content encoding string (optional, can be NULL) 4652 \return error if any 4653 */ 4654 GF_Err gf_isom_get_xml_metadata_description(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, const char **xmlnamespace, const char **schema_loc, const char **content_encoding); 4655 4656 #ifndef GPAC_DISABLE_ISOM_WRITE 4657 /*! creates a new timed metadata sample description for this track 4658 \param isom_file the target ISO file 4659 \param trackNumber the target track 4660 \param xmlnamespace the XML namespace 4661 \param schema_loc the XML schema location (optional, can be NULL) 4662 \param content_encoding the content encoding string (optional, can be NULL) 4663 \param outDescriptionIndex set to the index of the created sample description 4664 \return error if any 4665 */ 4666 GF_Err gf_isom_new_xml_metadata_description(GF_ISOFile *isom_file, u32 trackNumber, const char *xmlnamespace, const char *schema_loc, const char *content_encoding, u32 *outDescriptionIndex); 4667 #endif /*GPAC_DISABLE_ISOM_WRITE*/ 4668 4669 4670 4671 4672 /*! text flags operation type*/ 4673 typedef enum 4674 { 4675 GF_ISOM_TEXT_FLAGS_OVERWRITE = 0, 4676 GF_ISOM_TEXT_FLAGS_TOGGLE, 4677 GF_ISOM_TEXT_FLAGS_UNTOGGLE, 4678 } GF_TextFlagsMode; 4679 /*! sets text display flags according to given mode. 4680 \param isom_file the target ISO file 4681 \param trackNumber the target track 4682 \param sampleDescriptionIndex the target sample description index. If 0, sets the flags for all text descriptions 4683 \param flags the flag to set 4684 \param op_type the flag toggle mode 4685 \return error if any 4686 */ 4687 GF_Err gf_isom_text_set_display_flags(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 flags, GF_TextFlagsMode op_type); 4688 4689 /*! gets text description of a sample description 4690 \param isom_file the target ISO file 4691 \param trackNumber the target track 4692 \param sampleDescriptionIndex the target sample description index 4693 \param out_desc set to a newly allocated text sample descriptor - shall be freeed by user 4694 \return error if any 4695 */ 4696 GF_Err gf_isom_get_text_description(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, GF_TextSampleDescriptor **out_desc); 4697 4698 #ifndef GPAC_DISABLE_ISOM_WRITE 4699 4700 /*! creates a new TextSampleDescription in the file. 4701 \param isom_file the target ISO file 4702 \param trackNumber the target track 4703 \param desc the text sample description 4704 \param URLname URL value of the data reference, NULL if no data reference (media in the file) 4705 \param URNname URN value of the data reference, NULL if no data reference (media in the file) 4706 \param outDescriptionIndex set to the index of the created sample description 4707 \return error if any 4708 */ 4709 GF_Err gf_isom_new_text_description(GF_ISOFile *isom_file, u32 trackNumber, GF_TextSampleDescriptor *desc, const char *URLname, const char *URNname, u32 *outDescriptionIndex); 4710 4711 /*! resets text sample content 4712 \param tx_samp the target text sample 4713 \return error if any 4714 */ 4715 GF_Err gf_isom_text_reset(GF_TextSample * tx_samp); 4716 /*! resets text sample styles but keep text 4717 \param tx_samp the target text sample 4718 \return error if any 4719 */ 4720 GF_Err gf_isom_text_reset_styles(GF_TextSample *tx_samp); 4721 4722 /*! appends text to sample - text_len is the number of bytes to be written from text_data. This allows 4723 handling UTF8 and UTF16 strings in a transparent manner 4724 \param tx_samp the target text sample 4725 \param text_data the text data to add 4726 \param text_len the size of the data to add 4727 \return error if any 4728 */ 4729 GF_Err gf_isom_text_add_text(GF_TextSample *tx_samp, char *text_data, u32 text_len); 4730 /*! appends style modifyer to sample 4731 \param tx_samp the target text sample 4732 \param rec the style record to add 4733 \return error if any 4734 */ 4735 GF_Err gf_isom_text_add_style(GF_TextSample *tx_samp, GF_StyleRecord *rec); 4736 /*! appends highlight modifier for the sample 4737 \param tx_samp the target text sample 4738 \param start_char first char highlighted, 4739 \param end_char first char not highlighted 4740 \return error if any 4741 */ 4742 GF_Err gf_isom_text_add_highlight(GF_TextSample *tx_samp, u16 start_char, u16 end_char); 4743 4744 /*! sets highlight color for the whole sample 4745 \param tx_samp the target text sample 4746 \param argb color value 4747 \return error if any 4748 */ 4749 GF_Err gf_isom_text_set_highlight_color(GF_TextSample *tx_samp, u32 argb); 4750 /*! appends a new karaoke sequence in the sample 4751 \param tx_samp the target text sample 4752 \param start_time karaoke start time expressed in text stream timescale, but relative to the sample media time 4753 \return error if any 4754 */ 4755 GF_Err gf_isom_text_add_karaoke(GF_TextSample *tx_samp, u32 start_time); 4756 /*! appends a new segment in the current karaoke sequence - you must build sequences in order to be compliant 4757 \param tx_samp the target text sample 4758 \param end_time segment end time expressed in text stream timescale, but relative to the sample media time 4759 \param start_char first char highlighted, 4760 \param end_char first char not highlighted 4761 \return error if any 4762 */ 4763 GF_Err gf_isom_text_set_karaoke_segment(GF_TextSample *tx_samp, u32 end_time, u16 start_char, u16 end_char); 4764 /*! sets scroll delay for the whole sample (scrolling is enabled through GF_TextSampleDescriptor.DisplayFlags) 4765 \param tx_samp the target text sample 4766 \param scroll_delay delay for scrolling expressed in text stream timescale 4767 \return error if any 4768 */ 4769 GF_Err gf_isom_text_set_scroll_delay(GF_TextSample *tx_samp, u32 scroll_delay); 4770 /*! appends hyperlinking for the sample 4771 \param tx_samp the target text sample 4772 \param URL UTF-8 url 4773 \param altString UTF-8 hint (tooltip, ...) for end user 4774 \param start_char first char hyperlinked, 4775 \param end_char first char not hyperlinked 4776 \return error if any 4777 */ 4778 GF_Err gf_isom_text_add_hyperlink(GF_TextSample *tx_samp, char *URL, char *altString, u16 start_char, u16 end_char); 4779 /*! sets current text box (display pos&size within the text track window) for the sample 4780 \param tx_samp the target text sample 4781 \param top top coordinate of box 4782 \param left left coordinate of box 4783 \param bottom bottom coordinate of box 4784 \param right right coordinate of box 4785 \return error if any 4786 */ 4787 GF_Err gf_isom_text_set_box(GF_TextSample *tx_samp, s16 top, s16 left, s16 bottom, s16 right); 4788 /*! appends blinking for the sample 4789 \param tx_samp the target text sample 4790 \param start_char first char blinking, 4791 \param end_char first char not blinking 4792 \return error if any 4793 */ 4794 GF_Err gf_isom_text_add_blink(GF_TextSample *tx_samp, u16 start_char, u16 end_char); 4795 /*! sets wrap flag for the sample 4796 \param tx_samp the target text sample 4797 \param wrap_flags text wrap flags - currently only 0 (no wrap) and 1 ("soft wrap") are allowed in 3GP 4798 \return error if any 4799 */ 4800 GF_Err gf_isom_text_set_wrap(GF_TextSample *tx_samp, u8 wrap_flags); 4801 4802 /*! formats sample as a regular GF_ISOSample payload in a bitstream object. 4803 \param tx_samp the target text sample 4804 \param bs thetarget bitstream 4805 \return error if any 4806 */ 4807 GF_Err gf_isom_text_sample_write_bs(const GF_TextSample *tx_samp, GF_BitStream *bs); 4808 /*! gets the serialized size of the text sample 4809 \param tx_samp the target text sample 4810 \return the serialized size 4811 */ 4812 u32 gf_isom_text_sample_size(GF_TextSample *tx_samp); 4813 4814 /*! creates a new XML subtitle sample 4815 \return a new XML subtitle sample 4816 */ 4817 GF_GenericSubtitleSample *gf_isom_new_xml_subtitle_sample(); 4818 /*! deletes an XML subtitle sample 4819 \param subt_samp the target XML subtitle sample 4820 */ 4821 void gf_isom_delete_xml_subtitle_sample(GF_GenericSubtitleSample *subt_samp); 4822 /*! resets content of an XML subtitle sample 4823 \param subt_samp the target XML subtitle sample 4824 \return error if any 4825 */ 4826 GF_Err gf_isom_xml_subtitle_reset(GF_GenericSubtitleSample *subt_samp); 4827 /*! the corresponding serialized ISO sample 4828 \param subt_samp the target XML subtitle sample 4829 \return the corresponding serialized ISO sample 4830 */ 4831 GF_ISOSample *gf_isom_xml_subtitle_to_sample(GF_GenericSubtitleSample *subt_samp); 4832 /*! appends text to an XML subtitle sample 4833 \param subt_samp the target XML subtitle sample 4834 \param text_data the UTF-8 or UTF-16 data to add 4835 \param text_len the size of the text to add in bytes 4836 \return error if any 4837 */ 4838 GF_Err gf_isom_xml_subtitle_sample_add_text(GF_GenericSubtitleSample *subt_samp, char *text_data, u32 text_len); 4839 4840 #endif /*GPAC_DISABLE_ISOM_WRITE*/ 4841 4842 /*! @} */ 4843 4844 4845 /*! 4846 \addtogroup isocrypt_grp Content Protection 4847 \ingroup iso_grp 4848 4849 @{ 4850 */ 4851 4852 /*! DRM related code points*/ 4853 enum 4854 { 4855 /*! Storage location of CENC sample auxiliary in PSEC UUID box*/ 4856 GF_ISOM_BOX_UUID_PSEC = GF_4CC( 'P', 'S', 'E', 'C' ), 4857 /*! Storage location of CENC sample auxiliary in senc box*/ 4858 GF_ISOM_BOX_TYPE_SENC = GF_4CC( 's', 'e', 'n', 'c'), 4859 /*! PSSH box type */ 4860 GF_ISOM_BOX_TYPE_PSSH = GF_4CC( 'p', 's', 's', 'h'), 4861 /*! ISMA Encryption Scheme Type in the SchemeTypeInfoBox */ 4862 GF_ISOM_ISMACRYP_SCHEME = GF_4CC( 'i', 'A', 'E', 'C' ), 4863 /*! OMA DRM Encryption Scheme Type in the SchemeTypeInfoBox */ 4864 GF_ISOM_OMADRM_SCHEME = GF_4CC('o','d','k','m'), 4865 /*! CENC AES-CTR Encryption Scheme Type in the SchemeTypeInfoBox */ 4866 GF_ISOM_CENC_SCHEME = GF_4CC('c','e','n','c'), 4867 /*! CENC AES-CBC Encryption Scheme Type in the SchemeTypeInfoBox */ 4868 GF_ISOM_CBC_SCHEME = GF_4CC('c','b','c','1'), 4869 /*! Adobe Encryption Scheme Type in the SchemeTypeInfoBox */ 4870 GF_ISOM_ADOBE_SCHEME = GF_4CC('a','d','k','m'), 4871 /*! CENC AES-CTR Pattern Encryption Scheme Type in the SchemeTypeInfoBox */ 4872 GF_ISOM_CENS_SCHEME = GF_4CC('c','e','n','s'), 4873 /*! CENC AES-CBC Pattern Encryption Scheme Type in the SchemeTypeInfoBox */ 4874 GF_ISOM_CBCS_SCHEME = GF_4CC('c','b','c','s'), 4875 /*! PIFF Scheme Type in the SchemeTypeInfoBox */ 4876 GF_ISOM_PIFF_SCHEME = GF_4CC('p','i','f','f'), 4877 }; 4878 4879 /*! checks if a track is encrypted or protected 4880 \param isom_file the target ISO file 4881 \param trackNumber the target track 4882 \return GF_TRUE if track is protected, GF_FALSE otherwise*/ 4883 Bool gf_isom_is_track_encrypted(GF_ISOFile *isom_file, u32 trackNumber); 4884 4885 4886 /*! flags for GF_ISMASample*/ 4887 typedef enum 4888 { 4889 /*! signals the stream the sample belongs to uses selective encryption*/ 4890 GF_ISOM_ISMA_USE_SEL_ENC = 1, 4891 /*! signals the sample is encrypted*/ 4892 GF_ISOM_ISMA_IS_ENCRYPTED = 2, 4893 } GF_ISOISMACrypFlags; 4894 4895 /*! ISMA sample*/ 4896 typedef struct 4897 { 4898 /*! IV in ISMACryp is Byte Stream Offset*/ 4899 u64 IV; 4900 /*! IV size in bytes, repeated from sampleDesc for convenience*/ 4901 u8 IV_length; 4902 /*! key indicator*/ 4903 u8 *key_indicator; 4904 /*! key indicator size, repeated from sampleDesc for convenience*/ 4905 u8 KI_length; 4906 /*! payload size*/ 4907 u32 dataLength; 4908 /*! payload*/ 4909 u8 *data; 4910 /*! flags*/ 4911 u32 flags; 4912 } GF_ISMASample; 4913 /*! creates a new empty ISMA sample 4914 \return a new empty ISMA sample 4915 */ 4916 GF_ISMASample *gf_isom_ismacryp_new_sample(); 4917 4918 /*! delete an ISMA sample. 4919 \note the buffer content will be destroyed by default. If you wish to keep the buffer, set dataLength to 0 in the sample before deleting it 4920 \param samp the target ISMA sample 4921 */ 4922 void gf_isom_ismacryp_delete_sample(GF_ISMASample *samp); 4923 4924 /*! decodes ISMACryp sample based on all info in ISMACryp sample description 4925 \param data sample data 4926 \param dataLength sample data size in bytes 4927 \param use_selective_encryption set to GF_TRUE if sample uses selective encryption 4928 \param KI_length set to the size in bytes of the key indicator - 0 means no key roll 4929 \param IV_length set to the size in bytes of the initialization vector 4930 \return a newly allocated ISMA sample with the parsed data 4931 */ 4932 GF_ISMASample *gf_isom_ismacryp_sample_from_data(u8 *data, u32 dataLength, Bool use_selective_encryption, u8 KI_length, u8 IV_length); 4933 /*! rewrites ISMA sample as an ISO sample 4934 \param s the ISMA sample to rewrite 4935 \param dest the destination ISO sample 4936 \return error if any 4937 */ 4938 GF_Err gf_isom_ismacryp_sample_to_sample(const GF_ISMASample *s, GF_ISOSample *dest); 4939 4940 /*! decodes ISMACryp sample based on sample and its descrition index 4941 \param isom_file the target ISO file 4942 \param trackNumber the target track 4943 \param samp the sample to decode 4944 \param sampleDescriptionIndex the sample description index of the sample to decode 4945 \return the ISMA sample or NULL if not an ISMA sample or error 4946 */ 4947 GF_ISMASample *gf_isom_get_ismacryp_sample(GF_ISOFile *isom_file, u32 trackNumber, const GF_ISOSample *samp, u32 sampleDescriptionIndex); 4948 4949 /*! checks if sample description is protected or not 4950 \param isom_file the target ISO file 4951 \param trackNumber the target track 4952 \param sampleDescriptionIndex the sample description index. If 0, checks all sample descriptions for protected ones 4953 \return scheme protection 4CC or 0 if not protected*/ 4954 u32 gf_isom_is_media_encrypted(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 4955 4956 /*! checks if sample description is protected with ISMACryp 4957 \param isom_file the target ISO file 4958 \param trackNumber the target track 4959 \param sampleDescriptionIndex the sample description index 4960 \return GF_TRUE if ISMA protection is used*/ 4961 Bool gf_isom_is_ismacryp_media(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 4962 4963 /*! checks if sample description is protected with OMA DRM 4964 \param isom_file the target ISO file 4965 \param trackNumber the target track 4966 \param sampleDescriptionIndex the sample description index 4967 \return GF_TRUE if OMA DRM protection is used*/ 4968 Bool gf_isom_is_omadrm_media(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 4969 4970 /*! gets OMA DRM configuration - all output parameters are optional and may be NULL 4971 \param isom_file the target ISO file 4972 \param trackNumber the target track 4973 \param sampleDescriptionIndex the sample description index 4974 \param outOriginalFormat four character code of the unprotected sample description 4975 \param outSchemeType set to four character code of the protection scheme type 4976 \param outSchemeVersion set to scheme protection version 4977 \param outContentID set to associated ID of content 4978 \param outRightsIssuerURL set to the rights issuer (license server) URL 4979 \param outTextualHeaders set to OMA textual headers 4980 \param outTextualHeadersLen set to the size in bytes of OMA textual headers 4981 \param outPlaintextLength set to the size in bytes of clear data in file 4982 \param outEncryptionType set to the OMA encryption type used 4983 \param outSelectiveEncryption set to GF_TRUE if sample description uses selective encryption 4984 \param outIVLength set to the size of the initialization vector 4985 \param outKeyIndicationLength set to the size of the key indicator 4986 \return error if any 4987 */ 4988 GF_Err gf_isom_get_omadrm_info(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 *outOriginalFormat, 4989 u32 *outSchemeType, u32 *outSchemeVersion, 4990 const char **outContentID, const char **outRightsIssuerURL, const char **outTextualHeaders, u32 *outTextualHeadersLen, u64 *outPlaintextLength, u32 *outEncryptionType, Bool *outSelectiveEncryption, u32 *outIVLength, u32 *outKeyIndicationLength); 4991 4992 /*! retrieves ISMACryp info for the given track & SDI - all output parameters are optional - URIs SHALL NOT BE MODIFIED BY USER 4993 4994 \note outSelectiveEncryption, outIVLength and outKeyIndicationLength are usually not needed to decode an ISMA sample when using \ref gf_isom_get_ismacryp_sample 4995 4996 \param isom_file the target ISO file 4997 \param trackNumber the target track 4998 \param sampleDescriptionIndex the sample description index 4999 \param outOriginalFormat set to orginal unprotected media format 5000 \param outSchemeType set to 4CC of protection scheme (GF_ISOM_ISMACRYP_SCHEME = iAEC in ISMACryp 1.0) 5001 \param outSchemeVersion set to version of protection scheme (1 in ISMACryp 1.0) 5002 \param outSchemeURI set to URI location of scheme 5003 \param outKMS_URI set to URI location of key management system - only valid with ISMACryp 1.0 5004 \param outSelectiveEncryption set to whether sample-based encryption is used in media - only valid with ISMACryp 1.0 5005 \param outIVLength set to length of Initial Vector - only valid with ISMACryp 1.0 5006 \param outKeyIndicationLength set to length of key indicator - only valid with ISMACryp 1.0 5007 \return error if any 5008 */ 5009 GF_Err gf_isom_get_ismacryp_info(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 *outOriginalFormat, u32 *outSchemeType, u32 *outSchemeVersion, const char **outSchemeURI, const char **outKMS_URI, Bool *outSelectiveEncryption, u32 *outIVLength, u32 *outKeyIndicationLength); 5010 5011 /*! gets original format four character code type of a protected media sample description 5012 \param isom_file the target ISO file 5013 \param trackNumber the target track 5014 \param sampleDescriptionIndex the sample description index. If 0, checks all sample descriptions for a protected one 5015 \param outOriginalFormat set to orginal unprotected media format 5016 \return error if any 5017 */ 5018 GF_Err gf_isom_get_original_format_type(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 *outOriginalFormat); 5019 5020 /*! CENC subsample entry*/ 5021 typedef struct 5022 { 5023 /*! size of bytes in clear - 16 bit stored but we use 32*/ 5024 u32 bytes_clear_data; 5025 /*! size of bytes encrypted*/ 5026 u32 bytes_encrypted_data; 5027 } GF_CENCSubSampleEntry; 5028 5029 /*! CENC auxiliary info*/ 5030 typedef struct __cenc_sample_aux_info 5031 { 5032 /*! IV size: 0, 8 or 16; it MUST NOT be written to file*/ 5033 u8 IV_size; 5034 /*! IV can be 0, 64 or 128 bits - if 64, bytes 0-7 are used and 8-15 are 0-padded*/ 5035 bin128 IV; 5036 /*! number of subsamples*/ 5037 u16 subsample_count; 5038 /*! subsamples*/ 5039 GF_CENCSubSampleEntry *subsamples; 5040 } GF_CENCSampleAuxInfo; 5041 5042 #ifndef GPAC_DISABLE_ISOM_WRITE 5043 /*! removes protection info (does not perform decryption), for ISMA, OMA and CENC of a sample description 5044 \param isom_file the target ISO file 5045 \param trackNumber the target track 5046 \param sampleDescriptionIndex the sample description index 5047 \return error if any 5048 */ 5049 GF_Err gf_isom_remove_track_protection(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 5050 5051 /*! creates ISMACryp protection info for a sample description 5052 \param isom_file the target ISO file 5053 \param trackNumber the target track 5054 \param sampleDescriptionIndex the sample description index 5055 \param scheme_type 4CC of protection scheme (GF_ISOM_ISMACRYP_SCHEME = iAEC in ISMACryp 1.0) 5056 \param scheme_version version of protection scheme (1 in ISMACryp 1.0) 5057 \param scheme_uri URI location of scheme 5058 \param kms_URI URI location of key management system - only valid with ISMACryp 1.0 5059 \param selective_encryption whether sample-based encryption is used in media - only valid with ISMACryp 1.0 5060 \param KI_length length of key indicator - only valid with ISMACryp 1.0 5061 \param IV_length length of Initial Vector - only valid with ISMACryp 1.0 5062 \return error if any 5063 */ 5064 GF_Err gf_isom_set_ismacryp_protection(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 scheme_type, 5065 u32 scheme_version, char *scheme_uri, char *kms_URI, 5066 Bool selective_encryption, u32 KI_length, u32 IV_length); 5067 5068 /*! changes scheme URI and/or KMS URI for crypted files. Other params cannot be changed once the media is crypted 5069 \param isom_file the target ISO file 5070 \param trackNumber the target track 5071 \param sampleDescriptionIndex the sample description index 5072 \param scheme_uri new scheme URI, or NULL to keep previous 5073 \param kms_uri new KMS URI, or NULL to keep previous 5074 \return error if any 5075 */ 5076 GF_Err gf_isom_change_ismacryp_protection(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, char *scheme_uri, char *kms_uri); 5077 5078 5079 /*! creates OMA DRM protection for a sample description 5080 \param isom_file the target ISO file 5081 \param trackNumber the target track 5082 \param sampleDescriptionIndex the sample description index 5083 \param contentID associated ID of content 5084 \param kms_URI the rights issuer (license server) URL 5085 \param encryption_type the OMA encryption type used 5086 \param plainTextLength the size in bytes of clear data in file 5087 \param textual_headers OMA textual headers 5088 \param textual_headers_len the size in bytes of OMA textual headers 5089 \param selective_encryption GF_TRUE if sample description uses selective encryption 5090 \param KI_length the size of the key indicator 5091 \param IV_length the size of the initialization vector 5092 \return error if any 5093 */ 5094 GF_Err gf_isom_set_oma_protection(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, 5095 char *contentID, char *kms_URI, u32 encryption_type, u64 plainTextLength, char *textual_headers, u32 textual_headers_len, 5096 Bool selective_encryption, u32 KI_length, u32 IV_length); 5097 5098 /*! creates a generic protection for a sample description 5099 \param isom_file the target ISO file 5100 \param trackNumber the target track 5101 \param sampleDescriptionIndex the sample description index 5102 \param scheme_type 4CC of protection scheme (GF_ISOM_ISMACRYP_SCHEME = iAEC in ISMACryp 1.0) 5103 \param scheme_version version of protection scheme (1 in ISMACryp 1.0) 5104 \param scheme_uri URI location of scheme 5105 \param kms_URI the rights issuer (license server) URL 5106 \return error if any 5107 */ 5108 GF_Err gf_isom_set_generic_protection(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 scheme_type, u32 scheme_version, char *scheme_uri, char *kms_URI); 5109 5110 /*! allocates storage for CENC side data in a senc or UUID box 5111 \param isom_file the target ISO file 5112 \param trackNumber the target track 5113 \param container_type the code of the container (currently 'senc' for CENC or 'PSEC' for smooth) 5114 \param AlgorithmID algorith ID, usually 0 5115 \param IV_size the size of the init vector 5116 \param KID the default Key ID 5117 \return error if any 5118 */ 5119 GF_Err gf_isom_cenc_allocate_storage(GF_ISOFile *isom_file, u32 trackNumber, u32 container_type, u32 AlgorithmID, u8 IV_size, bin128 KID); 5120 5121 /*! adds cenc SAI for the last sample added to a track 5122 \param isom_file the target ISO file 5123 \param trackNumber the target track 5124 \param container_type the code of the container (currently 'senc' for CENC or 'PSEC' for smooth) 5125 \param IV_size the size of the init vector 5126 \param buf the SAI buffer 5127 \param len the size of the SAI buffer. If buf is NULL but len is given, this adds an unencrypted entry. otherwise, buf && len represent the sai cenc info to add 5128 \param use_subsamples if GF_TRUE, the media format uses CENC subsamples 5129 \param clear_IV the IV used for clear samples (when buf is null) 5130 \param use_saio_32bit forces usage of 32-bit saio boxes 5131 \return error if any 5132 */ 5133 GF_Err gf_isom_track_cenc_add_sample_info(GF_ISOFile *isom_file, u32 trackNumber, u32 container_type, u8 IV_size, u8 *buf, u32 len, Bool use_subsamples, u8 *clear_IV, Bool use_saio_32bit); 5134 5135 5136 5137 /*! creates CENC protection for a sample description 5138 \param isom_file the target ISO file 5139 \param trackNumber the target track 5140 \param sampleDescriptionIndex the sample description index 5141 \param scheme_type 4CC of protection scheme (GF_ISOM_ISMACRYP_SCHEME = iAEC in ISMACryp 1.0) 5142 \param scheme_version version of protection scheme (1 in ISMACryp 1.0) 5143 \param default_IsEncrypted default isEncrypted flag 5144 \param default_IV_size default IV size flag 5145 \param default_KID default key ID used 5146 \param default_crypt_byte_block default crypt block size for pattern encryption 5147 \param default_skip_byte_block default skip block size for pattern encryption 5148 \param default_constant_IV_size default constant IV size 5149 \param default_constant_IV default constant IV 5150 \return error if any 5151 */ 5152 GF_Err gf_isom_set_cenc_protection(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 scheme_type, 5153 u32 scheme_version, u32 default_IsEncrypted, u8 default_IV_size, bin128 default_KID, 5154 u8 default_crypt_byte_block, u8 default_skip_byte_block, 5155 u8 default_constant_IV_size, bin128 default_constant_IV); 5156 /*! adds PSSH info for a file, can be called several time per system ID 5157 \param isom_file the target ISO file 5158 \param systemID the ID of the protection system 5159 \param version the version of the protection system 5160 \param KID_count the number of key IDs 5161 \param KID the list of key IDs 5162 \param data opaque data for the protection system 5163 \param len size of the opaque data 5164 \param use_piff if GF_TRUE, use PIFF pssh UUID box when creating the pssh 5165 \return error if any 5166 */ 5167 GF_Err gf_cenc_set_pssh(GF_ISOFile *isom_file, bin128 systemID, u32 version, u32 KID_count, bin128 *KID, u8 *data, u32 len, Bool use_piff); 5168 5169 /*! removes CENC SAI size info 5170 \param isom_file the target ISO file 5171 \param trackNumber the target track 5172 \return error if any 5173 */ 5174 GF_Err gf_isom_remove_cenc_saiz(GF_ISOFile *isom_file, u32 trackNumber); 5175 /*! removes CENC SAI offset info 5176 \param isom_file the target ISO file 5177 \param trackNumber the target track 5178 \return error if any 5179 */ 5180 GF_Err gf_isom_remove_cenc_saio(GF_ISOFile *isom_file, u32 trackNumber); 5181 /*! removes CENC senc box info 5182 \param isom_file the target ISO file 5183 \param trackNumber the target track 5184 \return error if any 5185 */ 5186 GF_Err gf_isom_remove_samp_enc_box(GF_ISOFile *isom_file, u32 trackNumber); 5187 /*! removes all CENC sample groups 5188 \param isom_file the target ISO file 5189 \param trackNumber the target track 5190 \return error if any 5191 */ 5192 GF_Err gf_isom_remove_samp_group_box(GF_ISOFile *isom_file, u32 trackNumber); 5193 /*! removes CENC PSSH box 5194 \param isom_file the target ISO file 5195 \return error if any 5196 */ 5197 GF_Err gf_isom_remove_pssh_box(GF_ISOFile *isom_file); 5198 5199 #endif //GPAC_DISABLE_ISOM_WRITE 5200 5201 /*! checks if sample description is protected with Adobe systems 5202 \param isom_file the target ISO file 5203 \param trackNumber the target track 5204 \param sampleDescriptionIndex the sample description index 5205 \return GF_TRUE if ADOBE protection is used 5206 */ 5207 Bool gf_isom_is_adobe_protection_media(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 5208 5209 /*! gets adobe protection information for a sample description 5210 \param isom_file the target ISO file 5211 \param trackNumber the target track 5212 \param sampleDescriptionIndex the sample description index 5213 \param outOriginalFormat set to orginal unprotected media format 5214 \param outSchemeType set to 4CC of protection scheme (GF_ISOM_ISMACRYP_SCHEME = iAEC in ISMACryp 1.0) 5215 \param outSchemeVersion set to version of protection scheme (1 in ISMACryp 1.0) 5216 \param outMetadata set to adobe metadata string 5217 \return GF_TRUE if ADOBE protection is used 5218 */ 5219 GF_Err gf_isom_get_adobe_protection_info(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 *outOriginalFormat, u32 *outSchemeType, u32 *outSchemeVersion, const char **outMetadata); 5220 5221 #ifndef GPAC_DISABLE_ISOM_WRITE 5222 /*! creates an adobe protection for a sample description 5223 \param isom_file the target ISO file 5224 \param trackNumber the target track 5225 \param sampleDescriptionIndex the sample description index 5226 \param scheme_type 4CC of protection scheme (GF_ISOM_ISMACRYP_SCHEME = iAEC in ISMACryp 1.0) 5227 \param scheme_version version of protection scheme (1 in ISMACryp 1.0) 5228 \param is_selective_enc indicates if selective encryption is used 5229 \param metadata metadata information 5230 \param len size of metadata information in bytes 5231 \return error if any 5232 */ 5233 GF_Err gf_isom_set_adobe_protection(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 scheme_type, u32 scheme_version, Bool is_selective_enc, char *metadata, u32 len); 5234 5235 /*! removes the IPMPX tools from files 5236 \param isom_file the target ISO file 5237 */ 5238 void gf_isom_ipmpx_remove_tool_list(GF_ISOFile *isom_file); 5239 5240 #endif /*GPAC_DISABLE_ISOM_WRITE*/ 5241 5242 /*! checks of sample description is protected with CENC 5243 \param isom_file the target ISO file 5244 \param trackNumber the target track 5245 \param sampleDescriptionIndex the sample description index. If 0, checks all sample descriptions for protected ones 5246 \return GF_TRUE if sample protection is CENC 5247 */ 5248 Bool gf_isom_is_cenc_media(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 5249 /*! gets CENC information of a sample description 5250 \param isom_file the target ISO file 5251 \param trackNumber the target track 5252 \param sampleDescriptionIndex the sample description index 5253 \param outOriginalFormat set to orginal unprotected media format 5254 \param outSchemeType set to 4CC of protection scheme (GF_ISOM_ISMACRYP_SCHEME = iAEC in ISMACryp 1.0) 5255 \param outSchemeVersion set to version of protection scheme (1 in ISMACryp 1.0) 5256 \param outIVLength set to the IV size in bytes 5257 \return error if any 5258 */ 5259 GF_Err gf_isom_get_cenc_info(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 *outOriginalFormat, u32 *outSchemeType, u32 *outSchemeVersion, u32 *outIVLength); 5260 5261 /*! destroys a CENC sample auxiliary structure 5262 \param samp_aux_info the target auxiliary buffer 5263 */ 5264 void gf_isom_cenc_samp_aux_info_del(GF_CENCSampleAuxInfo *samp_aux_info); 5265 5266 /*! gets CENC auxiliary info of a sample 5267 \param isom_file the target ISO file 5268 \param trackNumber the target track 5269 \param sampleNumber the target sample 5270 \param sampleDescIndex the target sample description index 5271 \param sai set to the auxiliary info - shall be freeed by caller 5272 \param container_type set to type of box which contains the sample auxiliary information. Now we have two type: GF_ISOM_BOX_UUID_PSEC and GF_ISOM_BOX_TYPE_SENC 5273 \return error if any 5274 */ 5275 GF_Err gf_isom_cenc_get_sample_aux_info(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber, u32 sampleDescIndex, GF_CENCSampleAuxInfo **sai, u32 *container_type); 5276 5277 /*! gets CENC auxiliary info of a sample as a buffer 5278 \note the serialized buffer format is IV on IV_size bytes, then subsample count if any an [clear_bytes(u16), crypt_bytes(u32)] subsamples 5279 5280 \param isom_file the target ISO file 5281 \param trackNumber the target track 5282 \param sampleNumber the target sample 5283 \param sampleDescIndex the sample description index 5284 \param container_type is type of box which contains the sample auxiliary information. Now we have two type: GF_ISOM_BOX_UUID_PSEC and GF_ISOM_BOX_TYPE_SENC 5285 \param out_buffer set to a newly allocated buffer, or reallocated buffer if not NULL 5286 \param outSize set to the size of the serialized buffer. If an existing buffer was passed, the passed value shall be the allocated buffer size (the returned value is still the buffer size) 5287 \return error if any 5288 */ 5289 GF_Err gf_isom_cenc_get_sample_aux_info_buffer(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber, u32 sampleDescIndex, u32 *container_type, u8 **out_buffer, u32 *outSize); 5290 5291 /*! gets CENC default info for a sample description 5292 \param isom_file the target ISO file 5293 \param trackNumber the target track 5294 \param sampleDescriptionIndex the sample description index 5295 \param container_type set to the container type of SAI data 5296 \param default_IsEncrypted set to default isEncrypted flag 5297 \param default_IV_size set to default IV size flag 5298 \param default_KID set to default key ID used 5299 \param constant_IV_size set to default constant IV size 5300 \param constant_IV set to default constant IV 5301 \param crypt_byte_block set to default crypt block size for pattern encryption 5302 \param skip_byte_block set to default skip block size for pattern encryption 5303 */ 5304 void gf_isom_cenc_get_default_info(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex, u32 *container_type, Bool *default_IsEncrypted, u8 *default_IV_size, bin128 *default_KID, u8 *constant_IV_size, bin128 *constant_IV, u8 *crypt_byte_block, u8 *skip_byte_block); 5305 5306 5307 /*! checks if CENC protection uses pattern encryption 5308 \param isom_file the target ISO file 5309 \param trackNumber the target track 5310 \param sampleDescriptionIndex the sample description index 5311 \return GF_TRUE if protection uses pattern encryption 5312 */ 5313 Bool gf_isom_cenc_is_pattern_mode(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleDescriptionIndex); 5314 /*! gets the number of PSSH defined 5315 \param isom_file the target ISO file 5316 \return number of PSSH defined 5317 */ 5318 u32 gf_isom_get_pssh_count(GF_ISOFile *isom_file); 5319 5320 /*! gets PSS info 5321 \param isom_file the target ISO file 5322 \param pssh_index 1-based index of PSSH to query, see \ref gf_isom_get_pssh_count 5323 \param SystemID set to the protection system ID 5324 \param version set to the protection system version 5325 \param KID_count set to the number of key IDs defined 5326 \param KIDs array of defined key IDs 5327 \param private_data set to a buffer containing system ID private data 5328 \param private_data_size set to the size of the system ID private data 5329 \return error if any 5330 */ 5331 GF_Err gf_isom_get_pssh_info(GF_ISOFile *isom_file, u32 pssh_index, bin128 SystemID, u32 *version, u32 *KID_count, const bin128 **KIDs, const u8 **private_data, u32 *private_data_size); 5332 5333 /*! gets serialized PSS 5334 \param isom_file the target ISO file 5335 \param pssh_index 1-based index of PSSH to query, see \ref gf_isom_get_pssh_count 5336 \param pssh_data set to a newly allocated buffer containing serialized PSSH - shall be freeed by caller 5337 \param pssh_size set to the size of the allocated buffer 5338 \return error if any 5339 */ 5340 GF_Err gf_isom_get_pssh(GF_ISOFile *isom_file, u32 pssh_index, u8 **pssh_data, u32 *pssh_size); 5341 5342 5343 #ifndef GPAC_DISABLE_ISOM_DUMP 5344 /*! dumps ismacrypt protection of sample descriptions to xml trace 5345 \param isom_file the target ISO file 5346 \param trackNumber the target track 5347 \param trace the file object to dump to 5348 \return error if any 5349 */ 5350 GF_Err gf_isom_dump_ismacryp_protection(GF_ISOFile *isom_file, u32 trackNumber, FILE * trace); 5351 /*! dumps ismacrypt sample to xml trace 5352 \param isom_file the target ISO file 5353 \param trackNumber the target track 5354 \param SampleNum the target sample number 5355 \param trace the file object to dump to 5356 \return error if any 5357 */ 5358 GF_Err gf_isom_dump_ismacryp_sample(GF_ISOFile *isom_file, u32 trackNumber, u32 SampleNum, FILE *trace); 5359 #endif 5360 5361 /*! gets CENC configuration for a given sample 5362 \param isom_file the target ISO file 5363 \param trackNumber the target track 5364 \param sampleNumber the target sample number 5365 \param IsEncrypted set to GF_TRUE if the sample is encrypted, GF_FALSE otherwise (optional can be NULL) 5366 \param IV_size set to IV size in bytes used for the sample (optional can be NULL) 5367 \param KID set to key ID used for the sample (optional can be NULL) 5368 \param crypt_byte_block set to crypt block count for pattern encryption (optional can be NULL) 5369 \param skip_byte_block set to skip block count for pattern encryption (optional can be NULL) 5370 \param constant_IV_size set to constant IV size (optional can be NULL) 5371 \param constant_IV set to constant IV (optional can be NULL) 5372 \return error if any 5373 */ 5374 GF_Err gf_isom_get_sample_cenc_info(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber, Bool *IsEncrypted, u8 *IV_size, bin128 *KID, u8 *crypt_byte_block, u8 *skip_byte_block, u8 *constant_IV_size, bin128 *constant_IV); 5375 5376 5377 /*! @} */ 5378 5379 /*! 5380 \addtogroup isometa_grp Meta and Image File Format 5381 \ingroup iso_grp 5382 5383 @{ 5384 */ 5385 5386 5387 /*! gets meta type 5388 \param isom_file the target ISO file 5389 \param root_meta if GF_TRUE uses meta at the file, otherwise uses meta at the movie level if track number is 0 5390 \param track_num if GF_TRUE and root_meta is GF_FALSE, uses meta at the track level 5391 \return 0 if no meta found, or four char code of meta (eg, "mp21", "smil", ...)*/ 5392 u32 gf_isom_get_meta_type(GF_ISOFile *isom_file, Bool root_meta, u32 track_num); 5393 5394 /*! checks if the meta has an XML container (note that XML data can also be included as items). 5395 \param isom_file the target ISO file 5396 \param root_meta if GF_TRUE uses meta at the file, otherwise uses meta at the movie level if track number is 0 5397 \param track_num if GF_TRUE and root_meta is GF_FALSE, uses meta at the track level 5398 \return 0 (no XML or error), 1 (XML text), 2 (BinaryXML, eg BiM) */ 5399 u32 gf_isom_has_meta_xml(GF_ISOFile *isom_file, Bool root_meta, u32 track_num); 5400 5401 /*! extracts XML (if any) from given meta 5402 \param isom_file the target ISO file 5403 \param root_meta if GF_TRUE uses meta at the file, otherwise uses meta at the movie level if track number is 0 5404 \param track_num if GF_TRUE and root_meta is GF_FALSE, uses meta at the track level 5405 \param outName output file path and location for writing 5406 \param is_binary indicates if XML is Bim or regular XML 5407 \return error if any 5408 */ 5409 GF_Err gf_isom_extract_meta_xml(GF_ISOFile *isom_file, Bool root_meta, u32 track_num, char *outName, Bool *is_binary); 5410 5411 /*! checks the number of items in a meta 5412 \param isom_file the target ISO file 5413 \param root_meta if GF_TRUE uses meta at the file, otherwise uses meta at the movie level if track number is 0 5414 \param track_num if GF_TRUE and root_meta is GF_FALSE, uses meta at the track level 5415 \return number of items*/ 5416 u32 gf_isom_get_meta_item_count(GF_ISOFile *isom_file, Bool root_meta, u32 track_num); 5417 5418 /*! gets item info for the given item 5419 \note When an item is fully contained in file, both item_url and item_urn are set to NULL 5420 5421 \param isom_file the target ISO file 5422 \param root_meta if GF_TRUE uses meta at the file, otherwise uses meta at the movie level if track number is 0 5423 \param track_num if GF_TRUE and root_meta is GF_FALSE, uses meta at the track level 5424 \param item_num 1-based index of item to query 5425 \param itemID set to item ID in file (optional, can be NULL) 5426 \param type set to item 4CC type 5427 \param protection_idx set to the 1-based index of the protection in used, 0 if not protected 5428 \param is_self_reference set to item is the file itself 5429 \param item_name set to the item name (optional, can be NULL) 5430 \param item_mime_type set to the item mime type (optional, can be NULL) 5431 \param item_encoding set to the item content encoding type (optional, can be NULL) 5432 \param item_url set to the URL of external resource containing this item data if any. 5433 \param item_urn set to the URN of external resource containing this item data if any. 5434 \return error if any 5435 */ 5436 GF_Err gf_isom_get_meta_item_info(GF_ISOFile *isom_file, Bool root_meta, u32 track_num, u32 item_num, 5437 u32 *itemID, u32 *type, u32 *protection_idx, Bool *is_self_reference, 5438 const char **item_name, const char **item_mime_type, const char **item_encoding, 5439 const char **item_url, const char **item_urn); 5440 5441 5442 /*! gets item index from item ID 5443 \param isom_file the target ISO file 5444 \param root_meta if GF_TRUE uses meta at the file, otherwise uses meta at the movie level if track number is 0 5445 \param track_num if GF_TRUE and root_meta is GF_FALSE, uses meta at the track level 5446 \param item_ID ID of the item to search 5447 \return item index if found, 0 otherwise 5448 */ 5449 u32 gf_isom_get_meta_item_by_id(GF_ISOFile *isom_file, Bool root_meta, u32 track_num, u32 item_ID); 5450 5451 /*! extracts an item from given meta 5452 \param isom_file the target ISO file 5453 \param root_meta if GF_TRUE uses meta at the file, otherwise uses meta at the movie level if track number is 0 5454 \param track_num if GF_TRUE and root_meta is GF_FALSE, uses meta at the track level 5455 \param item_num 1-based index of item to query 5456 \param dump_file_name if NULL, uses item name for dumping, otherwise dumps in given file object (binary write mode) 5457 \return error if any 5458 */ 5459 GF_Err gf_isom_extract_meta_item(GF_ISOFile *isom_file, Bool root_meta, u32 track_num, u32 item_num, const char *dump_file_name); 5460 5461 /*! extracts item from given meta in memory 5462 \param isom_file the target ISO file 5463 \param root_meta if GF_TRUE uses meta at the file, otherwise uses meta at the movie level if track number is 0 5464 \param track_num if GF_TRUE and root_meta is GF_FALSE, uses meta at the track level 5465 \param item_id the ID of the item to dump 5466 \param out_data set to allocated buffer containing the item, shall be freeed by user 5467 \param out_size set to the size of the allocated buffer 5468 \param out_alloc_size set to the allocated size of the buffer (this allows passing an existing buffer without always reallocating it) 5469 \param mime_type set to the mime type of the item 5470 \param use_annex_b for image items based on NALU formats (AVC, HEVC) indicates to extract the data as Annex B format (with start codes) 5471 \return error if any 5472 */ 5473 GF_Err gf_isom_extract_meta_item_mem(GF_ISOFile *isom_file, Bool root_meta, u32 track_num, u32 item_id, u8 **out_data, u32 *out_size, u32 *out_alloc_size, const char **mime_type, Bool use_annex_b); 5474 5475 /*! gets primary item ID 5476 \param isom_file the target ISO file 5477 \param root_meta if GF_TRUE uses meta at the file, otherwise uses meta at the movie level if track number is 0 5478 \param track_num if GF_TRUE and root_meta is GF_FALSE, uses meta at the track level 5479 \return primary item ID, 0 if none found (primary can also be stored through meta XML)*/ 5480 u32 gf_isom_get_meta_primary_item_id(GF_ISOFile *isom_file, Bool root_meta, u32 track_num); 5481 5482 /*! item tile mode*/ 5483 typedef enum { 5484 /*! not a tile item*/ 5485 TILE_ITEM_NONE = 0, 5486 /*! a tile item without base*/ 5487 TILE_ITEM_ALL_NO_BASE, 5488 /*! a tile item with base*/ 5489 TILE_ITEM_ALL_BASE, 5490 /*! a tile item grid*/ 5491 TILE_ITEM_ALL_GRID, 5492 /*! a tile item single*/ 5493 TILE_ITEM_SINGLE 5494 } GF_TileItemMode; 5495 5496 /*! Image item properties*/ 5497 typedef struct 5498 { 5499 /*! width in pixels*/ 5500 u32 width; 5501 /*! height in pixless*/ 5502 u32 height; 5503 /*! pixel aspect ratio numerator*/ 5504 u32 hSpacing; 5505 /*! pixel aspect ratio denominator*/ 5506 u32 vSpacing; 5507 /*! horizontal offset in pixels*/ 5508 u32 hOffset; 5509 /*! vertical offset in pixels*/ 5510 u32 vOffset; 5511 /*! angle in radians*/ 5512 u32 angle; 5513 /*! hidden flag*/ 5514 Bool hidden; 5515 /*! pointer to configuration box*/ 5516 void *config; 5517 /*! tile item mode*/ 5518 GF_TileItemMode tile_mode; 5519 /*! tile number */ 5520 u32 single_tile_number; 5521 /*! time for importing*/ 5522 double time; 5523 /*! file containg iCC data for importing*/ 5524 char iccPath[GF_MAX_PATH]; 5525 /*! is alpha*/ 5526 Bool alpha; 5527 /*! number of channels*/ 5528 u8 num_channels; 5529 /*! bits per channels in bits*/ 5530 u8 bits_per_channel[3]; 5531 } GF_ImageItemProperties; 5532 5533 5534 #ifndef GPAC_DISABLE_ISOM_WRITE 5535 5536 /*! sets meta type (four char int, eg "mp21", ...), creating a meta box if not found 5537 \param isom_file the target ISO file 5538 \param root_meta if GF_TRUE uses meta at the file, otherwise uses meta at the movie level if track number is 0 5539 \param track_num if GF_TRUE and root_meta is GF_FALSE, uses meta at the track level 5540 \param metaType the type of meta to create. If 0, removes the meta box 5541 \return error if any 5542 */ 5543 GF_Err gf_isom_set_meta_type(GF_ISOFile *isom_file, Bool root_meta, u32 track_num, u32 metaType); 5544 5545 /*! removes meta XML info if any 5546 \param isom_file the target ISO file 5547 \param root_meta if GF_TRUE uses meta at the file, otherwise uses meta at the movie level if track number is 0 5548 \param track_num if GF_TRUE and root_meta is GF_FALSE, uses meta at the track level 5549 \return error if any 5550 */ 5551 GF_Err gf_isom_remove_meta_xml(GF_ISOFile *isom_file, Bool root_meta, u32 track_num); 5552 5553 /*! sets meta XML data from file - erase any previously (Binary)XML info 5554 \param isom_file the target ISO file 5555 \param root_meta if GF_TRUE uses meta at the file, otherwise uses meta at the movie level if track number is 0 5556 \param track_num if GF_TRUE and root_meta is GF_FALSE, uses meta at the track level 5557 \param XMLFileName the XML file to import as XML item 5558 \param IsBinaryXML indicates if the content of the XML file is binary XML (BIM) or not 5559 \return error if any 5560 */ 5561 GF_Err gf_isom_set_meta_xml(GF_ISOFile *isom_file, Bool root_meta, u32 track_num, char *XMLFileName, Bool IsBinaryXML); 5562 /*! set meta XML data from memory - erase any previously (Binary)XML info 5563 \param isom_file the target ISO file 5564 \param root_meta if GF_TRUE uses meta at the file, otherwise uses meta at the movie level if track number is 0 5565 \param track_num if GF_TRUE and root_meta is GF_FALSE, uses meta at the track level 5566 \param data buffer containing XML data 5567 \param data_size size of buffer in bytes 5568 \param IsBinaryXML indicates if the content of the buffer is binary XML (BIM) or not 5569 \return error if any 5570 */ 5571 GF_Err gf_isom_set_meta_xml_memory(GF_ISOFile *isom_file, Bool root_meta, u32 track_num, u8 *data, u32 data_size, Bool IsBinaryXML); 5572 5573 /*! gets next available item ID in a meta 5574 \param isom_file the target ISO file 5575 \param root_meta if GF_TRUE uses meta at the file, otherwise uses meta at the movie level if track number is 0 5576 \param track_num if GF_TRUE and root_meta is GF_FALSE, uses meta at the track level 5577 \param item_id set to the next available item ID 5578 \return error if any 5579 */ 5580 GF_Err gf_isom_meta_get_next_item_id(GF_ISOFile *isom_file, Bool root_meta, u32 track_num, u32 *item_id); 5581 5582 /*! adds an item to a meta box from file 5583 \param isom_file the target ISO file 5584 \param root_meta if GF_TRUE uses meta at the file, otherwise uses meta at the movie level if track number is 0 5585 \param track_num if GF_TRUE and root_meta is GF_FALSE, uses meta at the track level 5586 \param self_reference if GF_TRUE, indicates that the item is in fact the entire container file 5587 \param resource_path path to the file to add 5588 \param item_name name of the item 5589 \param item_id ID of the item, can be 0 5590 \param item_type four character code of item type 5591 \param mime_type mime type of the item, can be NULL 5592 \param content_encoding content encoding of the item, can be NULL 5593 \param URL URL of the item for external data reference (data is not contained in meta parent file) 5594 \param URN URN of the item for external data reference (data is not contained in meta parent file) 5595 \param image_props image properties information for image items 5596 \return error if any 5597 */ 5598 GF_Err gf_isom_add_meta_item(GF_ISOFile *isom_file, Bool root_meta, u32 track_num, Bool self_reference, char *resource_path, const char *item_name, u32 item_id, u32 item_type, const char *mime_type, const char *content_encoding, const char *URL, const char *URN, GF_ImageItemProperties *image_props); 5599 5600 /*! item extend description*/ 5601 typedef struct 5602 { 5603 /*! offset of extent in file*/ 5604 u64 extent_offset; 5605 /*! size of extent*/ 5606 u64 extent_length; 5607 /*! index of extent*/ 5608 u64 extent_index; 5609 #ifndef GPAC_DISABLE_ISOM_WRITE 5610 /*! for storage only, original offset in source file*/ 5611 u64 original_extent_offset; 5612 #endif 5613 } GF_ItemExtentEntry; 5614 5615 5616 /*! adds an item to a meta box from memory 5617 \param isom_file the target ISO file 5618 \param root_meta if GF_TRUE uses meta at the file, otherwise uses meta at the movie level if track number is 0 5619 \param track_num if GF_TRUE and root_meta is GF_FALSE, uses meta at the track level 5620 \param item_name name of the item 5621 \param item_id ID of the item, can be 0 5622 \param item_type four character code of item type 5623 \param mime_type mime type of the item, can be NULL 5624 \param content_encoding content encoding of the item, can be NULL 5625 \param image_props image properties information for image items 5626 \param data buffer containing the item data 5627 \param data_len size of item data buffer in bytes 5628 \param item_extent_refs list of item extend description, or NULL 5629 \return error if any 5630 */ 5631 GF_Err gf_isom_add_meta_item_memory(GF_ISOFile *isom_file, Bool root_meta, u32 track_num, const char *item_name, u32 item_id, u32 item_type, const char *mime_type, const char *content_encoding, GF_ImageItemProperties *image_props, char *data, u32 data_len, GF_List *item_extent_refs); 5632 5633 /*! creates image item(s) from samples of a media track 5634 \param isom_file the target ISO file 5635 \param root_meta if GF_TRUE uses meta at the file, otherwise uses meta at the movie level if meta_track_number is 0 5636 \param meta_track_number if GF_TRUE and root_meta is GF_FALSE, uses meta at the track level 5637 \param media_track track number to import samples from 5638 \param item_name name of the item 5639 \param item_id ID of the item, can be 0 5640 \param image_props image properties information for image items 5641 \param item_extent_refs list of item extend description, or NULL 5642 \return error if any 5643 */ 5644 GF_Err gf_isom_iff_create_image_item_from_track(GF_ISOFile *isom_file, Bool root_meta, u32 meta_track_number, u32 media_track, const char *item_name, u32 item_id, GF_ImageItemProperties *image_props, GF_List *item_extent_refs); 5645 5646 /*! removes item from meta 5647 \param isom_file the target ISO file 5648 \param root_meta if GF_TRUE uses meta at the file, otherwise uses meta at the movie level if track number is 0 5649 \param track_num if GF_TRUE and root_meta is GF_FALSE, uses meta at the track level 5650 \param item_num 1-based index of the item to remove 5651 \return error if any 5652 */ 5653 GF_Err gf_isom_remove_meta_item(GF_ISOFile *isom_file, Bool root_meta, u32 track_num, u32 item_num); 5654 5655 /*! sets the given item as the primary one 5656 \warning This SHALL NOT be used if the meta has a valid XML data 5657 \param isom_file the target ISO file 5658 \param root_meta if GF_TRUE uses meta at the file, otherwise uses meta at the movie level if track number is 0 5659 \param track_num if GF_TRUE and root_meta is GF_FALSE, uses meta at the track level 5660 \param item_num 1-based index of the item to remove 5661 \return error if any 5662 */ 5663 GF_Err gf_isom_set_meta_primary_item(GF_ISOFile *isom_file, Bool root_meta, u32 track_num, u32 item_num); 5664 5665 /*! adds an item reference to another item 5666 \param isom_file the target ISO file 5667 \param root_meta if GF_TRUE uses meta at the file, otherwise uses meta at the movie level if track number is 0 5668 \param track_num if GF_TRUE and root_meta is GF_FALSE, uses meta at the track level 5669 \param from_id ID of item the reference is from 5670 \param to_id ID of item the reference is to 5671 \param type four character code of reference 5672 \param ref_index set to the 1-based index of the reference 5673 \return error if any 5674 */ 5675 GF_Err gf_isom_meta_add_item_ref(GF_ISOFile *isom_file, Bool root_meta, u32 track_num, u32 from_id, u32 to_id, u32 type, u64 *ref_index); 5676 5677 #endif /*GPAC_DISABLE_ISOM_WRITE*/ 5678 5679 /*! 5680 \param isom_file the target ISO file 5681 \param root_meta if GF_TRUE uses meta at the file, otherwise uses meta at the movie level if track number is 0 5682 \param track_num if GF_TRUE and root_meta is GF_FALSE, uses meta at the track level 5683 \param item_id ID of the item 5684 \param out_image_props set to the image properties information of the item 5685 \return error if any 5686 */ 5687 GF_Err gf_isom_get_meta_image_props(GF_ISOFile *isom_file, Bool root_meta, u32 track_num, u32 item_id, GF_ImageItemProperties *out_image_props); 5688 5689 /*! @} */ 5690 5691 /*! 5692 \addtogroup isotags_grp iTunes tagging 5693 \ingroup iso_grp 5694 5695 @{ 5696 */ 5697 5698 /*! iTunes info tags */ 5699 typedef enum 5700 { 5701 /*probe is only used to check if iTunes info are present*/ 5702 GF_ISOM_ITUNE_PROBE = 0, 5703 /*all is only used to remove all tags*/ 5704 GF_ISOM_ITUNE_ALL = 1, 5705 GF_ISOM_ITUNE_ALBUM = GF_4CC( 0xA9, 'a', 'l', 'b' ), 5706 GF_ISOM_ITUNE_ARTIST = GF_4CC( 0xA9, 'A', 'R', 'T' ), 5707 GF_ISOM_ITUNE_COMMENT = GF_4CC( 0xA9, 'c', 'm', 't' ), 5708 GF_ISOM_ITUNE_COMPILATION = GF_4CC( 'c', 'p', 'i', 'l' ), 5709 GF_ISOM_ITUNE_COMPOSER = GF_4CC( 0xA9, 'c', 'o', 'm' ), 5710 GF_ISOM_ITUNE_COVER_ART = GF_4CC( 'c', 'o', 'v', 'r' ), 5711 GF_ISOM_ITUNE_CREATED = GF_4CC( 0xA9, 'd', 'a', 'y' ), 5712 GF_ISOM_ITUNE_DISK = GF_4CC( 'd', 'i', 's', 'k' ), 5713 GF_ISOM_ITUNE_TOOL = GF_4CC( 0xA9, 't', 'o', 'o' ), 5714 GF_ISOM_ITUNE_GENRE = GF_4CC( 'g', 'n', 'r', 'e' ), 5715 GF_ISOM_ITUNE_GROUP = GF_4CC( 0xA9, 'g', 'r', 'p' ), 5716 GF_ISOM_ITUNE_ITUNES_DATA = GF_4CC( '-', '-', '-', '-' ), 5717 GF_ISOM_ITUNE_NAME = GF_4CC( 0xA9, 'n', 'a', 'm' ), 5718 GF_ISOM_ITUNE_TEMPO = GF_4CC( 't', 'm', 'p', 'o' ), 5719 GF_ISOM_ITUNE_TRACK = GF_4CC( 0xA9, 't', 'r', 'k' ), 5720 GF_ISOM_ITUNE_TRACKNUMBER = GF_4CC( 't', 'r', 'k', 'n' ), 5721 GF_ISOM_ITUNE_WRITER = GF_4CC( 0xA9, 'w', 'r', 't' ), 5722 GF_ISOM_ITUNE_ENCODER = GF_4CC( 0xA9, 'e', 'n', 'c' ), 5723 GF_ISOM_ITUNE_ALBUM_ARTIST = GF_4CC( 'a', 'A', 'R', 'T' ), 5724 GF_ISOM_ITUNE_GAPLESS = GF_4CC( 'p', 'g', 'a', 'p' ), 5725 } GF_ISOiTunesTag; 5726 5727 /*! gets the given itunes tag info. 5728 \warning 'genre' may be coded by ID, the libisomedia doesn't translate the ID. In such a case, the result data is set to NULL and the data_len to the genre ID 5729 5730 \param isom_file the target ISO file 5731 \param tag the tag to query 5732 \param data set to the tag data pointer - do not modify 5733 \param data_len set to the size of the tag data 5734 \return error if any (GF_URL_ERROR if no tag is present in the file) 5735 */ 5736 GF_Err gf_isom_apple_get_tag(GF_ISOFile *isom_file, GF_ISOiTunesTag tag, const u8 **data, u32 *data_len); 5737 5738 #ifndef GPAC_DISABLE_ISOM_WRITE 5739 /*! sets the given tag info. 5740 5741 \warning For 'genre', data may be NULL in which case the genre ID taken from the data_len parameter 5742 5743 \param isom_file the target ISO file 5744 \param tag the tag to set 5745 \param data tag data buffer 5746 \param data_len size of the tag data buffer. If data and data_len are 0, removes the given tag 5747 \return error if any 5748 */ 5749 GF_Err gf_isom_apple_set_tag(GF_ISOFile *isom_file, GF_ISOiTunesTag tag, const u8 *data, u32 data_len); 5750 5751 /*! sets compatibility tag on AVC tracks (needed by iPod to play files... hurray for standards) 5752 \param isom_file the target ISO file 5753 \param trackNumber the target track 5754 \return error if any 5755 */ 5756 GF_Err gf_isom_set_ipod_compatible(GF_ISOFile *isom_file, u32 trackNumber); 5757 #endif /*GPAC_DISABLE_ISOM_WRITE*/ 5758 5759 /*! @} */ 5760 5761 /*! 5762 \addtogroup isogrp_grp Track Groups 5763 \ingroup iso_grp 5764 5765 @{ 5766 */ 5767 5768 /*! gets the number of switching groups declared in this track if any 5769 \param isom_file the target ISO file 5770 \param trackNumber the target track 5771 \param alternateGroupID alternate group id of track if speciifed, 0 otherwise 5772 \param nb_groups set to number of switching groups defined for this track 5773 \return error if any 5774 */ 5775 GF_Err gf_isom_get_track_switch_group_count(GF_ISOFile *isom_file, u32 trackNumber, u32 *alternateGroupID, u32 *nb_groups); 5776 5777 /*! get the list of criteria (expressed as 4CC IDs, cf 3GPP TS 26.244) 5778 \param isom_file the target ISO file 5779 \param trackNumber the track number 5780 \param group_index the 1-based index of the group to inspect 5781 \param switchGroupID set to the ID of the switch group if any, 0 otherwise (alternate-only group) 5782 \param criteriaListSize set to the number of criteria items in returned list 5783 \return list of criteria (four character codes, cf 3GPP TS 26.244) for the switch group 5784 */ 5785 const u32 *gf_isom_get_track_switch_parameter(GF_ISOFile *isom_file, u32 trackNumber, u32 group_index, u32 *switchGroupID, u32 *criteriaListSize); 5786 5787 #ifndef GPAC_DISABLE_ISOM_WRITE 5788 /*! sets a new (switch) group for this track 5789 \param isom_file the target ISO file 5790 \param trackNumber the target track 5791 \param trackRefGroup number of a track belonging to the same alternate group. If 0, a new alternate group will be created for this track 5792 \param is_switch_group if set, indicates that a switch group identifier shall be assigned to the created group. Otherwise, the criteria list is associated with the entire alternate group 5793 \param switchGroupID set to the ID of the switch group. On input, specifies the desired switchGroupID to use; if value is 0, next available switchGroupID in file is used. On output, is set to the switchGroupID used. 5794 \param criteriaList list of four character codes used as criteria - cf 3GPP TS 26.244 5795 \param criteriaListCount number of criterias in list 5796 \return error if any 5797 */ 5798 GF_Err gf_isom_set_track_switch_parameter(GF_ISOFile *isom_file, u32 trackNumber, u32 trackRefGroup, Bool is_switch_group, u32 *switchGroupID, u32 *criteriaList, u32 criteriaListCount); 5799 5800 /*! resets track switch group information 5801 \param isom_file the target ISO file 5802 \param trackNumber the target track 5803 \param reset_all_group if GF_TRUE, resets the entire alternate group this track belongs to; otherwise, resets switch group for the track only 5804 \return error if any 5805 */ 5806 GF_Err gf_isom_reset_track_switch_parameter(GF_ISOFile *isom_file, u32 trackNumber, Bool reset_all_group); 5807 5808 /*! resets all track switch group information in the entire movie 5809 \param isom_file the target ISO file 5810 \return error if any 5811 */ 5812 GF_Err gf_isom_reset_switch_parameters(GF_ISOFile *isom_file); 5813 5814 /*! sets track in group of a given type and ID 5815 \param isom_file the target ISO file 5816 \param trackNumber the target track 5817 \param track_group_id ID of the track group 5818 \param group_type four character code of the track group 5819 \param do_add if GF_FALSE, track is removed from that group, otherwise it is added 5820 \return error if any 5821 */ 5822 GF_Err gf_isom_set_track_group(GF_ISOFile *isom_file, u32 trackNumber, u32 track_group_id, u32 group_type, Bool do_add); 5823 5824 #endif /*GPAC_DISABLE_ISOM_WRITE*/ 5825 5826 /*! @} */ 5827 5828 /*! 5829 \addtogroup isosubs_grp Subsamples 5830 \ingroup iso_grp 5831 5832 @{ 5833 */ 5834 5835 5836 /*! checks if a sample has subsample information 5837 \param isom_file the target ISO file 5838 \param trackNumber the target track 5839 \param sampleNumber the target sample number 5840 \param flags the subsample flags to query (may be 0) 5841 \return the number of subsamples in the given sample for the given flags*/ 5842 u32 gf_isom_sample_has_subsamples(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber, u32 flags); 5843 5844 /*! gets subsample information on a sample 5845 \param isom_file the target ISO file 5846 \param trackNumber the target track 5847 \param sampleNumber the target sample number 5848 \param flags the subsample flags to query (may be 0) 5849 \param subSampleNumber the 1-based index of the subsample (see \ref gf_isom_sample_has_subsamples) 5850 \param size set to the subsample size 5851 \param priority set to the subsample priority 5852 \param reserved set to the subsample reserved value (may be used by derived specifications) 5853 \param discardable set to GF_TRUE if subsample is discardable 5854 \return error if any*/ 5855 GF_Err gf_isom_sample_get_subsample(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber, u32 flags, u32 subSampleNumber, u32 *size, u8 *priority, u32 *reserved, Bool *discardable); 5856 5857 #ifndef GPAC_DISABLE_ISOM_WRITE 5858 /*! adds subsample information to a given sample. Subsample information shall be added in increasing order of sampleNumbers, insertion of information is not supported 5859 5860 \note it is possible to add subsample information for samples not yet added to the file 5861 \note specifying 0 as subSampleSize will remove the last subsample information if any 5862 \param isom_file the target ISO file 5863 \param trackNumber the target track 5864 \param sampleNumber the target sample number 5865 \param flags the subsample flags to query (may be 0) 5866 \param subSampleSize size of the subsample. If 0, this will remove the last subsample information if any 5867 \param priority the subsample priority 5868 \param reserved the subsample reserved value (may be used by derived specifications) 5869 \param discardable indicates if the subsample is discardable 5870 \return error if any*/ 5871 GF_Err gf_isom_add_subsample(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber, u32 flags, u32 subSampleSize, u8 priority, u32 reserved, Bool discardable); 5872 5873 5874 #ifndef GPAC_DISABLE_ISOM_FRAGMENTS 5875 /*! adds subsample information for the latest sample added to the current track fragment 5876 \param isom_file the target ISO file 5877 \param TrackID the ID of the target track 5878 \param flags the subsample flags to query (may be 0) 5879 \param subSampleSize size of the subsample. If 0, this will remove the last subsample information if any 5880 \param priority the subsample priority 5881 \param reserved the subsample reserved value (may be used by derived specifications) 5882 \param discardable indicates if the subsample is discardable 5883 \return error if any*/ 5884 GF_Err gf_isom_fragment_add_subsample(GF_ISOFile *isom_file, GF_ISOTrackID TrackID, u32 flags, u32 subSampleSize, u8 priority, u32 reserved, Bool discardable); 5885 #endif // GPAC_DISABLE_ISOM_FRAGMENTS 5886 5887 #endif //GPAC_DISABLE_ISOM_WRITE 5888 5889 /*! @} */ 5890 5891 /*! 5892 \addtogroup isosgdp_grp Sample Groups 5893 \ingroup iso_grp 5894 5895 @{ 5896 */ 5897 5898 /*! defined sample groups in GPAC*/ 5899 enum { 5900 GF_ISOM_SAMPLE_GROUP_ROLL = GF_4CC( 'r', 'o', 'l', 'l'), 5901 GF_ISOM_SAMPLE_GROUP_PROL = GF_4CC( 'p', 'r', 'o', 'l'), 5902 GF_ISOM_SAMPLE_GROUP_RAP = GF_4CC( 'r', 'a', 'p', ' ' ), 5903 GF_ISOM_SAMPLE_GROUP_SEIG = GF_4CC( 's', 'e', 'i', 'g' ), 5904 GF_ISOM_SAMPLE_GROUP_OINF = GF_4CC( 'o', 'i', 'n', 'f'), 5905 GF_ISOM_SAMPLE_GROUP_LINF = GF_4CC( 'l', 'i', 'n', 'f'), 5906 GF_ISOM_SAMPLE_GROUP_TRIF = GF_4CC( 't', 'r', 'i', 'f' ), 5907 GF_ISOM_SAMPLE_GROUP_NALM = GF_4CC( 'n', 'a', 'l', 'm'), 5908 GF_ISOM_SAMPLE_GROUP_TELE = GF_4CC( 't', 'e', 'l', 'e'), 5909 GF_ISOM_SAMPLE_GROUP_SAP = GF_4CC( 's', 'a', 'p', ' '), 5910 GF_ISOM_SAMPLE_GROUP_ALST = GF_4CC( 'a', 'l', 's', 't'), 5911 GF_ISOM_SAMPLE_GROUP_RASH = GF_4CC( 'r', 'a', 's', 'h'), 5912 GF_ISOM_SAMPLE_GROUP_AVLL = GF_4CC( 'a', 'v', 'l', 'l'), //p15 5913 GF_ISOM_SAMPLE_GROUP_AVSS = GF_4CC( 'a', 'v', 's', 's'), //p15 5914 GF_ISOM_SAMPLE_GROUP_DTRT = GF_4CC( 'd', 't', 'r', 't'), //p15 5915 GF_ISOM_SAMPLE_GROUP_MVIF = GF_4CC( 'm', 'v', 'i', 'f'), //p15 5916 GF_ISOM_SAMPLE_GROUP_SCIF = GF_4CC( 's', 'c', 'i', 'f'), //p15 5917 GF_ISOM_SAMPLE_GROUP_SCNM = GF_4CC( 's', 'c', 'n', 'm'), //p15 5918 GF_ISOM_SAMPLE_GROUP_STSA = GF_4CC( 's', 't', 's', 'a'), //p15 5919 GF_ISOM_SAMPLE_GROUP_TSAS = GF_4CC( 't', 's', 'a', 's'), //p15 5920 GF_ISOM_SAMPLE_GROUP_SYNC = GF_4CC( 's', 'y', 'n', 'c'), //p15 5921 GF_ISOM_SAMPLE_GROUP_TSCL = GF_4CC( 't', 's', 'c', 'l'), //p15 5922 GF_ISOM_SAMPLE_GROUP_VIPR = GF_4CC( 'v', 'i', 'p', 'r'), //p15 5923 GF_ISOM_SAMPLE_GROUP_LBLI = GF_4CC( 'l', 'b', 'l', 'i'), //p15 5924 GF_ISOM_SAMPLE_GROUP_3GAG = GF_4CC( '3', 'g', 'a', 'g'), //3gpp 5925 GF_ISOM_SAMPLE_GROUP_AVCB = GF_4CC( 'a', 'v', 'c', 'b'), //3gpp 5926 }; 5927 5928 /*! gets 'rap ' and 'roll' group info for the given sample 5929 \param isom_file the target ISO file 5930 \param trackNumber the target track 5931 \param sampleNumber the target sample number 5932 \param is_rap set to GF_TRUE if sample is a rap (open gop), GF_FALSE otherwise 5933 \param has_roll set to GF_TRUE of sample has roll information, GF_FALSE otherwise 5934 \param roll_distance if sample has roll information, set to roll distance 5935 \return error if any*/ 5936 GF_Err gf_isom_get_sample_rap_roll_info(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber, Bool *is_rap, Bool *has_roll, s32 *roll_distance); 5937 5938 /*! returns opaque data of sample group 5939 \param isom_file the target ISO file 5940 \param trackNumber the target track 5941 \param sample_group_description_index index of sample group description entry to query 5942 \param grouping_type four character code of grouping typpe of sample group description to query 5943 \param default_index set to the default index for this sample group description if any, 0 otherwise (no defaults) 5944 \param data set to the internal sample group description data buffer 5945 \param size set to size of the sample group description data buffer 5946 \return GF_TRUE if found, GF_FALSE otherwise*/ 5947 Bool gf_isom_get_sample_group_info(GF_ISOFile *isom_file, u32 trackNumber, u32 sample_group_description_index, u32 grouping_type, u32 *default_index, const u8 **data, u32 *size); 5948 5949 /*! checks if a track as a CENC seig sample group used for key rolling 5950 \param isom_file the target ISO file 5951 \param trackNumber the target track 5952 \return GF_TRUE if found, GF_FALSE otherwise*/ 5953 Bool gf_isom_has_cenc_sample_group(GF_ISOFile *isom_file, u32 trackNumber); 5954 5955 /*! gets HEVC tiling info 5956 \param isom_file the target ISO file 5957 \param trackNumber the target track 5958 \param sample_group_description_index index of sample group description entry to query 5959 \param default_sample_group_index set to the default index for this sample group description if any, 0 otherwise (no defaults) 5960 \param id set to the tile group ID 5961 \param independent set to independent flag of the tile group (0: not constrained, 1: constrained in layer, 2: all intra slices) 5962 \param full_frame set to GF_TRUE if the tile corresponds to the entire picture 5963 \param x set to the horizontal position in pixels 5964 \param y set to the vertical position in pixels 5965 \param w set to the width in pixels 5966 \param h set to the height in pixels 5967 \return GF_TRUE if found, GF_FALSE otherwise*/ 5968 Bool gf_isom_get_tile_info(GF_ISOFile *isom_file, u32 trackNumber, u32 sample_group_description_index, u32 *default_sample_group_index, u32 *id, u32 *independent, Bool *full_frame, u32 *x, u32 *y, u32 *w, u32 *h); 5969 5970 5971 #ifndef GPAC_DISABLE_ISOM_WRITE 5972 5973 /*! sets rap flag for sample_number - this is used by non-IDR RAPs in AVC (also in USAC) were SYNC flag (stss table) cannot be used 5974 \warning sample group info MUST be added in order (no insertion in the tables) 5975 5976 \param isom_file the target ISO file 5977 \param trackNumber the target track 5978 \param sampleNumber the target sample number 5979 \param is_rap indicates if the sample is a RAP (open gop) sample 5980 \param num_leading_samples indicates the number of leading samples (samples after this RAP that have dependences on samples before this RAP and hence should be discarded when tuning in) 5981 \return error if any 5982 */ 5983 GF_Err gf_isom_set_sample_rap_group(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber, Bool is_rap, u32 num_leading_samples); 5984 5985 /*! sets roll_distance info for sample_number (number of frames before (<0) or after (>0) this sample to have a complete refresh of the decoded data (used by GDR in AVC) 5986 5987 \warning sample group info MUST be added in order (no insertion in the tables) 5988 \param isom_file the target ISO file 5989 \param trackNumber the target track 5990 \param sampleNumber the target sample number 5991 \param is_roll indicates that the sample is a roll recovery point 5992 \param roll_distance indicates the roll distance before a correct decoding is produced 5993 \return error if any 5994 */ 5995 GF_Err gf_isom_set_sample_roll_group(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber, Bool is_roll, s16 roll_distance); 5996 5997 /*! sets encryption group for a sample number 5998 \param isom_file the target ISO file 5999 \param trackNumber the target track 6000 \param sampleNumber the target sample number 6001 \param isEncrypted isEncrypted flag 6002 \param IV_size IV size, can be 0 if not encrypted 6003 \param KeyID key ID used 6004 \param crypt_byte_block crypt block size for pattern encryption, can be 0 6005 \param skip_byte_block skip block size for pattern encryption, can be 0 6006 \param constant_IV_size constant IV size, can be 0 6007 \param constant_IV constant IV, can be 0 6008 \return error if any 6009 */ 6010 GF_Err gf_isom_set_sample_cenc_group(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber, u8 isEncrypted, u8 IV_size, bin128 KeyID, u8 crypt_byte_block, u8 skip_byte_block, u8 constant_IV_size, bin128 constant_IV); 6011 6012 /*! sets a sample using the default CENC parameters in a CENC saig sample group SEIG, creating a sample group description if needed (when seig is already defined) 6013 \param isom_file the target ISO file 6014 \param trackNumber the target track 6015 \param sampleNumber the target sample number 6016 \return error if any 6017 */ 6018 GF_Err gf_isom_set_sample_cenc_default_group(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber); 6019 6020 /*! adds the given blob as a sample group description entry of the given grouping type. 6021 \param isom_file the target ISO file 6022 \param trackNumber the target track 6023 \param grouping_type the four character code of the grouping type 6024 \param data the payload of the sample group description 6025 \param data_size the size of the payload 6026 \param is_default if GF_TRUE, thie created entry will be marked as the default entry for the sample group description 6027 \param sampleGroupDescriptionIndex is set to the sample group description index (optional, can be NULL) 6028 \return error if any 6029 */ 6030 GF_Err gf_isom_add_sample_group_info(GF_ISOFile *isom_file, u32 trackNumber, u32 grouping_type, void *data, u32 data_size, Bool is_default, u32 *sampleGroupDescriptionIndex); 6031 6032 /*! removes a sample group description of the give grouping type, if found 6033 \param isom_file the target ISO file 6034 \param trackNumber the target track 6035 \param grouping_type the four character code of the grouping type 6036 \return error if any 6037 */ 6038 GF_Err gf_isom_remove_sample_group(GF_ISOFile *isom_file, u32 trackNumber, u32 grouping_type); 6039 6040 /*! adds a sample to the given sample group 6041 \param isom_file the target ISO file 6042 \param trackNumber the target track 6043 \param sampleNumber the target sample number 6044 \param grouping_type the four character code of the grouping type 6045 \param sampleGroupDescriptionIndex the 1-based index of the sample group description entry 6046 \param grouping_type_parameter the grouping type paramter (see ISO/IEC 14496-12) 6047 \return error if any 6048 */ 6049 GF_Err gf_isom_add_sample_info(GF_ISOFile *isom_file, u32 trackNumber, u32 sampleNumber, u32 grouping_type, u32 sampleGroupDescriptionIndex, u32 grouping_type_parameter); 6050 6051 #ifndef GPAC_DISABLE_ISOM_FRAGMENTS 6052 /*! sets sample group descriptions storage in trafs and not in initial movie (Smooth compatibility) 6053 \param isom_file the target ISO file 6054 \return error if any*/ 6055 GF_Err gf_isom_set_sample_group_in_traf(GF_ISOFile *isom_file); 6056 #endif 6057 6058 #endif // GPAC_DISABLE_ISOM_WRITE 6059 6060 6061 /*! @} */ 6062 6063 #endif /*GPAC_DISABLE_ISOM*/ 6064 6065 #ifdef __cplusplus 6066 } 6067 #endif 6068 6069 6070 #endif /*_GF_ISOMEDIA_H_*/ 6071 6072 6073