README.md 6.72 KB
Newer Older
Erwan Croze's avatar
Erwan Croze committed
1 2
[![pipeline status](https://gitlab.linphone.org/BC/public/mediastreamer2/badges/master/pipeline.svg)](https://gitlab.linphone.org/BC/public/mediastreamer2/commits/master)

3 4
Mediastreamer2
==============
François Grisez's avatar
François Grisez committed
5

6 7
Mediastreamer2 is a powerful and lightweight streaming engine for voice/video telephony applications.
This media processing and streaming toolkit is responsible for receiving and sending all multimedia streams in Linphone, including voice/video capture, encoding and decoding, and rendering.
aymeric's avatar
aymeric committed
8

9
For additional information, please [visit mediastreamer2's homepage on **linphone.org**](http://www.linphone.org/technical-corner/mediastreamer2)
10

11 12
License
-------
aymeric's avatar
aymeric committed
13

14
<Copyright © Belledonne Communications SARL>
aymeric's avatar
aymeric committed
15

16 17 18 19 20 21 22 23 24 25 26 27 28
Mediastreamer2 is dual licensed, available either either:
- under the GNU GPLv3 license for free (see LICENSE.txt file for details)
- under a proprietary license, for closed source projects. Contact sales@belledonne-communications.com for costs and other service information.


Documentation
-------------

Please browse supported features and RFCs from [<https://www.linphone.org/technical-corner/mediastreamer2/features>].

Mediastreamer2 has a concept of filters, that can be connected to form a graph. Each
filter is responsible for doing some kind of processing and 
delivers data to the next filter. As an example, you could get some
aymeric's avatar
aymeric committed
29 30
data from network and unpack it in an RTP filter. This RTP filter will
deliver the data to a decoder (speex, G711...) which will deliver it
31
to a filter that is able to play the PCM data or another to record it into a .wav
aymeric's avatar
aymeric committed
32
file.
33 34 35
A more high level API is available in mediastreamer2/mediastream.h header file, exposing
primitives to create audio and video streams suitable for a VoIP application.

aymeric's avatar
aymeric committed
36 37


Simon Morlat's avatar
Simon Morlat committed
38
Compilation and installation
François Grisez's avatar
François Grisez committed
39 40 41 42 43 44 45 46 47 48 49 50 51 52 53
----------------------------

### Required dependencies:

- **bctoolbox[1]**: portability layer
- **oRTP[2]**: RTP stack

### Optional dependencies

- **libsrtp** for SRTP encryption
- **bzrtp[3]** for ZRTP encryption
- **libgsm**: GSM codecs support
- **libbv16**: BV16 codec support
- **libopus** for Opus encoding and decoding
- **libspeex**: SPEEX codec support
54
- **libspeex-dsp: resampler and AEC
François Grisez's avatar
François Grisez committed
55 56 57 58 59 60 61 62
- **libalsa**: ALSA support (GNU/Linux only)
- **libpulse**: PulseAudio support (GNU/Linux only)
- **libv4l2**: video capture (GNU/Linux only;disablable)
- **libx11** and libxv: video display with X11 (GNU/Linux only)
- **libglx**: video dispaly with GLX (GNU/Linux only)
- **libvpx** for VP8 encoding and decoding
- **libmastroska-c** for recording/playing of audio/video streams
- **libturbojpeg**: video screenshot feature
63
- **ffmpeg**, h264 decoder, mpeg4 and mjpeg encoder/decoders, rescaling and pixel conversion.
François Grisez's avatar
François Grisez committed
64 65 66 67 68 69 70 71 72

### Build instructions:

The Autotools way is deprecated. Use [CMake](https://cmake.org) to configure the source code.

	cmake . -DCMAKE_INSTALL_PREFIX=<prefix> -DCMAKE_PREFIX_PATH=<search_path>
	
	make
	make install
73 74 75
	
Alternatively, mediastreamer2 library is integrated in *linphone-sdk[4]* meta project, which provides a convenient way
to build it for various targets.
François Grisez's avatar
François Grisez committed
76

77
#### Supported options:
François Grisez's avatar
François Grisez committed
78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94

- `CMAKE_INSTALL_PREFIX=<string>` : install prefix
- `CMAKE_PREFIX_PATH=<string>`    : column-separated list of prefixes where to search for dependencies
- `ENABLE_SHARED=NO`              : do not build the shared library
- `ENABLE_STATIC=NO`              : do not build the static library
- `ENABLE_STRICT=NO`              : build without strict compilation flags (-Wall -Werror)
- `ENABLE_UNIT_TESTS=YES`         : build tester binaries
- `ENABLE_DOC=NO`                 : do not generate the documentation
- `ENABLE_DEBUG_LOGS=YES`         : turn on debug-level logs


#### Note for packagers:

Our CMake scripts may automatically add some paths into research paths of generated binaries.
To ensure that the installed binaries are striped of any rpath, use `-DCMAKE_SKIP_INSTALL_RPATH=ON`
while you invoke cmake.

95 96 97 98 99 100 101 102 103
Rpm packaging
mediastremer2 rpm can be generated with cmake3 using the following command:
mkdir WORK
cd WORK
cmake3 ../
make package_source
rpmbuild -ta --clean --rmsource --rmspec mediastreamer-<version>-<release>.tar.gz


Simon Morlat's avatar
Simon Morlat committed
104

105
Environment variables used by mediastreamer2
François Grisez's avatar
François Grisez committed
106
--------------------------------------------
107

François Grisez's avatar
François Grisez committed
108
`MS2_RTP_FIXED_DELAY` : default value is 0. When set to 1, RTP packets belonging from one tick execution are actually sent at the beginning of the next tick.
109 110 111
This allows a zero jitter in the RTP timing at sender side. This is to be used for measurements, this mode has no interest for doing a real conversation and does not improve 
quality.

François Grisez's avatar
François Grisez committed
112
`MS_AUDIO_PRIO`, `MS_VIDEO_PRIO` : define the scheduling policy of the audio and video threads (MSTicker objects). Possible values are 'NORMAL', 'HIGH', 'REALTIME'.
113 114
The corresponding behavior is as follows:

François Grisez's avatar
François Grisez committed
115 116 117 118 119 120 121
	+-------------------+------------------------+------------------------+-------------------------+
	| Priority type     |     GNU/Linux          |        MacOS           |         Windows         |
	+-------------------+------------------------+------------------------+-------------------------+
	| NORMAL            | SCHED_OTHER, def. prio | SCHED_OTHER, def. prio | Default priority.       |
	| HIGH              | SCHED_RR, max prio     | SCHED_RR, max prio     | THREAD_PRIORITY_HIGHEST |
	| REALTIME          | SCHED_FIFO, max prio   | SCHED_FIFO, max prio   | THREAD_PRIORITY_HIGHEST |
	+-------------------+------------------------+------------------------+-------------------------+
122

François Grisez's avatar
François Grisez committed
123 124
Note that `SCHED_FIFO` leaves entire control of the cpu to the mediastreamer2 thread. In case of CPU overload
due to heavy encoder processing for example, a mono-core machine will stop responding.
125

François Grisez's avatar
François Grisez committed
126 127 128 129 130 131
- `MS_TICKER_SCHEDPRIO` : UNIX only. It is an integer defining the thread priority to be used by MSTicker. Values
                          are OS specific and depend on the scheduling policy `SCHED_FIFO`, `SCHED_RR` or `SCHED_OTHER`.
- `MS2_OPUS_COMPLEXITY` : opus codec complexity parameter. A value of -1 stands for mediastreamer2's own default value.
                          Otherwise it must be between 0 and 10.
- `MEDIASTREAMER_DEBUG` : when set to 1, verbose logging is activated by default.
- `DISPLAY`             : used by video display filters relying on X11 (GNU/Linux only).
aymeric's avatar
aymeric committed
132 133


Simon Morlat's avatar
Simon Morlat committed
134

François Grisez's avatar
François Grisez committed
135 136
Contact information
-------------------
aymeric's avatar
aymeric committed
137

138 139 140
Use the *linphone* mailing list for question about mediastreamer2.
  <linphone-developers@nongnu.org>.
Subscribe here:
François Grisez's avatar
François Grisez committed
141 142 143 144
  <https://savannah.nongnu.org/mail/?group=linphone>


--------------------------------------
145 146


François Grisez's avatar
François Grisez committed
147 148 149
- [1] git://git.linphone.org/bctoolbox.git *or* <http://www.linphone.org/releases/sources/bctoolbox>
- [2] git://git.linphone.org/ortp.git *or* <http://www.linphone.org/releases/sources/ortp>
- [3] git://git.linphone.org/bzrtp.git *or* <http://www.linphone.org/releases/sources/bzrtp>
150
- [4] linphone-sdk: https://gitlab.linphone.org/BC/public/linphone-sdk.git