Document of Airplay SDK on Android

1 Airplay SDK Overview

1.1 Purpose

Used to guide developers who use the BiJie Airplay receiver SDK for development and testing。

1.2 Readers

This document is intended for developers who develop Airplay receivers on the Android platform.

1.3 Airplay from Apple

2 Scope

2.1 Feature

The SDK can accept Airplay mirror from iPhone, iPad and imac which run iOS and MacOS. It can also support Android phones/PCs that use Mirror360 for Airplay screen projection processing, and provide an interface to the application layer for call processing.

2.2 SDK Framework

The BJAirplay Receiver SDK is generally divided into two layers

• cast_base_lib-1.0.20-release.aar：it’s an Android Module，It defines the basic MediaChannel，and the Module interface.

• bj_airplay_lib-1.0.22-release.aar：This is an Android module that defines the AirplayModule and related JNI interfaces.

The application should be developed based on bj_airplay_lib-1.0.22-release.aar. The applications in principle should not modify the contents of cast_base_lib-1.0.20-release.aar, bj_airplay_lib-1.0.22-release.aar.

2.3 DEMO Implementation of SDK

The Airplay Receiver SDK Demo is a reference implementation of the receiver. It implements the Airplay receiver function based on bj_airplay_lib-1.0.17-release.aar.

• AirplayModuleImp implements the ModuleImpItf interface.

• AirplayMirrorChannel implements the MediaChannel interface, which implements the processing of Airplay mirror sessions.

• AirplayAudioChannel implements the MediaChannel interface, which implements the processing of Airplay audio sessions.

• AirplayUrlPlayChannel implements the MediaChannel interface, which implements the processing of Airplay URL playback sessions.

2.4 SDK Deliverables

• SDK library (two AAR files)

• DEMO source code

• SDK interface documentation

3 Interface

The interface is mainly defined in the AirplayModule, ModuleImpItf and MediaChannel classes;

• The AirplayModule class provides interfaces such as initializing the SDK, to initialize the SDK, and forcing a session to end.

• ModuleImpItf is an interface class that needs to be implemented by the user. The SDK uses this interface class to notify the user program of the start and end of the Airplay screencast session. The user program needs to create corresponding MediaChannel implementation classes and corresponding player applications based on different session types .

• MediaChannel is an interface class that needs to be implemented by a user program. The SDK uses this interface class to notify applications of audio and video data, volume control, video rotation and other control events, and the application processes them in the corresponding player.

• Users need to implement MediaChannel, ModuleImpItf related interfaces, and can also refer to the DEMO source code provided by our company.

3.1 Interface in AirplayModule class

3.1.1 Set the Custom Module Implementation Class Interface for the Customer

• public void setImp(ModuleImpItf imp)

• INPUT:

  • User-implemented ModuleImpItf interface instance.

3.1.2 Initialize the Interface

public native int init(Properties props); The Init method of the AirplayModule class initializes the Airplay receiver module. The App is called at startup initialization, and the AirplayModule object should be designed to have only one global object

• Where Properties supports the setting of the following Properties:

• PARA_NAME_DEVICE_NAME: receiver name, Airplay receiver display name.

• PARA_NAME_PASSWORD: initial PIN code, default empty string, enter empty string if PIN code is not supported.

• PARA_NAME_KEY_ROTATION: does the mirror play support rotation, ranging from 0 to 1. The default is 1

• PARA_NAME_MDNS_DEAMON_ENABLE: whether to enable internal MDNSD for publishing the Airplay service, with a value of 0,1.

• The default is 1. It is recommended that the user fill in 1 here.

• Please note: if the receiver APP runs both the BJAirplay receiver and the BJCast receiver,

• then only set PARA_NAME_MDNS_DEAMON_ENABLE to 1 in one module,

• and the other must be set to 0.

• If both modules are initialized with this parameter of 1, one of the services will fail to publish.

• The return value:

• public static final int BJ_AIRPLAY_ERROR_SUCCESS = 0, ///success

• public static final int BJ_AIRPLAY_ERROR_PORT_BINDERROR = 1; ///Failed initialization, Airplay port binding failed

• public static final int BJ_AIRPLAY_ERROR_INIT_FAILED =2; ///Failed initialization

• public static final int BJ_AIRPLAY_ERROR_INIT_RAOP_FAILED = 3; ///Failed initialization，Raop port binding failed

• public static final int BJ_AIRPLAY_ERROR_VERIFY_GET_MAC_ERROR = -101; ///License check failed，Unable to get a valid MAC address

• public static final int BJ_AIRPLAY_ERROR_VERIFY_GET_HARDINFO_ERROR = -102; ///License check failed，Unable to obtain valid hardware information

