--- layout: page title: "v1 Migration Guide" subtitle: "Breaking Changes & new concepts" category: extra date: 2018-12-20 19:01:55 order: 1 --- CameraView v2 introduces various breaking changes that will allow for more flexibility in the future, removes useless features and makes method names consistent. Upgrading will require addressing these in your app, plus understanding new concepts. Until the final v2 release, these things might change, but likely they will not. ### Open, not start The `start()` method has been renamed to `open()`, and the `stop()` method to `close()`. This was done for consistency with the `onCameraOpened` callback. ### Jpeg Quality Both `cameraJpegQuality` and `setJpegQuality()` have been removed. They were working only with specific setups and made no real sense. We will use the default quality provided by the camera engine. ### Crop Output Both `cameraCropOutput` and `setCropOutput()` have been removed. This was an expensive operation that worked with pictures only. In v2, if you want your output to be cropped to match the view bounds, you will use the `*snapshot()` APIs (see below). ### Video Quality This was an opaque option packaging various parameters. It has been removed. You are expected to control the video quality by choosing the video size and setting video parameters with new APIs (see below). ### CameraUtils - The `BitmapCallback` has been moved into a separate class. - The `BitmapCallback` result is now `@Nullable`! This will happen if we encounter an `OutOfMemoryError` during decoding. You should consider passing a maxWidth and maxHeight instead of loading the full image. ### CameraOptions - Methods returning a `Set` now return a `Collection` instead. - `isVideoSnapshotSupported()` was removed, as we do not rely on internal video snapshot feature anymore. See below. - In addition to `getSupportedPictureSizes` and `getSupportedPictureAspectRatio`, we now have equivalent methods for video. See below. ### Session type The `SessionType` has been renamed to `Mode` which has a clearer meaning. - `setSessionType()` is now `setMode()` - `cameraSessionType` is now `cameraMode` ### Sizing - `getPreviewSize()` was removed. - `getPictureSize()`: now returns the real output picture size. This means that it accounts for rotation. It will also return `null` while in `VIDEO` mode: use getVideoSize in that case. - `getVideoSize()`: added. Returns the real output video size. This means that it accounts for rotation. It will return `null` while in `PICTURE` mode. - `getSnapshotSize()`: This is the size of pictures taken with `takePictureSnapshot()` and videos taken with `takeVideoSnapshot()`. It accounts for rotation and cropping. Read about snapshots below. As you might have guessed, video size is now configurable, with the addition of `setVideoSize(SizeSelector)` method. It works exactly like the picture one, so please refer to the size selector documentation. Defaults to `SizeSelectors.biggest()`. The engine will use the video size selector when mode is `VIDEO`, and the picture size selector when mode is `PICTURE`. ### Picture and videos #### Take, not capture - `capturePicture()` is now `takePicture()` - `captureSnapshot()` is now `takePictureSnapshot()` - `startCapturingVideo()` is now `takeVideo()`. Signature changed from long to int - `isCapturingVideo()` is now `isTakingVideo()` The new `isTakingPicture()` method was added for symmetry with videos. #### Snapshots This is the major improvement over v1. There are now 4 capture APIs, two for pictures and two for videos. - Standard APIs: `takePicture()` and `takeVideo()`. These take a high quality picture or video, depending on the `SizeSelector` and parameters that were used. The standard APIs **must** be called in the appropriate `Mode` (pictures must be taken in `PICTURE` mode, videos must be taken in `VIDEO` mode). - Snapshot APIs: `takePictureSnapshot()` and `takeVideoSnapshot()`. These take a super fast, reliable snapshot of the camera preview. The snapshot APIs can be called in any `Mode` (you can snap videos in picture mode). The good news is that snapshot APIs will **automatically crop the result**, for both video and pictures, which means that **square videos** or any other ratio are possible. |Method|Takes|Quality|Callable in `Mode.PICTURE`|Callable in `Mode.VIDEO`|Auto crop|Output size| |------|-----|-------|--------------------------|------------------------|---------|-----------| |`takePicture()`|Pictures|Standard|`yes`|`no`|`no`|That of `setPictureSize`| |`takeVideo()`|Videos|Standard|`no`|`yes`|`no`|That of `setVideoSize`| |`takePictureSnapshot()`|Pictures|Snapshot|`yes`|`yes`|`yes`|That of the view| |`takeVideoSnapshot()`|Videos|Snapshot|`yes`|`yes`|`yes`|That of the view| The video snapshot supports audio and respects the `Audio`, max duration, max size & codec settings, which makes it a powerful tool. The drawback is that it needs: - API 18. If called before, it throws - An OpenGL preview (see below). If not, it throws #### Video capturing Some new APIs were introduced, which are respected by both standard videos and snapshot videos: - `setAudioBitRate()` and `cameraAudioBitRate`: sets the audio bit rate in bit/s - `setVideoBitRate()` and `cameraVideoBitRate`: sets the video bit rate in bit/s ### Camera Preview The type of preview is now configurable with `cameraPreview` XML attribute and `Preview` control class. This defaults to the new `GL_SURFACE` and it is highly recommended that you do not change this. |Preview|Backed by|Info| |-------|---------|----| |`Preview.SURFACE`|A `SurfaceView`|This might be better for battery, but will not work well (AFAIR) with dynamic layout changes and similar things. No support for video snapshots.| |`Preview.TEXTURE`|A `TextureView`|Better. Requires hardware acceleration. No support for video snapshots.| |`Preview.GL_SURFACE`|A `GLSurfaceView`|Supports video snapshots. Might support GL real time filters in the future.| The GL surface, as an extra benefit, has a much more efficient way of capturing picture snapshots, that avoids OOM errors, rotating the image on the fly, reading EXIF, and other horrible things belonging to v1. These picture snapshots will also work while taking videos. ### Advanced feature: Preview Sizing We finally introduced a `setPreviewSize()` method which accepts a `SizeSelector`. The use of this method is discouraged if you don't know exactly what you are doing. The default preview size selector is already smart enough to - respect the picture/video aspect ratio - be a bit bigger than the view so that there is no upscaling There are not so many reason why you would use this method, other than, for example, control the frame processor size or, indirectly, the snapshots size. If what you are doing is just assigning an aspect ratio, for instance, please do so using `setPictureSize()` and `setVideoSize()`. **Note**: `getPreviewSize()` was removed as it has no useful meaning. ### CameraListener The listener interface brings two breaking signature changes: - `onPictureTaken()` now returns a `PictureResult`. Use `result.getJpeg()` to access the jpeg stream. The result class includes rich information about the picture (or picture snapshot) that was taken, plus handy utilities (`result.asBitmap()`...) - `onVideoTaken()` now returns a `VideoResult`. Use `result.getFile()` to access the video file. The result class includes rich information about the video (or video snapshot) that was taken. ### Experimental mode The v2 version introduces a `cameraExperimental` XML flag that you can use to enable experimental features. Might be used in the future to speed up development. ### Other improvements & changes - Added `@Nullable` and `@NonNull` annotations pretty much everywhere. This might **break** your Kotlin build. - Added `setGridColor()` and `cameraGridColor` to control the grid color - Default `Facing` value is not `BACK` anymore but rather a value that guarantees that you have cameras (if possible). If device has no `BACK` cameras, defaults to `FRONT`. - Removed `ExtraProperties` as it was useless. TODO: opencollective? TODO: improve the focus marker drawing, move out of XML (accept a drawable?)