## GstEncodingProfile

GstEncodingProfile — Encoding profile library

## Functions

#define | gst_encoding_profile_unref()
#define | gst_encoding_profile_ref()
GstEncodingProfile * | gst_encoding_profile_find ()
GstEncodingProfile * | gst_encoding_profile_from_discoverer ()
const gchar * | gst_encoding_profile_get_name ()
const gchar * | gst_encoding_profile_get_description ()
GstCaps * | gst_encoding_profile_get_format ()
const gchar * | gst_encoding_profile_get_preset ()
const gchar * | gst_encoding_profile_get_preset_name ()
guint | gst_encoding_profile_get_presence ()
GstCaps * | gst_encoding_profile_get_restriction ()
const gchar * | gst_encoding_profile_get_file_extension ()
void | gst_encoding_profile_set_name ()
void | gst_encoding_profile_set_description ()
void | gst_encoding_profile_set_enabled ()
void | gst_encoding_profile_set_format ()
void | gst_encoding_profile_set_preset ()
void | gst_encoding_profile_set_preset_name ()
void | gst_encoding_profile_set_restriction ()
void | gst_encoding_profile_set_presence ()
gboolean | gst_encoding_profile_is_equal ()
gboolean | gst_encoding_profile_is_enabled ()
GstCaps * | gst_encoding_profile_get_input_caps ()
const gchar * | gst_encoding_profile_get_type_nick ()
GstEncodingProfile * | gst_encoding_profile_copy ()
gboolean | gst_encoding_profile_get_allow_dynamic_output ()
void | gst_encoding_profile_set_allow_dynamic_output ()
GstEncodingContainerProfile * | gst_encoding_container_profile_new ()
gboolean | gst_encoding_container_profile_add_profile ()
gboolean | gst_encoding_container_profile_contains_profile ()
const GList * | gst_encoding_container_profile_get_profiles ()
GstEncodingAudioProfile * | gst_encoding_audio_profile_new ()
GstEncodingVideoProfile * | gst_encoding_video_profile_new ()
guint | gst_encoding_video_profile_get_pass ()
gboolean | gst_encoding_video_profile_get_variableframerate ()
void | gst_encoding_video_profile_set_pass ()
void | gst_encoding_video_profile_set_variableframerate ()
#define | gst_encoding_target_unref()
#define | gst_encoding_target_ref()
GstEncodingTarget * | gst_encoding_target_new ()
const gchar * | gst_encoding_target_get_name ()
const gchar * | gst_encoding_target_get_category ()
const gchar * | gst_encoding_target_get_description ()
const GList * | gst_encoding_target_get_profiles ()
GstEncodingProfile * | gst_encoding_target_get_profile ()
gboolean | gst_encoding_target_add_profile ()
gboolean | gst_encoding_target_save ()
gboolean | gst_encoding_target_save_to_file ()
GstEncodingTarget * | gst_encoding_target_load ()
GstEncodingTarget * | gst_encoding_target_load_from_file ()
GList * | gst_encoding_list_all_targets ()
GList * | gst_encoding_list_available_categories ()

## Properties

GstCaps * | restriction-caps | Read / Write

## Types and Values

| GstEncodingProfile
| GstEncodingContainerProfile
| GstEncodingAudioProfile
| GstEncodingVideoProfile
#define | GST_ENCODING_CATEGORY_DEVICE
#define | GST_ENCODING_CATEGORY_ONLINE_SERVICE
#define | GST_ENCODING_CATEGORY_STORAGE_EDITING
#define | GST_ENCODING_CATEGORY_CAPTURE
| GstEncodingTarget

## Object Hierarchy

        GObject
        ├── GstEncodingProfile
        │   ├── GstEncodingVideoProfile
        │   ├── GstEncodingAudioProfile
        │   ╰── GstEncodingContainerProfile
        ╰── GstEncodingTarget

## Includes

    #include <gst/pbutils/encoding-profile.h>

## Description

Functions to create and handle encoding profiles.

Encoding profiles describe the media types and settings one wishes to use for an encoding process. The top-level profiles are commonly GstEncodingContainerProfile(s) (which contains a user-readable name and description along with which container format to use). These, in turn, reference one or more GstEncodingProfile(s) which indicate which encoding format should be used on each individual streams.

GstEncodingProfile(s) can be provided to the 'encodebin' element, which will take care of selecting and setting up the required elements to produce an output stream conforming to the specifications of the profile.

