isomedia.h

一个用于智能手机的多媒体库适合S60 WinCE的跨平台开发库

and will be reassigned at next ESD fetch*/
void gf_isom_set_default_sync_track(GF_ISOFile *file, u32 trackNumber);

/*Return the number of track references of a track for a given ReferenceType - return -1 if error*/
s32 gf_isom_get_reference_count(GF_ISOFile *the_file, u32 trackNumber, u32 referenceType);

/*Return the referenced track number for a track and a given ReferenceType and Index
return -1 if error, 0 if the reference is a NULL one, or the trackNumber
*/
GF_Err gf_isom_get_reference(GF_ISOFile *the_file, u32 trackNumber, u32 referenceType, u32 referenceIndex, u32 *refTrack);

u8 gf_isom_get_pl_indication(GF_ISOFile *the_file, u8 PL_Code);

/*locates the first ObjectDescriptor using the given track by inspecting any OD tracks*/
u32 gf_isom_find_od_for_track(GF_ISOFile *file, u32 track);

/*returns file name*/
const char *gf_isom_get_filename(GF_ISOFile *the_file);

/*
		Update of the Reading API for IsoMedia Version 2
*/

/*retrieves the brand of the file. The brand is introduced in V2 to differenciate
MP4, MJPEG2000 and QT while indicating compatibilities
the brand is one of the above defined code, or any other registered brand

minorVersion is an optional parameter (can be set to NULL) , 
		"informative integer for the minor version of the major brand"
AlternateBrandsCount is an optional parameter (can be set to NULL) , 
	giving the number of compatible brands. 

	The function will set brand to 0 if no brand indication is found in the file
*/
GF_Err gf_isom_get_brand_info(GF_ISOFile *the_file, u32 *brand, u32 *minorVersion, u32 *AlternateBrandsCount);

/*gets an alternate brand indication. BrandIndex is 1-based
Note that the Major brand should always be indicated in the alternate brands*/
GF_Err gf_isom_get_alternate_brand(GF_ISOFile *the_file, u32 BrandIndex, u32 *brand);

/*get the number of padding bits at the end of a given sample if any*/
GF_Err gf_isom_get_sample_padding_bits(GF_ISOFile *the_file, u32 trackNumber, u32 sampleNumber, u8 *NbBits);
/*indicates whether the track samples use padding bits or not*/
Bool gf_isom_has_padding_bits(GF_ISOFile *the_file, u32 trackNumber);

/*returns width and height of the given visual sample desc - error if not a visual track*/
GF_Err gf_isom_get_visual_info(GF_ISOFile *the_file, u32 trackNumber, u32 StreamDescriptionIndex, u32 *Width, u32 *Height);

/*returns samplerate, channels and bps of the given audio track - error if not a audio track*/
GF_Err gf_isom_get_audio_info(GF_ISOFile *the_file, u32 trackNumber, u32 StreamDescriptionIndex, u32 *SampleRate, u32 *Channels, u8 *bitsPerSample);

/*returns track visual info - all coord values are expressed as 16.16 fixed point floats*/
GF_Err gf_isom_get_track_layout_info(GF_ISOFile *the_file, u32 trackNumber, u32 *width, u32 *height, s32 *translation_x, s32 *translation_y, s16 *layer);

/*
	User Data Manipulation (cf write API too)
*/

/* Gets the number of UserDataItems with the same ID / UUID in the desired track or 
in the movie if trackNumber is set to 0*/
u32 gf_isom_get_user_data_count(GF_ISOFile *the_file, u32 trackNumber, u32 UserDataType, bin128 UUID);
/* Gets the UserData for the specified item from the track or the movie if trackNumber is set to 0
data is allocated by the function and is yours to free
you musty pass (userData != NULL && *userData=NULL)*/
GF_Err gf_isom_get_user_data(GF_ISOFile *the_file, u32 trackNumber, u32 UserDataType, bin128 UUID, u32 UserDataIndex, char **userData, u32 *userDataSize);


/*gets 3char media language code - @three_char_code must be at least 4 char long*/
GF_Err gf_isom_get_media_language(GF_ISOFile *the_file, u32 trackNumber, char *three_char_code);

/*Unknown sample description*/
typedef struct
{
	/*codec tag is the containing box's tag, 0 if UUID is used*/
	u32 codec_tag;
	/*entry UUID if no tag is used*/
	bin128 UUID;

	u16 version;
	u16 revision;
	u32 vendor_code;

	/*video codecs only*/
	u32 temporal_quality;
	u32 spacial_quality;
	u16 width, height;
	u32 h_res, v_res;
	u16 depth;
	u16 color_table_index;
	char compressor_name[33];

	/*audio codecs only*/
	u32 samplerate;
	u16 nb_channels;
	u16 bits_per_sample;

	/*if present*/
	char *extension_buf;
	u32 extension_buf_size;
} GF_GenericSampleDescription;

/*returns wrapper for unknown entries - you must delete it yourself*/
GF_GenericSampleDescription *gf_isom_get_generic_sample_description(GF_ISOFile *the_file, u32 trackNumber, u32 StreamDescriptionIndex);

