How to get started with WebRTC and iOS without wasting 10 hours of your life | Ninjanetic Design
How to get started with WebRTC and iOS without wasting 10 hours of your life
November 16, 2013 |
(Updated 11/3/2014)
I recently had the chance to play around with the new , a really cool new technology that will eventually allow for point-to-point real-time video chat without plug-ins or extra software. Ideally this technology will be built into all modern browsers (it’s already in Chrome and Firefox!) but Apple is definitely dragging their feet. If you want to incorporate this technology into an iOS application, you need to directly use the WebRTC libraries that implement the protocol. Fortunately, an Objective-C implementation of
and is free to use.
That being said, incorporating the WebRTC libraries into your project is a total nightmare. The project is set up to support a large number of platforms simultaneously, so the build system is extremely complicated. Forget about opening Xcode and using interface builder, you are going to be doing everything from the command line if you want to work directly with the libraries.
Why not just take the compiled libraries and build on top of them? WebRTC is still on the bleeding edge of development, and changes are being made to the framework almost every day. Until a stable release point is reached, you will need to pull in the latest library changes as they happen in order to stay on top of development.
If you are building a production application then you are going to need to get down in the guts and work directly with the libraries, and in order to compile them you need to jump through a bunch of hoops (especially if you are working with Xcode 5 and iOS 7). It took a surprising amount of effort to get this to build for the simulator, and then trying to get it to build for a device was even more work. In hopes of saving other people some time, here’s a compilation of all the steps I needed to do to get the example application building and then running on both the iOS simulator and a physical device.
Get the code base
Keep in mind that at the time of this writing, this is a project being very actively developed. It’s very likely the build process is going to change as time goes on. These instructions are based on syncing the code base at revision r7538.
Prerequisites:
I’m doing this on a MacBook Pro running OS X Mavericks
You have Git installed and working
XCode 5.1+ with the Command Line Tools installed (Preferences -& Downloads -& Command Line Tools)
If you’re using an actual iOS device, you will need a valid development code signing identity, and properly provisioned iOS device attached to your computer
1) Create a working directory
Make a new directory somewhere,
and get ready because you’re going to need in the ballpark of 8 GB of free space
2) Download the Chromium depot tools
Switch into your working directory and grab the Chromium depot_tools repository with git:
git clone /chromium/tools/depot_tools.git
These are a bunch of tools used during the build process, and they will need to be in your path so you will need to modify your .bash_profile (or other shell file) and modify the PATH line like so:
export PATH=/a_bunch_of_stuff:/working_directory/depot_tools:$PATH
Next you will need to restart your terminal or re-run your bash profile so that the changes take effect:
source ~/.bash_profile
3) Download the WebRTC source
Back in your working directory, use the next few commands to download the massive source repository:
gclient config --name src /svn/trunk
echo "target_os = ['ios']" >> .gclient
gclient sync --force
Come back a few days later when it’s finished downloading, and then you can move on to setting up the build.
Building and running on the iOS 7/8 simulator
This source code is capable of building for a number of different platforms, and since we are only interested in building for iOS we are going to create our own build script that compiles and runs exclusively for the iOS simulator.
That’s right, forget about actually using Xcode we are going to be building everything from the command line. Oh yeah!
First, at the top level of your working directory create a new shell script file to kickoff the build:
touch build_apprtc.sh
chmod +x build_apprtc.sh
Open the file you just created, and paste in this:
makeall-iossim.sh
function build_iossim() {
echo "-- building WebRTC for the iOS simulator"
export GYP_GENERATORS="ninja"
export GYP_DEFINES="build_with_libjingle=1 build_with_chromium=0 libjingle_objc=1 OS=ios target_arch=ia32"
export GYP_GENERATOR_FLAGS="$GYP_GENERATOR_FLAGS output_dir=out_ios"
export GYP_CROSSCOMPILE=1
gclient runhooks
ninja -C out_ios/Release-iphonesimulator iossim AppRTCDemo
function build_iosdevice() {
echo "-- building WebRTC for iOS devices"
export GYP_GENERATORS="ninja"
export GYP_DEFINES="build_with_libjingle=1 build_with_chromium=0 libjingle_objc=1 OS=ios target_arch=armv7"
export GYP_GENERATOR_FLAGS="$GYP_GENERATOR_FLAGS output_dir=out_ios"
export GYP_CROSSCOMPILE=1
gclient runhooks
ninja -C out_ios/Release-iphoneos AppRTCDemo
function combine_libs() {
echo "-- combining libraries"
libtool -static -o src/out_ios/Release-iphonesimulator/libWebRTC-sim.a src/out_ios/Release-iphonesimulator/*.a
strip -S -x -o src/out_ios/Release-iphonesimulator/libWebRTC-sim-min.a -r src/out_ios/Release-iphonesimulator/libWebRTC-sim.a
libtool -static -o src/out_ios/Release-iphoneos/libWebRTC-ios.a src/out_ios/Release-iphoneos/*.a
strip -S -x -o src/out_ios/Release-iphoneos/libWebRTC-ios-min.a -r src/out_ios/Release-iphoneos/libWebRTC-ios.a
lipo -create src/out_ios/Release-iphonesimulator/libWebRTC-sim-min.a src/out_ios/Release-iphoneos/libWebRTC-ios-min.a -output libWebRTC.a
echo "The public headers are located in ./src/talk/app/webrtc/objc/public/*.h"
function build_all() {
build_iossim && build_iosdevice && combine_libs
function run_simulator() {
echo "-- running webrtc appdemo on iOS simulator"
src/out_ios/Release-iphonesimulator/iossim src/out_ios/Release-iphonesimulator/AppRTCDemo.app
function run_on_device() {
echo "-- launching on device"
ideviceinstaller -i src/out_ios/Release-iphoneos/AppRTCDemo.app
echo "-- launch complete"
# Run the function specified by the first parameter on the command line
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051
function build_iossim() {&&echo "-- building WebRTC for the iOS simulator"&&export GYP_GENERATORS="ninja"&&export GYP_DEFINES="build_with_libjingle=1 build_with_chromium=0 libjingle_objc=1 OS=ios target_arch=ia32"&&export GYP_GENERATOR_FLAGS="$GYP_GENERATOR_FLAGS output_dir=out_ios"&&export GYP_CROSSCOMPILE=1&&pushd src&&gclient runhooks&&ninja -C out_ios/Release-iphonesimulator iossim AppRTCDemo&&popd} function build_iosdevice() {&&echo "-- building WebRTC for iOS devices"&&export GYP_GENERATORS="ninja"&&export GYP_DEFINES="build_with_libjingle=1 build_with_chromium=0 libjingle_objc=1 OS=ios target_arch=armv7"&&export GYP_GENERATOR_FLAGS="$GYP_GENERATOR_FLAGS output_dir=out_ios"&&export GYP_CROSSCOMPILE=1&&pushd src&&gclient runhooks&&ninja -C out_ios/Release-iphoneos AppRTCDemo&&popd}&function combine_libs() {&&echo "-- combining libraries"&&libtool -static -o src/out_ios/Release-iphonesimulator/libWebRTC-sim.a src/out_ios/Release-iphonesimulator/*.a&&strip -S -x -o src/out_ios/Release-iphonesimulator/libWebRTC-sim-min.a -r src/out_ios/Release-iphonesimulator/libWebRTC-sim.a&&libtool -static -o src/out_ios/Release-iphoneos/libWebRTC-ios.a src/out_ios/Release-iphoneos/*.a&&strip -S -x -o src/out_ios/Release-iphoneos/libWebRTC-ios-min.a -r src/out_ios/Release-iphoneos/libWebRTC-ios.a&&lipo -create src/out_ios/Release-iphonesimulator/libWebRTC-sim-min.a src/out_ios/Release-iphoneos/libWebRTC-ios-min.a -output libWebRTC.a&&echo "The public headers are located in ./src/talk/app/webrtc/objc/public/*.h"}&function build_all() {&&build_iossim && build_iosdevice && combine_libs} function run_simulator() {&&echo "-- running webrtc appdemo on iOS simulator"&&src/out_ios/Release-iphonesimulator/iossim src/out_ios/Release-iphonesimulator/AppRTCDemo.app}&function run_on_device() {&&echo "-- launching on device"&&ideviceinstaller -i src/out_ios/Release-iphoneos/AppRTCDemo.app&&echo "-- launch complete"}&# Run the function specified by the first parameter on the command line$@
This script contains a few functions that allow you to build the AppRTC example app for a few different purposes. First, build the source code and example application by running the script with the following parameter:
./build_apprtc.sh build_iossim
Once the build has completed successfully, launch the iOS simulator and run the example application by using the following parameter:
./build_apprtc.sh run_simulator
Your iOS simulator should pop up automatically and launch the test application. To give it a try, you’re going to have to create a video session that the test application can connect to. The easiest way to do this is:
1) Open a Chrome browser tab on your computer or Android device (I’ve had great success with the Google Nexus 7 and 10).
3) Give the browser permissions to access your camera, and wait for your smiling face to show up.
Notice that the URL in your browser has changed. It will now look something like this:
5) The number appended to the end of the URL is the room number. This is the key piece of information you need to get the test application to connect. Switch back to the iOS simulator, and type that number into the text box. Press the join button on the keyboard and away it will go. The test application has not been the most reliable thing in the world for me, see you might need to try a few times before it connects successfully. Also be careful with the volume on your computer, it’s super easy to get a feedback loop going.
We have a demo! Now let’s see if we can get this thing to work on an actual iOS device.
Building and running directly on an iOS device
To build the test application for an actual iOS device, use the following parameter:
./build_apprtc.sh build_iosdevice
The script will switch the architecture to armv7 and codesign the application. In order to upload the compiled application to an attached iOS device, we need to install an additional tool called .
Its super-easy to install using
(although it takes a while to build).
brew install ideviceinstaller --HEAD
Once that tool is installed, you can use another parameter on the build script to install and run the application on your attached iOS device:
./build_apprtc.sh run_on_device
Curveball: IOS 7
(NOTE: the latest revisions of the framework have solved this problem, so you can skip this step. I’m leaving the solution here for those that run into it)
The build scripts were designed with iOS 6 in mind, and include an obsolete framework not available in the iOS 7 SDK.
Building the code for an actual iOS device will spit out an error that reads something like “ld: framework not found IOKit”. Fortunately, fixing this problem is as easy as deleting a few lines. Open src/talk/libjingle.gyp and search for:
framework IOKit
There should be 2 instances of that in the file, just delete both of those lines.
Curveball: Codesigning
The build scripts will look through your keychain and use the code signing identity associated with “iPhone developer”. If you have a single identity registered (i.e. you only ever work with one team or developer account) everything should be fine.
If this is you, skip down to the “finally” section below.
If you do not have a valid code signing identity set up & a provisioned iOS device attached to your computer, it’s not going to work.
Follow Apple’s guides on how to create an identity and provisioning profile.
If you are an iOS developer that works with multiple clients, odds are that you have multiple code signing identities for the identity “iPhone developer”. The WebRTC build scripts do not have proper handling for this situation, and will throw assertions if you have more than one code signing identity. Fortunately, we can modify the global build configuration to specify the exact code signing identity to use.
First, find the list of valid code signing identities that are available by running this from the command line:
security find-identity
You should see a block of output with all of your valid (and expired) identities. Look for the block at the bottom titled “Valid identities only”
Valid identities only
1) 34F3D92F755F343C9E05AE207ECDAD47C4183D77 "iPhone Developer: Jason Adams (SZ2V5SDF5DF)"
2) 257CA472EB76BE93AED28FEDE8FEEF "iPhone Distribution: My Company (FG45D44FR34)"
3) 8D5CB180EB47383E6 "iPhone Developer: Jason Adams (S56FDFPBY4)"
3 valid identities found
Choose the identity most appropriate for this project, and copy the text between the quotation marks on the corresponding line. Next, open the global configuration file src/build/common.gypi and search for the text ‘CODE_SIGN_IDENTITY’. It should occur around line 4830:
# iOS SDK wants everything for device signed
‘CODE_SIGN_IDENTITY[sdk=iphoneos*]‘: ‘iPhone Developer’
Switch the identity value with the one you chose from the valid identity list:
# iOS SDK wants everything for device signed
‘CODE_SIGN_IDENTITY[sdk=iphoneos*]‘: ‘iPhone Developer: Jason Adams (SZ2V5SDF5DF)’
By default, the test application will be built with a bundle ID of com.google.AppRTCDemo. If the signing identity & associated provisioning profile is restricted to a specific bundle ID or wildcard, you might need to switch the test project bundle ID to match (You will see the error “Install – Error occured: ApplicationVerificationFailed” if this is the case). To do that, open the file src/talk/examples/objc/AppRTCDemo/ios/Info.plist and change the following lines to match whatever bundle ID you need:
&key&CFBundleIdentifier&/key&
&string&com.google.AppRTCDemo&/string&
&&&&&&&&&key&CFBundleIdentifier&/key&&&&&&&&&&string&com.google.AppRTCDemo&/string&
Save the file, and kick off the build again. Otherwise, the build will fail with an error similar to “AssertionError: Multiple codesigning identities for identity: iPhone Developer”.
If you are still having trouble with the build choosing the right provisioning profile for the device you are working with, you can take a look at the provisioning profile that was chosen for you with the following command:
security cms -D -i src/out_ios/Release-iphoneos/AppRTCDemo.app/embedded.mobileprovision
NOTE: If you are switching bundle IDs, the build might not automatically pick up the changes. The best way to make sure it rebuilds the test app with the new bundle ID is to delete the output directory at src/out_ios/
If the build is pulling in the wrong provisioning profile even though you have the correct codesigning identity specified, there is a way to manually replace the embedded provisioning profile from the compiled AppRTCDemo.app with the following steps. It’s better to figure out the upstream problem though, since you would have to do this every single time you compile. If you really must do this every time, then you can add the following commands into the end of your makeall-iosdevice.sh script.
1) Delete the existing code signature from the compiled app
rm -rf src/out_ios/Release-iphoneos/AppRTCDemo.app/_CodeSignature/
2) Copy in a new provisioning profile to use, assuming it is sitting in your downloads directory
cp ~/Downloads/my_personal.mobileprovision src/out_ios/Release-iphoneos/AppRTCDemo.app/embedded.mobileprovision
3) Re-codesign the application using the signing identity that corresponds to the provisioning profile you just copied
codesign -f -s "iPhone Developer: Jason Adams (SZ2V5SDF5DF)" --resource-rules src/out_ios/Release-iphoneos/AppRTCDemo.app/ResourceRules.plist
src/out_ios/Release-iphoneos/AppRTCDemo.app
4) Install the newly-signed application onto your device
ideviceinstaller -d -i src/out_ios/Release-iphoneos/AppRTCDemo.app
If everything goes well, the upload will succeed and you’ll notice a new demo application icon show up on your device. The build script will not automatically launch the application, so just click on the icon to run the demo. From there follow the same instructions to join a chat room as we did with the simulator.
Debug Mode
To build the libraries in debug mode instead of release mode, all you need to do is replace every instance of “out_ios/Release-” with “out_ios/Debug-” in my build scripts.
The build environment will notice that change and use the appropriate optimization levels.
Making Code Changes
There is a ton of code here, but there’s really only a small amount that you need to worry about as an iOS developer. Here are the 2 key locations to start exploring:
AppRTCDemo test project – src/talk/examples/objc
This is the demo application with the high level communication logic and UI
Objective-C WebRTC libraries – src/talk/app/webrtc/objc
These are the Objective-C wrappers to the core communication libraries.
As long as you modify the code in place, the build scripts will automatically tie everything together and compile the finished demo application.
Incorporating WebRTC into Your Custom iOS Application
If you are building an application on top of the WebRTC framework, you don’t really want to mess around with the raw WebRTC source code if you can avoid it. What you really want is the compiled code in a static library that you can just throw into your XCode project. Fortunately for you, the build script will take care of this as well. Use the following parameter to build the libraries for both x86 & armv7 and then combine all of the compiled objects into a single fat library:
./build_apprtc.sh build_all
This will spit out a file named libWebRTC.a into your working directory. Drag this file into your XCode project along with the public headers found here:
src/talk/app/webrtc/objc/public/*.h
Additionally, you will need to add a few frameworks to your project in order for it to build correctly:
libc++.dylib
libicucore.dylib
Security.framework
CFNetwork.framework
GLKit.framework
libstdc++.6.dylib
AudioToolbox.framework
AVFoundation.framework
CoreAudio.framework
CoreMedia.framework
CoreVideo.framework
CoreGraphics.framework
OpenGLES.framework
QuartzCore.framework
libsqlite3.dylib
Also note that the WebRTC libraries currently only build for armv7 and x86. The standard architectures defined for a new XCode project expect armv7s & arm64. Your application build will fail at the moment unless you manually limit your project to only build for those architectures. Apple recently announced that arm64 is going to be required in applications submitted to the app store in the near future, so let’s hope the WebRTC libraries are updated to support that soon!
Enjoy playing around with the project, and definitely let me know if you learn any other tips or tricks.
Need Help?We can help you get your WebRTC application working for iOS or Android.
Current ye@r *
Leave this field empty