## camerabin2 camerabin2 — CameraBin2 |

## Synopsis

    struct              GstCameraBin2;

## Object Hierarchy

      GObject
       +----GstObject
             +----GstElement
                   +----GstBin
                         +----GstPipeline
                               +----GstCameraBin2

## Implemented Interfaces

GstCameraBin2 implements GstChildProxy and GstTagSetter.

## Properties

      "audio-capture-caps"       GstCaps*              : Read / Write
      "audio-capture-supported-caps" GstCaps*              : Read
      "audio-src"                GstElement*           : Read / Write
      "camera-src"               GstElement*           : Read / Write
      "idle"                     gboolean              : Read
      "image-capture-caps"       GstCaps*              : Read / Write
      "image-capture-encoder"    GstElement*           : Read / Write
      "image-capture-muxer"      GstElement*           : Read / Write
      "image-capture-supported-caps" GstCaps*              : Read
      "image-filter"             GstElement*           : Read / Write
      "location"                 gchar*                : Read / Write
      "max-zoom"                 gfloat                : Read
      "mode"                     GstCameraBin2Mode     : Read / Write
      "mute"                     gboolean              : Read / Write
      "post-previews"            gboolean              : Read / Write
      "preview-caps"             GstCaps*              : Read / Write
      "preview-filter"           GstElement*           : Read / Write
      "video-capture-caps"       GstCaps*              : Read / Write
      "video-capture-supported-caps" GstCaps*              : Read
      "video-filter"             GstElement*           : Read / Write
      "video-profile"            GstEncodingProfile*   : Read / Write
      "viewfinder-caps"          GstCaps*              : Read / Write
      "viewfinder-filter"        GstElement*           : Read / Write
      "viewfinder-sink"          GstElement*           : Read / Write
      "viewfinder-supported-caps" GstCaps*              : Read
      "zoom"                     gfloat                : Read / Write
      "image-profile"            GstEncodingProfile*   : Read / Write
      "audio-source"             GstElement*           : Read / Write
      "camera-source"            GstElement*           : Read / Write
      "audio-filter"             GstElement*           : Read / Write
      "flags"                    GstCamFlags           : Read / Write

## Signals

      "start-capture"                                  : Action
      "stop-capture"                                   : Action

## Description

CameraBin2 is a high-level camera object that encapsulates gstreamer elements, providing an API for controlling a digital camera.

### Note

Note that camerabin2 is still UNSTABLE and under development.

CameraBin2 has the following main features:

- Record videos
- Capture pictures
- Display a viewfinder
- Post preview images for each capture (video and image)

### Usage

Camerabin2 can be created using `gst_element_factory_make()` just like any other element. Video or image capture mode can be selected using the "mode" property and the file to save the capture is selected using "location" property.

