mptestdemo readme file
**********************************

Introduction:
_____________

The mptestdemo demonstrates how to use the Media Parsing (MP) functions
in the Media Tooklit (MTK).  Reference the Dialogic(R) Media Toolkit
Library Reference for a description of the MP APIs.

The MP APIs allow applications to retrieve file information from multimedia
files.  The types of files supported are ISO-based files (like 3GP/MP4) and
Dialogic proprietary media format (DMF) files.  The information retrieved
from the files is grouped into file-level/presentation information and
stream/codec-based information.

The mptestdemo code (mptestdemo.cpp) demonstrates simple usage of the four
MP APIs in the correct order for retrieving file information:
   1. mp_OpenFile()
   2. mp_GetFileInfoSize()
   3. mp_GetFileInfo()
   4. mp_CloseFile()
The mptestdemo code then displays the file information in an easily-readable
form.

Location:
_________

The source code is located in /usr/dialogic/demos/mptestdemo (along with this
readme file).

There is a pre-compiled binary/executable, named mptest, in /usr/dialogic/bin.
This executable is ready to run after the HMP installation.

There is also a makefile located with the source code which allows users to
build their own executable.  However, note that the makefile will build the 
target with the name mptestdemo, in order to not conflict with the
pre-compiled executable.



Command-Line Usage:
___________________

The following shows the command-line usage of mptest (or user-compiled mptestdemo),
which can also be seen by using the help:
> mptest -h

Usage: mptest [command options] filename
where commands options are:

Command options:
-h          Display this help screen and exit
-f<value>   File type:
               1  = ISO (any ISO-based file) - default
               2  = 3GP
               3  = MP4
               4  = F4V
               5  = 3G2
               6  = AVC
               10 = DMF (Dialogic proprietary)
-s          Ignore SDP information

The "-s" option, when used, allows the user to not display SDP information
if it in fact exists in the file.

The "-f" option is mandatory in order to display/retrieve information for 
DMF files.  For any supported ISO-based file (like 3GP, MP4, etc.), any
of the shown non-DMF values (currently 1-6) can be used for the file type.
Thus, the user can in fact skip the "-f" option for ISO-based files as the
default value is 1 for ISO.  However, note that part of the retrieved
information is the "real" file type, which uses the same values.  For example,
the user might specify the file as 3GP, but the retrieved information may
show that the file is actually MP4.


File Information:
_________________

For a complete description/format of the file information that can be
retrieved, please reference the Dialogic(R) Media Toolkit
Library Reference as well as the Media Parsing header file, mp_mtklib.h,
located in /usr/dialogic/inc.  As a quick overview, the file information
can be broken down as follows:

File-level info: file type, file version, number of audio/video tracks, etc.
Presentation-level info: creation time, duration, number of streams, etc.
Stream-level info: stream type (audio/video/hint), codec, bit rate,
                   frame rate, sampleCount, etc.
Codec-level info: codec-specific information like profile, level, etc.

Note that for DMF files, some of the information does not apply/exist.  For
example, there cannot be multiple tracks or even hint tracks in a DMF file.


Sampe Output:
_____________

The following shows a sample output from running mptest on a 3GP file that
contains H.264 as the video codec, AMR-NB as the audio codec, and also
contains hint tracks.

>mptest -f1 easy_H264_C_30_768.3gp

mptest - Dialogic Corporation 2011 - v1.0.51811

GETTING FILE INFO FROM easy_H264_C_30_768.3gp

File type is set as 1 (ISO)
	------------------------------------------------------
	File Info Descriptor:
	------------------------------------------------------
	   total size                      = 4522
	   file type                       = 2 (3GP)
	   format (major brand)            = 3gp6
	   version                         = 0 (v6.0.0)
	   compatible brands               = isom iso2 avc1 3gp6
	   flags                           = 0x00000000
	   num video tracks                = 1
	   Video Track Descriptor [0]:
	       stream ID                   = 1
	       num sync points             = 1

	   num audio tracks                = 1
	   Audio Track Descriptor [0]:
	       stream ID                   = 2

	   num video hint tracks           = 1
	   num audio hint tracks           = 1
	------------------------------------------------------
	Presentation Block Info:
	------------------------------------------------------
	   blk size                        = 1048
	   blk type                        = 1 (Presentation)
	   creation time                   = Thu Jan  1 19:00:00 1970
	   duration                        = 60058 ms
	   stream count                    = 4
	   max interleave                  = 520 ms
	   session-level SDP size          = 119 bytes