Unlike other systems, the encoding profiles do not specify which GstElement to use for the various encoding and muxing steps, but instead relies on specifying the format one wishes to use.

Encoding profiles can be created at runtime by the application or loaded from (and saved to) file using the GstEncodingTarget API.

### Defining a GstEncodingProfile as a string

#### Serialized encoding profile formats

#### Using encoders and muxer element factory name:

    1

    muxer_factory_name:video_encoder_factory_name:audio_encoder_factory_name

For example to encode a stream into a WebM container, with an OGG audio stream and a VP8 video stream, the serialized GstEncodingProfile looks like:

    1

    webmmux:vp8enc:vorbisenc

#### Define the encoding profile in a generic way using caps:

    1

    muxer_source_caps:video_encoder_source_caps:audio_encoder_source_caps

For example to encode a stream into a WebM container, with an OGG audio stream and a VP8 video stream, the serialized GstEncodingProfile looks like:

    1

    video/webm:video/x-vp8:audio/x-vorbis

It is possible to mix caps and element type names so you can specify a specific video encoder while using caps for other encoders/muxer.

#### Advanced encoding format serialization features:

You can also set the preset name of the encoding profile using the caps+preset_name syntax as in:

    1

    video/webm:video/x-vp8+youtube-preset:audio/x-vorbis

Moreover, you can set the `presence` property of an encoding profile using the `|presence` syntax as in:

    1

    video/webm:video/x-vp8|1:audio/x-vorbis

This field allows specifies the maximum number of times a GstEncodingProfile can be used inside an encodebin. If 0, it is not a mandatory stream and can be used as many times as necessary.

You can also use the `restriction_caps->encoded_format_caps` syntax to specify the restriction caps to be set on a GstEncodingProfile

It corresponds to the restriction GstCaps to apply before the encoder that will be used in the profile. The fields present in restriction caps are properties of the raw stream (that is, before encoding), such as height and width for video and depth and sampling rate for audio. This property does not make sense for muxers. See gst_encoding_profile_get_restriction for more details.

To force a video stream to be encoded with a Full HD resolution (using WebM as the container format, VP8 as the video codec and Vorbis as the audio codec), you should use:

    1

    "video/webm:video/x-raw,width=1920,height=1080->video/x-vp8:audio/x-vorbis"

> NOTE: Make sure to enclose into quotes to avoid '>' to be reinterpreted by the shell.

In the case you are using encoder types, the following is also possible:

    1

    "matroskamux:x264enc,width=1920,height=1080:audio/x-vorbis"

#### Some serialized encoding formats examples:

MP3 audio and H264 in MP4:

    1

    video/quicktime,variant=iso:video/x-h264:audio/mpeg,mpegversion=1,layer=3

Vorbis and theora in OGG:

    1

    application/ogg:video/x-theora:audio/x-vorbis

AC3 and H264 in MPEG-TS:

    1

    video/mpegts:video/x-h264:audio/x-ac3

#### Loading a profile from encoding targets

Anywhere where you have to use a string to define a GstEncodingProfile, you can use load it from a GstEncodingTarget using the following syntaxes:

    1

    target_name[/profilename/category]

or

    1

    /path/to/target.gep:profilename

### Example: Creating a profile

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26

    #include <gst/pbutils/encoding-profile.h>
    ...
    GstEncodingProfile *
    create_ogg_theora_profile(void)
    {
     GstEncodingContainerProfile *prof;
     GstCaps *caps;

     caps = gst_caps_from_string("application/ogg");
     prof = gst_encoding_container_profile_new("Ogg audio/video",
        "Standard OGG/THEORA/VORBIS",
        caps, NULL);
     gst_caps_unref (caps);

     caps = gst_caps_from_string("video/x-theora");
     gst_encoding_container_profile_add_profile(prof,
          (GstEncodingProfile*) gst_encoding_video_profile_new(caps, NULL, NULL, 0));
     gst_caps_unref (caps);

     caps = gst_caps_from_string("audio/x-vorbis");
     gst_encoding_container_profile_add_profile(prof,
          (GstEncodingProfile*) gst_encoding_audio_profile_new(caps, NULL, NULL, 0));
     gst_caps_unref (caps);

     return (GstEncodingProfile*) prof;
    }

