OMCS 开发手册之 Android SDK 说明

      (OMCS android SDK 目前版本提供的功能有:语音、视频、远程桌面(手机屏幕分享)、电子白板。) 

  如果您已经了解了OMCS语音视频框架PC版本的使用方法,那么上手Android版本的SDK是非常简单的。在本文中,我们将安卓SDK中重要的API列出来加以说明,很多重复性的内容就不再一一赘述了。

一. IMultimediaManager 接口

OMCS框架客户端的核心接口是IMultimediaManager(多媒体管理器接口),在客户端中以单例模式提供,可以通过MultimediaManagerFactory类的静态方法GetSingleton()获取该单例的引用。IMultimediaManager接口定义中基础的部分如下:

/**
     * 与多媒体服务器建立连接,并初始化本地多媒体管理器。
     * 如果与服务器连接失败,将抛出网络异常。
     *
     * @param userID     当前登陆的用户ID。
     * @param password   当前登录的用户的密码。
     * @param serverIP   OMCS服务器IP
     * @param serverPort OMCS服务器端口
     * @param context
     */
    LogonResponse initialize(String userID, String password, String serverIP, int serverPort, Context context) throws InterruptedException;

    /**
     * 与OMCS服务器的TCP连接状态监听
     * @param connectionEventListener 连接状态监听器
     */
    void  setConnectionEventListener(IConnectionEventListener connectionEventListener);

    /**
     * 设备的guest监听。
     * @param listener
     */
    void setDeviceGuestListener(IDeviceGuestListener listener);

    /**
     * 主动断开来访者guest到本地多媒体设备的连接。
     * @param guestID 来访者ID
     * @param deviceType  设备类型
     * @param notifyGuest 是否通知对方。如果通知对方,对方的连接器将触发Disconnected事件。
     */
    void disconnectGuest(String guestID, MultimediaDeviceType deviceType, boolean notifyGuest);

    /**
     * 查询本地的某设备是否正在工作?     *
     * @param deviceType 设备类型
     * @return 工作中?
     */
    boolean deviceIsWorking(MultimediaDeviceType deviceType);

    /**
     * 当前登录用户的ID。
     *
     * @return
     */
    String getCurrentUserID();

    /**
     * 获取语音消息控制器。
     * @return
     */
    IAudioMessageController getAudioMessageController();

    /**
     * 在广播帧的时候,是否允许丢弃帧。必须在初始化前设置才有效。     *
     * @param isAllow
     */
    void setAllowDiscardFrameWhenBroadcast(boolean isAllow);

    /**
     * 注入自定义的摄像头采集器。将取代OMCS框架内部自带的摄像头采集器。
     * @param cameraCapturer
     */
    void setCameraCapturer(ICameraCapturer cameraCapturer);

   /**
     * 注入自定义的麦克风采集器。将取代OMCS框架内部自带的麦克风采集器。
     * @param microphoneCapturer
     */
    void setMicrophoneCapturer(IMicrophoneCapturer microphoneCapturer);

    /**
     * 注入自定义的桌面采集器。将取代OMCS框架内容自动的桌面采集器
     * @param desktopCapturer
     */
    void setDesktopCapturer(IDesktopCapturer desktopCapturer);

 

基础部分的方法很容易理解,但要注意:

(1)与服务器的连接状态         

        IConnectionEventListener接口 用于监听与服务器TCP连接的状态监听,比如,连接断开、重连开始、重连完成等事件。(注意:OMCS框架内部采用了自动重连机制)

       通过IMultimediaManager的setConnectionEventListener方法注入该监听器。

(2)Guest连接、断开事件

        IDeviceGuestListener接口 用于监听Guest连接到我的设备,或与我的设备断开连接的事件。

       通过IMultimediaManager的setDeviceGuestListener方法注入该监听器。  

1.摄像头

