rmmp4api.h

Sigma SMP8634 Mrua v. 2.8.2.0

/*****************************************
 Copyright � 2001-2003  
 Sigma Designs, Inc. All Rights Reserved
 Proprietary and Confidential
 *****************************************/

/** 
 * @defgroup mp4api Mpeg4 File playback
 * @ingroup rmfmodules
 *  
 * These functions allow you to play local Mpeg4, DivX4/5
 * or pure Mpeg4 video files. You can also play
 * streamed Mpeg4 files with these functions.
 * 
 **/


/**
  @file   rmmp4api.h
  @brief  Describes the external API of the MP4 module.

  @ingroup mp4api
  @author Julien Soulier
  @date   2001-10-15
*/

#ifndef __RMMP4API_H__
#define __RMMP4API_H__

/*@{*/

#include "../../rmmpeg4types/rmmpeg4types.h"
#include "../../rmlibcw/include/rmfile.h"

/** opaque handle on Mp4 client. */
typedef struct _RMmp4Client *ExternalRMmp4Client;
/** opaque handle on Mp4 client track. */
typedef struct _RMmp4Track  *ExternalRMmp4Track;

/**
   Open a Darwin mpeg4 client. The url must thus start with a
   rtsp:// string.

   @param url  url to open. 
   @param mp4c returned client.  
   @return RM_ERROR if the url is not valid.
           RM_ERROR_NOT_MP4 if the url is not a mp4 url. 
*/
RM_EXTERN_C RMstatus RMOpenUrlMP4(const RMascii *url, 
				  ExternalRMmp4Client *mp4c);

/**
   Open a Darwin mpeg4 client for broadcast session using an local sdp file. 

   @param fileName : file containing the initialization infos. 
   @param mp4c returned client.  
   @return RM_ERROR if the url is not valid.
           RM_ERROR_NOT_MP4 if the url is not a mp4 url. 
*/
RM_EXTERN_C RMstatus RMOpenSdpFileMP4(const RMnonAscii *fileName, 
				      ExternalRMmp4Client *mp4c);

/**
   Opens a mp4 client on a local file.

   @param filename file to open.
   @param mp4c returned client.
   @param fileType can be MPEG4/DIVX/MPEG4VIDEO
   @return RM_ERROR if the url is not valid.
           RM_ERROR_NOT_MP4 if the url is not a mp4 url.  
*/
RM_EXTERN_C RMstatus RMOpenFileMP4(const RMnonAscii *filename,
				   RMascii *fileType,
				   ExternalRMmp4Client *mp4c);


/**
   Opens a mp4 client on a local file.

   @param file a file already opened by application. This allows application to implement its own file operations.
   @param mp4c returned client.
   @param fileType can be MPEG4/DIVX/MPEG4VIDEO
   @return RM_ERROR if the url is not valid.
           RM_ERROR_NOT_MP4 if the url is not a mp4 url.  
*/
RM_EXTERN_C RMstatus RMOpenExternalFileMP4(RMfile file, 
					   RMascii *fileType, 
					   ExternalRMmp4Client *mp4c);

/**
   Sends a play to the darwin server. This call must be done before
   trying to get any data. For a mp4 file it does nothing.
   
   @param mp4c client 
   @return RM_OK
*/
RM_EXTERN_C	RMstatus RMPlayMP4(ExternalRMmp4Client mp4c);


/**
   Sends a pause to the darwin server. No effect for a file client.
 
   @param mp4c client 
   @return RM_OK
*/
RM_EXTERN_C	RMstatus RMPauseMP4(ExternalRMmp4Client mp4c);


/**
   Sends a stop to the darwin server. No effect for a file client. 
   
   @param mp4c client 
   @return RM_OK
*/
RM_EXTERN_C	RMstatus RMStopMP4(ExternalRMmp4Client mp4c);


/**
   Seeks to the time in seconds in the movie. 
   
   @param mp4c client 
   @param time  time in seconds from the beginning to seek to.
   @return time in second we really seek.
*/
RM_EXTERN_C RMreal RMSeekMP4(ExternalRMmp4Client mp4c, RMreal time);

/**
   Seeks to the time in milliseconds in the movie. 
   
   @param mp4c client 
   @param time_ms  time in milliseconds from the beginning to seek to.
   @return time in milliseconds we really seeked to.
*/
RM_EXTERN_C RMuint32 RMSeekMP4millisec(ExternalRMmp4Client mp4c, RMuint32 time_ms);

/**
   Prints debug output concerning the opened mp4 presentation.

   @param mp4c client
*/
RM_EXTERN_C void RMPrintMP4(ExternalRMmp4Client mp4c);


/**
   Tries to get a video track ID contained in the mp4 presentation.

   @param mp4c client 
   @return trackID if there is a valid video track
           0 if there is no video track.
*/
RM_EXTERN_C RMuint32 RMGetMP4VideoTrackID(ExternalRMmp4Client mp4c);


