Contents
Introduction
The FFMPEG library
Patching FFMPEG
Compiling on Unix
Compiling on Windows
Compiling OpenH323
Configuring on Unix
Configuring on Windows
Modifying applications
Running
Testing
Change history
Introduction
Thanks to the efforts of many people, a H.263 video codec that complies with RFC2190 is now available for OpenH323. This is the industry standard transport and encoding for H.263 as used by software such NetMeeting, and it's availability means that OpenH323 based endpoints can now interoperate with most other video based software.
The following people are responsible for this code:
Derek Smithies, coordinator and implementor of the OpenH323 video code
Guilhem Tardy, author of the RFC 2190 compliant H.263 interfaces
AliceStreet Ltd, who provided the funding for Guilhem
The FFMPEG Project, creators of the underlying H.263 codec
Craig Southeren, OpenH323 coordinator and co-founder
The FFMPEG library used to implement the H.263 codec uses the Library (or Lesser) GPL license, which does not permit directly linking with non-GPL code unless the entire application is available as source code. This is at odds with the MPL license used by OpenH323, which allows binary-only distrbutions under some circumstances. However, paragraph 6, clause b of the LGPL says it is acceptable to do the following:
b) Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (1) uses at run time a copy of the library already present on the user's computer system, rather than copying library functions into the executable, and (2) will operate properly with a modified version of the library, if the user installs one, as long as the modified version is interface-compatible with the version that the work was made with.
To comply with these terms, the FFMPEG library is not linked either statically or dynamically with OpenH323, but is loaded at run-time as a module under the explicit control of OpenH323. I have previously confirmed via email with Richard Stallman that this is a correct interpretation of the LGPL.
The FFMPEG library
To use H.263 with OpenH323, it is necessary to have compiled version of the ffmpeg library for your platform. It is recommended that you use of the precompiled libraries for Windows or Linux unless you have some specific need to alter the ffmpeg sources yourself
- For Linux, download header files and a recompiled library
- For Windows, download header files and a recompiled library
If you need to compile your own ffmpeg (perhaps for development purposes) then see the instructions below:
Patching ffmpeg
A fully patched version of the library can be downloaded from here
To create your own patched version, follow the instructions below:
- Download and extract version 0.4.7 of the ffmpeg library from http://sourceforge.net/projects/ffmpeg/ or download from here. Version 0.4.7 was used - later versions may work but are untested
- Downloaded the ffmpeg patches from Guilhem Tardys's site or download from here, and unzip the file
- Apply the patches using the the following command:
patch -p0 < ffmpeg-0.4.7.patch
Compiling for Unix
It is only necessary to follow these steps if you need to change or alter the ffmpeg library itself. If you are only compiling OpenH323 or your application, then please use the precompiled files.
- Configure and make ffmpeg using the following command:
./configure --enable-shared --disable-a52 --disable-pp --disable-ffserver --disable-ffplay
make
- The required file is located in libavcodec/libavcodec.so. If debug symbols are not required, the size of the file can be reduced significantly using the following command:
strip libavcodec/libavcodec.so
Windows
It is only necessary to follow these steps if you need to change or alter the ffmpeg library itself. If you are only compiling OpenH323 or your application, then please use the precompiled files.
ffmpeg can only be compiled on Windows using the MingW compiler. Once this is installed, the same procedure can be used to create the libavcodec.dll file as for Unix except that a different configure line is used, as follows:
make ./configure --extra-cflags="-mno-cygwin -mms-bitfields" --extra-ldflags="-Wl,--add-stdcall-alias" --enable-mingw32 --enable-shared --disable-a52 --disable-pp --disable-ffserver --disable-ffplay
Guilhem Tardy has additional information on compiling ffmpeg for Windows on his site
Compiling OpenH323
If you are using a version of OpenH323 after 1.14.1, then full support for H.263 is already included.
If you are using a version prior to this, then you will some additional code. See Guilhem Tardy's page for more information on this.
Unix
OpenH323 1.41.1 or later can be configured for H.263 using the following command line:
./configure --enable-rfc2190avcodec=dir
Where dir is either the directory ffmpeg/libavcodec (if the full sources are available) or the directory containing the "avcodec.h" and "common.h" header files (if the precompiled versions are used).
If successful, the configure output will contain the following:
...
checking /home/craigs/tmp/tmp/avcodec.h usability... yes
checking /home/craigs/tmp/tmp/avcodec.h presence... yes
checking for /home/craigs/tmp/tmp/avcodec.h... yes
configure: Skipping tests for VIC H.263 and non-standard H.263
...
OpenH323 can then be compiled as normal
Windows
When OpenH323 is compiled on Windows, the configure program will look for a file called "avcodec_rfc2190.h" to signify the presence of a patched version of ffmpeg. The precompiled files for Windows , and the prepatched ffmpeg library source already contain this file, but if you are patching your own ffmpeg sources then you will need to ensure this file is put into the directory that contains the libavcodec.dll and the header files
configure will show the following line when detects an ffmpeg that is compatible with RFC 2190:
Located ffmpeg RFC2190 AVCODEC Library at dir
Modifying applications
The exact modifications required to add RFC 2190 H.263 functions an application will vary, but they will normally require the following steps:
-
Remove any reference to the previous non-standard H.263 and VIC263 based codecs
-
Add '#include "rfc2190avcodec.h" '
-
Add the required capability called "H323_RFC2190_H263Capability"
Note that "#if H323_RFC2190_AVCODEC" can be used to enable condition inclusion of any code that requires this codec.
Running
At run-time, OpenH323 will look for the file libavcodec.so (or libavcodec.dll for Windows) in the directories specified by the environment variable PWLIBPLUGINDIR. If this variable is defined, it will look in the directory /usr/lib/pwlib (or C:\PWLIB_PLUGINS for Windows) unless the value of P_DEFAULT_PLUGIN_DIR was changed using configure.
If the libavcodec.so cannot be found, the following message is printed to stderr:
Cannot find libavcodec.so as required for RFC2190 H.263 video codec.
This function may appear to be installed, but will not operate correctly.
Please put the file libavcodec.so into one of the following directories:
/usr/lib/pwlib
This list of directories can be set using the PWLIBPLUGINDIR environment
Testing
Run ohphone with the following command:
./obj_linux_x86_d/ohphone --videoreceive null -Dgsm -n -l -D261 --videotransmit -a
NetMeeting can then be used to call this endpoint, and it will automatically answer and send video with a test pattern. Note that no video hardware is required for this test.
Change History
| 11 June 2004 | Craig Southeren | Updated links to Guilhem Tardy's pages |
| 25 May 2004 | Craig Southeren | Added extra Windows information Added links to Guilhem Tardy's pages |
| 23 April 2004 | Craig Southeren | Added links on contributors names Fixed spelling mistakes Added new information on LGPL interpretation |
| 22 April 2004 | Craig Southeren | Initial version |
