isomedia.h

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

GF_Err gf_isom_remove_edit_segment(GF_ISOFile *the_file, u32 trackNumber, u32 seg_index);

/*
				User Data Manipulation

		You can add specific typed data to either a track or the movie: the UserData
	The type must be formated as a FourCC if you have a registered 4CC type
	but the usual is to set a UUID (128 bit ID for box type) which never conflict
	with existing structures in the format
		To manipulate a UUID user data set the UserDataType to 0 and specify a valid UUID.
Otherwise the UUID parameter is ignored
		Several items with the same ID or UUID can be added (this allows you to store any
	kind/number of private information under a unique ID / UUID)
*/
/*Add a user data item in the desired track or in the movie if TrackNumber is 0*/
GF_Err gf_isom_add_user_data(GF_ISOFile *the_file, u32 trackNumber, u32 UserDataType, bin128 UUID, char *data, u32 DataLength);

/*remove all user data items from the desired track or from the movie if TrackNumber is 0*/
GF_Err gf_isom_remove_user_data(GF_ISOFile *the_file, u32 trackNumber, u32 UserDataType, bin128 UUID);

/*remove a user data item from the desired track or from the movie if TrackNumber is 0
use the UDAT read functions to get the item index*/
GF_Err gf_isom_remove_user_data_item(GF_ISOFile *the_file, u32 trackNumber, u32 UserDataType, bin128 UUID, u32 UserDataIndex);

/*remove track, moov (trackNumber=0) or file-level (trackNumber=0xFFFFFFFF) UUID box of matching type*/
GF_Err gf_isom_remove_uuid(GF_ISOFile *movie, u32 trackNumber, bin128 UUID);
/*adds track, moov (trackNumber=0) or file-level (trackNumber=0xFFFFFFFF) UUID box of given type*/
GF_Err gf_isom_add_uuid(GF_ISOFile *movie, u32 trackNumber, bin128 UUID, char *data, u32 data_size);

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

/*use a compact track version for sample size. This is not usually recommended 
except for speech codecs where the track has a lot of small samples
compaction is done automatically while writing based on the track's sample sizes*/
GF_Err gf_isom_use_compact_size(GF_ISOFile *the_file, u32 trackNumber, u8 CompactionOn);

/*sets the brand of the movie*/
GF_Err gf_isom_set_brand_info(GF_ISOFile *the_file, u32 MajorBrand, u32 MinorVersion);

/*adds or remove an alternate brand for the movie*/
GF_Err gf_isom_modify_alternate_brand(GF_ISOFile *the_file, u32 Brand, u8 AddIt);

/*set the number of padding bits at the end of a given sample if needed
if the function is never called the padding bit info is ignored
this MUST be called on an existin sample*/
GF_Err gf_isom_set_sample_padding_bits(GF_ISOFile *the_file, u32 trackNumber, u32 sampleNumber, u8 NbBits);


/*since v2 you must specify w/h of video tracks for authoring tools (no decode the video cfg / first sample)*/
GF_Err gf_isom_set_visual_info(GF_ISOFile *the_file, u32 trackNumber, u32 StreamDescriptionIndex, u32 Width, u32 Height);

/*mainly used for 3GPP text since most ISO-based formats ignore these (except MJ2K) 
all coord values are expressed as 16.16 fixed point floats*/
GF_Err gf_isom_set_track_layout_info(GF_ISOFile *the_file, u32 trackNumber, u32 width, u32 height, s32 translation_x, s32 translation_y, s16 layer);

/*set SR & nbChans for audio description*/
GF_Err gf_isom_set_audio_info(GF_ISOFile *the_file, u32 trackNumber, u32 StreamDescriptionIndex, u32 sampleRate, u32 nbChannels, u8 bitsPerSample);

/*non standard extensions: set/remove a fragment of a sample - this is 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*/
GF_Err gf_isom_add_sample_fragment(GF_ISOFile *the_file, u32 trackNumber, u32 sampleNumber, u16 FragmentSize);
GF_Err gf_isom_remove_sample_fragment(GF_ISOFile *the_file, u32 trackNumber, u32 sampleNumber);
/*remove all sample fragment info for this track*/
GF_Err gf_isom_remove_sample_fragments(GF_ISOFile *the_file, u32 trackNumber);

/*set CTS unpack mode (used for B-frames & like): in unpack mode, each sample uses one entry in CTTS tables
unpack=0: set unpack on - !!creates a CTTS table if none found!!
unpack=1: set unpack off and repacks all table info
*/
GF_Err gf_isom_set_cts_packing(GF_ISOFile *the_file, u32 trackNumber, Bool unpack);
/*modify CTS offset of a given sample (used for B-frames) - MUST be called in unpack mode only*/
GF_Err gf_isom_modify_cts_offset(GF_ISOFile *the_file, u32 trackNumber, u32 sample_number, u32 offset);
/*remove CTS offset table (used for B-frames)*/
GF_Err gf_isom_remove_cts_info(GF_ISOFile *the_file, u32 trackNumber);