/**
   Tries to get an audio track ID contained in the mp4 presentation.

   @param mp4c client 
   @return trackID if there is a valid audio track
           0 if there is no audio track.
*/
RM_EXTERN_C RMuint32 RMGetMP4AudioTrackID(ExternalRMmp4Client mp4c);


/**
   Opens a mpeg-4 track from the presentation.

   @param mp4c client 
   @param trackID       
   @return valid track handle
           NULL if the trackID is not valid.
*/
RM_EXTERN_C ExternalRMmp4Track RMOpenMP4Track(ExternalRMmp4Client mp4c,
					      RMuint32 trackID);


/**
   Closes the mpeg-4 track.

   @param mp4c  client
   @param mp4t  track to close
*/
RM_EXTERN_C void RMCloseMP4Track(ExternalRMmp4Client mp4c, 
				 ExternalRMmp4Track mp4t);


/**
   Closes the mp4 client.

   @param mp4c client
*/
RM_EXTERN_C void RMCloseMP4(ExternalRMmp4Client mp4c);


/* MP4 TRACK INTERFACE */

/**
   Prints debug output from the track.

   @param mp4t track
*/
RM_EXTERN_C void RMPrintMP4Track(ExternalRMmp4Track mp4t);


/**
   Dumps the track bitstream in a file. The dumped data does not
   contained the DSI.

   @param mp4t  
   @param dumpname is a pointer to a buffer of bytes that may contain
   a traditional representation of a filename (char*) but also a 
   unicode representation.
*/
RM_EXTERN_C void RMDumpMP4Track(ExternalRMmp4Track mp4t, 
				const RMuint8 *dumpname);


/**
   Gets the timescale for this track. This is the number of CTS units
   per second.

   @param mp4t track
   @return timescale
*/
RM_EXTERN_C RMuint32 RMGetMP4TrackTimeScale(ExternalRMmp4Track mp4t);


/**
   Gets the size in bytes of the next sample to get.

   @param mp4t track
   @return size of the next sample.
*/
RM_EXTERN_C RMuint32 RMGetNextMP4SampleSize(ExternalRMmp4Track mp4t);


/**
   Gets the next sample. The sample buffer must be allocated before
   calling this function. It should be allocated fot maxSize. If the
   sample size is lesser than maxSize, then the sample contains the
   complete Access Unit. Otherwise the sample contains only maxSize of
   the AU. In case of an incomplete AU, the next call will send the
   rest of the AU. There are flags in the sample to tell if this
   sample contained the beginning of an AU and if it is also the end
   of one.

   @param mp4t track
   @param mp4s sample 
   @param maxSize size of the allocated buffer in sample      
   @return TRUE if there the sample returned is valid.
           FALSE if the sample is not valid. (normally end of track)
*/
RM_EXTERN_C RMbool RMGetNextMP4Sample(ExternalRMmp4Track mp4t, 
				      RMmp4Sample *mp4s, 
				      RMuint32 maxSize);



/**
   Works as the get next sample but gets only the I frames.

   @param mp4t track
   @param mp4s sample 
   @param maxSize size of the allocated buffer in sample      
   @return TRUE if there the sample returned is valid.
           FALSE if the sample is not valid. (normally end of track)
*/
RM_EXTERN_C RMbool RMGetNextMP4RandomAccessSample(ExternalRMmp4Track mp4t, RMmp4Sample *mp4s, RMuint32 maxSize);

     
/**
   Works as the get next sample but gets only the I frames and it goes backward.
   
   @param mp4t track
   @param mp4s sample 
   @param maxSize size of the allocated buffer in sample      
   @return TRUE if there the sample returned is valid.
           FALSE if the sample is not valid. (normally end of track)
*/
RM_EXTERN_C RMbool RMGetPrevMP4RandomAccessSample(ExternalRMmp4Track mp4t, RMmp4Sample *mp4s, RMuint32 maxSize);

/**
   Gets the DSI from the track. The buffer is allocated in this
   function. It is also freed when the track is closed.

   @param mp4t track
   @param size  size of the DSI
   @return dsi buffer
*/
RM_EXTERN_C RMuint8 *RMGetMP4TrackDSI(ExternalRMmp4Track mp4t, 
				      RMuint32 *size);

/**
   Returns the duration of the track in timescale unit.

   @param mp4t  
   @return track duration
*/
RM_EXTERN_C RMuint32 RMGetMP4TrackDuration(ExternalRMmp4Track mp4t);


/**
   returns the number of samples in this track.

   @param mp4t  
   @return 
*/
RM_EXTERN_C RMuint32 RMGetMP4TrackSampleCount(ExternalRMmp4Track mp4t);

/**
   Returns the amount of random access sample in the track.

   @param mp4t  
   @return 
*/
RM_EXTERN_C RMuint32 RMGetMP4TrackRandomAccessSampleCount(ExternalRMmp4Track mp4t);

