Version Recorder Date Judges Content
0.9 吴工 2018-11-15 First draft
1.0 方工 2018-12-20 Update SDK import method.
1.1 吴工 2019-01-21 Modify part of the interface

1 Overview

1.1 Purpose

Used to guide developers using BiJie’s BJCast AirplayProxyReceiver SDK for development and testing.

1.2 Readers

This document is intended for developers who develop the receiving end functionality of the Android platform BJCast AirplayProxyReceiver SDK.

1.3 Definition of abbreviations

Airplay Wireless Communication Technology developed by Apple

2 Scope

2.1 Feature

The SDK can be docked using the IOS transmitter implemented by BJAirplaySDK, and can receive its Airplay image projection screen and provide application interface application integration.

2.2 Framework

BJAirplayProxyReceiver SDK is divided into two layers

  • cast_base_lib-1.0.17-release.aar:it’s an Android Module,It defines the
    basic MediaChannel,and related JNI interface.
  • bj_simple_airplay_lib-1.0.18-release.aar:it’s an Android Module,defines
    AirplayModule, and related JNI interfaces.

The application should be based on bj_simple_airplay_lib-1.0.18-release.aar.
The application should not be modified in principle in cast_base_lib-1.0.17-release.aarbj_simple_airplay_lib-1.0.18-release.aar.


BJAirplayReceiver SDK Demo is a reference implementation of the receiver, which implements the Airplay receiver function based onbj_airplay_lib-1.0.17-release.aar:

  • AirplayModuleImp implements the ModuleImpItf interface.
  • AirplayMirrorChannel implements the MediaChannel interface to handle the processing of Airplay mirror sessions.
  • AirplayUrlPlayChannel implements the MediaChannel interface and implements the handling of Airplay URL playback sessions.

2.4 SDK Deliverable

  • SDK library (two AAR files)
  • DEMO source code
  • SDK interface documentation

3 Interface

3.1 Describer

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

The AirplayModule class provides initialization of the SDK, initialization of the SDK, and forced termination of a session and other interfaces.

ModuleImpItf is an interface class that needs to be implemented by the user. The SDK informs the user program of the start and end of the Airplay projection session through the interface class. The user program needs to create the corresponding MediaChannel implementation class and corresponding player application according to different session types.

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

Users need to implement MediaChannel, ModuleImpItf related interface, also refer to the DEMO source code provided by our company. The interfaces are defined primarily in the AirplayModule, the ModuleImpact and MediaChannel classes;

3.2 AirplayModule class

3.2.1 Set Custom Implementation

public void setImp(ModuleImpItf imp)

  • INPUT:
    • imp: User-implemented instance of ModuleImpItf interface.

3.2.2 Init

public native boolean init(Properties props)

  • INPUT:
    • props: Properties supports the setting of the following properties:
      • PARA_NAME_KEY_ROTATION: Whether the mirror playback supports rotation, the value range is 0, 1. The default is 1
      • PARA_NAME_KEY_RESOLUTION: Resolution supported by the Airplay protocol on the receiving end, in the range of 0, 1. The default is 0, 0: indicates 1080P, and 1 indicates 720P.
      • PARA_NAME_KEY_FRAMERATE: Frame rate setting, the range is 30,60. The default is 60
    • boolean: true is inited successful; false is inited failed;
  • Description:
    The AirplayModule class’s init method initializes the Airplay receiver module. The App is called when the startup is initialized, and the AirplayModule object should be inited only one times.

3.2.3 Deinitializing

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.2.4 Kickout one User

public native void kickOut(MediaChannel channel)

  • INPUT:
    • Channel: is the corresponding session created by ModuleImpItf::reqMediaChannel.

3.2.5 Callback of Created Channel

public MediaChannel reqMediaChannel(MediaChannelInfo channelInfo, UserInfo

  • INPUT:
    • channelInfo: describes the type information of the current session.
    • userInfo: describes the IP, device model, and device name of the transmitter.
    • MediaChannel: the creaded media channel
  • Description:
    This is a callback interface. When the Airplay protocol stack finds channel access, the JNI layer will actively call this interface. The application layer needs to implement the relevant logic. It needs to implement the logic in the client’s own ModuleItf implementation class.

Specific implementation can refer to the DEMO source code.

3.2.6 Callback of Released Channel

public void relMediaChannel(MediaChannel channel)

  • INPUT:
    • channel: the MediaChannel which created by reqMediaChannel.
  • Description:
    The callback interface is called when the underlying ends the channel . The application layer implements the relevant logic.

    Specific implementation can refer to the DEMO source code.

3.3 MediaChannel Class

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. The application of receiver needs to focus on the following interfaces.

3.3.1 Setting the window handle

public void setSurface(Surface surface)

  • INPUT:
    • surface:the windows handle of the video view
  • Description:
    Configure the window handle for the render output. The Surface is obtained from the player view created by the user.

    Can refer to the implementation in Demo.

3.3.2 Callback of Audio Data

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. The PCM format is bit depth 16, the number of channels is 2, and the sampling rate is 44100. Note that the time stamp ts of the audio and video data has been converted to the time system of us, so the audio and video synchronization can be directly processed in the application layer in units of us.

    This interface involved while this is a Airplay mirroring session.

    Can refer to the implementation in Demo.

3.3.3 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 render. Specific implementation can refer to the DEMO source code in the SDK.

    This interface involved while this is a Airplay mirroring session.

    Can refer to the implementation in Demo.

3.3.4 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.5 Video Rotate interface

public void rotate(int angle)

  • INPUT:
    • angle: the angle of rotate, the range is 0,90,180,270
  • Description:
    the callback function that to notice application should be rotate the video view.
    while PARA_NAME_KEY_ROTATION set to 1, this function maybe called while iphone is rotated.
    This interface involves while this is Airplay mirroring session

3.3.6 URL Pause Interface

public void pause()

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

3.3.7 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.8 URL Seek Interface

public void seek(int sec)

  • INPUT:
    • sec: the position of the play, 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.9 Obtain Position of URL

public int getPts()

    • int: return the position of the play of video or audio. The unit is millisecond.
  • Description:
    This interface involves the Airplay URL play feature.

3.3.10 Get length of URL

public int getDuation()

    • int:return the total length of the video or audio play. The unit is millisecond.
  • Description:
    This interface involves the Airplay URL play feature.

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 or not to accept the logical control of a session.

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.

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_simple_airplay_lib-1.0.17-release.aar', ext: 'aar')
    compile (name: 'cast_base_lib-1.0.17-release.aar', ext: 'aar'), 
  1. Implement the ModuleImpItf interface, refer to AirplayModuleImp. The reqMediaChannel interface returns an instance of the MediaChannel, and launches the playback interface.
  2. Implement the MediaChannel related function interface, refer to AirplayMirrorChannel, AirplayUrlPlayChannel.
  3. 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.

6 Differences from Airplay

  • This way you can cast screens between different LANs, while standard Airplay can only cast screens in the same LAN.
  • The transmitter of this mode needs to use the APP, which can realize more functions, such as short code projection, zooming in and out, etc.Only supports Airplay image, supports switching to URL delivery in mirror mode
  • This mode does not support the URL method, and the standard Airplay is supported.