SIP SIMPLE Client SDK

h1. WIPVideo

Notes while video is a work in progress. Repository: http://devel.ag-projects.com/cgi-bin/darcsweb.cgi?r=saul/python-sipsimple-video;a=summary

h2. Dependencies

The following dependencies are required to build PJSIP with video support (including H264)

* SDL 2

* ffmpeg (libavformat, libswscale, libavcodec, libavutil)

* libx264

Versions I have tried:

* SDL (2.0.0-7655)

* ffmpeg (2.0 release)

* libx264 (snapshot-20130806-2245-stable)

h2. Patches

-If the above versions are used, PJSIP needs to be patched with the attached patch (avcodec.diff) or it won't compile. This does not occur when compiling it against the latest library versions on Debian unstable.- No longer needed.

h2. Installing dependencies (Debian / Ubuntu systems)

The situation here is a bit sad. Both Debian and Ubuntu ship with libav instead of FFmpeg, but libraries are called the same. PJSIP had to be patched in order to properly work with libav, and the patch as not yet been included upstream.

On Debian, when the Debian-Multimedia repositories are used (quite common) you get FFmpeg and not libav. Oh the joy!

Installing dependencies on Debian:

<pre>

apt-get install libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libsdl2-dev libx264-dev libavcodec-extra

</pre>

If using the Debian-Multimedia repositories, do not install libavcodec-extra.

Installing dependencies on Ubuntu:

<pre>

apt-get install libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libsdl2-dev libx264-dev libavcodec-extra53

</pre>

*Note on H.264 support*: In order to have H.264 support, FFmpeg (or libav) need to be compiled with support for it. The standard packages don't, hence the need for installing the libavcodec-extra packages.

h2. Compiling dependencies

All dependencies will be compiled to a directory in the user's HOME directory:

<pre>

export MY_VIDEO_LIBS=$HOME/work/ag-projects/video/local

</pre>

h3. libx264

<pre>

./configure --enable-shared --disable-avs --disable-swscale --disable-lavf --disable-ffms --disable-gpac --prefix=$MY_VIDEO_LIBS

make

make install

# If a 32bit build is wanted, then run this configure instead:

./configure --host=i386-apple-darwin --enable-shared --disable-avs --disable-swscale --disable-lavf --disable-ffms --disable-gpac --prefix=$MY_VIDEO_LIBS

</pre>

h3. ffmpeg

<pre>

# Some exports

export PKG_CONFIG_PATH=$MY_VIDEO_LIBS/lib/pkgconfig

./configure --enable-shared --disable-static --enable-memalign-hack --enable-gpl --enable-libx264 --prefix=$MY_VIDEO_LIBS --extra-cflags="`pkg-config --cflags x264`" --extra-ldflags="`pkg-config --libs x264`"

make

make install

# If a 32bit build is wanted do:

./configure --enable-shared --disable-static --enable-memalign-hack --enable-gpl --enable-libx264 --prefix=$MY_VIDEO_LIBS --extra-cflags="`pkg-config --cflags x264`" --extra-ldflags="`pkg-config --libs x264`" --cc="gcc -m32" --disable-asm

# TODO: I WANT MY ASM

</pre>

h3. SDL

*Note for Cocoa*: There is a bug in SDL, when a Cocoa window is closed, it brings up the next window in the z stack. There is no obvious solution for this, see SDL_cocoawindow.m

<pre>

./configure --disable-audio --prefix=$MY_VIDEO_LIBS

make

make install

# If a 32bit build is wanted:

CFLAGS="-arch i386" CXXFLAGS="-arch i386" LDFLAGS="-arch i386" ./configure --disable-audio --prefix=$MY_VIDEO_LIBS

</pre>

h2. Compiling PJSIP (pjsua, for testing)

<pre>

svn co http://svn.pjsip.org/repos/pjproject/trunk pjsip

cd pjsip

echo "#define PJMEDIA_HAS_VIDEO 1" > pjlib/include/pj/config_site.h

./configure --with-sdl=$MY_VIDEO_LIBS --with-ffmpeg=$MY_VIDEO_LIBS

# if a 32bit build is wanted:

# CFLAGS="-arch i386" CXXFLAGS="-arch i386" LDFLAGS="-arch i386" ./configure --with-sdl=$MY_VIDEO_LIBS --with-ffmpeg=$MY_VIDEO_LIBS

make dep

make

# pjsua will be located in pjsip-apps/bin/

</pre>

h2. Proposed API

API for video components is based on 2 different types of video capable entities:

* VideoProducer: a source for video data, for example a video camera or a remote video stream

* VideoConsumer: a sink or destination for video data, for example a video rendering window

h3. Data flow

Data flow works in _pull_ fashion, that is, a producer doesn't start to produce data until there is a consumer which will consume it.

h3. VideoProducer

Produces video data. 

Internal API:

* _add_consumer: attach a consumer, called by the consumer

* _remove_consumer: detach a consumer from a producer, called by the consumer

Public API:

* start: start producing video as soon as a consumer is attached

* stop: immediately stop producing data

* close: remove all consumers and stop producing video data (also deallocate all C structures)

* producer_port: pointer to the pjmedia_port object

h3. VideoConsumer

Consumes video data.

Public API:

* producer: (r/w property) attach this consumer to a producer, in order to render the video data generated by the producer. If set to None, it's detached

* consumer_port: pointer to the pjmedia_port object

* close: detach from producer and free all resources (also deallocate all C structures)

h3. Producer and consumer objects

* VideoDevice: Producer, acquires video from a user camera.

* VideoWindow: Consumer, renders video in an SDL window. Extra methods: show/hide. Properties: native_handle, size.

* LocalVideoStream: Consumer, takes video from a VideoDevice and sends it to the remote party.

* RemoteVideoStream: Producer, produces video sent by the remote party.

These are just theoretical objects, won't be implemented in the first go.

* VideoFileWriter: Consumer, saves incoming video data to a video file.

* VideoFilePlayer: Producer, produces video data out of a video file.

* VideoMixer: Producer/Consumer, consumes video from multiple sources and produces aggregated video data.

NOTE: pjsip does have a AVI file player, which also seems to support audio.

h2. H264

Information about H264 profiles:

* http://en.wikipedia.org/wiki/H.264/MPEG-4_AVC#Levels

* https://supportforums.cisco.com/blog/149561/video-telepresence-sip-h264-profile-level-id

h2. OpenH264 implementation

PJSIP has an initial version of a wrapper for Cisco's OpenH264 implementation (http://www.openh264.org/). http://trac.pjsip.org/repos/changeset?reponame=&old=4815%40%2F&new=4815%40%2F

OpenH264 seems to implement SVC, which is better than AVC.