/**
   Returns the vop time increment in timescale unit.

   @param mp4t  
   @return 
*/
RM_EXTERN_C RMuint32 RMGetMP4TrackVopTimeIncrement(ExternalRMmp4Track mp4t);



/*************************************** NeroDigital specific */

#define MP4_MAX_CHAPTER_NAME_LEN 256

RM_EXTERN_C RMstatus RMGetMP4ClosestChapter(ExternalRMmp4Client mp4c, RMuint32 currentTime_ms, RMuint32 *nextChapterTime_ms, RMuint8 *chapterName, RMuint32 maxNameLen, RMint32 chapter);
RM_EXTERN_C RMstatus RMGetMP4ChapterByIndex(ExternalRMmp4Client mp4c, RMuint32 index, RMuint32 *ChapterTime_ms, RMuint8 *chapterName, RMuint32 maxNameLen);
RM_EXTERN_C RMbool RMisNeroMP4(ExternalRMmp4Client mp4c);
RM_EXTERN_C RMbool RMcanNeroMP4bePlayed(ExternalRMmp4Client mp4c);
RM_EXTERN_C RMuint32 RMGetMP4NumberOfVideoTracks(ExternalRMmp4Client mp4c);
RM_EXTERN_C RMuint32 RMGetMP4NumberOfAudioTracks(ExternalRMmp4Client mp4c);
RM_EXTERN_C RMuint32 RMGetMP4NumberOfSPUTracks(ExternalRMmp4Client mp4c);
RM_EXTERN_C RMuint32 RMGetMP4NumberOfSubtitleTracks(ExternalRMmp4Client mp4c);
RM_EXTERN_C RMstatus RMGetMP4VideoTrackIDByIndex(ExternalRMmp4Client mp4c, RMuint32 index, RMuint32 *trackID);
RM_EXTERN_C RMstatus RMGetMP4AudioTrackIDByIndex(ExternalRMmp4Client mp4c, RMuint32 index, RMuint32 *trackID);
RM_EXTERN_C RMstatus RMGetMP4SPUTrackIDByIndex(ExternalRMmp4Client mp4c, RMuint32 index, RMuint32 *trackID);
RM_EXTERN_C RMstatus RMGetMP4SubtitleTrackIDByIndex(ExternalRMmp4Client mp4c, RMuint32 index, RMuint32 *trackID);
RM_EXTERN_C RMstatus RMGetMP4MovieTimescale(ExternalRMmp4Client mp4c, RMuint32 *timescale);
RM_EXTERN_C RMuint32 RMSeekMP4Track(ExternalRMmp4Client mp4c, RMuint32 time_ms, ExternalRMmp4Track mp4t);
RM_EXTERN_C RMstatus RMGetMP4TrackWidth(ExternalRMmp4Track mp4t, RMuint32 *width);
RM_EXTERN_C RMstatus RMGetMP4TrackHeight(ExternalRMmp4Track mp4t, RMuint32 *height);
RM_EXTERN_C RMstatus RMGetMP4TrackSize(ExternalRMmp4Track mp4t, RMuint32 *sizeTrack, RMuint32 *sampleCount);
RM_EXTERN_C RMstatus RMGetMP4TrackNextSampleSize(ExternalRMmp4Track mp4t, RMuint32 *size);
RM_EXTERN_C RMstatus RMGetMP4TrackNextReadPos(ExternalRMmp4Track mp4t, RMuint64 *nextReadPos);
RM_EXTERN_C RMstatus RMGetMP4TrackStartupDelay(ExternalRMmp4Track mp4t, RMuint32 *startup_delay);

RM_EXTERN_C RMbool   RMisH264Track(ExternalRMmp4Track mp4t);
RM_EXTERN_C RMstatus RMGetH264Level(ExternalRMmp4Track mp4t, RMuint32 *level);
RM_EXTERN_C RMstatus RMGetH264Profile(ExternalRMmp4Track mp4t, RMuint32 *profile);
RM_EXTERN_C RMstatus RMGetH264LengthSize(ExternalRMmp4Track mp4t, RMuint32 *lengthSize);

RM_EXTERN_C RMstatus RMGetMP4TrackType(ExternalRMmp4Track mp4t, RMmpeg4TrackType *type);
RM_EXTERN_C RMstatus RMGetMP4TrackSampleRate(ExternalRMmp4Track mp4t, RMuint32 *sampleRate);
RM_EXTERN_C RMstatus RMGetMP4TrackChannelCount(ExternalRMmp4Track mp4t, RMuint32 *channelCount);
RM_EXTERN_C RMstatus RMGetMP4TrackBitPerSample(ExternalRMmp4Track mp4t, RMuint32 *bitPerSample);

/** @} */

#endif // __RMMP4API_H__