IMultimediaManager接口中与摄像头设置相关的方法如下:

 /**
     * 使用的摄像头索引
     */
    int getCameraDeviceIndex();

    /**
     * 设置使用的摄像头的索引。
     * @param index 0-后 1-前
     */
    void setCameraDeviceIndex(int index);

    /**
     * 切换摄像头并重新打开指定摄像头(必须设置配置参数,否则报错)
     * @param index 0-后 1-前
     */
    void switchCameraDeviceIndex(int index) throws Exception;

    /**开始相机预览。
     * @param holder
     */
    void startCameraPreview( SurfaceHolder holder );

    /**
     * 设置打开相机的回调。
     * @param _callback
     */
    void setCameraOpenCallBack(ICamOpenOverCallback _callback);

    Camera getCamera();

    /**
     * 旋转摄像头预览图像
     * @param rotateAngle
     */
    void setCameraRotateAngle(RotateAngle rotateAngle);

    /**
     * 获取摄像头采集视频的分辨率。
     */
    Size getCameraVideoSize();

    /**摄像头采集视频的大小。默认为320x240。
     * @param width 宽
     * @param height 高
     */
    void setCameraVideoSize(int width,int height);

    /**
     * 本地摄像头视频的编码质量。取值0~31,默认值10。取值越小,越清晰。
     *
     * @param quality
     */
    void setCameraEncodeQuality(int quality);

    /**
     * 是否将摄像头集到的视频输出给Guest。(必须在初始化完成之后设置才有效)
     * 如果为true,表示输出;否则,表示将采集到的视频数据丢弃,不发送给guest。默认值为true。
     *
     * @param isOutput
     */
    void setOutputVideo(boolean isOutput);

(1)CameraSurfaceView 类

          OMCS 提供了 CameraSurfaceView 类,用于显示自己的摄像头的预览画面,OMCS框架会在其surfaceCreated回调中自动打开摄像头,并在其surfaceDestroyed回调中关闭摄像头。

          当OMCS打开摄像头完成时,会回调ICamOpenOverCallback 接口。通过IMultimediaManager的setCameraOpenCallBack方法,可以注入自己的ICamOpenOverCallback实现。        

(2)ICamOpenOverCallback 接口

          可以让采集视频的activity实现ICamOpenOverCallback接口,当摄像头打开成功或失败时此回调方法会被调用。

          在打开摄像头成功的回调方法cameraHasOpened里, 调用CameraSurfaceView 的 getSurfaceHolder可以得到SurfaceHolder 引用,将其传给 startCameraPreview方法,便可开启摄像头预览。

(3)setCameraVideoSize 、setCameraEncodeQuality 、setCameraRotateAngle、setCameraDeviceIndex、switchCameraDeviceIndex、setOutputVideo  都很容易理解,不赘述。

2.麦克风             

   /**
     * 控制是否输出麦克风的声音给guest。默认值为true。(必须在初始化完成之后设置才有效)
     * @param isOutput 是否输出?
     */
    void setOutputAudio(boolean isOutput);

        setOutputAudio方法 用于控制是否将声音发送给guest。在抢麦场景中经常使用,默认将setOutputVideo设置为false,抢到麦的就将其设置为true。

3.屏幕/桌面

安卓端可以将自己的屏幕分享给guest观看或监视(guest端可以是PC、安卓、iOS)。

   /**
     * 如果其它guset会连接到当前手机的屏幕(远程桌面、屏幕分享),那么必须先设置Activity。
     * @param activity
     */
    void setDesktopRecordActivity(Activity activity);

    /**
     * 如果其它guset会连接到当前手机的屏幕(远程桌面、屏幕分享),那么必须在setDesktopRecordActivity方法所设置的目标Activity的onActivityResult方法中调用该方法。
     * @param requestCode
     * @param resultCode
     * @param data
     */
    void setDesktopRecordActivityResult(int requestCode, int resultCode, Intent data);
		
    /**
     * 设置允许对方控制自己的桌面 (注 :activity 为null时 ,表示不允许控制)
     * @param activity
     */
    void setDesktopControlActivity(Activity activity) ;
        
    /**
     * 本地屏幕的编码质量。取值0~31,默认值10。取值越小,越清晰。
     *
     * @param quality
     */
    void setDesktopEncodeQuality(int quality);
	
    /**
     * 输出屏幕的分辨率的缩小系数。默认值:0.5。取值范围:大于等于0.1且小于等于1。
     *
     * @param coef 缩小的比例系数。取值范围:大于等于0.1且小于等于1。
     */
    void setDesktopZoomCoef(float coef);

    /**
     * 本地屏幕最大帧频。取值8~30,默认值16。
     *
     * @param maxFPS
     */
    void setDesktopMaxFPS(int maxFPS);

    /**
     * 设置当前桌面设备的运行模式。默认值:DesktopDeviceRunMode.RunWhenNeed。
     * 如果手机持有者拒绝了屏幕采集的权限请求,则将恢复为默认值:DesktopDeviceRunMode.RunWhenNeed。
     * @param mode
     */
    void setDesktopDeviceRunMode(DesktopDeviceRunMode mode)  throws Exception;

    /**
     * 获取当前桌面设备的运行模式。
     * @return
     */
    DesktopDeviceRunMode getDesktopDeviceRunMode();