### Example: Using an encoder preset with a profile

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36

    #include <gst/pbutils/encoding-profile.h>
    ...
    GstEncodingProfile *
    create_ogg_theora_profile(void)
    {
     GstEncodingVideoProfile *v;
     GstEncodingAudioProfile *a;
     GstEncodingContainerProfile *prof;
     GstCaps *caps;
     GstPreset *preset;

     caps = gst_caps_from_string ("application/ogg");
     prof = gst_encoding_container_profile_new ("Ogg audio/video",
        "Standard OGG/THEORA/VORBIS",
        caps, NULL);
     gst_caps_unref (caps);

     preset = GST_PRESET (gst_element_factory_make ("theoraenc", "theorapreset"));
     g_object_set (preset, "bitrate", 1000, NULL);
     // The preset will be saved on the filesystem,
     // so try to use a descriptive name
     gst_preset_save_preset (preset, "theora_bitrate_preset");
     gst_object_unref (preset);

     caps = gst_caps_from_string ("video/x-theora");
     v = gst_encoding_video_profile_new (caps, "theorapreset", NULL, 0);
     gst_encoding_container_profile_add_profile (prof, (GstEncodingProfile*) v);
     gst_caps_unref (caps);

     caps = gst_caps_from_string ("audio/x-vorbis");
     a = gst_encoding_audio_profile_new (caps, NULL, NULL, 0);
     gst_encoding_container_profile_add_profile (prof, (GstEncodingProfile*) a);
     gst_caps_unref (caps);

     return (GstEncodingProfile*) prof;
    }

### Example: Listing categories, targets and profiles

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27

    #include <gst/pbutils/encoding-profile.h>
    ...
    GstEncodingProfile *prof;
    GList *categories, *tmpc;
    GList *targets, *tmpt;
    ...
    categories = gst_encoding_list_available_categories ();

    ... Show available categories to user ...

    for (tmpc = categories; tmpc; tmpc = tmpc->next) {
      gchar *category = (gchar *) tmpc->data;

      ... and we can list all targets within that category ...

      targets = gst_encoding_list_all_targets (category);

      ... and show a list to our users ...

      g_list_foreach (targets, (GFunc) gst_encoding_target_unref, NULL);
      g_list_free (targets);
    }

    g_list_foreach (categories, (GFunc) g_free, NULL);
    g_list_free (categories);

    ...

### Encoding Target

On top of the notion of profiles, we implement the notion of EncodingTarget. Encoding Targets are basically a higher level of abstraction to define formats for specific target types. Those can define several GstEncodingProfiles with different names, for example one for transcoding in full HD, another one for low res, etc.. which are defined in the same encoding target.

Basically if you wan to encode a stream to send it to, say, youtube you should have a Youtube encoding target defined in the "online-service" category.

#### Encoding target serialization format

Encoding targets are serialized in a KeyFile like files.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20

    [GStreamer Encoding Target]
    name : <name>
    category : <category>
    \description : <description> #translatable

    [profile-<profile1name>]
    name : <name>
    \description : <description> #optional
    format : <format>
    preset : <preset>

    [streamprofile-<id>]
    parent : <encodingprofile.name>[,<encodingprofile.name>..]
    \type : <type> # "audio", "video", "text"
    format : <format>
    preset : <preset>
    restriction : <restriction>
    presence : <presence>
    pass : <pass>
    variableframerate : <variableframerate>

### Location of encoding target files

$GST_DATADIR/gstreamer-GST_API_VERSION/encoding-profile $HOME/gstreamer-GST_API_VERSION/encoding-profile

There also is a GST_ENCODING_TARGET_PATH environment variable defining a list of folder containing encoding target files.

#### Naming convention

    1

    $(target.category)/$(target.name).gep

### Naming restrictions:

- lowercase ASCII letter for the first character

- Same for all other characters + numerics + hyphens

## Functions

### gst_encoding_profile_unref()

    #define gst_encoding_profile_unref(profile) (g_object_unref ((GObject*) profile))

Decreases the reference count of the `profile` , possibly freeing the `profile` .

#### Parameters

profile | a GstEncodingProfile |

### gst_encoding_profile_ref()

    #define gst_encoding_profile_ref(profile) (g_object_ref ((GObject*) profile))

Increases the reference count of the `profile` .

#### Parameters

profile | a GstEncodingProfile |

### gst_encoding_profile_find ()

    GstEncodingProfile *
    gst_encoding_profile_find (const gchar *targetname,
                               const gchar *profilename,
                               const gchar *category);

