spectrum

spectrum — audio spectrum analyzer

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

Description

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

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

  • GstClockTime "endtime": the end time of the buffer that triggered the message. Always present.

  • GstValueList of gfloat "magnitude": the level for each frequency band in dB. All values below the value of the GstSpectrum: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.

This element cannot be used with the gst-launch command in a sensible way. This sample code demonstrates how to use it in an application.

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 <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 2008-02-09 (0.10.6)

Element Information

plugin spectrum
author Erik Walthinsen <omega@cse.ogi.edu>, Stefan Kost <ensonic@users.sf.net>, Sebastian Dröge <slomo@circular-chaos.org>
class Filter/Analyzer/Audio

Element Pads

name src
direction source
presence always
details audio/x-raw-int, width=(int)16, depth=(int)16, signed=(boolean)true, endianness=(int)1234, rate=(int)[ 1, 2147483647 ], channels=(int)[ 1, 2147483647 ]; audio/x-raw-int, width=(int)32, depth=(int)32, signed=(boolean)true, endianness=(int)1234, rate=(int)[ 1, 2147483647 ], channels=(int)[ 1, 2147483647 ]; audio/x-raw-float, width=(int){ 32, 64 }, endianness=(int)1234, rate=(int)[ 1, 2147483647 ], channels=(int)[ 1, 2147483647 ]
name sink
direction sink
presence always
details audio/x-raw-int, width=(int)16, depth=(int)16, signed=(boolean)true, endianness=(int)1234, rate=(int)[ 1, 2147483647 ], channels=(int)[ 1, 2147483647 ]; audio/x-raw-int, width=(int)32, depth=(int)32, signed=(boolean)true, endianness=(int)1234, rate=(int)[ 1, 2147483647 ], channels=(int)[ 1, 2147483647 ]; audio/x-raw-float, width=(int){ 32, 64 }, endianness=(int)1234, rate=(int)[ 1, 2147483647 ], channels=(int)[ 1, 2147483647 ]

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

Post a level message for each passed interval.

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

Post the magnitude of the spectrum.

Default value: TRUE


The "message-phase" property

  "message-phase"            gboolean              : Read / Write

Post the phase of the spectrum.

Default value: FALSE