## gsttuner gsttuner — Interface for elements providing tuner operations |

## Synopsis

    #include <gst/interfaces/tuner.h>

                        GstTuner;
    struct              GstTunerClass;
    const GList *       gst_tuner_list_channels             (GstTuner *tuner);
    GstTunerChannel *   gst_tuner_get_channel               (GstTuner *tuner);
    void                gst_tuner_set_channel               (GstTuner *tuner,
                                                             GstTunerChannel *channel);
    const GList *       gst_tuner_list_norms                (GstTuner *tuner);
    GstTunerNorm *      gst_tuner_get_norm                  (GstTuner *tuner);
    void                gst_tuner_set_norm                  (GstTuner *tuner,
                                                             GstTunerNorm *norm);
    gulong              gst_tuner_get_frequency             (GstTuner *tuner,
                                                             GstTunerChannel *channel);
    void                gst_tuner_set_frequency             (GstTuner *tuner,
                                                             GstTunerChannel *channel,
                                                             gulong frequency);
    gint                gst_tuner_signal_strength           (GstTuner *tuner,
                                                             GstTunerChannel *channel);
    GstTunerNorm *      gst_tuner_find_norm_by_name         (GstTuner *tuner,
                                                             gchar *norm);
    GstTunerChannel *   gst_tuner_find_channel_by_name      (GstTuner *tuner,
                                                             gchar *channel);
    void                gst_tuner_channel_changed           (GstTuner *tuner,
                                                             GstTunerChannel *channel);
    void                gst_tuner_norm_changed              (GstTuner *tuner,
                                                             GstTunerNorm *norm);
    void                gst_tuner_frequency_changed         (GstTuner *tuner,
                                                             GstTunerChannel *channel,
                                                             gulong frequency);
    void                gst_tuner_signal_changed            (GstTuner *tuner,
                                                             GstTunerChannel *channel,
                                                             gint signal);

## Object Hierarchy

      GInterface
       +----GstTuner

## Prerequisites

GstTuner requires GstImplementsInterface and GstElement.

## Signals

      "channel-changed"                                : Run Last
      "frequency-changed"                              : Run Last
      "norm-changed"                                   : Run Last
      "signal-changed"                                 : Run Last

## Description

The GstTuner interface is provided by elements that have the ability to tune into multiple input signals, for example TV or radio capture cards.

The interpretation of 'tuning into' an input stream depends on the element implementing the interface. For v4lsrc, it might imply selection of an input source and/or frequency to be configured on a TV card. Another GstTuner implementation might be to allow selection of an active input pad from multiple input pads.

That said, the GstTuner interface functions are biased toward the TV capture scenario.

The general parameters provided are for configuration are:

- Selection of a current GstTunerChannel. The current channel represents the input source (e.g. Composite, S-Video etc for TV capture).
- The GstTunerNorm for the channel. The norm chooses the interpretation of the incoming signal for the current channel. For example, PAL or NTSC, or more specific variants there-of.
- Channel frequency. If the current channel has the ability to tune between multiple frequencies (if it has the GST_TUNER_CHANNEL_FREQUENCY flag) then the frequency can be changed/retrieved via the `gst_tuner_set_frequency()` and `gst_tuner_get_frequency()` methods.

Where applicable, the signal strength can be retrieved and/or monitored via a signal.

## Details

### GstTuner

    typedef struct _GstTuner GstTuner;

### struct GstTunerClass

    struct GstTunerClass {
      GTypeInterface klass;

      /* virtual functions */
      const GList * (* list_channels)   (GstTuner        *tuner);
      void          (* set_channel)     (GstTuner        *tuner,
                                         GstTunerChannel *channel);
      GstTunerChannel *
                    (* get_channel)     (GstTuner        *tuner);

      const GList * (* list_norms)      (GstTuner        *tuner);
      void          (* set_norm)        (GstTuner        *tuner,
                                         GstTunerNorm    *norm);
      GstTunerNorm *(* get_norm)        (GstTuner        *tuner);

      void          (* set_frequency)   (GstTuner        *tuner,
                                         GstTunerChannel *channel,
                                         gulong           frequency);
      gulong        (* get_frequency)   (GstTuner        *tuner,
                                         GstTunerChannel *channel);
      gint          (* signal_strength) (GstTuner        *tuner,
                                         GstTunerChannel *channel);

      /* signals */
      void (*channel_changed)   (GstTuner        *tuner,
                                 GstTunerChannel *channel);
      void (*norm_changed)      (GstTuner        *tuner,
                                 GstTunerNorm    *norm);
      void (*frequency_changed) (GstTuner        *tuner,
                                 GstTunerChannel *channel,
                                 gulong           frequency);
      void (*signal_changed)    (GstTuner        *tuner,
                                 GstTunerChannel *channel,
                                 gint             signal);

      gpointer _gst_reserved[GST_PADDING];
    };