Find the GstEncodingProfile with the specified name and category.

#### Parameters

targetname | The name of the target. | [transfer none]
profilename | (allow-none): The name of the profile, if `NULL` provided, it will default to the encoding profile called `default`. | [transfer none]
category | The target category. Can be `NULL`. | [transfer none][allow-none]

#### Returns

The matching GstEncodingProfile or `NULL`.

[transfer full]

### gst_encoding_profile_from_discoverer ()

    GstEncodingProfile *
    gst_encoding_profile_from_discoverer (GstDiscovererInfo *info);

Creates a GstEncodingProfile matching the formats from the given GstDiscovererInfo. Streams other than audio or video (eg, subtitles), are currently ignored.

#### Parameters

info | The GstDiscovererInfo to read from. | [transfer none]

#### Returns

The new GstEncodingProfile or `NULL`.

[transfer full]

### gst_encoding_profile_get_name ()

    const gchar *
    gst_encoding_profile_get_name (GstEncodingProfile *profile);

#### Parameters

profile | a GstEncodingProfile |

#### Returns

the name of the profile, can be `NULL`.

### gst_encoding_profile_get_description ()

    const gchar *
    gst_encoding_profile_get_description (GstEncodingProfile *profile);

#### Parameters

profile | a GstEncodingProfile |

#### Returns

the description of the profile, can be `NULL`.

### gst_encoding_profile_get_format ()

    GstCaps *
    gst_encoding_profile_get_format (GstEncodingProfile *profile);

#### Parameters

profile | a GstEncodingProfile |

#### Returns

the GstCaps corresponding to the media format used in the profile. Unref after usage.

[transfer full]

### gst_encoding_profile_get_preset ()

    const gchar *
    gst_encoding_profile_get_preset (GstEncodingProfile *profile);

#### Parameters

profile | a GstEncodingProfile |

#### Returns

the name of the GstPreset to be used in the profile. This is the name that has been set when saving the preset.

### gst_encoding_profile_get_preset_name ()

    const gchar *
    gst_encoding_profile_get_preset_name (GstEncodingProfile *profile);

#### Parameters

profile | a GstEncodingProfile |

#### Returns

the name of the GstPreset factory to be used in the profile.

### gst_encoding_profile_get_presence ()

    guint
    gst_encoding_profile_get_presence (GstEncodingProfile *profile);

#### Parameters

profile | a GstEncodingProfile |

#### Returns

The number of times the profile is used in its parent container profile. If 0, it is not a mandatory stream.

### gst_encoding_profile_get_restriction ()

    GstCaps *
    gst_encoding_profile_get_restriction (GstEncodingProfile *profile);

#### Parameters

profile | a GstEncodingProfile |

#### Returns

The restriction GstCaps to apply before the encoder that will be used in the profile. The fields present in restriction caps are properties of the raw stream (that is before encoding), such as height and width for video and depth and sampling rate for audio. Does not apply to GstEncodingContainerProfile (since there is no corresponding raw stream). Can be `NULL`. Unref after usage.

[transfer full]

### gst_encoding_profile_get_file_extension ()

    const gchar *
    gst_encoding_profile_get_file_extension
                                   (GstEncodingProfile *profile);

#### Parameters

profile | a GstEncodingProfile |

#### Returns

a suitable file extension for `profile` , or NULL.

### gst_encoding_profile_set_name ()

    void
    gst_encoding_profile_set_name (GstEncodingProfile *profile,
                                   const gchar *name);

Set `name` as the given name for the `profile` . A copy of `name` will be made internally.

#### Parameters

profile | a GstEncodingProfile |
name | the name to set on the profile |

### gst_encoding_profile_set_description ()

    void
    gst_encoding_profile_set_description (GstEncodingProfile *profile,
                                          const gchar *description);

Set `description` as the given description for the `profile` . A copy of `description` will be made internally.

#### Parameters

profile | a GstEncodingProfile |
description | the description to set on the profile |

### gst_encoding_profile_set_enabled ()

    void
    gst_encoding_profile_set_enabled (GstEncodingProfile *profile,
                                      gboolean enabled);

Set whether the profile should be used or not.

#### Parameters

profile | a GstEncodingProfile |
enabled | `FALSE` to disable profile, `TRUE` to enable it |

### gst_encoding_profile_set_format ()

    void
    gst_encoding_profile_set_format (GstEncodingProfile *profile,
                                     GstCaps *format);

