# camerabin

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

> Note that camerabin is still UNSTABLE and under development.

CameraBin has the following main features:

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

## Usage

Camerabin can be created using gst_element_factory_make just like any other element. Video or image capture mode can be selected using the GstCameraBin:mode property and the file to save the capture is selected using GstCameraBin:location property.

After creating camerabin, 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 GstCameraBin::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 GstCameraBin::start-capture to start recording, then send a GstCameraBin::stop-capture to stop recording. Note that both signals are asynchronous, so, calling GstCameraBin::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 GstCameraBin: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

Camerabin 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 camerabin which formats it should encode the captures to, those should be set to GstCameraBin:image-profile and GstCameraBin: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.

GstCameraBin: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.

Camerabin has a GstCameraBin: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 GstWrapperCameraBinSrc, it will adapt your source and provide 3 pads.

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

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

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

Camerabin also allows applications to insert custom GstElement on any of its branches: video capture, image capture, viewfinder and preview. Check GstCameraBin:video-filter, GstCameraBin:image-filter, GstCameraBin:viewfinder-filter and GstCameraBin:preview-filter.

## Example launch line

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

     gst-launch-1.0 -v -m camerabin

## Hierarchy

    GObject
        ╰──GInitiallyUnowned
            ╰──GstObject
                ╰──GstElement
                    ╰──GstBin
                        ╰──GstPipeline
                            ╰──camerabin

## Implemented interfaces

    GstChildProxy
    GstTagSetter

## Factory details

Authors: – Thiago Santos

Classification: – `Generic/Bin/Camera`

Rank – none

Plugin – camerabin

Package – GStreamer Bad Plug-ins

## Signals

### start-capture

    start_capture_callback (GstElement * param_0,
                            gpointer udata)

    def start_capture_callback (param_0, udata):
        #python callback for the 'start-capture' signal

    function start_capture_callback(param_0: GstElement * param_0, udata: gpointer udata): {
        // javascript callback for the 'start-capture' signal
    }

Parameters:

`param_0` –
No description available
`udata` –
No description available

Flags: Run Last / Action

### stop-capture

    stop_capture_callback (GstElement * param_0,
                           gpointer udata)

    def stop_capture_callback (param_0, udata):
        #python callback for the 'stop-capture' signal

    function stop_capture_callback(param_0: GstElement * param_0, udata: gpointer udata): {
        // javascript callback for the 'stop-capture' signal
    }

Parameters:

`param_0` –
No description available
`udata` –
No description available

Flags: Run Last / Action

## Properties

### audio-capture-caps

    “audio-capture-caps” GstCaps *

Format to capture audio for video recording represented as GstCaps

Flags : Read / Write

Default value :

    ANY

### audio-capture-supported-caps

    “audio-capture-supported-caps” GstCaps *

Formats supported for capturing audio represented as GstCaps

Flags : Read

### audio-filter

    “audio-filter” GstElement *

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

Flags : Read / Write

### audio-source

    “audio-source” GstElement *

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

Flags : Read / Write

### camera-source

    “camera-source” GstElement *

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

Flags : Read / Write

### flags

    “flags” Cam-flags *

Control the behaviour of encodebin.

Flags : Read / Write

Default value : (none)

### idle

    “idle” gboolean

If camerabin2 is idle (not doing captures).

Flags : Read

Default value : true

### image-capture-caps

    “image-capture-caps” GstCaps *

Caps for image capture

Flags : Read / Write

Default value :

    ANY

### image-capture-supported-caps

    “image-capture-supported-caps” GstCaps *

Formats supported for capturing images represented as GstCaps

Flags : Read

### image-filter

    “image-filter” GstElement *

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

Flags : Read / Write

### image-profile

    “image-profile” GstEncodingProfile *

The GstEncodingProfile to use for image captures.

Flags : Read / Write

### location

    “location” gchararray

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

Flags : Read / Write

Default value : cap_%%d

### max-zoom

    “max-zoom” gfloat

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

Flags : Read

Default value : 10

### mode

    “mode” GstCameraBin2Mode *

The capture mode (still image capture or video recording)

Flags : Read / Write

Default value : mode-image (1)

### mute

    “mute” gboolean

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

Flags : Read / Write

Default value : false

### post-previews

    “post-previews” gboolean

If capture preview images should be posted to the bus

Flags : Read / Write

Default value : false

### preview-caps

    “preview-caps” GstCaps *

The caps of the preview image to be posted

Flags : Read / Write

### preview-filter

    “preview-filter” GstElement *

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

Flags : Read / Write

### video-capture-caps

    “video-capture-caps” GstCaps *

Caps for video capture

Flags : Read / Write

Default value :

    ANY

### video-capture-supported-caps

    “video-capture-supported-caps” GstCaps *

Formats supported for capturing videos represented as GstCaps

Flags : Read

### video-filter

    “video-filter” GstElement *

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

Flags : Read / Write

### video-profile

    “video-profile” GstEncodingProfile *

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

Flags : Read / Write

### viewfinder-caps

    “viewfinder-caps” GstCaps *

Restricts the caps that can be used on the viewfinder

Flags : Read / Write

Default value :

    ANY

### viewfinder-filter

    “viewfinder-filter” GstElement *

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

Flags : Read / Write

### viewfinder-sink

    “viewfinder-sink” GstElement *

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

Flags : Read / Write

### viewfinder-supported-caps

    “viewfinder-supported-caps” GstCaps *

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

Flags : Read

### zoom

    “zoom” gfloat

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

Flags : Read / Write

Default value : 1

## Named constants

### Cam-flags

#### Members

`no-audio-conversion` (0x00000001) – Do not use audio conversion elements
`no-video-conversion` (0x00000002) – Do not use video conversion elements
`no-viewfinder-conversion` (0x00000004) – Do not use viewfinder conversion elements
`no-image-conversion` (0x00000008) – Do not use image conversion elements

The results of the search are