manual-dparams.md

   1 ---
   2 title: Dynamic Controllable Parameters
   3 ...
   4
   5 # Dynamic Controllable Parameters
   6
   7 ## Getting Started
   8
   9 The controller subsystem offers a lightweight way to adjust gobject
  10 properties over stream-time. Normally these properties are changed using
  11 `g_object_set()`. Timing those calls reliably so that the changes affect
  12 certain stream times is close to impossible. The controller takes time
  13 into account. It works by attaching control-sources to properties using
  14 control-bindings. Control-sources provide values for a given time-stamp
  15 that are usually in the range of 0.0 to 1.0. Control-bindings map the
  16 control-value to a gobject property they are bound to - converting the
  17 type and scaling to the target property value range. At run-time the
  18 elements continuously pull values changes for the current stream-time to
  19 update the gobject properties. GStreamer includes a few different
  20 control-sources and control-bindings already, but applications can
  21 define their own by sub-classing from the respective base classes.
  22
  23 Most parts of the controller mechanism is implemented in GstObject. Also
  24 the base classes for control-sources and control-bindings are included
  25 in the core library. The existing implementations are contained within
  26 the `gstcontroller` library. You need to include the header in your
  27 application's source file:
  28
  29 ``` c
  30 ...
  31 #include <gst/gst.h>
  32 #include <gst/controller/gstinterpolationcontrolsource.h>
  33 #include <gst/controller/gstdirectcontrolbinding.h>
  34 ...
  35
  36 ```
  37
  38 Your application should link to the shared library
  39 `gstreamer-controller`. One can get the required flag for compiler and
  40 linker by using pkg-config for gstreamer-controller-1.0.
  41
  42 ## Setting up parameter control
  43
  44 If we have our pipeline set up and want to control some parameters, we
  45 first need to create a control-source. Lets use an interpolation
  46 control-source:
  47
  48 ``` c
  49   csource = gst_interpolation_control_source_new ();
  50   g_object_set (csource, "mode", GST_INTERPOLATION_MODE_LINEAR, NULL);
  51
  52 ```
  53
  54 Now we need to attach the control-source to the gobject property. This
  55 is done with a control-binding. One control source can be attached to
  56 several object properties (even in different objects) using separate
  57 control-bindings.
  58
  59 ``` c
  60       gst_object_add_control_binding (object, gst_direct_control_binding_new (object, "prop1", csource));
  61
  62 ```
  63
  64 This type control-source takes new property values from a list of
  65 time-stamped parameter changes. The source can e.g. fill gaps by
  66 smoothing parameter changes This behavior can be configured by setting
  67 the mode property of the control-source. Other control sources e.g.
  68 produce a stream of values by calling `sin()` function. They have
  69 parameters to control e.g. the frequency. As control-sources are
  70 GstObjects too, one can attach control-sources to these properties too.
  71
  72 Now we can set some control points. These are time-stamped gdouble
  73 values and are usually in the range of 0.0 to 1.0. A value of 1.0 is
  74 later mapped to the maximum value in the target properties value range.
  75 The values become active when the timestamp is reached. They still stay
  76 in the list. If e.g. the pipeline runs a loop (using a segmented seek),
  77 the control-curve gets repeated as
  78 well.
  79
  80 ``` c
  81   GstTimedValueControlSource *tv_csource = (GstTimedValueControlSource *)csource;
  82   gst_timed_value_control_source_set (tv_csource, 0 * GST_SECOND, 0.0);
  83   gst_timed_value_control_source_set (tv_csource, 1 * GST_SECOND, 1.0);
  84
  85 ```
  86
  87 Now everything is ready to play. If the control-source is e.g. bound to
  88 a volume property, we will head a fade-in over 1 second. One word of
  89 caution, the volume element that comes with gstreamer has a value range
  90 of 0.0 to 4.0 on its volume property. If the above control-source is
  91 attached to the property the volume will ramp up to 400%\!
  92
  93 One final note - the controller subsystem has a built-in live-mode. Even
  94 though a property has a control-source assigned one can change the
  95 GObject property through the `g_object_set()`. This is highly useful
  96 when binding the GObject properties to GUI widgets. When the user
  97 adjusts the value with the widget, one can set the GObject property and
  98 this remains active until the next programmed control-source value
  99 overrides it. This also works with smoothed parameters. It does not work
 100 for control-sources that constantly update the property (e.g. the
 101 lfo\_control\_source).
 102