Sets the media format used in the profile.

#### Parameters

profile | a GstEncodingProfile |
format | the media format to use in the profile. | [transfer none]

### gst_encoding_profile_set_preset ()

    void
    gst_encoding_profile_set_preset (GstEncodingProfile *profile,
                                     const gchar *preset);

Sets the name of the GstElement that implements the GstPreset interface to use for the profile. This is the name that has been set when saving the preset.

#### Parameters

profile | a GstEncodingProfile |
preset | the element preset to use. | [nullable]

### gst_encoding_profile_set_preset_name ()

    void
    gst_encoding_profile_set_preset_name (GstEncodingProfile *profile,
                                          const gchar *preset_name);

Sets the name of the GstPreset's factory to be used in the profile.

#### Parameters

profile | a GstEncodingProfile |
preset_name | The name of the preset to use in this `profile` . |

### gst_encoding_profile_set_restriction ()

    void
    gst_encoding_profile_set_restriction (GstEncodingProfile *profile,
                                          GstCaps *restriction);

Set the restriction GstCaps to apply before the encoder that will be used in the profile. See `gst_encoding_profile_get_restriction()` for more about restrictions. Does not apply to GstEncodingContainerProfile.

#### Parameters

profile | a GstEncodingProfile |
restriction | the restriction to apply. | [transfer full]

### gst_encoding_profile_set_presence ()

    void
    gst_encoding_profile_set_presence (GstEncodingProfile *profile,
                                       guint presence);

Set the number of time the profile is used in its parent container profile. If 0, it is not a mandatory stream

#### Parameters

profile | a GstEncodingProfile |
presence | the number of time the profile can be used |

### gst_encoding_profile_is_equal ()

    gboolean
    gst_encoding_profile_is_equal (GstEncodingProfile *a,
                                   GstEncodingProfile *b);

Checks whether the two GstEncodingProfile are equal

#### Parameters

a | a GstEncodingProfile |
b | a GstEncodingProfile |

#### Returns

`TRUE` if `a` and `b` are equal, else `FALSE`.

### gst_encoding_profile_is_enabled ()

    gboolean
    gst_encoding_profile_is_enabled (GstEncodingProfile *profile);

### gst_encoding_profile_get_input_caps ()

    GstCaps *
    gst_encoding_profile_get_input_caps (GstEncodingProfile *profile);

Computes the full output caps that this `profile` will be able to consume.

#### Parameters

profile | a GstEncodingProfile |

#### Returns

The full caps the given `profile` can consume. Call `gst_caps_unref()` when you are done with the caps.

[transfer full]

### gst_encoding_profile_get_type_nick ()

    const gchar *
    gst_encoding_profile_get_type_nick (GstEncodingProfile *profile);

#### Parameters

profile | a GstEncodingProfile |

#### Returns

the human-readable name of the type of `profile` .

### gst_encoding_profile_copy ()

    GstEncodingProfile *
    gst_encoding_profile_copy (GstEncodingProfile *self);

Makes a deep copy of `self`

#### Parameters

self | The GstEncodingProfile to copy |

#### Returns

The copy of `self`

Since 1.12.

[transfer full]

### gst_encoding_profile_get_allow_dynamic_output ()

    gboolean
    gst_encoding_profile_get_allow_dynamic_output
                                   (GstEncodingProfile *profile);

Get whether the format that has been negotiated in at some point can be renegotiated later during the encoding.

#### Parameters

profile | a GstEncodingProfile |

### gst_encoding_profile_set_allow_dynamic_output ()

    void
    gst_encoding_profile_set_allow_dynamic_output
                                   (GstEncodingProfile *profile,
                                    gboolean allow_dynamic_output);

Sets whether the format that has been negotiated in at some point can be renegotiated later during the encoding.

#### Parameters

profile | a GstEncodingProfile |
allow_dynamic_output | Whether the format that has been negotiated first can be renegotiated during the encoding |

### gst_encoding_container_profile_new ()

    GstEncodingContainerProfile *
    gst_encoding_container_profile_new (const gchar *name,
                                        const gchar *description,
                                        GstCaps *format,
                                        const gchar *preset);

Creates a new GstEncodingContainerProfile.

#### Parameters

name | The name of the container profile, can be `NULL`. | [allow-none]
description | The description of the container profile, can be `NULL`. | [allow-none]
format | The format to use for this profile. | [transfer none]
preset | The preset to use for this profile. | [allow-none]