(1)setDesktopRecordActivity:安卓系统要求在后台采集屏幕图像,必须和一个Activity绑定。

(2)setDesktopRecordActivityResult:当采集屏幕图像时,APP会向安卓系统申请权限,此时界面会弹出权限请求的提示给用户操作同意/拒绝,用户操作之后,APP拿到用户的操作结果(同意或拒绝),则调用setDesktopRecordActivityResult通知OMCS框架。 

 

二.多媒体连接器 Connector

       当自己作为Guest,需要访问Owner的摄像头等设备时,就需要使用连接器。所有的连接器都从MultimediaConnector基类继承,MultimediaConnector包含的功能如下:

    /**
     * 设置连接器事件监听器。    
     */
    void setConnectorEventListener(IConnectorEventListener listener);

    /**
     * 获取当前连接器的设备类型    
     */
    MultimediaDeviceType getDeviceType() ;

    /**
     * 与目标设备是否已连接?     
     */
    boolean isConnected();

    /**
     * Owner方的UserID。
     */
    String getOwnerID();

   /**
     * 尝试连接目标多媒体设备。
     *
     * @param destUserID 目标用户的UserID
     */
    void beginConnect(String destUserID);

    /**
     * 与目标用户的多媒体设备断开连接。
     */
    void disconnect();

 (1)调用beginConnect方法,以尝试连接目标用户Owner的设备,框架将通过回调IConnectorEventListener接口通知连接的结果。

(2)我们要使用的CameraConnector、MicrophoneConnector、DesktopConnector都是从MultimediaConnector继承的。

1.CameraConnector

       摄像头连接器还包含了如下功能:

    /**
     * 设置摄像头连接器状态回调。     
     */
    void setCameraConnectorCallback(ICameraConnectorCallback callback);

    /**
     * 设置要绘制视频的View。    
     */
    void setOtherVideoPlayerSurfaceView(OMCSSurfaceView view);

    /**
     * Owner端是否输出了视频?(对应Owner端可以调用setOutputVideo方法)     
     */
    boolean getOwnerOutput();

    /**
     * 修改Owner端的视频采集分辨率。     
     */
    void changeOwnerCameraVideoSize(int width,int height);

    /**
     * 设置视频图像缩放。
     * @param videoScale 是否等比缩放?如果否,则表示填满画布
     * @param videoScale4BigSide false 表示小的那边留黑边,true表示裁剪大的那一边
     */
    void setVideoUniformScale(boolean videoScale,boolean videoScale4BigSide) 

   /**
     * 设置视频图像旋转的角度(0,90,180,270)。
     * @param angle
     */
    public void setRotateAngle(RotateAngle angle) 

      通过ICameraConnectorCallback回调,我们可以得知Owner端的摄像头采集分辨率发生了变化、outputVideo状态发生了变化。 

      CameraConnector通过OMCSSurfaceView来绘制视频图像:

(1)如果需要旋转视频图像,可以调用CameraConnector的setRotateAngle方法来设置旋转的角度:0,90,180,270。         

(2)如果要设置视频图像是等比缩放还是拉伸以填满画布,可以调用CameraConnector的setVideoUniformScale方法,默认值为false(填满画布)。         

