Introduction

This libraries contains a collection of C++ (and sometimes C) libraries that AVPKit is letting loose on the world.

Our intention in open sourcing these libraries is to break down the walls of communication between people. To that end, a lot of these libraries deal with getting at raw data for different systems, and for helping people to share and create cool stuff using that data.

That said, it is not our intent to encourage people to use these libraries for illegal purposes, and we explicitly encourage people to respect the rights of others when they use these libraries.

Licensing

All AVPKit Open Source Libraries are released under the GNU Lesser General Public License v3 (LGPL). See the COPYING and COPYING.LESSER files in each library for details..

Libraries

Here is a brief summary of the current libraries in this release:

AVPKit's Core

A C++ Library for encoding and decoding pretty much any Internet available audio or video file. See com::avpkit::core.

This C++ library is a slightly simpler and safer C++ wrapper around the excellent FFMPEG libav* libraries. It also adds a reference-counted memory model so that ownership of objects can be shared.

It's main raison d'etre is to be plugged into other languages (e.g. Java, Python, etc.) and allow relatively safe encoding and decoding of video. It ships today with a Java wrapper (using the also excellent SWIG system).

We don't expect a lot of people to use the C++ interface directly (instead we expect people to use the Java interface), but we're not going to stop people either. The installation scripts should install all the header files you need, and the Java documentation is really just generated from the C++ documentation anyway, so have fun. Bear in mind that if you're #1 concern is performance, you should just use the libav interfaces in C directly. Why? Because we slightly favor protecting the programmer from themselves and ease of use over performance (the opposite of what FFMPEG favors; they slightly favor performance over protection and ease of use). What do we mean:

We copy data out of video frames upon a decode, and data out of packets on an encode into our own structures because FFMPEG will re-use the AVPacket and AVFrame buffers out from under you, and most other folks will be surprised if it just disappears (particularly true if a Java object passes a com::avpkit::core::IVideoPicture across a thread boundary).
We do error checking of arguments, whereas FFMPEG assumes you know what you're doing.
When encoding audio we'll queue up enough data for a audio frame to be encoded, whereas FFMPEG requires you to do that. (note: if you care about this, always pass in eactly one audio frame's worth of data for your given encoder and we won't do this).

All these things take CPU time and some memory space. In short, FFMPEG is a slightly faster but sharper knife, where as AVPKit is a slightly slower but safer knife. Still, you can make some real fancy dishes with either.

AVPKit's AVPKit IO

A C++ Library for allowing people to plug in custom data sources for FFMPEG to use. See com::avpkit::core::io.

By default FFMPEG can read files, and some other protocols (like http). Sometimes it can be useful to extend that, and the AVPKit IO library allows that. Again, it's main raison d'etre is to allow other languages (e.g. Java) to extend the data sources that can feed FFMPEG. See the Java FileProtocolHandler object for an example.

AVPKit's Ferry

A set of C++ and other language (e.g. Java) classes for ferrying data from other languages to C/C++ and back. See com::avpkit::ferry.

SWIG, an excellent utility for wrapping C/C++ code for other languages does a lot of great things. But sometimes it can use some help, and that's where this library comes in. This library implements the reference-counting memory scheme (used by the com::avpkit::core package) to allow C++ to pass objects in to other languages and relatively seemlessly integrate with their garbage collection systems. It also provides mechanism for allocating memory from the other language (instead of the C++ heap) to help that language keep track of memory, mechanisms for logging in the other language, and mechanisms for allowing the other language to directly modify C++/C memory (if possible). Most people won't use this outside of the AVPKit library, but if you're curious, go digging. It relies HEAVILY on SWIG for a lot of the heavy lifting.

Developer Notes

Thread Safety

The AVPKit library is not synchronized and callers must ensure multiple threads are not using the same object at the same time. For example, only one thread may encodeAudio on an IStreamCoder instance at a time.

For C++ we do not by default include any thread-locking library. If internal library synchronization is needed, we rely on the facilities of the runtime environment it's running in. That means in Java it uses the Java thread management libraries to ensure safety.

However if you're just running raw C++, then we don't use any threading library. In general that's fine. You need to follow these rules: 1) Ensure that only one AVPKit method is working on a AVPKit object at a time. So for example, if you're using IStreamCoder to decodeVideo into a IVideoPicture, make sure no other thread is using the IStreamCoder or the IVideoPicture at the time. 2) Unfortunately there is one area where you must provide a global lock. You must make sure that IStreamCoder::open on any IStreamCoder object is locked (FFMPEG requires this).

As mentioned earlier, we don't expect the C++ api to be used on its own, but if this proves wrong, we will consider adding threading (e.g. pthreads on Linux, w32threads on Windows) support if not running inside a Virtual Machine. Let us know.