spectrum

spectrum — Run an FFT on the audio signal, output spectrum data

Synopsis

                    GstSpectrum;

Object Hierarchy

  GObject
   +----GstObject
         +----GstElement
               +----GstBaseTransform
                     +----GstAudioFilter
                           +----GstSpectrum

Properties

  "bands"                    guint                 : Read / Write
  "interval"                 guint64               : Read / Write
  "message"                  gboolean              : Read / Write
  "threshold"                gint                  : Read / Write
  "message-magnitude"        gboolean              : Read / Write
  "message-phase"            gboolean              : Read / Write
  "post-messages"            gboolean              : Read / Write

Description

The Spectrum element analyzes the frequency spectrum of an audio signal. If the "post-messages" property is TRUE, it sends analysis results as application messages named "spectrum" after each interval of time given by the "interval" property.

The message's structure contains some combination of these fields:

  • GstClockTime "timestamp": the timestamp of the buffer that triggered the message.

  • GstClockTime "stream-time": the stream time of the buffer.

  • GstClockTime "running-time": the running_time of the buffer.

  • GstClockTime "duration": the duration of the buffer.

  • GstClockTime "endtime": the end time of the buffer that triggered the message as stream time (this is deprecated, as it can be calculated from stream-time + duration)

  • GstValueList of gfloat "magnitude": the level for each frequency band in dB. All values below the value of the "threshold" property will be set to the threshold. Only present if the message-magnitude property is true.

  • GstValueList of gfloat "phase": The phase for each frequency band. The value is between -pi and pi. Only present if the message-phase property is true.

Example application

/* GStreamer
 * Copyright (C) 2006 Stefan Kost <ensonic@users.sf.net>
 * Copyright (C) 2008 Jan Schmidt <jan.schmidt@sun.com>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <gst/gst.h>

static guint spect_bands = 20;

#define AUDIOFREQ 32000

/* receive spectral data from element message */
gboolean
message_handler (GstBus * bus, GstMessage * message, gpointer data)
{
  if (message->type == GST_MESSAGE_ELEMENT) {
    const GstStructure *s = gst_message_get_structure (message);
    const gchar *name = gst_structure_get_name (s);
    GstClockTime endtime;

    if (strcmp (name, "spectrum") == 0) {
      const GValue *magnitudes;
      const GValue *phases;
      const GValue *mag, *phase;
      gdouble freq;
      guint i;

      if (!gst_structure_get_clock_time (s, "endtime", &endtime))
        endtime = GST_CLOCK_TIME_NONE;

      g_print ("New spectrum message, endtime %" GST_TIME_FORMAT "\n",
          GST_TIME_ARGS (endtime));

      magnitudes = gst_structure_get_value (s, "magnitude");
      phases = gst_structure_get_value (s, "phase");

      for (i = 0; i < spect_bands; ++i) {
        freq = (gdouble) ((AUDIOFREQ / 2) * i + AUDIOFREQ / 4) / spect_bands;
        mag = gst_value_list_get_value (magnitudes, i);
        phase = gst_value_list_get_value (phases, i);

        if (mag != NULL && phase != NULL) {
          g_print ("band %d (freq %g): magnitude %f dB phase %f\n", i, freq,
              g_value_get_float (mag), g_value_get_float (phase));
        }
      }
      g_print ("\n");
    }
  }
  return TRUE;
}

int
main (int argc, char *argv[])
{
  GstElement *bin;
  GstElement *src, *audioconvert, *spectrum, *sink;
  GstBus *bus;
  GstCaps *caps;
  GMainLoop *loop;

  gst_init (&argc, &argv);

  bin = gst_pipeline_new ("bin");

  src = gst_element_factory_make ("audiotestsrc", "src");
  g_object_set (G_OBJECT (src), "wave", 0, "freq", 6000.0, NULL);
  audioconvert = gst_element_factory_make ("audioconvert", NULL);
  g_assert (audioconvert);

  spectrum = gst_element_factory_make ("spectrum", "spectrum");
  g_object_set (G_OBJECT (spectrum), "bands", spect_bands, "threshold", -80,
      "message", TRUE, "message-phase", TRUE, NULL);

  sink = gst_element_factory_make ("fakesink", "sink");
  g_object_set (G_OBJECT (sink), "sync", TRUE, NULL);

  gst_bin_add_many (GST_BIN (bin), src, audioconvert, spectrum, sink, NULL);

  caps = gst_caps_new_simple ("audio/x-raw-int",
      "rate", G_TYPE_INT, AUDIOFREQ, NULL);

  if (!gst_element_link (src, audioconvert) ||
      !gst_element_link_filtered (audioconvert, spectrum, caps) ||
      !gst_element_link (spectrum, sink)) {
    fprintf (stderr, "can't link elements\n");
    exit (1);
  }
  gst_caps_unref (caps);

  bus = gst_element_get_bus (bin);
  gst_bus_add_watch (bus, message_handler, NULL);
  gst_object_unref (bus);

  gst_element_set_state (bin, GST_STATE_PLAYING);

  /* we need to run a GLib main loop to get the messages */
  loop = g_main_loop_new (NULL, FALSE);
  g_main_loop_run (loop);

  gst_element_set_state (bin, GST_STATE_NULL);

  gst_object_unref (bin);

  return 0;
}

Last reviewed on 2009-01-14 (0.10.12)

Details

GstSpectrum

typedef struct _GstSpectrum GstSpectrum;

Property Details

The "bands" property

  "bands"                    guint                 : Read / Write

Number of frequency bands.

Default value: 128


The "interval" property

  "interval"                 guint64               : Read / Write

Interval of time between message posts (in nanoseconds).

Allowed values: >= 1

Default value: 100000000


The "message" property

  "message"                  gboolean              : Read / Write

Whether to post a 'spectrum' element message on the bus for each passed interval (deprecated, use post-messages).

Default value: TRUE


The "threshold" property

  "threshold"                gint                  : Read / Write

dB threshold for result. All lower values will be set to this.

Allowed values: <= 0

Default value: -60


The "message-magnitude" property

  "message-magnitude"        gboolean              : Read / Write

Whether to add a 'magnitude' field to the structure of any 'spectrum' element messages posted on the bus.

Default value: TRUE


The "message-phase" property

  "message-phase"            gboolean              : Read / Write

Whether to add a 'phase' field to the structure of any 'spectrum' element messages posted on the bus.

Default value: FALSE


The "post-messages" property

  "post-messages"            gboolean              : Read / Write

Post messages on the bus with spectrum information.

Default value: TRUE

Since 0.10.17