Adding Support for H.264

The two most common video codecs supported by IceLink are VP8 and H.264. All IceLink SDKs support VP8 out-of-the-box, and almost all IceLink SDKs support H.264 as well, but using H.264 in .NET, UWP, and Java clients requires some additional steps to enable. For these platforms, IceLink uses the OpenH264 library (developed and maintained by Cisco) to provide support for H.264 encoding and decoding. This documentation outlines best practices for working with OpenH264 and adding support for H.264 to your client applications.

Examples

Note that the example applications shipped in the SDK demonstrate working code for handling H.264 and follow the best practices outlined here.

Licensing

As mentioned, the OpenH264 library is provided by Cisco. It is free to use but there are restrictions when including the binaries in your distributions. The full license terms are available here, but generally if you ship any of the binaries in your release then you must pay the corresponding royalties to MPEG LA. That is why all of the IceLink example apps download the appropriate version of the library at runtime. Read on to see how!

Platform Support for H.264

Codec Mismatch

Note that in the case where clients cannot match codecs you will get codec mismatch errors and your connections will fail. The solution to this problem is to use LiveSwitch's SFU/MCU connections, which can transcode on-the-fly. Learn more about LiveSwitch here.

Web

Browsers supply their own codecs internally. You do not need to do anything special to support H.264 in Web clients. It depends solely on whether the browser supports the codec.

Chrome Firefox Edge (40+) IE11 Safari Chrome on Android Chrome on iOS Safari on iOS Firefox on Android Firefox on iOS Opera
Yes Yes Yes No Yes No rcvonly Yes Yes rcvonly Yes
  • rcvonly - getUserMedia is not supported by the browser, so while the codecs are supported, receive only streams are possible whereas send/receive or send only streams are not supported.

Native Platforms

.NET UWP Java Android iOS Obj-C iOS Swift macOS Obj-C macOS Swift Xamarin Android Xamarin iOS Xamarin Forms (Android) Xamarin Forms (iOS)
Yes Partial1 Yes Partial2 Partial3 Partial3 Partial3 Partial3 Partial2 No Partial2 No
  1. Very partial. An OpenH264 integration library is included, but the OpenH264 library cannot currently be downloaded at runtime due to UWP restrictions. To support H.264 for UWP you would have to include the OpenH264 binary provided by Cisco into your release and pay the corresponding royalties to MPEG LA (http://www.mpegla.com/main/programs/AVC/Pages/Intro.aspx).
  2. On Android, Cisco currently provides OpenH264 binaries for armeabi-v7a only.
  3. Both macOS and iOS support H.264 natively, but there are known issues with VideoToolbox on macOS and iOS that limit H.264 support on these platforms.

Working with OpenH264

Downloading the OpenH264 Binary at Runtime

IceLink provides a utility class that can be easily used to download the appropriate version of the OpenH264 binary at runtime. The utility makes use of a static function DownloadOpenH264 to do the heavy lifting, and it returns a promise that allows you to execute additional code when the download completes, and handle any error case. What follows is a code sample demonstrating how to do this. This same code is shipped in the IceLink SDK example applications and can be copied directly from those examples.

FM.IceLink.OpenH264.Utility.DownloadOpenH264().Then((o) => {
	// Success! The download is complete
	... start local media ...
})
.Fail((ex) => {
	// Failure ... the download failed. Perhaps there is no network connection.
});
fm.icelink.openh264.Utility.downloadOpenH264().then((o) -> {
	// Success! The download is complete
	... start local media ...
})
.fail((ex) => {
	// Failure ... the download failed. Perhaps there is no network connection.

});

Best Practices

For the best user experience we recommend that you:

  • Download the OpenH264 library prior to starting local media. 
  • If the application is installable (e.g. desktop) you can download at install-time - as long as the download takes place on the client device.