#### Returns

The newly created GstEncodingContainerProfile.

### gst_encoding_container_profile_add_profile ()

    gboolean
    gst_encoding_container_profile_add_profile
                                   (GstEncodingContainerProfile *container,
                                    GstEncodingProfile *profile);

Add a GstEncodingProfile to the list of profiles handled by `container` .

No copy of `profile` will be made, if you wish to use it elsewhere after this method you should increment its reference count.

#### Parameters

container | the GstEncodingContainerProfile to use |
profile | the GstEncodingProfile to add. | [transfer full]

#### Returns

`TRUE` if the `stream` was properly added, else `FALSE`.

### gst_encoding_container_profile_contains_profile ()

    gboolean
    gst_encoding_container_profile_contains_profile
                                   (GstEncodingContainerProfile *container,
                                    GstEncodingProfile *profile);

Checks if `container` contains a GstEncodingProfile identical to `profile` .

#### Parameters

container | a GstEncodingContainerProfile |
profile | a GstEncodingProfile |

#### Returns

`TRUE` if `container` contains a GstEncodingProfile identical to `profile` , else `FALSE`.

### gst_encoding_container_profile_get_profiles ()

    const GList *
    gst_encoding_container_profile_get_profiles
                                   (GstEncodingContainerProfile *profile);

#### Parameters

profile | a GstEncodingContainerProfile |

#### Returns

the list of contained GstEncodingProfile.

[element-type GstPbutils.EncodingProfile][transfer none]

### gst_encoding_audio_profile_new ()

    GstEncodingAudioProfile *
    gst_encoding_audio_profile_new (GstCaps *format,
                                    const gchar *preset,
                                    GstCaps *restriction,
                                    guint presence);

Creates a new GstEncodingAudioProfile

All provided allocatable arguments will be internally copied, so can be safely freed/unreferenced after calling this method.

#### Parameters

format | the GstCaps. | [transfer none]
preset | the preset(s) to use on the encoder, can be NULL. | [allow-none]
restriction | the GstCaps used to restrict the input to the encoder, can be NULL. See `gst_encoding_profile_get_restriction()` for more details. | [allow-none]
presence | the number of time this stream must be used. 0 means any number of times (including never) |

#### Returns

the newly created GstEncodingAudioProfile.

### gst_encoding_video_profile_new ()

    GstEncodingVideoProfile *
    gst_encoding_video_profile_new (GstCaps *format,
                                    const gchar *preset,
                                    GstCaps *restriction,
                                    guint presence);

Creates a new GstEncodingVideoProfile

All provided allocatable arguments will be internally copied, so can be safely freed/unreferenced after calling this method.

If you wish to control the pass number (in case of multi-pass scenarios), please refer to the `gst_encoding_video_profile_set_pass()` documentation.

If you wish to use/force a constant framerate please refer to the `gst_encoding_video_profile_set_variableframerate()` documentation.

#### Parameters

format | the GstCaps. | [transfer none]
preset | the preset(s) to use on the encoder, can be NULL. | [allow-none]
restriction | the GstCaps used to restrict the input to the encoder, can be NULL. See `gst_encoding_profile_get_restriction()` for more details. | [allow-none]
presence | the number of time this stream must be used. 0 means any number of times (including never) |

#### Returns

the newly created GstEncodingVideoProfile.

### gst_encoding_video_profile_get_pass ()

    guint
    gst_encoding_video_profile_get_pass (GstEncodingVideoProfile *prof);

Get the pass number if this is part of a multi-pass profile.

#### Parameters

prof | a GstEncodingVideoProfile |

#### Returns

The pass number. Starts at 1 for multi-pass. 0 if this is not a multi-pass profile

### gst_encoding_video_profile_get_variableframerate ()

    gboolean
    gst_encoding_video_profile_get_variableframerate
                                   (GstEncodingVideoProfile *prof);

#### Parameters

prof | a GstEncodingVideoProfile |

#### Returns

Whether non-constant video framerate is allowed for encoding.

### gst_encoding_video_profile_set_pass ()

    void
    gst_encoding_video_profile_set_pass (GstEncodingVideoProfile *prof,
                                         guint pass);

Sets the pass number of this video profile. The first pass profile should have this value set to 1. If this video profile isn't part of a multi-pass profile, you may set it to 0 (the default value).

#### Parameters

prof | a GstEncodingVideoProfile |
pass | the pass number for this profile |