/*retrieves default values for a track fragment. Each variable is optional and 
if set will contain the default value for this track samples*/
GF_Err gf_isom_get_fragment_defaults(GF_ISOFile *the_file, u32 trackNumber, 
							 u32 *defaultDuration, u32 *defaultSize, u32 *defaultDescriptionIndex,
							 u32 *defaultRandomAccess, u8 *defaultPadding, u16 *defaultDegradationPriority);


/*non standard extensions used for video packets in order to keep AU structure in the file format 
(no normative tables for that). Info is NOT written to disk.
*/
/*get number of fragments for a sample */
u32 gf_isom_get_sample_fragment_count(GF_ISOFile *the_file, u32 trackNumber, u32 sampleNumber);
/*get sample fragment size*/
u16 gf_isom_get_sample_fragment_size(GF_ISOFile *the_file, u32 trackNumber, u32 sampleNumber, u32 FragmentIndex);

/*returns 1 if file is single AV (max one audio, one video, one text and basic od/bifs)*/
Bool gf_isom_is_single_av(GF_ISOFile *file);

/*guess which std this file refers to. return value:
	GF_ISOM_BRAND_ISOM: unrecognized std
	GF_ISOM_BRAND_3GP5: 3GP file (max 1 audio, 1 video) without text track
	GF_ISOM_BRAND_3GP6: 3GP file (max 1 audio, 1 video) with text track
	GF_ISOM_BRAND_3GG6: 3GP file multitrack file
	GF_ISOM_BRAND_3G2A: 3GP2 file
	GF_ISOM_BRAND_AVC1: AVC file
	FCC("ISMA"): ISMA file (may overlap with 3GP)
	GF_ISOM_BRAND_MP42: any generic MP4 file (eg with BIFS/OD/MPEG-4 systems stuff)

  for files without movie, returns the file meta handler type
*/
u32 gf_isom_guess_specification(GF_ISOFile *file);


#ifndef GPAC_READ_ONLY


/********************************************************************
				EDITING/WRITING API FUNCTIONS
********************************************************************/

/*set the timescale of the movie*/
GF_Err gf_isom_set_timescale(GF_ISOFile *the_file, u32 timeScale);

/*creates a new Track. If trackID = 0, the trackID is chosen by the API
returns the track number or 0 if error*/
u32 gf_isom_new_track(GF_ISOFile *the_file, u32 trackID, u32 MediaType, u32 TimeScale);

/*removes the desired track - internal cross dependancies will be updated.
WARNING: any OD streams with references to this track through  ODUpdate, ESDUpdate, ESDRemove commands
will be rewritten*/
GF_Err gf_isom_remove_track(GF_ISOFile *the_file, u32 trackNumber);

/*sets the enable flag of a track*/
GF_Err gf_isom_set_track_enabled(GF_ISOFile *the_file, u32 trackNumber, u8 enableTrack);

/*changes the trackID - all track references present in the file are updated
returns error if trackID is already in used in the file*/
GF_Err gf_isom_set_track_id(GF_ISOFile *the_file, u32 trackNumber, u32 trackID);

/*Add samples to a track. Use streamDescriptionIndex to specify the desired stream (if several)*/
GF_Err gf_isom_add_sample(GF_ISOFile *the_file, u32 trackNumber, u32 StreamDescriptionIndex, GF_ISOSample *sample);

/*Add sync shadow sample to a track. 
- There must be a regular sample with the same DTS. 
- Sync Shadow samples MUST be RAP
- Currently, adding sync shadow must be done in order (no sample insertion)
*/
GF_Err gf_isom_add_sample_shadow(GF_ISOFile *the_file, u32 trackNumber, GF_ISOSample *sample);

/*add data to current sample in the track. Use this function for media with
fragmented options such as MPEG-4 video packets. This will update the data size.
CANNOT be used with OD media type*/
GF_Err gf_isom_append_sample_data(GF_ISOFile *the_file, u32 trackNumber, char *data, u32 data_size);

/*Add sample references to a track. The dataOffset is the offset of the data in the referenced file
you MUST have created a StreamDescription with URL or URN specifying your referenced file
Use streamDescriptionIndex to specify the desired stream (if several)*/
GF_Err gf_isom_add_sample_reference(GF_ISOFile *the_file, u32 trackNumber, u32 StreamDescriptionIndex, GF_ISOSample *sample, u64 dataOffset);

/*set the duration of the last media sample. If not set, the duration of the last sample is the
duration of the previous one if any, or media TimeScale (default value).*/
GF_Err gf_isom_set_last_sample_duration(GF_ISOFile *the_file, u32 trackNumber, u32 duration);

/*sets a track reference*/
GF_Err gf_isom_set_track_reference(GF_ISOFile *the_file, u32 trackNumber, u32 referenceType, u32 ReferencedTrackID);

/*removes a track reference*/
GF_Err gf_isom_remove_track_reference(GF_ISOFile *the_file, u32 trackNumber, u32 referenceType, u32 ReferenceIndex);

