Synchronized recording of video from multiple cameras

You can record a video from multiple cameras. You can make all cameras configured on your system start recording at the same time. The Camera library allows you to start recording from multiple cameras and ensures that the timestamps on the encoded video match.

Here are some situations when synchronized recording is important to ensure that there isn't any latency between the video from multiple cameras:

Synchronizing and replicating multiple streams together. For example, you may need to synchronize and replicate streams from multiple cameras to stitch together a video to give a 360-degree view.
Using time-sensitive algorithms that use multiple camera streams. For example, you may be applying algorithms to identify objects. Typically, the tolerance of delay for playback must be minimal for those algorithms to work properly. Therefore, the recording from multiple cameras must be synchronized to deliver video streams from the imaging datapath in realtime.

When you want to record video from multiple cameras, each camera creates its own file. You can play those individual files separately, or you can run third-party algorithms on the video to combine or stitch together the video. Often these third-party algorithms require that the video is synchronized.

To ensure that the video is synchronized, you must add the cameras into a video group. A video group is a set of cameras associated with each other. When a camera is added into a video group, calls to camera_start_video() or camera_start_encode() no longer start recording or encoding video right away, but wait until a call to camera_start_video_group() is made. You can call camera_start_video() and camera_start_encode() on several cameras and then call camera_start_video_group() to start recording or encoding for all of the cameras in the group, simultaneously.

Here are the basic steps to start recording on multiple cameras at one time:

Open each camera you want to use. You will get a separate handle for each camera. For more information, see “Connect to the camera.”
Set the viewfinder for each camera. For details, see “Set the viewfinder mode for the camera.”
Set up Screen. See “Connect Screen with the Camera API” for more information.
Start the viewfinder and configure camera settings.
Create a Screen context, window, and buffers. For more information, see “Using streams” in the “Resource Sharing” chapter of the Screen Developer's Guide.
If you change the format, width, and height of the viewfinder from its default settings, you must set the matching video properties to those new values because the default properties for video should match the viewfinder properties that were overwritten. The exception is framerate, where you can set the viewfinder to record at an integer multiple of the viewfinder framerate, as long as the framerate isn't higher. For example, if your viewfinder framerate is set to 30 fps, you can record 15 fps (multiple of two) or 10 fps (multiple of three).
You can get the viewfinder properties from the camera using camera_get_vf_property(). Here are the typical properties that you should check:
- CAMERA_IMGPROP_FORMAT
- CAMERA_IMGPROP_WIDTH
- CAMERA_IMGPROP_HEIGHT
- CAMERA_IMGPROP_ROTATION
- CAMERA_IMGPROP_FRAMERATE
- CAMERA_IMGPROP_VIDEOCODEC
  Note: If you set this property to CAMERA_VIDEOCODEC_NONE, you record to uncompressed video. You can specify whether to record to MOV or UCV (UnCompressed Video) when you call camera_roll_open_video(); for more details, see the next step.
- CAMERA_IMGPROP_AUDIOCODEC
Then, you can set the properties using camera_set_video_property(). You can set any of the properties listed above using this function.
Create a video group using camera_create_video_group(). You will get a group ID passed back by reference from the call.
Call camera_add_video_group_entry() to associate (or add) each camera into the video group. Ensure that you specify the group ID that you got from the previous step and the handle for each camera when you call this function. You can add or remove cameras before you call camera_start_video_group() or camera_start_video().
To encode or record video, call camera_start_encode() or camera_start_video(), respectively.
Note: This step doesn't actually start the encoding or recording.
Call camera_start_video_group() to start encoding or recording on all cameras in the group at the same time.
To stop recording, you can call camera_stop_video_group(), but then you must call camera_stop_encode() or camera_stop_video() to finalize encoding or recording the video files for each camera. You can remove cameras from the video group after you stop recording.
When you are done using the video group, call camera_destroy_video_group(). Any cameras still associated with the video group are automatically disassociated from the group before the function completes. It's a good idea to set the group ID variable to CAMERA_VIDEO_GROUP_INVALID after camera_destroy_video_group() completes.