/*set 3char code media language*/
GF_Err gf_isom_set_media_language(GF_ISOFile *the_file, u32 trackNumber, char *three_char_code);

/*removes given stream description*/
GF_Err gf_isom_remove_sample_description(GF_ISOFile *the_file, u32 trackNumber, u32 streamDescIndex);

/*
	some authoring extensions
*/
/*sets name for authoring - if name is NULL reset authoring name*/
GF_Err gf_isom_set_track_name(GF_ISOFile *the_file, u32 trackNumber, char *name);
/*gets authoring name*/
const char *gf_isom_get_track_name(GF_ISOFile *the_file, u32 trackNumber);

/*
			MPEG-4 Extensions
*/

/*set a profile and level indication for the movie iod (created if needed)
if the flag is ProfileLevel is 0 this means the movie doesn't require
the specific codec (equivalent to 0xFF value in MPEG profiles)*/
GF_Err gf_isom_set_pl_indication(GF_ISOFile *the_file, u8 PL_Code, u8 ProfileLevel);

/*set the rootOD ID of the movie if you need it. By default, movies are created without root ODs*/
GF_Err gf_isom_set_root_od_id(GF_ISOFile *the_file, u32 OD_ID);

/*set the rootOD URL of the movie if you need it (only needed to create empty file pointing 
to external ressource)*/
GF_Err gf_isom_set_root_od_url(GF_ISOFile *the_file, char *url_string);

/*remove the root OD*/
GF_Err gf_isom_remove_root_od(GF_ISOFile *the_file);

/*Add a system descriptor to the OD of the movie*/
GF_Err gf_isom_add_desc_to_root_od(GF_ISOFile *the_file, GF_Descriptor *theDesc);

/*add a track to the root OD*/
GF_Err gf_isom_add_track_to_root_od(GF_ISOFile *the_file, u32 trackNumber);

/*remove a track to the root OD*/
GF_Err gf_isom_remove_track_from_root_od(GF_ISOFile *the_file, u32 trackNumber);

/*Create a new StreamDescription (GF_ESD) in the file. The URL and URN are used to 
describe external media, this will creat a data reference for the media*/
GF_Err gf_isom_new_mpeg4_description(GF_ISOFile *the_file, u32 trackNumber, GF_ESD *esd, char *URLname, char *URNname, u32 *outDescriptionIndex);

/*use carefully. Very usefull when you made a lot of changes (IPMP, IPI, OCI, ...)
THIS WILL REPLACE THE WHOLE DESCRIPTOR ...*/
GF_Err gf_isom_change_mpeg4_description(GF_ISOFile *the_file, u32 trackNumber, u32 StreamDescriptionIndex, GF_ESD *newESD);

/*Add a system descriptor to the ESD of a stream - you have to delete the descriptor*/
GF_Err gf_isom_add_desc_to_description(GF_ISOFile *the_file, u32 trackNumber, u32 StreamDescriptionIndex, GF_Descriptor *theDesc);


/*Default extensions*/

/*Create a new unknown StreamDescription in the file. The URL and URN are used to 
describe external media, this will creat a data reference for the media
use this to store media not currently supported by the ISO media format
*/
GF_Err gf_isom_new_generic_sample_description(GF_ISOFile *the_file, u32 trackNumber, char *URLname, char *URNname, GF_GenericSampleDescription *udesc, u32 *outDescriptionIndex);

/*change the data field of an unknown sample description*/
GF_Err gf_isom_change_generic_sample_description(GF_ISOFile *the_file, u32 trackNumber, u32 StreamDescriptionIndex, GF_GenericSampleDescription *udesc);

/*
special shortcut for stream description cloning from a given input file (this avoids inspecting for media type)
@the_file, @trackNumber: destination file and track
@orig_file, @orig_track, @orig_desc_index: orginal file, track and sample description
@URLname, @URNname, @outDescriptionIndex: same usage as with gf_isom_new_mpeg4_description
*/
GF_Err gf_isom_clone_sample_description(GF_ISOFile *the_file, u32 trackNumber, GF_ISOFile *orig_file, u32 orig_track, u32 orig_desc_index, char *URLname, char *URNname, u32 *outDescriptionIndex);

/*special shortcut: clones a track (everything except media data and sample info (DTS? CTS, RAPs, etc...) 
also clones sampleDescriptions
@keep_data_ref: if set, external data references are kept, otherwise they are removed (track media data will be self-contained)
@dest_track: track number of cloned track*/
GF_Err gf_isom_clone_track(GF_ISOFile *orig_file, u32 orig_track, GF_ISOFile *dest_file, Bool keep_data_ref, u32 *dest_track);
/*special shortcut: clones IOD PLs from orig to dest if any*/
GF_Err gf_isom_clone_pl_indications(GF_ISOFile *orig, GF_ISOFile *dest);
/*clones root OD from input to output file, without copying root OD track references*/
GF_Err gf_isom_clone_root_od(GF_ISOFile *input, GF_ISOFile *output);

