camerabin

camerabin — Handle lot of features present in DSC

Properties

GstElement * audioenc Read / Write
GstElement * audiosrc Read / Write
gchar * filename Read / Write
GstCaps * filter-caps Read / Write
GstElement * imageenc Read / Write
GstElement * imagepp Read / Write
GstCaps * inputcaps Read
GstCameraBinMode mode Read / Write
gboolean mute Read / Write
GstElement * vfsink Read / Write
GstElement * videoenc Read / Write
GstElement * videomux Read / Write
GstElement * videopp Read / Write
GstElement * videosrc Read / Write
gfloat zoom Read / Write
GstCaps * preview-caps Read / Write
GstElement * audio-encoder Read / Write
GstElement * audio-source Read / Write
GstElement * image-encoder Read / Write
GstElement * image-post-processing Read / Write
GstElement * video-encoder Read / Write
GstElement * video-muxer Read / Write
GstElement * video-post-processing Read / Write
GstElement * video-source Read / Write
GstCaps * video-source-caps Read
GstElement * viewfinder-sink Read / Write
GstCameraBinFlags flags Read / Write
gboolean block-after-capture Read / Write
gint image-capture-height Read / Write
gint image-capture-width Read / Write
GstFraction video-capture-framerate Read / Write
gint video-capture-height Read / Write
gint video-capture-width Read / Write
GstElement * video-source-filter Read / Write
GstElement * viewfinder-filter Read / Write
gboolean idle Read
GstElement * preview-source-filter Read / Write
gboolean ready-for-capture Read
GstElement * image-formatter Read / Write

Signals

Types and Values

Object Hierarchy

    GObject
    ╰── GstObject
        ╰── GstElement
            ╰── GstBin
                ╰── GstPipeline
                    ╰── GstCameraBin

Implemented Interfaces

GstCameraBin implements GstChildProxy, GstImplementsInterface, GstColorBalance and GstTagSetter.

Description

GstCameraBin is a high-level camera object that encapsulates the gstreamer internals and provides a task based API for the application. It consists of three main data paths: view-finder, image capture and video capture.

CameraBin structure

Structural decomposition of CameraBin object.

Example launch line

gst-launch -v -m camerabin

Image capture

Image capture is selected by switching “mode” to MODE_IMAGE. Taking still images is initiated with the “capture-start” action signal. Once the image has been captured, "image-captured" gst message is posted to the bus and capturing another image is possible. If application has set “preview-caps” property, then a "preview-image" gst message is posted to bus containing preview image formatted according to specified caps. Eventually when image has been saved “image-done” signal is emitted. Available resolutions can be taken from the “video-source-caps” property. Image capture resolution can be set with “set-image-resolution” action signal. Some video source elements implement the GstPhotography interface, which contains functions and properties for setting photography parameters. One can use gst_bin_iterate_all_by_interface() to get a reference to it.


Video capture

Video capture is selected by switching “mode” to MODE_VIDEO. The capture is started with the “capture-start” action signal too. In addition to image capture one can use “capture-pause” to pause recording and “capture-stop” to end recording. Available resolutions and fps can be taken from the “video-source-caps” property. “set-video-resolution-fps” action signal can be used to set frame rate and resolution for the video recording and view finder as well.


States

Elements within GstCameraBin are created and destroyed when switching between NULL and READY states. Therefore element properties should be set in NULL state. User set elements are not unreffed until GstCameraBin is unreffed or replaced by a new user set element. Initially only elements needed for view finder mode are created to speed up startup. Image bin and video bin elements are created when setting the mode or starting capture. GstCameraBin must be in the PLAYING state before “capture-start” is called.


Video and image previews

GstCameraBin contains “preview-caps” property, which is used to determine whether the application wants a preview image of the captured picture or video. When set, a GstMessage named "preview-image" will be sent. This message will contain a GstBuffer holding the preview image, converted to a format defined by those preview caps. The ownership of the preview image is kept in GstCameraBin, so application should ref the preview buffer object if it needs to use it elsewhere than in message handler. Defining preview caps is done by selecting the capturing “mode” first and then setting the property. Camerabin remembers caps separately for both modes, so it is not necessary to set the caps again after changing the mode.


Since the muxers tested so far have problems with discontinous buffers, QoS has been disabled, and then in order to record video, you MUST ensure that there is enough CPU to encode the video. Thus choose smart resolution and frames per second values. It is also highly recommended to avoid color conversions; make sure all the elements involved work with the same colorspace (i.e. rgb or yuv i420 or whatelse).