### gst_encoding_video_profile_set_variableframerate ()

    void
    gst_encoding_video_profile_set_variableframerate
                                   (GstEncodingVideoProfile *prof,
                                    gboolean variableframerate);

If set to `TRUE`, then the incoming stream will be allowed to have non-constant framerate. If set to `FALSE` (default value), then the incoming stream will be normalized by dropping/duplicating frames in order to produce a constance framerate.

#### Parameters

prof | a GstEncodingVideoProfile |
variableframerate | a boolean |

### gst_encoding_target_unref()

    #define             gst_encoding_target_unref(target)

Decreases the reference count of the `target` , possibly freeing it.

#### Parameters

target | a GstEncodingTarget |

### gst_encoding_target_ref()

    #define             gst_encoding_target_ref(target)

Increases the reference count of the `target` .

#### Parameters

target | a GstEncodingTarget |

### gst_encoding_target_new ()

    GstEncodingTarget *
    gst_encoding_target_new (const gchar *name,
                             const gchar *category,
                             const gchar *description,
                             const GList *profiles);

Creates a new GstEncodingTarget.

The name and category can only consist of lowercase ASCII letters for the first character, followed by either lowercase ASCII letters, digits or hyphens ('-').

The `category` should be one of the existing well-defined categories, like GST_ENCODING_CATEGORY_DEVICE, but it can be a application or user specific category if needed.

#### Parameters

name | The name of the target. |
category | The name of the category to which this `target` belongs. For example: GST_ENCODING_CATEGORY_DEVICE. | [transfer none]
description | A description of GstEncodingTarget in the current locale. | [transfer none]
profiles | A GList of GstEncodingProfile. | [transfer none][element-type GstPbutils.EncodingProfile]

#### Returns

The newly created GstEncodingTarget or `NULL` if there was an error.

[transfer full]

### gst_encoding_target_get_name ()

    const gchar *
    gst_encoding_target_get_name (GstEncodingTarget *target);

#### Parameters

target | a GstEncodingTarget |

#### Returns

The name of the `target` .

[transfer none]

### gst_encoding_target_get_category ()

    const gchar *
    gst_encoding_target_get_category (GstEncodingTarget *target);

#### Parameters

target | a GstEncodingTarget |

#### Returns

The category of the `target` . For example: GST_ENCODING_CATEGORY_DEVICE.

[transfer none]

### gst_encoding_target_get_description ()

    const gchar *
    gst_encoding_target_get_description (GstEncodingTarget *target);

#### Parameters

target | a GstEncodingTarget |

#### Returns

The description of the `target` .

[transfer none]

### gst_encoding_target_get_profiles ()

    const GList *
    gst_encoding_target_get_profiles (GstEncodingTarget *target);

#### Parameters

target | a GstEncodingTarget |

#### Returns

A list of GstEncodingProfile(s) this `target` handles.

[transfer none][element-type GstPbutils.EncodingProfile]

### gst_encoding_target_get_profile ()

    GstEncodingProfile *
    gst_encoding_target_get_profile (GstEncodingTarget *target,
                                     const gchar *name);

#### Parameters

target | a GstEncodingTarget |
name | the name of the profile to retrieve |

#### Returns

The matching GstEncodingProfile, or `NULL`.

[transfer full]

### gst_encoding_target_add_profile ()

    gboolean
    gst_encoding_target_add_profile (GstEncodingTarget *target,
                                     GstEncodingProfile *profile);

Adds the given `profile` to the `target` . Each added profile must have a unique name within the profile.

The `target` will steal a reference to the `profile` . If you wish to use the profile after calling this method, you should increase its reference count.

#### Parameters

target | the GstEncodingTarget to add a profile to |
profile | the GstEncodingProfile to add. | [transfer full]

#### Returns

`TRUE` if the profile was added, else `FALSE`.

### gst_encoding_target_save ()

    gboolean
    gst_encoding_target_save (GstEncodingTarget *target,
                              GError **error);

Saves the `target` to a default user-local directory.

#### Parameters

target | a GstEncodingTarget |
error | If an error occured, this field will be filled in. |

#### Returns

`TRUE` if the target was correctly saved, else `FALSE`.

### gst_encoding_target_save_to_file ()

    gboolean
    gst_encoding_target_save_to_file (GstEncodingTarget *target,
                                      const gchar *filepath,
                                      GError **error);

Saves the `target` to the provided file location.