### gst_tuner_list_channels ()

    const GList *       gst_tuner_list_channels             (GstTuner *tuner);

Retrieve a GList of GstTunerChannels available (e.g. 'composite', 's-video', ...) from the given tuner object.

`tuner` : | the GstTuner (a GstElement) to get the channels from.
Returns : | A list of channels available on this tuner. The list is owned by the GstTuner and must not be freed.

### gst_tuner_get_channel ()

    GstTunerChannel *   gst_tuner_get_channel               (GstTuner *tuner);

Retrieve the current channel from the tuner.

`tuner` : | the GstTuner (a GstElement) to get the current channel from.
Returns : | the current channel of the tuner object.

### gst_tuner_set_channel ()

    void                gst_tuner_set_channel               (GstTuner *tuner,
                                                             GstTunerChannel *channel);

Tunes the object to the given channel, which should be one of the channels returned by `gst_tuner_list_channels()`.

`tuner` : | the GstTuner (a GstElement) that owns the channel.
`channel` : | the channel to tune to.

### gst_tuner_list_norms ()

    const GList *       gst_tuner_list_norms                (GstTuner *tuner);

Retrieve a GList of available GstTunerNorm settings for the currently tuned channel on the given tuner object.

`tuner` : | the GstTuner (*a GstElement) to get the list of norms from.
Returns : | A list of norms available on the current channel for this tuner object. The list is owned by the GstTuner and must not be freed.

### gst_tuner_get_norm ()

    GstTunerNorm *      gst_tuner_get_norm                  (GstTuner *tuner);

Get the current video norm from the given tuner object for the currently selected channel.

`tuner` : | the GstTuner (a GstElement) to get the current norm from.
Returns : | the current norm.

### gst_tuner_set_norm ()

    void                gst_tuner_set_norm                  (GstTuner *tuner,
                                                             GstTunerNorm *norm);

Changes the video norm on this tuner to the given norm, which should be one of the norms returned by `gst_tuner_list_norms()`.

`tuner` : | the GstTuner (a GstElement) to set the norm on.
`norm` : | the norm to use for the current channel.

### gst_tuner_get_frequency ()

    gulong              gst_tuner_get_frequency             (GstTuner *tuner,
                                                             GstTunerChannel *channel);

Retrieve the current frequency from the given channel. As for `gst_tuner_set_frequency()`, the GstTunerChannel must support frequency operations, as indicated by the GST_TUNER_CHANNEL_FREQUENCY flag.

`tuner` : | The GstTuner (a GstElement) that owns the given channel.
`channel` : | The GstTunerChannel to retrieve the frequency from.
Returns : | The current frequency, or 0 on error.

### gst_tuner_set_frequency ()

    void                gst_tuner_set_frequency             (GstTuner *tuner,
                                                             GstTunerChannel *channel,
                                                             gulong frequency);

Sets a tuning frequency on the given tuner/channel. Note that this requires the given channel to be a "tuning" channel, which can be checked using `GST_TUNER_CHANNEL_HAS_FLAG()`, with the proper flag being GST_TUNER_CHANNEL_FREQUENCY.

The frequency is in Hz, with minimum steps indicated by the frequency_multiplicator provided in the GstTunerChannel. The valid range is provided in the min_frequency and max_frequency properties of the GstTunerChannel.

`tuner` : | The GstTuner (a GstElement) that owns the given channel.
`channel` : | The GstTunerChannel to set the frequency on.
`frequency` : | The frequency to tune in to.

### gst_tuner_signal_strength ()

    gint                gst_tuner_signal_strength           (GstTuner *tuner,
                                                             GstTunerChannel *channel);

Get the strength of the signal on this channel. Note that this requires the current channel to be a "tuning" channel, i.e. a channel on which frequency can be set. This can be checked using `GST_TUNER_CHANNEL_HAS_FLAG()`, and the appropriate flag to check for is GST_TUNER_CHANNEL_FREQUENCY.