Synopsis

Element Information

plugin

camerabin

author

Nokia Corporation <multimedia@maemo.org>, Edgard Lima <edgard.lima@indt.org.br>

class

Generic/Bin/Camera

Element Pads

Functions

Types and Values

struct GstCameraBin

struct GstCameraBin;

The opaque GstCameraBin structure.


enum GstCameraBinMode

Capture mode to use.

Members

MODE_IMAGE

image capture

 

MODE_VIDEO

video capture

 

Property Details

The “audioenc” property

  “audioenc”                 GstElement *

Audio encoder GStreamer element (default is vorbisenc).

Flags: Read / Write


The “audiosrc” property

  “audiosrc”                 GstElement *

Audio source GStreamer element (default is pulsesrc).

Flags: Read / Write


The “filename” property

  “filename”                 gchar *

Set filename for the still image capturing or video capturing.

Flags: Read / Write

Default value: ""


The “filter-caps” property

  “filter-caps”              GstCaps *

Caps applied to capsfilter element after videosrc [ ! ffmpegcsp ]. You can use this e.g. to make sure video color format matches with encoders and other elements configured to camerabin and/or change resolution and frame rate.

Flags: Read / Write


The “imageenc” property

  “imageenc”                 GstElement *

Image encoder GStreamer element (default is jpegenc).

Flags: Read / Write


The “imagepp” property

  “imagepp”                  GstElement *

Image Post-Processing GStreamer element (default is NULL).

Flags: Read / Write


The “inputcaps” property

  “inputcaps”                GstCaps *

The allowed modes of the video source operation.

Flags: Read


The “mode” property

  “mode”                     GstCameraBinMode

Set the mode of operation: still image capturing or video recording. Setting the mode will create and destroy image bin or video bin elements according to the mode. You can set this property at any time, changing the mode will stop ongoing capture.

Flags: Read / Write

Default value: Still image capture (default)


The “mute” property

  “mute”                     gboolean

Mute audio in video recording mode. Set this property only when GstCameraBin is in READY, PAUSED or PLAYING.

Flags: Read / Write

Default value: FALSE


The “vfsink” property

  “vfsink”                   GstElement *

View finder sink GStreamer element (default is autovideosink).

Flags: Read / Write


The “videoenc” property

  “videoenc”                 GstElement *

Video encoder GStreamer element (default is theoraenc).

Flags: Read / Write


The “videomux” property

  “videomux”                 GstElement *

Video muxer GStreamer element (default is oggmux).

Flags: Read / Write


The “videopp” property

  “videopp”                  GstElement *

Video post processing GStreamer element (default is NULL).

Flags: Read / Write


The “videosrc” property

  “videosrc”                 GstElement *

Video source GStreamer element (default is v4l2src).

Flags: Read / Write


The “zoom” property

  “zoom”                     gfloat

Set up the zoom applied to the frames. Set this property only when GstCameraBin is in READY, PAUSED or PLAYING.

Flags: Read / Write

Allowed values: [1,10]

Default value: 1


The “preview-caps” property

  “preview-caps”             GstCaps *

If application wants to receive a preview image, it needs to set this property to depict the desired image format caps. When this property is not set (NULL), message containing the preview image is not sent.

Flags: Read / Write


The “audio-encoder” property

  “audio-encoder”            GstElement *

Set up an audio encoder element. This property can only be set while GstCameraBin is in NULL state. The ownership of the element will be taken by GstCameraBin.

Flags: Read / Write


The “audio-source” property

  “audio-source”             GstElement *

Set up an audio source element. By default "autoaudiosrc" or DEFAULT_AUDIOSRC will be used. This property can only be set while GstCameraBin is in NULL state. The ownership of the element will be taken by GstCameraBin.

Flags: Read / Write


The “image-encoder” property

  “image-encoder”            GstElement *

Set up an image encoder (for example, jpegenc or pngenc) element. This property can only be set while GstCameraBin is in NULL state. The ownership of the element will be taken by GstCameraBin.

Flags: Read / Write


The “image-post-processing” property

  “image-post-processing”    GstElement *

Set up an element to do image post processing. This property can only be set while GstCameraBin is in NULL state. The ownership of the element will be taken by GstCameraBin.

