Package com.twilio.video

Class Camera2Capturer

  • All Implemented Interfaces:
    VideoCapturer, VideoCapturer
    public class Camera2Capturer
extends java.lang.Object
implements VideoCapturer
    The Camera2Capturer class is used to provide video frames for a LocalVideoTrack from the provided cameraId. The frames are provided via a CameraCaptureSession. Camera2Capturer must be run on devices Build.VERSION_CODES.LOLLIPOP or higher.

    This class represents an implementation of a VideoCapturer interface. Although public, these methods are not meant to be invoked directly.

    This capturer can be reused, but cannot be shared across multiple LocalVideoTracks simultaneously. It is possible to construct multiple instances with different camera IDs, but there are device specific limitations on how many camera2 sessions can be open.

    • Constructor Summary

      Constructors 
      Constructor Description
      Camera2Capturer​(android.content.Context context, java.lang.String cameraId)
      Constructs a Camera2Capturer instance.
      Camera2Capturer​(android.content.Context context, java.lang.String cameraId, Camera2Capturer.Listener listener)
      Constructs a Camera2Capturer instance.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void dispose()
      This method provides an optional step to perform a final cleanup.
      java.lang.String getCameraId()
      Returns the currently set camera ID.
      void initialize​(SurfaceTextureHelper surfaceTextureHelper, android.content.Context context, CapturerObserver capturerObserver)
      This function is used to initialize the camera thread, the android application context, and the capture observer.
      boolean isScreencast()
      Indicates that the camera2 capturer is not a screen cast.
      static boolean isSupported​(android.content.Context context)
      Indicates if Camera2Capturer is compatible with device.
      void startCapture​(int width, int height, int framerate)
      Start capturing frames in a format that is as close as possible to width x height and framerate.
      void stopCapture()
      Stops all frames being captured.
      void switchCamera​(java.lang.String newCameraId)
      Switches the current cameraId.
      boolean updateCaptureRequest​(CaptureRequestUpdater captureRequestUpdater)
      Schedules a capture request update.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Constructor Detail

      • Camera2Capturer

        public Camera2Capturer​(@NonNull
                       android.content.Context context,
                       @NonNull
                       java.lang.String cameraId)
        Constructs a Camera2Capturer instance.
        Parameters:
        context - application context
        cameraId - unique identifier of the camera device to open that must be specified in CameraManager.getCameraIdList()

      • Camera2Capturer

        public Camera2Capturer​(@NonNull
                       android.content.Context context,
                       @NonNull
                       java.lang.String cameraId,
                       @Nullable
                       Camera2Capturer.Listener listener)
        Constructs a Camera2Capturer instance.
        Parameters:
        context - application context
        cameraId - unique identifier of the camera device to open that must be specified in CameraManager.getCameraIdList()
        listener - an optional listener of camera2 capturer events

    • Method Detail

      • isSupported

        public static boolean isSupported​(@NonNull
                                  android.content.Context context)
        Indicates if Camera2Capturer is compatible with device.

        This method checks that all the following conditions are true:

        1. The device API level is at least Build.VERSION_CODES.LOLLIPOP.
        2. All device cameras have hardware support level greater than CameraMetadata.INFO_SUPPORTED_HARDWARE_LEVEL_LEGACY.

        For more details on supported hardware levels see the Android documentation.
        Parameters:
        context - application context.
        Returns:
        true if device supports Camera2Capturer and false if not.

      • isScreencast

        public boolean isScreencast()
        Indicates that the camera2 capturer is not a screen cast.
        Specified by:
        isScreencast in interface VideoCapturer
        Returns:
        true if-and-only-if this is a screen capturer.

      • initialize

        public void initialize​(@NonNull
                       SurfaceTextureHelper surfaceTextureHelper,
                       @NonNull
                       android.content.Context context,
                       @NonNull
                       CapturerObserver capturerObserver)
        Description copied from interface: VideoCapturer
        This function is used to initialize the camera thread, the android application context, and the capture observer. It will be called only once and before any startCapture() request. The camera thread is guaranteed to be valid until dispose() is called. If the VideoCapturer wants to deliver texture frames, it should do this by rendering on the SurfaceTexture in surfaceTextureHelper, register itself as a listener, and forward the frames to CapturerObserver.onFrameCaptured(). The caller still has ownership of surfaceTextureHelper and is responsible for making sure surfaceTextureHelper.dispose() is called. This also means that the caller can reuse the SurfaceTextureHelper to initialize a new VideoCapturer once the previous VideoCapturer has been disposed.
        Specified by:
        initialize in interface VideoCapturer

      • startCapture

        public void startCapture​(int width,
                         int height,
                         int framerate)
        Description copied from interface: VideoCapturer
        Start capturing frames in a format that is as close as possible to width x height and framerate.
        Specified by:
        startCapture in interface VideoCapturer

      • stopCapture

        public void stopCapture()
        Stops all frames being captured.

        Note: This method is not meant to be invoked directly.

        Specified by:
        stopCapture in interface VideoCapturer

      • getCameraId

        @NonNull
public java.lang.String getCameraId()
        Returns the currently set camera ID.

      • switchCamera

        public void switchCamera​(@NonNull
                         java.lang.String newCameraId)
        Switches the current cameraId.
        Parameters:
        newCameraId - the new camera id.

      • updateCaptureRequest

        public boolean updateCaptureRequest​(@NonNull
                                    CaptureRequestUpdater captureRequestUpdater)
        Schedules a capture request update.

        A CaptureRequest.Builder optimal for capturing video for streaming will be provided for modification to the provided CaptureRequestUpdater. Modifications to the CaptureRequest.Builder will be applied to the CameraCaptureSession after the invocation of CaptureRequestUpdater.apply(CaptureRequest.Builder). updateCaptureRequest(CaptureRequestUpdater) can be invoked while capturing frames or not. If the Camera2Capturer is not capturing the CaptureRequestUpdater will be called when capturer resumes.

        The following snippet demonstrates how to turn on the flash of a camera while capturing. 

        
     // Create the camera2 capturer
     Camera2Capturer camera2Capturer = new Camera2Capturer(context, cameraId, camera2Listener);

     // Start the camera2 capturer
     LocalVideoTrack camera2VideoTrack = LocalVideoTrack.create(context, true, camera2Capturer);

     // Schedule the capture request update
     camera2Capturer.updateCaptureRequest(new CaptureRequestUpdater() {
         @Override
         public void apply(@NonNull CaptureRequest.Builder captureRequestBuilder) {
             captureRequestBuilder.set(CaptureRequest.FLASH_MODE, CaptureRequest.FLASH_MODE_TORCH);
         }
     }

        The camera2 capturer will raise an Camera2Capturer.Exception to the provided Camera2Capturer.Listener with the code Camera2Capturer.Exception.CAPTURE_REQUEST_UPDATE_FAILED if a successfully scheduled capture request update failed to be applied.

        Parameters:
        captureRequestUpdater - capture request updater that receives the capture request builder that can be modified.
        Returns:
        true if the update was scheduled or false if an update is pending or could not be scheduled.