Start Interactive Live Audio Streaming
This article describes how to create a simple Cocos2d-x project and integrate the Agora Voice SDK to build an Android or iOS app with the basic live audio streaming function.
Understand the tech
The following figure shows the workflow to integrate into your app in order to add Interactive Live Streaming Premium functionality.
As shown in the figure, the workflow for adding Interactive Live Streaming Premium in your project is as follows:
-
Set the client role Each user in an Interactive Live Streaming Premium channel is either a host or an audience member. Hosts publish streams to the channel, and the audience subscribe to the streams.
-
Retrieve a token A token is the credential that authenticates a user when your app client joins a channel. In a test or production environment, your app client retrieves tokens from a server in your security infrastructure.
-
Join a channel Call
joinChannel
to create and join a channel. App clients that pass the same channel name join the same channel. -
Publish and subscribe to audio and video in the channel After joining a channel, app clients with the role of the host can publish audio and video. For an auidence memeber to send audio and video, you can call
setClientRole
to switch the client role.
For an app client to join a channel, you need the following information:
- The App ID: A randomly generated string provided by Agora for identifying your app. You can get the App ID from Agora Console.
- The user ID: The unique identifier of a user. You need to specify the user ID yourself, and ensure that it is unique in the channel.
- A token: In a test or production environment, your app client retrieves tokens from a server in your security infrastructure. For this page, you use a temporary token with a validity period of 24 hours that you retrieve from Agora Console.
- The channel name: A string that identifies the channel for the live stream.
Prerequisites
Development environment
- Cocos2d-x 3.0 or later.
- Python 2.7.5 or later. (Cocos2d-x does not support Python 3 or later.)
- For Android:
- Android Studio 3.0 or later.
- NDK r18b or later.
- cmake.
- For iOS:
- Xcode 9.0 or later.
Deployment environment
- For Android:A mobile device running Android 4.1 or later.
- For iOS: A mobile device running iOS 9.0 or later. Agora recommends you run this sample project on a physical mobile device, as some simulators may not support the full features of this project.
Other Prerequisites
A valid Agora account.
Create a Cocos2d-x project
This section describes how to use the Cocos2d-x command line tool to create a new project.
-
Go to the Cocos2d-x download page, select a version of Cocos2d-x, and then download it.
-
Extract the files from the downloaded package, and run the
setup.py
script in the root directory to set the environmental variables.You can run
cocos -v
in the terminal to check whether the Cocos2d-x command line tool is set up correctly. You should see the following output if the setup is correct: -
Use the
cocos new
command to create a new project:Where:
-
<game name>
: Sets the project name. -
-p <package identifier>
: Sets the package name of the project. The package name should be in the format ofcom.MyCompany.MyGame
, for example,io.agora.gaming.cocos2d
. -
-l <language>
: Sets the programming language used by the project. Optional values includecpp
,lua
, andjs
.To integrate the Agora SDK, the
<language>
parameter must be set ascpp
. -
-d <location>
: Sets the directory of the project.
-
cocos new
command, see the documentation for the Cocos command line tool.Integrate the Agora Voice SDK
Follow these steps to integrate the Agora SDK into your project:
-
Go to SDK Downloads, download the latest version of the Agora Voice SDK, and extract the files from the downloaded SDK package.
-
Create an
sdk
folder in your project root directory for the Agora Voice SDK. You can create the folder and add subfolders in the following structure:
./sdk/android/agora
or ./sdk/ios/agora
path in all configuration files with your path for the Agora Voice SDK.-
For Android: Copy the following files or subfolders from the
audio/libs/android
folder of the downloaded SDK package to the path of your project:File or subfolder Path of your project agora-rtc-sdk.jar
file./sdk/android/lib
arm64-v8a
folder./sdk/android/agora
armeabi-v7a
folder./sdk/android/agora
include
folder./sdk/android/agora
x86_64
folder./sdk/android/agora
x86
folder./sdk/android/agora
-
For iOS: Copy the following dynamic libraries from the
audio/libs/ios
folder of the downloaded SDK package to./sdk/ios/agora
of your project:AgoraRtcKit.framework
Agorafdkaac.framework
Agoraffmpeg.framework
AgoraSoundTouch.framework
For iOS, if you need to support a simulator, then copy the above dynamic libraries from theaudio/libs/ios/ALL_ARCHITECTURE
folder to./sdk/ios/agora
of your project instead.
The dynamic libraries under this path contains the x86-64 architecture, which affects the distribution of your app in the App Store. Therefore, you need to remove the x86-64 architecture in the libraries before uploading the app to the App Store.
- (For Android only) Add the configuration of the
.so
libraries to the build files. You can choose any of the following methods:
-
Method one: If you use cmake as the build tool, that is, you set
PROP_BUILD_TYPE=cmake
in the./proj.android/gradle.properties
file, do the following:a. Add the following code to the
CMakeLists.txt
file in the project root directory:b. Add the following code after
assets.srcDir "../../Resources"
in theproj.android/app/build.gradle
file to include the.so
libraries: -
Method two: If you use ndk-build as the build tool, that is, you set
PROP_BUILD_TYPE=ndk-build
in the./proj.android/gradle.properties
file, and then add the following code to the./proj.android/app/jni/Android.mk
file:If you choose ndk-build, you do not need to setjniLibs.srcDirs
, as ndk-build will automatically include the.so
libraries.
Add project permissions
-
For Android: Add the following permissions in the
./proj.android/app/AndroidManifest.xml
file for device access according to your needs: -
For iOS: Add the following permissions in the
./proj.ios_mac/ios/info.plist
file for device access according to your needs:
Get the device permission (Android only)
Add the following code in ./proj.android/app/src/org/cocos2dx/cpp/AppActivity.java
to access the microphone of the Android device when launching the activity:
Implement interactive live audio streaming
Now you can call the core APIs provided by the Agora Voice SDK to implement basic interactive live audio streaming.
1. Import classes and add declarations
Add the following code in HelloWorldScene.h
to import classes and add declarations of variables and functions:
-
Import
AgoraRtcKit
andIAgoraRtcEngine
classes. -
Define App ID and token. To create and initialize an
IRtcEngine
object, you need to pass in the App ID of your Agora project. See Get an App ID for details. To ensure communication security, you need to use tokens (dynamic keys) to authenticate users joining a channel.- For testing, you can generate a temporary token in Agora Console.
- For production, Agora recommends using a token generated at your server. See Generate a Token.
-
Add function declarations.
2. Create the UI
Create the user interface (UI) for live audio streaming.
We recommend adding the following elements into the UI:
- A channel name edit box
- A join-channel button
- A leave-channel button
In the Agora sample project Cocos2d-x, the code for creating the UI elements and handling the button click events is as follows:
-
The channel name edit box
-
The join-channel button
-
The leave-channel button
3. Initialize IRtcEngine
Create and initialize the IRtcEngine
object before calling any other Agora APIs. Call the createAgoraRtcEngine
and initialize
methods, and pass in your App ID to initialize the IRtcEngine
object.
4. Set the channel profile
After initializing the IRtcEngine
object, call setChannelProfile
to set the channel profile as LIVE_BROADCASTING
.
One IRtcEngine
object uses one profile only. If you want to switch to another profile, release the current IRtcEngine
object with the release method and create a new one before calling the setChannelProfile
method.
5. Set the user role
An interactive streaming channel has two client roles: BROADCASTER
and AUDIENCE
; and the default role is AUDIENCE
. After setting the channel profile to LIVE_BROADCASTING
, your app may use the following steps to set the client role:
- Allow the user to set the role as
BROADCASTER
orAUDIENCE
. - Call
setClientRole
and pass in the client role set by the user.
Note that during the interactive live audio streaming, only the host can be heard. If you want to switch the client role after joining the channel, call the setClientRole
method.
6. Join a channel
After setting the client role, you can call joinChannel
, pass in a token, channel name, and user ID to join a channel.
mute
methods accordingly.7. Leave the channel
Call the leaveChannel
method to leave the current live streaming according to your scenario.
8. Release IRtcEngine
if you want to release the memory of the Agora engine when exiting the HelloWorld
scene, call release
to destroy the Agora engine.
Run the project
For Android:
- Enable Developer options and USB Debugging on your Android device, and then connect it to your computer using a USB cable.
- Open the
Cocos2d-x/proj.android
folder with Android Studio. - Select File > Project Structure > SDK Location, fill in the local path of your NDK under Android NDK Location, and then click Apply > OK.
- Click Sync Project with Gradle Files.
- After the Gradle synchronization finishes, click Build and run.
For iOS:
- Open
Cocos2d-x/proj.ios_mac/Hello-Cocos2d-Agora.xcodeproj
with Xcode. - Connect your iOS device to your computer using a USB cable.
- Click the Build and run button in Xcode.
When the interactive live audio streaming starts successfully, audience members can hear the voice of hosts in the app.
See also
Agora provides an open-source Agora-Cocos-Quickstart/Cocos2d-x sample project on GitHub that implements a basic voice call. You can refer to this sample project and the sample code in this article to implement the interactive live audio streaming.