Flags: Read / Write


The “video-encoder” property

  “video-encoder”            GstElement *

Set up a video encoder element. This property can only be set while GstCameraBin is in NULL state. The ownership of the element will be taken by GstCameraBin.

Flags: Read / Write


The “video-muxer” property

  “video-muxer”              GstElement *

Set up a video muxer element. This property can only be set while GstCameraBin is in NULL state. The ownership of the element will be taken by GstCameraBin.

Flags: Read / Write


The “video-post-processing” property

  “video-post-processing”    GstElement *

Set up an element to do video post processing. This property can only be set while GstCameraBin is in NULL state. The ownership of the element will be taken by GstCameraBin.

Flags: Read / Write


The “video-source” property

  “video-source”             GstElement *

Set up a video source element. By default "autovideosrc" or DEFAULT_VIDEOSRC will be used. This property can only be set while GstCameraBin is in NULL state. The ownership of the element will be taken by GstCameraBin.

Flags: Read / Write


The “video-source-caps” property

  “video-source-caps”        GstCaps *

The allowed modes of operation of the video source. Have in mind that it doesn't mean GstCameraBin can operate in all those modes, it depends also on the other elements in the pipeline. Remember to gst_caps_unref after using it.

Flags: Read


The “viewfinder-sink” property

  “viewfinder-sink”          GstElement *

Set up a sink element to render frames in view finder. By default "autovideosink" or DEFAULT_VIDEOSINK will be used. This property can only be set while GstCameraBin is in NULL state. The ownership of the element will be taken by GstCameraBin.

Flags: Read / Write


The “flags” property

  “flags”                    GstCameraBinFlags

Control the behaviour of encodebin.

Flags: Read / Write

Default value: Enable source crop and scale|Enable colorspace conversion for viewfinder|Enable scale for viewfinder|Enable audio conversion for video capture|Enable colorspace conversion for still image|Enable colorspace conversion for video capture


The “block-after-capture” property

  “block-after-capture”      gboolean

Block viewfinder after capture. If it is TRUE when 'capture-start' is issued, camerabin will prepare to block and freeze the viewfinder after capturing. Setting it to FALSE will abort the blocking if it hasn't happened yet, or will enable again the viewfinder if it is already blocked. Note that setting this property to TRUE after 'capture-start' will only work for the next capture. This makes possible for applications to set the property to FALSE to abort the current blocking and already set it back to TRUE again to block at the next capture.

This is useful if application wants to display the preview image and running the viewfinder at the same time would be just a waste of CPU cycles.

Flags: Read / Write

Default value: FALSE


The “image-capture-height” property

  “image-capture-height”     gint

The height to be used when capturing still images. If 0, the viewfinder's height will be used.

Flags: Read / Write

Allowed values: [0,32767]

Default value: 600


The “image-capture-width” property

  “image-capture-width”      gint

The width to be used when capturing still images. If 0, the viewfinder's width will be used.

Flags: Read / Write

Allowed values: [0,32767]

Default value: 800


The “video-capture-framerate” property

  “video-capture-framerate”  GstFraction

The framerate to be used when capturing video.

Flags: Read / Write


The “video-capture-height” property

  “video-capture-height”     gint

The height to be used when capturing video.

Flags: Read / Write

Allowed values: [0,32767]

Default value: 600


The “video-capture-width” property

  “video-capture-width”      gint

The width to be used when capturing video.

Flags: Read / Write

Allowed values: [0,32767]

Default value: 800


The “video-source-filter” property

  “video-source-filter”      GstElement *

Set up optional video filter element, all frames from video source will be processed by this element. e.g. An application might add image enhancers/parameter adjustment filters here to improve captured image/video results, or add analyzers to give feedback on capture the application. This property can only be set while GstCameraBin is in NULL state. The ownership of the element will be taken by GstCameraBin.

Flags: Read / Write


The “viewfinder-filter” property

  “viewfinder-filter”        GstElement *

viewfinder filter GStreamer element.

Flags: Read / Write


The “idle” property

  “idle”                     gboolean

When TRUE no capturing/encoding/saving is running and it is safe to set camerabin to NULL to release resources without losing data.

In case of errors, this property is made unreliable. Set the pipeline back to READY or NULL to make it reliable again.

Flags: Read

Default value: TRUE


The “preview-source-filter” property

  “preview-source-filter”    GstElement *

