================================================================================
Stagefright Plugins for Android
================================================================================

1. Enhance the Android multimedia framework providing additional Plugins for
   user interaction
2. FFmpeg provides demuxers and av codecs;
3. NamExtractor is a extractor plugin, it would be loaded by Stagefright when 
   Stagefright started. NamExtractor will load FFmpegExtractor.FFmpegExtractor
   is the reference to "ffmpeg/ffplay" to achieve. 
4. libstagefright_soft_ffmpegvdec plugin is video decoder
5. libstagefright_soft_ffmpegadec plugin is audio decoder

================================================================================
Why is named nam[NamExtractor]?
================================================================================

Namtso, or Lake Nam, is one of the three holy lakes in Tibet Autonomous Region
and should not be missed by any traveler to Tibet. In Tibetan, Namtso means
"Heavenly Lake." It is famous for its high altitude and imposing scenery.

I used to travel there in 2011 Sep.

================================================================================
Requirements
================================================================================

CyanogenMod 9.x (Ice Cream Sandwich)
http://wiki.cyanogenmod.com/wiki/Galaxy_Nexus_(GSM):_Compile_CyanogenMod_(Linux)

FFMPEG-1.0 release
http://ffmpeg.org
ref: git://android.git.linaro.org/platform/external/ffmpeg.git

================================================================================
How to build
================================================================================

1. Get the Source
   clone cm-9.1.0 source from CyanogenMod git:
       repo init -u git://github.com/CyanogenMod/android.git -b cm-9.1.0
   plz ref: http://wiki.cyanogenmod.com/wiki/Galaxy_Nexus_(GSM):_Compile_CyanogenMod_(Linux)

   clone my sources from the omxcodec{github} git!
   in your "android/external" folder, run:
   stagefright-plugins:
       git clone git@github.com:omxcodec/stagefright-plugins.git stagefright-plugins
   ffmpeg:
       git clone git@github.com:omxcodec/android_external_ffmpeg.git ffmpeg -b omxcodec-1.0

   in your "android/external" folder, run:
   cp stagefright-plugins/repo/local_manifest.xml ../.repo
   cd ..      // go to android folder
   repo sync  // sync "frameworks_base" code again!

   "repo sync" sync "frameworks_base" code again! of course, you can merge my
   android_external_ffmpeg code instread of "repo sync" frameworks_base. once you do,
   so you should pay attention to the "USES_NAM" flag, it is only in the
   "android/frameworks/base" directory
 
2. Compile
   add USES_NAM flag to COMMON_GLOBAL_CFLAGS in android build system
       vi vendor/samsung/maguro/BoardConfigVendor.mk and add these lines to it
           USES_NAM := true
           ifdef USES_NAM
               COMMON_GLOBAL_CFLAGS += -DUSES_NAM
           endif

   ffmpeg:
       cd android/external/ffmpeg
       mm ffmpeg  // NOT "mm", plz FIXME!

       cd android/external/stagefright-plugins
       mm

3. Install
   adb root
   adb remount
   adb sync // sync your android build system to your phone or pad
   reboot   // reboot your phone or pad

4. Run
   get test media files:
       wget http://movies.apple.com/media/us/ipad/2012/tv-spots/apple-ipad-this_good-us-20120307_848x480.mov
       wget http://movies.apple.com/media/us/ipad/2012/80ba527a-1a34-4f70-aae8-14f87ab76eea/tours/apple-ipad-feature-us-20120307_848x480.mp4

   let us suppose your media files locate at "/sdcard/Movies/" folder.
   one console window, you should run:
       adb logcat
   and other cosole window, you should run:
   test NamExtractor and FFmpegExtractor plugins:
       adb shell am start -a android.intent.action.VIEW -d file:///mnt/sdcard/Movies/apple-ipad-this_good-us-20120307_848x480.mov -t video/*
       adb shell am start -a android.intent.action.VIEW -d file:///mnt/sdcard/Movies/apple-ipad-feature-us-20120307_848x480.mp4 -t video/*
   test SoftFFmpegVideo decoder plugin:
       cd android/external/stagefright-plugins/tools folder, run:
       adb root
       ./install // install my scripts
       adb root && adb shell set-vdec-sw1 // let omxcodec choose software decoder
       adb shell am start -a android.intent.action.VIEW -d file:///mnt/sdcard/Movies/apple-ipad-this_good-us-20120307_848x480.mov -t video/*
       adb shell am start -a android.intent.action.VIEW -d file:///mnt/sdcard/Movies/apple-ipad-feature-us-20120307_848x480.mp4 -t video/*

   run it and enjoy!

================================================================================
Features
================================================================================
Input formats:
    MP4 / MOV / 3GP
    TS / PS
    AVI
    ASF / WMV / WMA
    Matroska (MKV)
    Real(RM,RMVB)
    WAV
    FLV(H.264+AAC)

Video formats:
    MPEG-1/2
    MPEG-4
    H.263
    H.264 / MPEG-4 AVC
    WMV 1/2
    WMV 3 / WMV-9 / VC-1
    Real Video

Audio formats:
    MPEG Layer 1/2
    MP3 - MPEG Layer 3
    AAC - MPEG-4 part3
    AC3 - A/52 (Dolby Digital)
    WMA 1/2
    WMA 3
    Real Audio
    AMR (3GPP)
    APE
    DTS
    FLAC
    
================================================================================
Known issues
================================================================================
1. some .mov movies do not av resync when seeking
2. some video stream ended while seeking
3. more video and audio codecs codec to be integrated
4. more formats to be integrated

If you need help with the library, or just want to discuss nam related issues, 
you can contact me: Michael Chen (omxcodec@gmail.com)