• public static final int BJ_AIRPLAY_ERROR_VERIFY_MAC_FAILED = -103; ///License check failed，MAC address validation failed

• public static final int BJ_AIRPLAY_ERROR_VERIFY_HARDINFO_FAILED = -104; ///License check failed，Failed to verify hardware information

• public static final int BJ_AIRPLAY_ERROR_VERIFY_SDKTYPE_FAILED = -105; ///License check failed，Not a legitimate Airplay License

• public static final int BJ_AIRPLAY_ERROR_VERIFY_TIME_EXPIRED = -106; ///License check failed，License expired

• public static final int BJ_AIRPLAY_ERROR_VERIFY_DECODELICENSE_FAILED = -107; ///License check failed，Invalid license key, format error

• public static final int BJ_AIRPLAY_ERROR_VERIFY_OTHER_ERROR = -108; ///License check failed

• public static final int BJ_AIRPLAY_ERROR_VERIFY_ERROR_EMPTY_CLICENSE = -109; ///License check failed，The license to be verified cannot be empty

3.1.3 Initialize the Interface

public native void fini();

• Description: The fini method of the AirplayModule class initializes the Airplay module. Called when the App destroys the Airplay receiver service.

3.1.4 Update the PIN Code Interface

public native void setPassword(String pass);

• Description: Update Airplay PIN code. Empty string means PIN codes is disabled, and other valid strings represent PIN codes.

3.1.5 Force End Airplay Session Interface

public native void kickOut(MediaChannel channel);

• Description: Channel creates the corresponding session for the ModuleImpItf, reqMediaChannel.

3.1.6 Modify Airplay Receiver Name Interface in Real Time

public native void rename(String name);

3.2 ModuleImpItf Interface

ModuleImpItf defines an interface class that requires users to implement these interfaces

3.2.1 Session Access Interface

public MediaChannel reqMediaChannel(MediaChannelInfo channelInfo,UserInfo userInfo) ;

• INPUT:

  • Session information that describes its business type

  • ChannelInfo describes the type information for the current session.

  • userInfo describes the IP, device model, and device name of the transmitting end and other information.

• OUTPUT:

  • The created MediaChannel object.

  • This is a callback interface.

  • When the Airplay protocol stack finds that there is a session access, the JNI layer will actively call this interface.

  • The application layer needs to implement the relevant logic, which needs to be implemented in the client’s own ModuleItf implementation class.

  • Specific implementation can refer to the DEMO source code.

3.2.2 Session End Interface

public void relMediaChannel(MediaChannel channel) Callback interface, called when the bottom layer receives the end of the session. The application layer implements the relevant logic. Specific implementation can refer to the DEMO source code.

3.2.3 Projection Property Negotiation Interface