2.MicrophoneConnector

      与CameraConnector相似,甚至更简单,不再赘述。 

3.DesktopConnector

      通过DesktopConnector可以观看Owner端的屏幕,并进行操作。(即远程桌面和远程协助)。

      DesktopConnector与CameraConnector相似,不再赘述。  

4.WhiteBoardConnector

       通过WhiteBoardConnector可以连接到电子白板,并可在电子白板上绘制图形。白板绘制功能接口如下: 

   /**
     * 设置白板课件监听器
     * */
    void setCoursewareListener(ICoursewareListener listener);

    /**
     * 设置Page显示的尺寸(绘图只能在该范围内绘制)  默认尺寸1200,900
     * @param width
     * @param height
     */
    void setPageSize(int width, int height);

    /**
     * 重置界面到最初状态
     * */
    void resetScale();

    /**
     * 设置界面为画曲线状态
     * */
    void setDrawCurveEnable(boolean enabled);

    /**
     * 设置选择View 的状态  (目前仅支持选中PictureView)
     * @param enabled
     */
    void setHitViewEnabled(boolean enabled);

    /**
     * 获取当前选中的View 的状态  (目前仅支持选中PictureView)
     */
    boolean getHitViewEnabled();

    /**
     * 插入图片
     * @param bitmap
     */
    void insertPictureView(Bitmap bitmap);

    /**
     * 设置已选中的PictureView视图为背景
     */
    void setSelectedPictureViewAsBackImage();

    /**
     * 移除背景
     */
    void removeWhiteBoardBackImage();

    /**
     * 移除当前页面自己最后一次新增的view
     * */
    void removeMyLastView();

    /**
     * 设置控制点图像
     * */
    void setPointer(Bitmap bitmap);

    /**
     * 获取Page显示的尺寸
     * @return
     */
    Size getPageSize();

    /**
     * 是否显示Page的边框,默认不显示
     * @param isDisplay
     */
    void setDisplayPageBorder(boolean isDisplay);

    /**
     * 清空当前页
     */
    void clearCurrentPage();

    /**
     * 创建新的一页
     */
    void createPage();

    /**
     * 移除当前页
     * @throws Exception
     */
    void removeCurrentPage() throws Exception;

    /**
     * 获取当前显示页的索引
     * @return
     */
    int getCurrentPageIndex();

    /**
     * 设置当前显示页的索引 (0开始)
     * @param pageIndex
     */
    void setCurrentPageIndex(int pageIndex);

    /**
     * 获取总页数
     * @return
     */
    int getTotalPageCount();

    /**
     * 设置页面事件变动监听器
     * @param listener
     */
    void setPageEventListener(IPageEventListener listener);

     

    其中 IPageEventListener接口定义如下:

     /**
     * 当前页面索引变动 (索引0开始)
     * @param pageIndex
     * @return
     */
    void curPageIndexChanged(int pageIndex);

    /**
     * 当前总页数变动
     * @param totalPageCount
     * @return
     */
    void totalPageCountChanged(int totalPageCount);

     

        关于课件,安卓端白板目前只支持RAR、ZIP的图片压缩包。当PC客户端打开课件时,安卓端白板会自动下载、解压、并在白板中显示课件。

        ICoursewareListener 接口用于监听课件下载与解压的进度,其定义如下:   

  /**
     * 开始下载课件
     * @param courseware
     * @return
     */
    void downloadStarted(String courseware);

    /**
     * 下载课件的进度
     * @param courseware
     * @param progressNum
     * @param totalProgressNum
     * @return
     */
    void downloadProgress(String courseware,long progressNum,long totalProgressNum);

    /**
     * 下载课件失败
     * @param courseware
     * @param failReason
     * @return
     */
    void downloadFail(String courseware,String failReason);

    /**
     * 下载课件完成
     * @param courseware
     * @return
     */
    void downloadCompleted(String courseware);

    /**
     * 开始解压 压缩包课件
     * @param courseware
     * @return
     */
    void decompressStarted(String courseware);

    /**
     * 解压 压缩包课件失败
     * @param courseware
     * @param failReason
     * @return
     */
    void decompressFail(String courseware, String failReason);

    /**
     * 解压 压缩包课件完成
     * @param courseware
     * @return
     */
    void decompressCompleted(String courseware);

