1OpenH264 2======== 3OpenH264 is a codec library which supports H.264 encoding and decoding. It is suitable for use in real time applications such as WebRTC. See http://www.openh264.org/ for more details. 4 5Encoder Features 6---------------- 7- Constrained Baseline Profile up to Level 5.2 (Max frame size is 36864 macro-blocks) 8- Arbitrary resolution, not constrained to multiples of 16x16 9- Rate control with adaptive quantization, or constant quantization 10- Slice options: 1 slice per frame, N slices per frame, N macroblocks per slice, or N bytes per slice 11- Multiple threads automatically used for multiple slices 12- Temporal scalability up to 4 layers in a dyadic hierarchy 13- Simulcast AVC up to 4 resolutions from a single input 14- Spatial simulcast up to 4 resolutions from a single input 15- Long Term Reference (LTR) frames 16- Memory Management Control Operation (MMCO) 17- Reference picture list modification 18- Single reference frame for inter prediction 19- Multiple reference frames when using LTR and/or 3-4 temporal layers 20- Periodic and on-demand Instantaneous Decoder Refresh (IDR) frame insertion 21- Dynamic changes to bit rate, frame rate, and resolution 22- Annex B byte stream output 23- YUV 4:2:0 planar input 24 25Decoder Features 26---------------- 27- Constrained Baseline Profile up to Level 5.2 (Max frame size is 36864 macro-blocks) 28- Arbitrary resolution, not constrained to multiples of 16x16 29- Single thread for all slices 30- Long Term Reference (LTR) frames 31- Memory Management Control Operation (MMCO) 32- Reference picture list modification 33- Multiple reference frames when specified in Sequence Parameter Set (SPS) 34- Annex B byte stream input 35- YUV 4:2:0 planar output 36 37OS Support 38---------- 39- Windows 64-bit and 32-bit 40- Mac OS X 64-bit and 32-bit 41- Mac OS X ARM64 42- Linux 64-bit and 32-bit 43- Android 64-bit and 32-bit 44- iOS 64-bit and 32-bit 45- Windows Phone 32-bit 46 47Architectures verified to be working 48---------- 49- ppc64el 50 51Processor Support 52----------------- 53- Intel x86 optionally with MMX/SSE (no AVX yet, help is welcome) 54- ARMv7 optionally with NEON, AArch64 optionally with NEON 55- Any architecture using C/C++ fallback functions 56 57Building the Library 58-------------------- 59NASM needed to be installed for assembly code: workable version 2.10.06 or above, NASM can be downloaded from http://www.nasm.us/. 60For Mac OSX 64-bit NASM needed to be below version 2.11.08 as NASM 2.11.08 will introduce error when using RIP-relative addresses in Mac OSX 64-bit 61 62To build the arm assembly for Windows Phone, gas-preprocessor is required. It can be downloaded from git://git.libav.org/gas-preprocessor.git 63 64For Android Builds 65------------------ 66To build for android platform, You need to install android sdk and ndk. You also need to export `**ANDROID_SDK**/tools` to PATH. On Linux, this can be done by 67 68 export PATH=**ANDROID_SDK**/tools:$PATH 69 70The codec and demo can be built by 71 72 make OS=android NDKROOT=**ANDROID_NDK** TARGET=**ANDROID_TARGET** 73 74Valid `**ANDROID_TARGET**` can be found in `**ANDROID_SDK**/platforms`, such as `android-12`. 75You can also set `ARCH`, `NDKLEVEL` according to your device and NDK version. 76`ARCH` specifies the architecture of android device. Currently `arm`, `arm64`, `x86` and `x86_64` are supported, the default is `arm`. (`mips` and `mips64` can also be used, but there's no specific optimization for those architectures.) 77`NDKLEVEL` specifies android api level, the default is 12. Available possibilities can be found in `**ANDROID_NDK**/platforms`, such as `android-21` (strip away the `android-` prefix). 78 79By default these commands build for the `armeabi-v7a` ABI. To build for the other android 80ABIs, add `ARCH=arm64`, `ARCH=x86`, `ARCH=x86_64`, `ARCH=mips` or `ARCH=mips64`. 81To build for the older `armeabi` ABI (which has armv5te as baseline), add `APP_ABI=armeabi` (`ARCH=arm` is implicit). 82To build for 64-bit ABI, such as `arm64`, explicitly set `NDKLEVEL` to 21 or higher. 83 84For iOS Builds 85-------------- 86You can build the libraries and demo applications using xcode project files 87located in `codec/build/iOS/dec` and `codec/build/iOS/enc`. 88 89You can also build the libraries (but not the demo applications) using the 90make based build system from the command line. Build with 91 92 make OS=ios ARCH=**ARCH** 93 94Valid values for `**ARCH**` are the normal iOS architecture names such as 95`armv7`, `armv7s`, `arm64`, and `i386` and `x86_64` for the simulator. 96Another settable iOS specific parameter 97is `SDK_MIN`, specifying the minimum deployment target for the built library. 98For other details on building using make on the command line, see 99'For All Platforms' below. 100 101For Linux Builds 102-------------- 103 104You can build the libraries (but not the demo applications) using the 105make based build system from the command line. Build with 106 107 make OS=linux ARCH=**ARCH** 108 109 You can set `ARCH` according to your linux device . 110`ARCH` specifies the architecture of the device. Currently `arm`, `arm64`, `x86` and `x86_64` are supported 111 112 NOTICE: 113 If your computer is x86 architecture, for build the libnary which be used on arm/aarch64 machine, you may need to use cross-compiler, for example: 114 make OS=linux CC=aarch64-linux-gnu-gcc CXX=aarch64-linux-gnu-g++ ARCH=arm64 115 or 116 make OS=linux CC=arm-linux-gnueabi-gcc CXX=arm-linux-gnueabi-g++ ARCH=arm 117 118 119For Windows Builds 120------------------ 121 122"make" must be installed. It is recommended to install the Cygwin and "make" must be selected to be included in the installation. After the installation, please add the Cygwin bin path to your PATH. 123 124openh264/build/AutoBuildForWindows.bat is provided to help compile the libraries on Windows platform. 125Usage of the .bat script: 126 127 `AutoBuildForWindows.bat Win32-Release-ASM` for x86 Release build 128 `AutoBuildForWindows.bat Win64-Release-ASM` for x86_64 Release build 129 `AutoBuildForWindows.bat ARM64-Release-ASM` for arm64 release build 130for more usage, please refer to the .bat script help. 131 132For All Platforms 133------------------- 134 135Using make 136---------- 137 138From the main project directory: 139- `make` for automatically detecting architecture and building accordingly 140- `make ARCH=i386` for x86 32-bit builds 141- `make ARCH=x86_64` for x86 64-bit builds 142- `make ARCH=arm64` for arm64 Mac 64-bit builds 143- `make V=No` for a silent build (not showing the actual compiler commands) 144- `make DEBUGSYMBOLS=True` for two libraries, one is normal libraries, another one is removed the debugging symbol table entries (those created by the -g option) 145 146The command line programs `h264enc` and `h264dec` will appear in the main project directory. 147 148A shell script to run the command-line apps is in `testbin/CmdLineExample.sh` 149 150Usage information can be found in `testbin/CmdLineReadMe` 151 152Using meson 153----------- 154 155Meson build definitions have been added, and are known to work on Linux 156and Windows, for x86 and x86 64-bit. 157 158See <http://mesonbuild.com/Installing.html> for instructions on how to 159install meson, then: 160 161``` shell 162meson builddir 163ninja -C builddir 164``` 165 166Run the tests with: 167 168``` shell 169meson test -C builddir -v 170``` 171 172Install with: 173 174``` shell 175ninja -C builddir install 176``` 177 178Using the Source 179---------------- 180- `codec` - encoder, decoder, console (test app), build (makefile, vcproj) 181- `build` - scripts for Makefile build system 182- `test` - GTest unittest files 183- `testbin` - autobuild scripts, test app config files 184- `res` - yuv and bitstream test files 185 186Known Issues 187------------ 188See the issue tracker on https://github.com/cisco/openh264/issues 189- Encoder errors when resolution exceeds 3840x2160 190- Encoder errors when compressed frame size exceeds half uncompressed size 191- Decoder errors when compressed frame size exceeds 1MB 192- Encoder RC requires frame skipping to be enabled to hit the target bitrate, 193 if frame skipping is disabled the target bitrate may be exceeded 194 195License 196------- 197BSD, see `LICENSE` file for details. 198