=========================
b=AS:714a=x-copyright: MP4/3GP File hinted with GPAC 0.4.6-DEV (build 1) (C)2000-2005 - http://gpac.sourceforge.net=========================
	------------------------------------------------------
	Video Stream Info:
	------------------------------------------------------
	   blk size                        = 76
	   blk type                        = 4 (VIDEO)
	   stream ID                       = 1
	   codec                           = 3 (H264)
	   creation time                   = Thu Jan  1 19:00:00 1970
	   duration                        = 60058 ms
	   bitrate                         = 701.33 kbps
	   frame rate                      = 29.97 fps
	   sample rate (timescale )        = 60000 Hz
	   sample size                     = 0
	   max sample size                 = 26429
	   sample count                    = 1800
	   byte count                      = 5265034
	   media handler Name              = vide
	   width                           = 352 pixels
	   height                          = 288 pixels
	   layer                           = 0
	   horizontal resolution           = 72 dpi
	   vertical resolution             = 72 dpi
	   ------------------------------------------------------
	   H264 Codec Info:
	   ------------------------------------------------------
	      blk size                     = 1038
	      blk type                     = 22  (H264)
	      packetization mode           = 6   (H264_MODE1 (non-interleaved))
	      profile                      = 66  (Baseline)
	      profile_iop                  = 64 (0x40)
	      level                        = 20  (Level 2)
	      DCI size                     = 32 bytes
	      ===============================================
	      00 00 00 01 27 42 40 14 95 A8 58 25 B0 11 00 00 
	      03 03 E9 00 00 EA 60 04 00 00 00 01 28 CE 3C 80 
	      ===============================================
	      DCI size (ISO format)        = 35 bytes
	      ===============================================
	      01 42 40 14 FF E1 00 14 27 42 40 14 95 A8 58 25 
	      B0 11 00 00 03 03 E9 00 00 EA 60 04 01 00 04 28 
	      CE 3C 80 
	      ===============================================
	------------------------------------------------------
	Audio Stream Info:
	------------------------------------------------------
	   blk size                        = 68
	   blk type                        = 3 (AUDIO)
	   stream ID                       = 2
	   codec                           = 100 (AMR-NB)
	   creation time                   = Thu Jan  1 19:00:00 1970
	   duration                        = 60000 ms
	   bitrate                         = 12.80 kbps
	   frame rate                      = 50.00 fps
	   sample rate (timescale )        = 8000 Hz
	   sample size                     = 32
	   max sample size                 = 32
	   sample count                    = 3000
	   byte count                      = 96000
	   media handler Name              = soun
	   channel count                   = 2
	   bits per sample                 = 16 bits
	   ------------------------------------------------------
	   AMR Codec Info:
	   ------------------------------------------------------
	      blk size                     = 20
	      blk type                     = 10 (AMR)
	      packetization mode           = 8 (AMR_OCTET_ALIGN)
	      ptime                        = 0 (Unknown)
	      AMR mode set                 = 0x81FF - 4.75 5.15 5.90 6.70 7.40 7.95 10.2 12.2 AMR_SID NO_DATA kbits/s
	      mode chg period              = 0
	      frames / sample              = 1
	      vendor                       = FFMP
	------------------------------------------------------
	Hint Stream Info:
	------------------------------------------------------
	   blk size                        = 1108
	   blk type                        = 5 (HINT)
	   stream ID                       = 65536
	   codec                           = 1 (RTP)
	   creation time                   = Thu Nov 12 10:40:06 2009
	   duration                        = 60058 ms
	   bitrate                         = 18.43 kbps
	   frame rate                      = 29.97 fps
	   sample rate (timescale )        = 90000 Hz
	   sample size                     = 0
	   max sample size                 = 564
	   sample count                    = 1800
	   byte count                      = 138324
	   media handler Name              = hint
	   reference stream IDs            = 1 0 0 0
	   track-level SDP size            = 222 bytes
=========================
m=video 0 RTP/AVP 96b=AS:701a=rtpmap:96 H264/90000a=control:trackID=65536a=fmtp:96 profile-level-id=424014; packetization-mode=1; sprop-parameter-sets=J0JAFJWoWCWwEQAAAwPpAADqYAQ=,KM48gA==a=framesize:96 352-288=========================
	   ------------------------------------------------------
	   RTP Protocol Info:
	   ------------------------------------------------------
	      blk size                     = 28
	      blk type                     = 30 (RTP)
	      hint track version           = 1
	      hint version compatibility   = 1
	      max packet size              = 1406 bytes
	      RTP time base (timescale)    = 90000
	      flags                        = 0 (No flag)
	      RTP timestamp offset         = 0
	      RTP sequence offset          = 0
	------------------------------------------------------
	Hint Stream Info:
	------------------------------------------------------
	   blk size                        = 1108
	   blk type                        = 5 (HINT)
	   stream ID                       = 65537
	   codec                           = 1 (RTP)
	   creation time                   = Thu Nov 12 10:40:06 2009
	   duration                        = 60000 ms
	   bitrate                         = 19.20 kbps
	   frame rate                      = 50.00 fps
	   sample rate (timescale )        = 8000 Hz
	   sample size                     = 48
	   max sample size                 = 48
	   sample count                    = 3000
	   byte count                      = 144000
	   media handler Name              = hint
	   reference stream IDs            = 2 0 0 0
	   track-level SDP size            = 103 bytes
=========================
m=audio 0 RTP/AVP 97b=AS:13a=rtpmap:97 AMR/8000/1a=control:trackID=65537a=fmtp:97 octet-align=========================
	   ------------------------------------------------------
	   RTP Protocol Info:
	   ------------------------------------------------------
	      blk size                     = 28
	      blk type                     = 30 (RTP)
	      hint track version           = 1
	      hint version compatibility   = 1
	      max packet size              = 45 bytes
	      RTP time base (timescale)    = 8000
	      flags                        = 0 (No flag)
	      RTP timestamp offset         = 0
	      RTP sequence offset          = 0



