Recording Video with CameraX VideoCapture API
source link: https://medium.com/androiddevelopers/recording-video-with-camerax-videocapture-api-a36cfd8a48c8
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
Recording Video with CameraX VideoCapture API
Posted by Trevor McGuire, Software Engineer, and Gerry Fan, Android DevRel Engineer
A picture is worth a thousand words, and CameraX ImageCapture
has already made it much easier to tell your story through still images on Android. Now with the new VideoCapture API
, CameraX can help you create thousands of continuous pictures to tell an even better and more engaging story! The VideoCapture API
tremendously simplifies the video recording task so that you can focus on other important parts of your cutting-edge apps!
In this post, we will introduce the new CameraX VideoCapture API
and how to use it in your applications.
Architected to be simple to use
VideoCapture
is a new CameraX UseCase
, together with the other three predefined UseCases
to cover different Camera needs in your applications:
At an architectural level, CameraX VideoCapture API in CameraX (1.1.0-beta01 and higher) works like this:
VideoCapture
configures the Camera to generate video frames (with video stabilization enabled, etc.).Recorder
encodes and compresses the video frames with appropriate bit rate(also synchronizes with the audio stream if audio recording is enabled).Recorder
combines the Video and Audio streams into one stream.Recorder
writes the combined stream to a file on disk.
This is most likely similar to other capturing systems that you are already familiar with, but note that it hides the complex logic required to make all these pieces work together seamlessly. Now let’s see how to get a VideoCapture
session up.
At the interface level, apps configure a VideoCapture UseCase
in these two stages:
- First, configure an output type:
Recorder
is the one to use for now, but more are planned for the future. - Second, create and configure a
Recording
session: multiple recordings can be created from the sameRecorder
, but only one can be active (recording video) at any time.
Here’s a high level view of the API configuration steps. The shaded blocks are parts of VideoCapture API
:
Using the VideoCapture API
Similar to other CameraX UseCases
, follow these generic steps to record with VideoCapture
:
- Add CameraX dependencies.
- Create a
VideoCapture UseCase
and aCameraSelector
. - Bind to a lifecycle owner.
- Create a
Recording
session (specific to theVideoCapture UseCase
). - Start and stop the session (specific to the
VideoCapture UseCase
).
The sections below have the details.
Add CameraX Dependencies
Start by adding the CameraX libraries into your dependencies. VideoCapture
is implemented with the camera-video
library, but you’ll also need other CameraX libraries, so we recommend simply adding them all to make things easier. Starting from 1.1.0-beta01
release, all Camerax components have been converged to the unified versioning: in the 1.1.0-beta01
and later releases, all components are at the same version, including camera-video
. This makes managing the dependencies simpler.
Create VideoCapture UseCase
To create a VideoCapture
instance, your app needs to know the type of the VideoOutput
for the VideoCapture UseCase
. In this release, Recorder
performs file recording, which saves recorded video to the local storage described in a later step. Your app can use the default settings or specify a video Quality
, as described next, when building a Recorder
object.
Select the Video Resolution
Video resolution capabilities vary on different hardware platforms. To provide a generic API and encourage platform innovation, CameraX implements these two facilitating classes:
Quality
, which lets you specify the target resolution, including Ultra HD (UHD
), Full HD (FHD
), High Definition(HD
), and Standard Definition (SD
). The exact dimension for each resolution is up to the platform implementation.QualitySelector
, which lets you define a selecting strategy from the predefinedQuality
resolutions.
Apps can specify one of several Quality
options, with or without a FallbackStrategy
, to authorize CameraX to choose the best video recording resolution. For example, the following code creates a QualitySelector
with the highest resolution supported on the platform, and if the highest resolution can not be achieved with the requested UseCase
combination or for other reasons, lets CameraX pick any resolution that is supportable.
Similarly the application can also specify a QualitySelector
with an ordered list of Quality
options, plus an optional FallbackStrategy
. Check out the reference doc for usage details.
Apps can also query for the underlying platform resolution capabilities, in terms of Quality
and Size
, with the QualitySelector
class. For example the following code can pull a list of the supported VideoCapture Qualities
and their corresponding resolutions:
Please note that the returned resolutions may not be supportable when the UseCase
combination changes, or when additional camera features, such as Extensions
, are required. For those reasons, we highly recommend setting a fallback strategy when creating your QualitySelector
.
Create a Recorder and a VideoCapture UseCase Instance
With a QualitySelector
, creating a Recorder
type of VideoCapture
is simple:
Bind the UseCase to a LifecycleCamera
CameraX provides LifecycleCamera
interface to manage Camera’s life cycles on application’s behalf. Applications creates a LifecycleCamera
by binding a CameraSelector
and the use case combinations to a LifecycleOwner
such as your activity or your fragment:
The above code snippet binds a Preview
and VideoCapture
combination, the default back-facing camera to an AndroidX Fragment
. This camera will be closed and any in-progress recording will also be automatically stopped when the LifecycleOwner
is stopped.
You can further configure the Camera
instance that is returned from ProcessCameraProvider.bindToLifecycle()
. For example, Torch
can be enabled before or during a recording, and Zoom
controls can also be used during a recording. Refer to the official documentation for the detailed instructions.
Note that this step is common to all CameraX UseCases
(such as Preview
, ImageCapture
, and ImageAnalysis
).
In the current release, the valid UseCase
combinations are:
VideoCapture
+Preview
— supported for all camera devices.VideoCapture
+Preview
+ImageCapture
— requires LIMITED and above Camera2 device.VideoCapture
+Preview
+ImageAnalysis
— requires LEVEL_3 Camera2 devices available from Android N (API Level 24) and above.
You can build a CameraSelector
to your particular requirements; for example, the following code creates a LEVEL_3 camera device CameraSelector
if the platform has one:
To see the latest supported combinations, check out the documentation.
Create the recording session
After the VideoCapture UseCase
is bound to a LifecycleCamera
, the contained Recorder
is ready to be used, and from a Recorder
, applications can create Recording
instances to record video (and audio). A Recording
has two stages, the PendingRecording
stage for configuration and the active Recording
stage for run-time control:
You need to prepare a Recording
with:
OutputOptions
, which can beAndroid MediaStore, File
, orFileDescriptor
- a
VideoRecordEvent
listener to respond to run-time recording events
And optionally:
- include
Audio
in this recording (Audio recording is Off by default)
The PendingRecording
is turned into an active Recording
object right after the application calls the start()
method to kick start recording. The PendingRecording
class offers a fluent API for configuring the Recording
, and in most cases does not need to be stored by the application. Concurrent recordings are unsupported with this release, and an application can have one active Recording
at any time. To record multiple clips, create a new Recording
after the current capture completes.
CameraX video capture operates asynchronously: application requests such as start capturing will occur on a background executor; applications get notified, at a later time via capture events, when those requests are indeed carried out by CameraX. In this sense, applications will need to create and pass a VideoRecordEvent
listener when calling the PendingRecording.start()
method described later in this post. For example, the following code creates a simple listener to notify user about the Start
and the Finalize
events:
CameraX implements a rich set of VideoRecordEvents
, including the start()
method and others that we will touch on in the next section. Make sure to check out the API documentation for the complete events and descriptions. As a general guideline, for any runtime control that you use, you need to handle its corresponding VideoRecordEvent
.
One thing to notice is that every VideoRecordEvent
includes a RecordingStats
object indicating the audio and video capture statistics , such as the file size and duration of the current recording. Your app can use this to display the recording progress to users.
Once you have aVideoRecordEvent
listener, creating a Recording
is straightforward. For example, the following code creates a Recording
to capture a media file in the Android MediaStore
:
With the Recording
started, now let’s see what application can do next.
Run-time control the Recording
For an active Recording
, applications can take the following actions:
All run-time control requests to the CameraX Recording
, including the PendingRecording.start()
, are carried out asynchronously by CameraX
:
CameraX
enqueues the request and immediately returns the control to the application.CameraX
notifies the application when the request is fulfilled, with its corresponding event object.
The application needs to handle the events in its VideoRecordEvent
listener in order to know the result of run-time control requests, and update other parts of the application, such as updating UI or playing back the captured video. For example, the following code uses a Inten.ACTION_VIEW
to playback the recorded video:
That’s all that is needed to record a Video with the new CameraX VideoCapture
API!
What’s next for VideoCapture API?
Sharing videos with friends and on social media is more popular than ever, and CameraX wants to help you support this growing trend. We’re considering new features that you’ve requested, such as buffer transformations and using multiple camera sources in the same recording, and we’re continuing to invest in the API to give you a simple and consistent video capturing experience across all of Android.
We see the CameraX project as a collaboration between Android, our device manufacturers, and you, our camera app developers. We’re inviting you to join this project by creating pull requests, sharing your feedback and ideas in the CameraX developer group, or filing issues in the CameraX issue tracker. Thanks for the feedback you’ve given so far!
To learn more about CameraX, visit the CameraX documentation, CameraX codelab, and github samples; to keep up with the latest CameraX development, join the CameraX developer forum if you are not there yet.
Recommend
About Joyk
Aggregate valuable and interesting links.
Joyk means Joy of geeK