三. 语音消息控制器

      类似微信的语音消息功能,通过通过IMultimediaManager的getAudioMessageController方法可以获取语音消息控制器的引用。

      关于IAudioMessageController接口的使用,请参见《OMCS 开发手册(10) -- 语音消息》。        


四. 注入自定义视频流

      通过IMultimediaManager提供的 setCameraCapturer方法来向OMCS 注入自定义的外部视频流,以取代手机摄像头采集到的图像。

    /**
     * 注入自定义的摄像头采集器。将取代OMCS框架内部自带的摄像头采集器。
     * @param cameraCapturer
     */
    void setCameraCapturer(ICameraCapturer cameraCapturer);

      其中ICameraCapturer 接口包含了如下方法:

/**
 * 摄像头采集器接口。
 */
public interface ICameraCapturer {

    /**
     * 采集的视频数据类型 (NV21、H264)
     * @return
     */
    VideoDataType getVideoDataType();

    /**
     * 采集的视频的分辨率。
     * @return
     */
    Size getVideoSize() ;

    /**
     * 开始采集
     * @param callback
     */
    void start(ICameraCapturerCallback callback);

    /**
     * 停止采集
     */
    void stop();
}

      实现 ICameraCapturer 接口,如果我们需要外接注入时,就new一个刚实现的视频采集类的实例注入到多媒体管理器;如果不需要外接数据注入null即可。

 

五. API使用流程

1. 设置多媒体管理器的摄像头,类似下面的示例代码:     

  (1)MultimediaManagerFactory.GetSingleton().setCameraVideoSize(640, 480);

  (2)MultimediaManagerFactory.GetSingleton().setCameraEncodeQuality(15); 

2. 调用多媒体管理器的initialize方法,初始化并登录到OMCS服务器。

3. 使用设备连接器Connector

    (1)调用Connector的setConnectorEventListener设置回调,监听连接目标设备是否成功。

    (2)调用Connector的beginConnect方法,连接到目标设备。

    (3)使用完毕,调用Connector的disconnect方法断开到目标设备的连接。

六. Demo及下载

      我们为 OMCS入门Demo 增加了一个简单的Android客户端,可与PC进行视频聊天,其运行效果如下所示:

      登录:                                                                                                                       

            

       连接对方:  

      

视频对话: 

 

下载:

(1)OMCS入门Demo源码(服务端 + PC端) (安卓端与PC端 公用同一个服务端) 

(2)OMCS入门Demo之Android端 apk  & Source code

(3)Android 注入自定义视频流 Demo 源码

 

下一篇:OMCS FAQ -- OMCS 常见问题解答

上一篇:OMCS 开发手册(11) -- 深入摄像头、麦克风、扬声器

--------------------------------------------------------------------------------------------------------------------  

下载免费版本的OMCS以及 demo源码

阅读 更多OMCS开发手册系列文章

Q Q:168757008

官网: www.oraycn.com

导航

首页

官方网站

联系我们

站内搜索

OrayTalk 企业即时通讯系统

傲瑞通官网

详细说明

客户端下载

OrayMeeting 视频会议系统

详细说明

客户端下载

ESFramework 通信框架

详细说明

SDK与Demo下载

ESFramework FAQ

版本变更记录

OMCS 语音视频框架

详细说明

SDK与Demo下载

OMCS FAQ

版本变更记录

OVCS 视频会议Demo

详细说明

源码下载

傲瑞实用组件

SDK下载

H5Media 纯网页音视频交互

NPusher 推流组件

MCapture 语音视频采集组件

MFile 语音视频录制组件

MPlayer 语音视频播放组件

OAUS 自动升级系统

StriveEngine 轻量级的通信引擎

傲瑞组件 FAQ

授权

授权流程

产品选购指南

授权方案说明

授权SDK使用说明

其它

支持信创国产化

SDK使用技巧

联系我们