LibSourcey

Repository
https://github.com/sourcey/libsourcey
Licence
LGPL, Pro Licence
Required Dependencies
libuv, CMake, C++11 compiler
Optional Dependencies
FFmpeg (>= 2.8.3), OpenCV (>= 3.0), WebRTC, OpenSSL (> 1.0.1g), RtAudio, JsonCpp

LibSourcey Logo LibSourcey is a collection of open source cross platform C++11 modules and classes that provide developers with a flexible high performance arsenal for the rapid development of real-time messaging and live media streaming applications.

LibSourcey is built on top of Node.js’s underlying libuv library and utilises event-based asynchronous IO in to maximise performance and minimise concurrency reliance for building mission critical server-side applications. Modern C++11 design principles have been adhered to throughout for clear and readable code, and straighforward integration into existing projects.

For media streaming applications, LibSourcey provides a simple and flexible method of capturing live audio/video streams (OpenCV/FFmpeg), processing, filtering and encoding them using any video format (FFmpeg), and broadcasting the result over the Internet (libuv). This is made possible by implementing a thin layer over the top of some brilliant open source projects, such as FFmpeg, OpenCV and libuv. The only required third-party dependency is libuv, and that is included in the local source and compiled automatically. All others dependencies are optional.

Unfortunately documentation still a little sparse at this point, but we hope to change that in the near future. Until then, use the source, Luke!, and we welcome all community contributions to LibSourcey in order to promote the development of better real-time native and web applications

LibSourcey provides full support for the following protocols: TCP, SSL, UDP, HTTP, JSON, XML, STUN, SDP, SocketIO.
Partial support is provided for the following protocols: WebSockets, TURN, ICE, RTP, and XMPP.

Dependencies

Required: libuv, CMake, C++11 compiler (GCC, Visual Studio, Xcode)
Optional: FFmpeg (>= 2.8.3), OpenCV (>= 3.0), WebRTC, OpenSSL (>= 1.0.1g), RtAudio, JsonCpp

Installation

LibSourcey is designed to compile on any system with C++11 compiler, so it should compile on all Linux, Windows and Apple platforms.

Note: To compile LibSourcey with video and streaming capabilities enabled you should install the latest version of both FFmpeg and OpenCV, otherwise dependent modules and features will be disabled by default.

Installing on Linux

This guide is written for Ubuntu 14.04, but installation is super simple and should be fairly portable across most flavours of Linux.

Install Dependencies
sudo apt-get update
sudo apt-get install -y build-essential pkg-config git cmake openssl libssl-dev jackd2 libjack-jackd2-dev
Install FFmpeg (optional)

FFmpeg is an optional but recommended dependency that’s required to make use of LibSourcey’s media encoding capabilities.

Please follow the official guide for installing FFmpeg which works out of the box with LibSourcey.

Install OpenCV (optional)

OpenCV is an optional dependecy that’s used by LibSourcey for it’s video capture, video analysis and computer vision algorithms. Note that if you’re compiling FFmpeg yourself (as above), then you should compile OpenCV with WITH_FFMPEG=OFF otherwise conflicting FFmpeg libraries may be installed on your system.

cd ~/tmp
wget https://github.com/Itseez/opencv/archive/3.0.0.zip -O opencv-3.0.0.zip
unzip opencv-3.0.0.zip
cd opencv-3.0.0
mkdir build
cd build
cmake -D CMAKE_BUILD_TYPE=RELEASE -D CMAKE_INSTALL_PREFIX=/usr/local -D WITH_TBB=ON -D WITH_V4L=ON -D WITH_QT=ON -D WITH_OPENGL=ON -D WITH_FFMPEG=OFF ..
make -j $(nproc)
sudo make install
sudo /bin/bash -c 'echo "/usr/local/lib" > /etc/ld.so.conf.d/opencv.conf'
sudo ldconfig
Install LibSourcey
cd ~/tmp
git clone https://github.com/sourcey/libsourcey.git
cd libsourcey
mkdir build
cd build
cmake .. -D CMAKE_BUILD_TYPE=RELEASE # extra cmake commands here...
make
sudo make install

All done!

See here for a complete list of build options, and here for examples.

Installing on Windows

Install Dependencies
Install Git
Install TortoiseGit, a convenient git front-end that integrates right into Windows Explorer. MinGW users can use msysgit.
Install CMake
CMake generates the LibSourcey project files so you can build on most platforms and compilers. Download CMake
Install OpenSSL
Download and install the Windows OpenSSL binaries.
Download LibSourcey
Clone the repository: git clone https://github.com/sourcey/libsourcey.git.
If you haven’t got Git for some reason you can download and extract the package archive from Github.
Generate Project Files

Open the CMake GUI and set the project directory to point to the LibSourcey root directory. Execute “Configure” to do the initial configuration, then adjust any options, then press “Configure” again and then press “Generate”.

See here for a complete list of build options, and here for examples.

Compile with Visual Studio
  1. Generate solutions using CMake, as described above. Make sure, you chose the proper generator (32-bit or 64-bit)
  2. Launch Visual Studio, locate and open the “libsourcey.sln” solution file in your generated build folder (eg: C:\LibSourcey\build\libsourcey.sln). Select “Debug” configuration, build the solution (Ctrl-Shift-B), and/or select “Release” and build it.
  3. Add {CMAKE_BINARY_DIR}\bin\Release, {CMAKE_BINARY_DIR}\bin\Debug (containing “libscy.dll” and “libscyd.dll”, respectively) to the system path (My Computer–[Right button click]->Properties->Advanced->Environment Variables->Path)

Installing on Apple (MacOS)