#### Parameters

target | a GstEncodingTarget |
filepath | the location to store the `target` at. |
error | If an error occured, this field will be filled in. |

#### Returns

`TRUE` if the target was correctly saved, else `FALSE`.

### gst_encoding_target_load ()

    GstEncodingTarget *
    gst_encoding_target_load (const gchar *name,
                              const gchar *category,
                              GError **error);

Searches for the GstEncodingTarget with the given name, loads it and returns it.

If the category name is specified only targets from that category will be searched for.

#### Parameters

name | the name of the GstEncodingTarget to load (automatically converted to lower case internally as capital letters are not valid for target names). |
category | the name of the target category, like GST_ENCODING_CATEGORY_DEVICE. Can be `NULL`. | [allow-none]
error | If an error occured, this field will be filled in. |

#### Returns

The GstEncodingTarget if available, else `NULL`.

[transfer full]

### gst_encoding_target_load_from_file ()

    GstEncodingTarget *
    gst_encoding_target_load_from_file (const gchar *filepath,
                                        GError **error);

Opens the provided file and returns the contained GstEncodingTarget.

#### Parameters

filepath | The file location to load the GstEncodingTarget from |
error | If an error occured, this field will be filled in. |

#### Returns

The GstEncodingTarget contained in the file, else `NULL`.

[transfer full]

### gst_encoding_list_all_targets ()

    GList *
    gst_encoding_list_all_targets (const gchar *categoryname);

List all available GstEncodingTarget for the specified category, or all categories if `categoryname` is `NULL`.

#### Parameters

categoryname | The category, for ex: GST_ENCODING_CATEGORY_DEVICE. Can be `NULL`. | [allow-none]

#### Returns

The list of GstEncodingTarget.

[transfer full][element-type GstEncodingTarget]

### gst_encoding_list_available_categories ()

    GList *
    gst_encoding_list_available_categories
                                   (void);

Lists all GstEncodingTarget categories present on disk.

#### Returns

A list of GstEncodingTarget categories.

[transfer full][element-type gchar*]

## Types and Values

### GstEncodingProfile

    typedef struct _GstEncodingProfile GstEncodingProfile;

The opaque base class object for all encoding profiles. This contains generic information like name, description, format and preset.

### GstEncodingContainerProfile

    typedef struct _GstEncodingContainerProfile GstEncodingContainerProfile;

Encoding profiles for containers. Keeps track of a list of GstEncodingProfile

### GstEncodingAudioProfile

    typedef struct _GstEncodingAudioProfile GstEncodingAudioProfile;

Variant of GstEncodingProfile for audio streams.

### GstEncodingVideoProfile

    typedef struct _GstEncodingVideoProfile GstEncodingVideoProfile;

Variant of GstEncodingProfile for video streams, allows specifying the `pass` .

### GST_ENCODING_CATEGORY_DEVICE

    #define GST_ENCODING_CATEGORY_DEVICE            "device"

GstEncodingTarget category for device-specific targets. The name of the target will usually be the constructor and model of the device, and that target will contain GstEncodingProfiles suitable for that device.

### GST_ENCODING_CATEGORY_ONLINE_SERVICE

    #define GST_ENCODING_CATEGORY_ONLINE_SERVICE    "online-service"

GstEncodingTarget category for online-services. The name of the target will usually be the name of the online service and that target will contain GstEncodingProfiles suitable for that online service.

### GST_ENCODING_CATEGORY_STORAGE_EDITING

    #define GST_ENCODING_CATEGORY_STORAGE_EDITING   "storage-editing"

GstEncodingTarget category for storage, archiving and editing targets. Those targets can be lossless and/or provide very fast random access content. The name of the target will usually be the container type or editing target, and that target will contain GstEncodingProfiles suitable for editing or storage.

### GST_ENCODING_CATEGORY_CAPTURE

    #define GST_ENCODING_CATEGORY_CAPTURE           "capture"

GstEncodingTarget category for recording and capture. Targets within this category are optimized for low latency encoding.

### GstEncodingTarget

    typedef struct _GstEncodingTarget GstEncodingTarget;

Collection of GstEncodingProfile for a specific target or use-case.

When being stored/loaded, targets come from a specific category, like GST_ENCODING_CATEGORY_DEVICE.

## Property Details

### The `“restriction-caps”` property

      “restriction-caps”         GstCaps *

The restriction caps to use.

Flags: Read / Write