/*returns true if same set of sample description in both tracks - this does include self-contained checking
and reserved flags. The specific media cfg (DSI & co) is not analysed, only
a brutal memory comparaison is done*/
Bool gf_isom_is_same_sample_description(GF_ISOFile *f1, u32 tk1, GF_ISOFile *f2, u32 tk2);

GF_Err gf_isom_set_JPEG2000(GF_ISOFile *mov, Bool set_on);

/*
			Movie Fragments Writing API
		Movie Fragments is a feature of ISO media files for fragmentation
	of a presentation meta-data and interleaving with its media data.
	This enables faster http fast start for big movies, and also reduces the risk
	of data loss in case of a recording crash, because meta data and media data
	can be written to disk at regular times
		This API provides simple function calls to setup such a movie and write it
	The process implies:
		1- creating a movie in the usual way (track, stream descriptions, (IOD setup
	copyright, ...)
		2- possibly add some samples in the regular fashion
		3- setup track fragments for all track that will be written in a fragmented way
	(note that you can create/write a track that has no fragmentation at all)
		4- finalize the movie for fragmentation (this will flush all meta-data and 
	any media-data added to disk, ensuring all vital information for the presentation
	is stored on file and not lost in case of crash/poweroff)
	
	  then 5-6 as often as desired
		5- start a new movie fragment
		6- add samples to each setup track


  IMPORTANT NOTES:
		* Movie Fragments can only be used in GF_ISOM_OPEN_WRITE mode (capturing)
  and no editing functionalities can be used
		* the fragmented movie API uses TrackID and not TrackNumber 
*/

/*
setup a track for fragmentation by specifying some default values for 
storage efficiency
*TrackID: track identifier
*DefaultStreamDescriptionIndex: the default description used by samples in this track
*DefaultSampleDuration: default duration of samples in this track
*DefaultSampleSize: default size of samples in this track (0 if unknown)
*DefaultSampleIsSync: default key-flag (RAP) of samples in this track
*DefaultSamplePadding: default padding bits for samples in this track
*DefaultDegradationPriority: default degradation priority for samples in this track

*/
GF_Err gf_isom_setup_track_fragment(GF_ISOFile *the_file, u32 TrackID, 
							 u32 DefaultStreamDescriptionIndex,
							 u32 DefaultSampleDuration,
							 u32 DefaultSampleSize,
							 u8 DefaultSampleIsSync,
							 u8 DefaultSamplePadding,
							 u16 DefaultDegradationPriority);

/*flushes data to disk and prepare movie fragmentation*/
GF_Err gf_isom_finalize_for_fragment(GF_ISOFile *the_file);

/*starts a new movie fragment*/
GF_Err gf_isom_start_fragment(GF_ISOFile *the_file);


enum
{
	/*indicates that the track fragment has no samples but still has a duration
	(silence-detection in audio codecs, ...). 
	param: indicates duration*/
	GF_ISOM_TRAF_EMPTY,
	/*I-Frame detection: this can reduce file size by detecting I-frames and
	optimizing sample flags (padding, priority, ..)
	param: on/off (0/1)*/
	GF_ISOM_TRAF_RANDOM_ACCESS,
	/*activate data cache on track fragment. This is usefull when writing interleaved
	media from a live source (typically audio-video), and greatly reduces file size
	param: Number of samples (> 1) to cache before disk flushing. You shouldn't try 
	to cache too many samples since this will load your memory. base that on FPS/SR*/
	GF_ISOM_TRAF_DATA_CACHE
};

/*set options. Options can be set at the begining of each new fragment only, and for the
lifetime of the fragment*/
GF_Err gf_isom_set_fragment_option(GF_ISOFile *the_file, u32 TrackID, u32 Code, u32 param);


/*adds a sample to a fragmented track

*TrackID: destination track
*sample: sample to add
*StreamDescriptionIndex: stream description for this sample. If 0, the default one 
is used
*Duration: sample duration.
Note: because of the interleaved nature of the meta/media data, the sample duration
MUST be provided (in case of regular tracks, this was computed internally by the lib)
*PaddingBits: padding bits for the sample, or 0
*DegradationPriority for the sample, or 0

*/

GF_Err gf_isom_fragment_add_sample(GF_ISOFile *the_file, u32 TrackID, GF_ISOSample *sample, 
								 u32 StreamDescriptionIndex, 
								 u32 Duration,
								 u8 PaddingBits, u16 DegradationPriority);

/*appends data into last sample of track for video fragments/other media
CANNOT be used with OD tracks*/
GF_Err gf_isom_fragment_append_data(GF_ISOFile *the_file, u32 TrackID, char *data, u32 data_size, u8 PaddingBits);



/******************************************************************
		GENERIC Publishing API
******************************************************************/

/*Removes all sync shadow entries for a given track. The shadow samples are NOT removed; they must be removed
by the user app*/
GF_Err gf_isom_remove_sync_shadows(GF_ISOFile *the_file, u32 trackNumber);