Optional preview source filter GStreamer element.

Flags: Read / Write


The “ready-for-capture” property

  “ready-for-capture”        gboolean

When TRUE new capture can be prepared. If FALSE capturing is ongoing and starting a new capture immediately is not possible.

Flags: Read

Default value: TRUE


The “image-formatter” property

  “image-formatter”          GstElement *

Set up an image formatter (for example, jifmux) element. This property can only be set while GstCameraBin is in NULL state. The ownership of the element will be taken by GstCameraBin.

Flags: Read / Write

Signal Details

The “img-done” signal

gboolean
user_function (GstCameraBin *gstcamerabin,
               gchar        *arg1,
               gpointer      user_data)

Parameters

gstcamerabin

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “user-image-res” signal

void
user_function (GstCameraBin *gstcamerabin,
               gint          arg1,
               gint          arg2,
               gpointer      user_data)

Parameters

gstcamerabin

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Action


The “user-pause” signal

void
user_function (GstCameraBin *gstcamerabin,
               gpointer      user_data)

Parameters

gstcamerabin

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Action


The “user-res-fps” signal

void
user_function (GstCameraBin *gstcamerabin,
               gint          arg1,
               gint          arg2,
               gint          arg3,
               gint          arg4,
               gpointer      user_data)

Parameters

gstcamerabin

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Action


The “user-start” signal

void
user_function (GstCameraBin *gstcamerabin,
               gpointer      user_data)

Parameters

gstcamerabin

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Action


The “user-stop” signal

void
user_function (GstCameraBin *gstcamerabin,
               gpointer      user_data)

Parameters

gstcamerabin

the object which received the signal.

 

user_data

user data set when the signal handler was connected.

 

Flags: Action


The “capture-pause” signal

void
user_function (GstCameraBin *camera,
               gpointer      user_data)

Pauses video recording or resumes paused video recording. If in image mode or not recording, does nothing.

Parameters

camera

the camera bin element

 

user_data

user data set when the signal handler was connected.

 

Flags: Action


The “capture-start” signal

void
user_function (GstCameraBin *camera,
               gpointer      user_data)

Starts image capture or video recording depending on the Mode. If there is a capture already going on, does nothing. Resumes video recording if it has been paused.

Parameters

camera

the camera bin element

 

user_data

user data set when the signal handler was connected.

 

Flags: Action


The “capture-stop” signal

void
user_function (GstCameraBin *camera,
               gpointer      user_data)

Stops still image preview, continuous image capture and video recording and returns to the view finder mode.

Parameters

camera

the camera bin element

 

user_data

user data set when the signal handler was connected.

 

Flags: Action


The “image-done” signal

gboolean
user_function (GstCameraBin *camera,
               gchar        *filename,
               gpointer      user_data)

Signal emitted when the file has just been saved.

Don't call any GstCameraBin method from this signal, if you do so there will be a deadlock.

Parameters

camera

the camera bin element

 

filename

the name of the file just saved

 

user_data

user data set when the signal handler was connected.

 

Flags: Run Last


The “set-image-resolution” signal

void
user_function (GstCameraBin *camera,
               gint          width,
               gint          height,
               gpointer      user_data)

Changes the resolution used for still image capture. Does not affect view finder mode and video recording.

This actually sets the 'image-capture-width' and 'image-capture-height' properties.

Parameters

camera

the camera bin element

 

width

number of horizontal pixels

 

height

number of vertical pixels

 

user_data

user data set when the signal handler was connected.

 

Flags: Action


The “set-video-resolution-fps” signal

void
user_function (GstCameraBin *camera,
               gint          width,
               gint          height,
               gint          fps_n,
               gint          fps_d,
               gpointer      user_data)

Changes the frame resolution and frames per second of the video source. The application must be aware of the resolutions supported by the camera. Supported resolutions and frame rates can be get using input-caps property.

Setting fps_n or fps_d to 0 configures maximum framerate for the given resolution, unless in night mode when minimum is configured.

This is the same as setting the 'video-capture-width', 'video-capture-height' and 'video-capture-framerate' properties, but it already updates the caps to force use this resolution and framerate.

Parameters

camera

the camera bin element

 

width

number of horizontal pixels

 

height

number of vertical pixels

 

fps_n

frames per second numerator

 

fps_d

frames per second denominator

 

user_data

user data set when the signal handler was connected.

 

Flags: Action