The valid range of the signal strength is indicated in the min_signal and max_signal properties of the GstTunerChannel.

`tuner` : | the GstTuner (a GstElement) that owns the given channel.
`channel` : | the GstTunerChannel to get the signal strength from.
Returns : | Signal strength, or 0 on error.

### gst_tuner_find_norm_by_name ()

    GstTunerNorm *      gst_tuner_find_norm_by_name         (GstTuner *tuner,
                                                             gchar *norm);

Look up a GstTunerNorm by name.

`tuner` : | A GstTuner instance
`norm` : | A string containing the name of a GstTunerNorm
Returns : | A GstTunerNorm, or NULL if no norm with the provided name is available.

### gst_tuner_find_channel_by_name ()

    GstTunerChannel *   gst_tuner_find_channel_by_name      (GstTuner *tuner,
                                                             gchar *channel);

Look up a GstTunerChannel by name.

`tuner` : | A GstTuner instance
`channel` : | A string containing the name of a GstTunerChannel
Returns : | A GstTunerChannel, or NULL if no channel with the provided name is available.

### gst_tuner_channel_changed ()

    void                gst_tuner_channel_changed           (GstTuner *tuner,
                                                             GstTunerChannel *channel);

Called by elements implementing the GstTuner interface when the current channel changes. Fires the "channel-changed" signal.

`tuner` : | A GstTuner instance
`channel` : | A GstTunerChannel instance

### gst_tuner_norm_changed ()

    void                gst_tuner_norm_changed              (GstTuner *tuner,
                                                             GstTunerNorm *norm);

Called by elements implementing the GstTuner interface when the current norm changes. Fires the "norm-changed" signal.

`tuner` : | A GstTuner instance
`norm` : | A GstTunerNorm instance

### gst_tuner_frequency_changed ()

    void                gst_tuner_frequency_changed         (GstTuner *tuner,
                                                             GstTunerChannel *channel,
                                                             gulong frequency);

Called by elements implementing the GstTuner interface when the configured frequency changes. Fires the "frequency-changed" signal on the tuner, and the "frequency-changed" signal on the channel.

`tuner` : | A GstTuner instance
`channel` : | The current GstTunerChannel
`frequency` : | The new frequency setting

### gst_tuner_signal_changed ()

    void                gst_tuner_signal_changed            (GstTuner *tuner,
                                                             GstTunerChannel *channel,
                                                             gint signal);

Called by elements implementing the GstTuner interface when the incoming signal strength changes. Fires the "signal-changed" signal on the tuner and the "signal-changed" signal on the channel.

`tuner` : | A GstTuner instance
`channel` : | The current GstTunerChannel
`signal` : | The new signal strength

## Signal Details

### The `"channel-changed"` signal

    void                user_function                      (GstTuner        *tuner,
                                                            GstTunerChannel *channel,
                                                            gpointer         user_data)      : Run Last

Reports that the current GstTunerChannel has changed.

`tuner` : | The element providing the GstTuner interface
`channel` : | The new configured channel.
`user_data` : | user data set when the signal handler was connected.

### The `"frequency-changed"` signal

    void                user_function                      (GstTuner        *tuner,
                                                            GstTunerChannel *frequency,
                                                            gulong           arg2,
                                                            gpointer         user_data)      : Run Last

Reports that the current frequency has changed.

`tuner` : | The element providing the GstTuner interface
`frequency` : | The new frequency (an unsigned long)
`user_data` : | user data set when the signal handler was connected.

### The `"norm-changed"` signal

    void                user_function                      (GstTuner     *tuner,
                                                            GstTunerNorm *norm,
                                                            gpointer      user_data)      : Run Last

Reports that the current GstTunerNorm has changed.

`tuner` : | The element providing the GstTuner interface
`norm` : | The new configured norm.
`user_data` : | user data set when the signal handler was connected.

### The `"signal-changed"` signal

    void                user_function                      (GstTuner        *tuner,
                                                            GstTunerChannel *channel,
                                                            gint             signal,
                                                            gpointer         user_data)      : Run Last

Reports that the signal strength has changed.

See Also: `gst_tuner_signal_strength()`

`tuner` : | The element providing the GstTuner interface
`channel` : | The current GstTunerChannel
`signal` : | The new signal strength (an integer)
`user_data` : | user data set when the signal handler was connected.