Defining a GstEncodingProfile as a string

1

muxer_factory_name:video_encoder_factory_name:audio_encoder_factory_name

1

webmmux:vp8enc:vorbisenc

1

muxer_source_caps:video_encoder_source_caps:audio_encoder_source_caps

1

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

1

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

1

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

1

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

1

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

1

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

1

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

1

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

1

target_name[/profilename/category]

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.

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.

1

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

Naming restrictions:

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 .

gst_encoding_profile_ref()

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

Increases the reference count of the profile .

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.

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.

gst_encoding_profile_get_name ()

const gchar *
gst_encoding_profile_get_name (GstEncodingProfile *profile);

gst_encoding_profile_get_description ()

const gchar *
gst_encoding_profile_get_description (GstEncodingProfile *profile);

gst_encoding_profile_get_format ()

GstCaps *
gst_encoding_profile_get_format (GstEncodingProfile *profile);

gst_encoding_profile_get_preset ()

const gchar *
gst_encoding_profile_get_preset (GstEncodingProfile *profile);

gst_encoding_profile_get_preset_name ()

const gchar *
gst_encoding_profile_get_preset_name (GstEncodingProfile *profile);

gst_encoding_profile_get_presence ()

guint
gst_encoding_profile_get_presence (GstEncodingProfile *profile);

gst_encoding_profile_get_restriction ()

GstCaps *
gst_encoding_profile_get_restriction (GstEncodingProfile *profile);

gst_encoding_profile_get_file_extension ()

const gchar *
gst_encoding_profile_get_file_extension
                               (GstEncodingProfile *profile);

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.

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.

gst_encoding_profile_set_enabled ()

void
gst_encoding_profile_set_enabled (GstEncodingProfile *profile,
                                  gboolean enabled);

Set whether the profile should be used or not.

Since 1.6

gst_encoding_profile_set_format ()

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

Sets the media format used in the profile.

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.

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.

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.

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

gst_encoding_profile_is_equal ()

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

Checks whether the two GstEncodingProfile are equal

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.

gst_encoding_profile_get_type_nick ()

const gchar *
gst_encoding_profile_get_type_nick (GstEncodingProfile *profile);

gst_encoding_profile_copy ()

GstEncodingProfile *
gst_encoding_profile_copy (GstEncodingProfile *self);

Makes a deep copy of self

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.

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.

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.

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.

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 .

gst_encoding_container_profile_get_profiles ()

const GList *
gst_encoding_container_profile_get_profiles
                               (GstEncodingContainerProfile *profile);

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.

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.

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.

gst_encoding_video_profile_get_variableframerate ()

gboolean
gst_encoding_video_profile_get_variableframerate
                               (GstEncodingVideoProfile *prof);

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).

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.

gst_encoding_target_unref()

#define             gst_encoding_target_unref(target)

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

gst_encoding_target_ref()

#define             gst_encoding_target_ref(target)

Increases the reference count of the target .

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.

gst_encoding_target_get_name ()

const gchar *
gst_encoding_target_get_name (GstEncodingTarget *target);

gst_encoding_target_get_category ()

const gchar *
gst_encoding_target_get_category (GstEncodingTarget *target);

gst_encoding_target_get_description ()

const gchar *
gst_encoding_target_get_description (GstEncodingTarget *target);

gst_encoding_target_get_profiles ()

const GList *
gst_encoding_target_get_profiles (GstEncodingTarget *target);

gst_encoding_target_get_profile ()

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

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.

gst_encoding_target_save ()

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

Saves the target to a default user-local directory.

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.

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.

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.

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.

gst_encoding_list_available_categories ()

GList *
gst_encoding_list_available_categories
                               (void);

Lists all GstEncodingTarget categories present on disk.

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.

The “restriction-caps” property

  “restriction-caps”         GstCaps *

The restriction caps to use.

Flags: Read / Write