Install Dependencies
Install Git
Download the latest Git installer package, double click on the installer to start the installation wizard. You’ll be prompted for your system password in order for the installer to complete.
Install CMake
CMake generates the LibSourcey project files so you can build on most platforms and compilers. Download CMake
Install OpenSSL
If you don’t already have OpenSSL development headers on your Mac, then please follow this guide to install them.
Download LibSourcey
Clone the repository: git clone https://github.com/sourcey/libsourcey.git.
If you haven’t got Git for some reason you can download and extract the package archive from Github.
Generate Project Files

Open the CMake GUI and set the project directory to point to the LibSourcey root directory. Execute “Configure” to do the initial configuration, then adjust any options, then press “Configure” again and then press “Generate”.

See here for a complete list of build options, and here for examples.

Compile with Xcode
  • Generate Xcode project using CMake, as described above.
  • Launch Xcode, locate and open libsourcey.xcodeproj. Select “Debug”, build the BUILD_ALL target (Cmd-B), select “Release” and build it too.
CMake Build Options

The main build options you will want to configure are as follows:

  • BUILD_SHARED_LIBS: Build shared libraries (.dll/.so) instead of static ones (.lib/.a). default: NOT (WIN32 OR ANDROID OR IOS)
  • BUILD_DEPENDENCIES: Build LibSourcey in source third-party dependencies. default: ON
  • BUILD_MODULES: Build LibSourcey modules. default: ON
  • BUILD_MODULE_xxx: Enable or disable a specific module replacing xxx with the module name.
  • BUILD_APPLICATIONS: Build LibSourcey modules default: ON
  • BUILD_APPLICATION_xxx: Enable or disable a specific applications replacing xxx with the module name.
  • BUILD_MODULE_TESTS: Build module test applications default: ON
  • BUILD_MODULES_xxx: Enable or disable a specific module replacing xxx with the module name.
  • BUILD_MODULE_SAMPLES: Build module sample applications default: ON

If you are using third-party libraries is custom locations then make sure you update the CMake include paths: CMAKE_SYSTEM_PREFIX_PATH and CMAKE_LIBRARY_PATH. The only third-party libraries that may need configuring if you’re using them are FFmpeg, OpenCV and WebRTC.

For an exhaustive list of options check the CMakeLists.txt in the main directory.

Core Modules

The following modules are included in the core LibSourcey repository:

Base

Re-usable utility classes and interfaces used throughout LibSourcey.

Net

TCP, SSL and UDL socket implementation build on top of libuv architecture.

HTTP

HTTP server and client stack including support for WebSockets, multipart streaming, and file transfers. The HTTP parser is based on the super-fast C code used by nginx.

Media

dependencies: OpenCV, FFmpeg, RtAudio
Wrappers around FFmpeg and OpenCV for device capture, encoding, recording and streaming. The Media API makes extensive use of the PacketStream classes so that encoders, processors and packetisers can be dynamically added and removed from a media source.

UV

The UV module is a set of C++ wrappers for Joyent’s brilliant libuv library.

JSON

dependencies: JsonCpp
Thin wrappers and helper functions for the JsonCpp library.

STUN

RFC 5389 implementation which includes support for ICE and TURN and TURN TCP messages.

TURN

Server and client stack which supports both RFC 5766 (Traversal Using Relays around NAT) and RFC 6062 (Traversal Using Relays around NAT Extensions for TCP Allocations) specifications.

SocketIO

SocketIO C++ client. Read more about SocketIO.

Symple

Client implementation of Sourcey’s home grown real time messaging and presence protocol. More about Symple.

SDP

RFC 4566 implementation which includes extra support for ICE headers.

External Modules

The following LibSourcey modules are available in external repositories:

Pacm

Pacm is an embeddable package manager which speaks JSON with the server. More about Pacm.

Pluga

Pluga is a simple C++ plugin system that’s dead simple to use in your own projects. More about Pluga.

Anionu SDK

dependencies: OpevCV
The Anionu SDK includes a C++ API, tools, and client implementation for building Spot plugins and applications that integrate with the Anionu cloud surveillance serivice.

Private Modules

The following closed source modules are available. Please contact us if you are interested in using any of them in your projects.

ICE

The ICE module is a complete implementation of RFC 5245 (Interactive Connectivity Establishment) based on LibSourcey architecture. ICE is a protocol for Network Address Translator (NAT) Traversal for Offer/Answer protocols. This module is currently not open source. Please contact us if you are interested in using it.

RTP

Our RTP module is quite basic and at this point it only supports RTP and RTCP packetisation. RTCP session management still needs to implemented. If anyone happens to make a project of this we would be very happy to improve our RTP module.

XML

dependencies: pugixml
Thin wrappers around the pugixml XML library to better support LibSourcey architecture.

XMPP

dependencies: pugixml, libstrophe
Our XMPP module includes a full client implementation with Jingle session support.

Examples

There is also plenty of examples available in the samples and tests folder of each module for you to cut your teeth on.

If you’re interested in media streaming examples check out the mediaserver sample in the symple module. Remember, you will need to compile LibSourcey with OpenCV and FFmpeg enabled to use it: https://github.com/sourcey/libsourcey/tree/master/src/symple/samples/mediaserver

For a redistributable C++ package manager, take a look at pacm, and specifically the pacmconsole application: http://sourcey.com/pacm/

Also, check out pluga, a simple C++ plugin API using LibSourcey: http://sourcey.com/pluga/

For an article on the LibSourcey way of doing things, check out this writeup on using the PacketSteram API for encoding H.264 on the fly: http://sourcey.com/libsourcey-packetstream-api/

Contributing

  1. Fork LibSourcey on Github
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request

Issues

If you find any bugs or issues please use the Github issue tracker.