public void probeRenderAbility(Properties props)； Callback interface. When the bottom layer initiates a screen projection, this interface will be called for parameter negotiation. For example, negotiate the maximum frame rate of the current Airplay screencast session. Users can customize the interface to dynamically adjust the maximum frame rate of the session. For example: @Overridepublic void probeRenderAbility(Properties props){ // users can customize this function to achieve the maximum frame rate of Airplay screen casting session. Set the frame rate to 60 by referring to the following code int framerate = 60; props.setProperty(AirplayModule.PARA_NAME_KEY_FRAMERATE,Integer.toString(framerate));}

3.3 MediaChannel Session Interface

When the channel is successfully established, the protocol stack will call the corresponding interface in the MediaChannel class to send back data or get the status.

The following interfaces need to be implemented in the MediaChannel subclass. The client needs to implement the following interfaces according to their actual conditions.

The important interfaces in the MediaChannel subclass are as follows.

Airplay receiver needs to focus on the following interfaces.

3.3.1 Setting the Window Handle

public void setSurface(Surface surface) Configure the window handle for the render output. The Surface is obtained from the player view created by the user. Refer to the implementation in Demo.

3.3.2 Callback of Audio Data Interface

public void onAudioFrame(byte[] buffer,int len,long ts)

• INPUT:

  • buffer: audio data byte array

  • len: length of audio data

  • ts: timestamp (us)

• Description: JNI takes back the audio data. The audio is PCM format data. The user needs to implement the playback processing function of the audio data. For the specific implementation, refer to the DEMO source code in the SDK. Where buffer is the audio data array, len is the data length, and ts is the timestamp The interface relates to pure audio Airplay projection screen session and mirroring projection screen session

3.3.3 Update the Cover Information of Audio Playback Interface

public void onRefreshCoverArt(byte[] buffer,int len);

• Description: JNI returns the music cover information in jpe format, buffer is the content of JPG, and len is the content length of JPG file. The interface relates to pure audio Airplay projection screen session.

3.3.4 Update the Song Information of Audio Play Interface

public void onRefreshTrackInfo(String album,String title,String artist)

• Description: JNI returns the title of the music, the artist, the album information, the title as the title, the artist as the artist information, and the album as the album information (some application players actually transmit the lyrics). The interface relates to pure audio Airplay projection screen session.

3.3.5 Video Data Callback Interface

public void onVideoFrame(byte[] buffer,int len,long ts)

• INPUT:

  • buffer: video data byte array

  • len: the length of the video data

  • ts: timestamp (in us)

• Description: Mirror video data interface, the interface spits out a frame of H264 video data, the user needs to decode and play.

  Where buffer is the array of video data, len is the length of the data, and ts is the timestamp.

  Can refer to the implementation in Demo.

  This interface involved while this is a Airplay mirroring session.

3.3.6 Volume Control Interface

public void setVolume(int volume)

• INPUT:

  • volume: the volume of the audio from iphone, the rage is 0~100. the 100 means the volume is the highest.

• Description: This interface involves while this is Airplay mirroring session or audio session.

3.3.7 Video Rotate Interface

public void rotate(int angle)

• Description: This interface informs the player that the video needs to be rotated,value range is 0,90,180,270. While the init interface of 3.1.2 is initialized and the PARA_NAME_KEY_ROTATION is set to 1 , the interface is triggered while the Airplay mirror screen is cast. This interface involves while this is Airplay mirroring session

3.3.8 URL Pause Interface

public void pause()

• Description: This callback function to notice the application to pause video play. This interface involves the Airplay URL play feature.

3.3.9 URL Play Interface

public void play()

• Description: This callback function to notice the application to start or resume play video or audio. This interface involves the Airplay URL play feature.

3.3.10 URL Seek Interface

public void seek(int sec)

• INPUT:

  • sec: Notifies the player where the progress bar is dragged and dropped, the unit is second

• Description: This callback function to notice the application that the seek position of the video or audio. This interface involves the Airplay URL play feature.

3.3.11 Obtain Position of URL

public int getPts()

• OUTPUT:

  • int: return the position of the play of video. The unit is millisecond.

• Description: This interface involves the Airplay URL play feature.

3.3.12 Get length of URL

public int getDuation()

• Description: Gets the length of the URL of the currently playing video. The unit is millisecond. This interface involves the Airplay URL play feature.

3.3.13 The Current State of the Video URL Player

public int getPlayerStatus();

• Description: The SDK will display the current actual state of the player. The client needs to implement the interface correctly and return its status. Refer to the implementation in the demo. This interface involves the Airplay URL play feature. The return value range is defined in the MediaConst class as: public static final int PLAYER_STATUS_LOADING = 0; public static final int PLAYER_STATUS_PLAYING = 1; public static final int PLAYER_STATUS_PAUSED = 2; public static final int PLAYER_STATUS_ENDED = 3; public static final int PLAYER_STATUS_FAILED = 4; Its meaning is described as follows

  • LOADING: Means that during loading, initialization will occur

  • PLAYING: In the play

  • PAUSED: In the pause

  • ENDED: End of the play

  • FAILED Playback failed

4 Demo Description

4.1 Describer

In the Demo, AirplayModuleImp implements the ModuleImpItf interface, which implements the reqMediaChannel and relMediaChannel methods, where application can control whether to accept the logical control of a session(Such as maximum control of 2 channels).

The reqMediaChannel creates a MediaChannel implementation corresponding to the session type, and starts playing the related View to create a Surface for playback.

AirplayMirrorChannel corresponds to the airplay mirror screen.

AirplayAudioChannel corresponds to the pure audio projection screen.

AirplayUrlPlayChannel corresponds to the video or audio URL playback scenario.

They all implement the relevant functional interfaces in MediaChannel.

5 How to Use SDK

1. Import aar, create a new libs directory in the app directory and place the aar file in the directory, then add the following code to above and inside the dependencies in build.gradle file ( user can refer to demo)

    repositories{ flatDir { dirs 'libs '} }
    compile (name: ‘bj_airplay_lib-1.0.22-release.aar’, ext: ‘aar’)
    compile (name: ‘cast_base_lib-1.0.20-release.aar’, ext: ‘aar’), 

2. Implement the ModuleImpItf interface, refer to AirplayModuleImp. The reqMediaChannel interface returns an instance of the MediaChannel, and launches the playback interface.

3. Implement the MediaChannel related function interface, refer to AirplayMirrorChannel,AirplayAudioChannel,AirplayUrlPlayChannel.

4. To implement its playback interface, refer to the implementation of AirplaySurfaceVideoView in the view package, and set the Surface of the playback interface to MediaChannel.