2 * Copyright (C) 2009 Sebastian Dröge <sebastian.droege@collabora.co.uk>
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
21 * SECTION:gststreamvolume
22 * @short_description: Interface for elements that provide a stream volume
26 * This interface is implemented by elements that provide a stream volume. Examples for
27 * such elements are #volume and #playbin2.
30 * Applications can use this interface to get or set the current stream volume. For this
31 * the "volume" #GObject property can be used or the helper functions gst_stream_volume_set_volume()
32 * and gst_stream_volume_get_volume(). This volume is always a linear factor, i.e. 0.0 is muted
33 * 1.0 is 100%. For showing the volume in a GUI it might make sense to convert it to
34 * a different format by using gst_stream_volume_convert_volume(). Volume sliders should usually
37 * Separate from the volume the stream can also be muted by the "mute" #GObject property or
38 * gst_stream_volume_set_mute() and gst_stream_volume_get_mute().
41 * Elements that provide some kind of stream volume should implement the "volume" and
42 * "mute" #GObject properties and handle setting and getting of them properly.
43 * The volume property is defined to be a linear volume factor.
52 #include "streamvolume.h"
56 gst_stream_volume_class_init (GstStreamVolumeInterface * iface)
58 g_object_interface_install_property (iface,
59 g_param_spec_double ("volume",
61 "Linear volume factor, 1.0=100%",
62 0.0, G_MAXDOUBLE, 1.0, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
63 g_object_interface_install_property (iface,
64 g_param_spec_boolean ("mute",
66 "Mute the audio channel without changing the volume",
67 FALSE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
71 gst_stream_volume_get_type (void)
73 static volatile gsize type = 0;
74 if (g_once_init_enter (&type)) {
76 static const GTypeInfo info = {
77 sizeof (GstStreamVolumeInterface),
79 NULL, /* base_finalize */
80 (GClassInitFunc) gst_stream_volume_class_init, /* class_init */
81 NULL, /* class_finalize */
82 NULL, /* class_data */
85 NULL /* instance_init */
87 tmp = g_type_register_static (G_TYPE_INTERFACE,
88 "GstStreamVolume", &info, 0);
89 g_type_interface_add_prerequisite (tmp, G_TYPE_OBJECT);
91 g_once_init_leave (&type, tmp);
97 * gst_stream_volume_get_volume:
98 * @volume: #GstStreamVolume that should be used
99 * @format: #GstStreamVolumeFormat which should be returned
101 * Returns: The current stream volume as linear factor
106 gst_stream_volume_get_volume (GstStreamVolume * volume,
107 GstStreamVolumeFormat format)
111 g_return_val_if_fail (GST_IS_STREAM_VOLUME (volume), 1.0);
113 g_object_get (volume, "volume", &val, NULL);
114 if (format != GST_STREAM_VOLUME_FORMAT_LINEAR)
116 gst_stream_volume_convert_volume (GST_STREAM_VOLUME_FORMAT_LINEAR,
122 * gst_stream_volume_set_volume:
123 * @volume: #GstStreamVolume that should be used
124 * @format: #GstStreamVolumeFormat of @val
125 * @val: Linear volume factor that should be set
130 gst_stream_volume_set_volume (GstStreamVolume * volume,
131 GstStreamVolumeFormat format, gdouble val)
133 g_return_if_fail (GST_IS_STREAM_VOLUME (volume));
135 if (format != GST_STREAM_VOLUME_FORMAT_LINEAR)
137 gst_stream_volume_convert_volume (format,
138 GST_STREAM_VOLUME_FORMAT_LINEAR, val);
139 g_object_set (volume, "volume", val, NULL);
143 * gst_stream_volume_get_mute:
144 * @volume: #GstStreamVolume that should be used
146 * Returns: Returns %TRUE if the stream is muted
151 gst_stream_volume_get_mute (GstStreamVolume * volume)
155 g_return_val_if_fail (GST_IS_STREAM_VOLUME (volume), FALSE);
157 g_object_get (volume, "mute", &val, NULL);
162 * gst_stream_volume_set_mute:
163 * @volume: #GstStreamVolume that should be used
164 * @mute: Mute state that should be set
169 gst_stream_volume_set_mute (GstStreamVolume * volume, gboolean mute)
171 g_return_if_fail (GST_IS_STREAM_VOLUME (volume));
173 g_object_set (volume, "mute", mute, NULL);
177 * gst_stream_volume_convert_volume:
178 * @from: #GstStreamVolumeFormat to convert from
179 * @to: #GstStreamVolumeFormat to convert to
180 * @val: Volume in @from format that should be converted
182 * Returns: the converted volume
187 gst_stream_volume_convert_volume (GstStreamVolumeFormat from,
188 GstStreamVolumeFormat to, gdouble val)
191 case GST_STREAM_VOLUME_FORMAT_LINEAR:
192 g_return_val_if_fail (val >= 0.0, 0.0);
194 case GST_STREAM_VOLUME_FORMAT_LINEAR:
196 case GST_STREAM_VOLUME_FORMAT_CUBIC:
197 return pow (val, 1 / 3.0);
198 case GST_STREAM_VOLUME_FORMAT_DB:
199 return 20.0 * log10 (val);
202 case GST_STREAM_VOLUME_FORMAT_CUBIC:
203 g_return_val_if_fail (val >= 0.0, 0.0);
205 case GST_STREAM_VOLUME_FORMAT_LINEAR:
206 return val * val * val;
207 case GST_STREAM_VOLUME_FORMAT_CUBIC:
209 case GST_STREAM_VOLUME_FORMAT_DB:
210 return 3.0 * 20.0 * log10 (val);
213 case GST_STREAM_VOLUME_FORMAT_DB:
215 case GST_STREAM_VOLUME_FORMAT_LINEAR:
216 return pow (10.0, val / 20.0);
217 case GST_STREAM_VOLUME_FORMAT_CUBIC:
218 return pow (10.0, val / (3.0 * 20.0));
219 case GST_STREAM_VOLUME_FORMAT_DB:
224 g_return_val_if_reached (0.0);