After creating camerabin2, applications might want to do some customization (there's a section about this below), then select the desired mode and start capturing.

In image capture mode, just send a "start-capture" and a picture will be captured. When the picture is stored on the selected location, a `GST_MESSAGE_ELEMENT` named 'image-done' will be posted on the GstBus.

In video capture mode, send a "start-capture" to start recording, then send a "stop-capture" to stop recording. Note that both signals are asynchronous, so, calling "stop-capture" doesn't guarantee that the video has been properly finished yet. Applications should wait for the 'video-done' message to be posted on the bus.

In both modes, if "post-previews" is `TRUE`, a GstBuffer will be post to the GstBus in a field named 'buffer', in a 'preview-image' message of type `GST_MESSAGE_ELEMENT`.

### Customization

Camerabin2 provides various customization properties, allowing the user to set custom filters, selecting the viewfinder sink and formats to use to encode the captured images/videos.

GstEncodingProfiles are used to tell camerabin2 which formats it should encode the captures to, those should be set to "image-profile" and "video-profile". Default is jpeg for images, and ogg (theora and vorbis) for video. If a profile without an audio stream is set for video, audio will be disabled on recordings.

"preview-caps" can be used to select which format preview images should be posted on the GstBus. It has to be a raw video format.

Camerabin2 has a "camera-source" property so applications can set their source that will provide buffers for the viewfinder and for captures. This camera source is a special type of source that has 3 pads. To use a 'regular' source with a single pad you should use GstWrapperCameraBinSource, it will adapt your source and provide 3 pads.

Applications can also select the desired viewfinder sink using "viewfinder-sink", it is also possible to select the audio source using "audio-source".

The viewfinder resolution can be configured using "viewfinder-caps", these GstCaps should be a subset of "viewfinder-supported-caps".

To select the desired resolution for captures, camerabin2 provides "image-capture-caps" and "video-capture-caps", these caps must be a subset of what the source can produce. The allowed caps can be probed using "image-capture-supported-caps" and "video-capture-supported-caps". In an analogous way, there are "audio-capture-caps" and "audio-capture-supported-caps".

Camerabin2 also allows applications to insert custom GstElements on any of its branches: video capture, image capture, viewfinder and preview. Check "video-filter", "image-filter", "viewfinder-filter" and "preview-filter".

### Example launch line

Unfortunatelly, camerabin2 can't be really used from gst-launch, as you need to send signals to control it. The following pipeline might be able to show the viewfinder using all the default elements.

    1
    gst-launch -v -m camerabin2

## Synopsis

### Element Information

plugin | camerabin2
author | Thiago Santos <thiago.sousa.santos@collabora.co.uk>
class | Generic/Bin/Camera

### Element Pads

## Details

### struct GstCameraBin2

    struct GstCameraBin2;

## Property Details

### The `"audio-capture-caps"` property

      "audio-capture-caps"       GstCaps*              : Read / Write

Format to capture audio for video recording represented as GstCaps.

### The `"audio-capture-supported-caps"` property

      "audio-capture-supported-caps" GstCaps*              : Read

Formats supported for capturing audio represented as GstCaps.

### The `"audio-src"` property

      "audio-src"                GstElement*           : Read / Write

The audio source element to be used on video recordings. It is only taken into use on the next null to ready transition.

### The `"camera-src"` property

      "camera-src"               GstElement*           : Read / Write

The camera source element to be used. It is only taken into use on the next null to ready transition.

### The `"idle"` property

      "idle"                     gboolean              : Read

If camerabin2 is idle (not doing captures).

Default value: TRUE

### The `"image-capture-caps"` property

      "image-capture-caps"       GstCaps*              : Read / Write

Caps for image capture.

### The `"image-capture-encoder"` property

      "image-capture-encoder"    GstElement*           : Read / Write

The image encoder element to be used on image captures.

### The `"image-capture-muxer"` property

      "image-capture-muxer"      GstElement*           : Read / Write

The image encoder element to be used on image captures.

### The `"image-capture-supported-caps"` property

      "image-capture-supported-caps" GstCaps*              : Read

Formats supported for capturing images represented as GstCaps.

### The `"image-filter"` property

      "image-filter"             GstElement*           : Read / Write

The element that will process captured image frames. (Should be set on NULL state).

### The `"location"` property

      "location"                 gchar*                : Read / Write

Location to save the captured files. A %d might be used on thefilename as a placeholder for a numeric index of the capture.Default is cap_%d.

Default value: "cap_%d"

### The `"max-zoom"` property

      "max-zoom"                 gfloat                : Read

Digital zoom factor (e.g. 1.5 means 1.5x).

Allowed values: >= 1

Default value: 10

### The `"mode"` property

      "mode"                     GstCameraBin2Mode     : Read / Write

Set the mode of operation: still image capturing or video recording.

Default value: Still image capture (default)

### The `"mute"` property

      "mute"                     gboolean              : Read / Write

If the audio recording should be muted. Note that this still saves audio data to the resulting file, but they are silent. Use a video-profile without audio to disable audio completely.

Default value: FALSE

### The `"post-previews"` property

      "post-previews"            gboolean              : Read / Write

If capture preview images should be posted to the bus.

Default value: FALSE

### The `"preview-caps"` property

      "preview-caps"             GstCaps*              : Read / Write

The caps of the preview image to be posted.

### The `"preview-filter"` property

      "preview-filter"           GstElement*           : Read / Write

The element that will process preview buffers. (Should be set on NULL state).

### The `"video-capture-caps"` property

      "video-capture-caps"       GstCaps*              : Read / Write

Caps for video capture.

### The `"video-capture-supported-caps"` property

      "video-capture-supported-caps" GstCaps*              : Read

Formats supported for capturing videos represented as GstCaps.

### The `"video-filter"` property

      "video-filter"             GstElement*           : Read / Write

The element that will process captured video frames. (Should be set on NULL state).

### The `"video-profile"` property

      "video-profile"            GstEncodingProfile*   : Read / Write

The GstEncodingProfile to use for video recording. Audio is enabled when this profile supports audio.

### The `"viewfinder-caps"` property

      "viewfinder-caps"          GstCaps*              : Read / Write

Restricts the caps that can be used on the viewfinder.

### The `"viewfinder-filter"` property

      "viewfinder-filter"        GstElement*           : Read / Write

The element that will process frames going to the viewfinder. (Should be set on NULL state).

### The `"viewfinder-sink"` property

      "viewfinder-sink"          GstElement*           : Read / Write

The video sink of the viewfinder. It is only taken into use on the next null to ready transition.

### The `"viewfinder-supported-caps"` property

      "viewfinder-supported-caps" GstCaps*              : Read

The caps that the camera source can produce on the viewfinder pad.

### The `"zoom"` property

      "zoom"                     gfloat                : Read / Write

Digital zoom factor (e.g. 1.5 means 1.5x).

Allowed values: [1,10]

Default value: 1

### The `"image-profile"` property

      "image-profile"            GstEncodingProfile*   : Read / Write

The GstEncodingProfile to use for image captures.

### The `"audio-source"` property

      "audio-source"             GstElement*           : Read / Write

The audio source element to be used on video recordings. It is only taken into use on the next null to ready transition.

### The `"camera-source"` property

      "camera-source"            GstElement*           : Read / Write

The camera source element to be used. It is only taken into use on the next null to ready transition.

### The `"audio-filter"` property

      "audio-filter"             GstElement*           : Read / Write

The element that will process captured audio buffers when recording. (Should be set on NULL state).

### The `"flags"` property

      "flags"                    GstCamFlags           : Read / Write

Flags to control behaviour.

## Signal Details

### The `"start-capture"` signal

    void                user_function                      (GstCameraBin2 *gstcamerabin2,
                                                            gpointer       user_data)          : Action

`gstcamerabin2` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"stop-capture"` signal

    void                user_function                      (GstCameraBin2 *gstcamerabin2,
                                                            gpointer       user_data)          : Action

`gstcamerabin2` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.