/*sets track handler name. name is either NULL (reset), a UTF-8 formatted string or a UTF8 file 
resource in the form "file://path/to/file_utf8" */
GF_Err gf_isom_set_handler_name(GF_ISOFile *the_file, u32 trackNumber, const char *nameUTF8);

/*Update the sample size table - this is needed when using @gf_isom_append_sample_data in case the resulting samples
are of same sizes (typically in 3GP speech tracks)*/
GF_Err gf_isom_refresh_size_info(GF_ISOFile *file, u32 trackNumber);

/*Update Sample functions*/

/*update a given sample of the media.
@data_only: if set, only the sample data is updated, not other info*/
GF_Err gf_isom_update_sample(GF_ISOFile *the_file, u32 trackNumber, u32 sampleNumber, GF_ISOSample *sample, Bool data_only);

/*update a sample reference in the media. Note that the sample MUST exists,
that sample->data MUST be NULL and sample->dataLength must be NON NULL;*/
GF_Err gf_isom_update_sample_reference(GF_ISOFile *the_file, u32 trackNumber, u32 sampleNumber, GF_ISOSample *sample, u64 data_offset);

/*Remove a given sample*/
GF_Err gf_isom_remove_sample(GF_ISOFile *the_file, u32 trackNumber, u32 sampleNumber);

/*changes media time scale*/
GF_Err gf_isom_set_media_timescale(GF_ISOFile *the_file, u32 trackNumber, u32 new_timescale);

/*set the save file name of the (edited) movie. 
If the movie is edited, the default fileName is avp_#openName)
NOTE: you cannot save an edited file under the same name (overwrite not allowed)
If the movie is created (WRITE mode), the default filename is #openName*/
GF_Err gf_isom_set_final_name(GF_ISOFile *the_file, char *filename);


/*set the storage mode of a file (FLAT, STREAMABLE, INTERLEAVED)*/
GF_Err gf_isom_set_storage_mode(GF_ISOFile *the_file, u8 storageMode);
u8 gf_isom_get_storage_mode(GF_ISOFile *the_file);

/*set the interleaving time of media data (INTERLEAVED mode only)
InterleaveTime is in MovieTimeScale*/
GF_Err gf_isom_set_interleave_time(GF_ISOFile *the_file, u32 InterleaveTime);
u32 gf_isom_get_interleave_time(GF_ISOFile *the_file);

/*set the copyright in one language.*/
GF_Err gf_isom_set_copyright(GF_ISOFile *the_file, const char *threeCharCode, char *notice);

/*deletes copyright (1-based indexes)*/
GF_Err gf_isom_remove_copyright(GF_ISOFile *the_file, u32 index);

/*add chapter info:
if trackNumber is 0, the chapter info is added to the movie, otherwise to the track
@timestamp: chapter start time in milliseconds. Chapters are added in order to the file. If a chapter with same timestamp
	is found, its name is updated but no entry is created.
@name: chapter name. If NULL, defaults to 'Chapter N'
*/
GF_Err gf_isom_add_chapter(GF_ISOFile *the_file, u32 trackNumber, u64 timestamp, char *name);

/*deletes copyright (1-based index, index 0 for all)*/
GF_Err gf_isom_remove_chapter(GF_ISOFile *the_file, u32 trackNumber, u32 index);

/*set watermark info for movie*/
GF_Err gf_isom_set_watermark(GF_ISOFile *the_file, bin128 UUID, u8* data, u32 length);

/*Track Edition functions - used to change the normal playback of the media if desired
NOTE: IT IS THE USER RESPONSABILITY TO CREATE A CONSISTENT TIMELINE FOR THE TRACK
This API provides the basic hooks and some basic consistency checking
but can not check the desired functionality of the track edits
*/

/*update or insert a new edit segment in the track time line. Edits are used to modify
the media normal timing. EditTime and EditDuration are expressed in Movie TimeScale
If a segment with EditTime already exists, IT IS ERASED
if there is a segment before this new one, its duration is adjust to match EditTime of
the new segment
WARNING: The first segment always have an EditTime of 0. You should insert an empty or dwelled segment first.*/
GF_Err gf_isom_set_edit_segment(GF_ISOFile *the_file, u32 trackNumber, u64 EditTime, u64 EditDuration, u64 MediaTime, u8 EditMode);

/*same as above except only modifies duartion type and mediaType*/
GF_Err gf_isom_modify_edit_segment(GF_ISOFile *the_file, u32 trackNumber, u32 seg_index, u64 EditDuration, u64 MediaTime, u8 EditMode);
/*same as above except only appends new segment*/
GF_Err gf_isom_append_edit_segment(GF_ISOFile *the_file, u32 trackNumber, u64 EditDuration, u64 MediaTime, u8 EditMode);

/*remove the edit segments for the whole track*/
GF_Err gf_isom_remove_edit_segments(GF_ISOFile *the_file, u32 trackNumber);

/*remove the given edit segment (1-based index). If this is not the last segment, the next segment duration
is updated to maintain a continous timeline*/