1 /* GStreamer DTMF source
5 * Copyright (C) <2007> Collabora.
6 * Contact: Youness Alaoui <youness.alaoui@collabora.co.uk>
7 * Copyright (C) <2007> Nokia Corporation.
8 * Contact: Zeeshan Ali <zeeshan.ali@nokia.com>
9 * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
10 * 2000,2005 Wim Taymans <wim@fluendo.com>
12 * This library is free software; you can redistribute it and/or
13 * modify it under the terms of the GNU Library General Public
14 * License as published by the Free Software Foundation; either
15 * version 2 of the License, or (at your option) any later version.
17 * This library is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 * Library General Public License for more details.
22 * You should have received a copy of the GNU Library General Public
23 * License along with this library; if not, write to the
24 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
25 * Boston, MA 02111-1307, USA.
29 * SECTION:element-dtmfsrc
30 * @short_description: Generates DTMF packets
35 * The DTMFSrc element generates DTMF (ITU-T Q.23 Specification) tone packets on request
36 * from application. The application communicates the beginning and end of a
37 * DTMF event using custom upstream gstreamer events. To report a DTMF event, an
38 * application must send an event of type GST_EVENT_CUSTOM_UPSTREAM, having a
39 * structure of name "dtmf-event" with fields set according to the following
46 * <colspec colname='Name' />
47 * <colspec colname='Type' />
48 * <colspec colname='Possible values' />
49 * <colspec colname='Purpose' />
54 * <entry>GType</entry>
55 * <entry>Possible values</entry>
56 * <entry>Purpose</entry>
63 * <entry>G_TYPE_INT</entry>
65 * <entry>The application uses this field to specify which of the two methods
66 * specified in RFC 2833 to use. The value should be 0 for tones and 1 for
67 * named events. This element is only capable of generating tones.
71 * <entry>number</entry>
72 * <entry>G_TYPE_INT</entry>
74 * <entry>The event number.</entry>
77 * <entry>volume</entry>
78 * <entry>G_TYPE_INT</entry>
80 * <entry>This field describes the power level of the tone, expressed in dBm0
81 * after dropping the sign. Power levels range from 0 to -63 dBm0. The range of
82 * valid DTMF is from 0 to -36 dBm0. Can be omitted if start is set to FALSE.
86 * <entry>start</entry>
87 * <entry>G_TYPE_BOOLEAN</entry>
88 * <entry>True or False</entry>
89 * <entry>Whether the event is starting or ending.</entry>
92 * <entry>method</entry>
93 * <entry>G_TYPE_INT</entry>
95 * <entry>The method used for sending event, this element will react if this field
104 * <para>For example, the following code informs the pipeline (and in turn, the
105 * DTMFSrc element inside the pipeline) about the start of a DTMF named
106 * event '1' of volume -25 dBm0:
111 * structure = gst_structure_new ("dtmf-event",
112 * "type", G_TYPE_INT, 0,
113 * "number", G_TYPE_INT, 1,
114 * "volume", G_TYPE_INT, 25,
115 * "start", G_TYPE_BOOLEAN, TRUE, NULL);
117 * event = gst_event_new_custom (GST_EVENT_CUSTOM_UPSTREAM, structure);
118 * gst_element_send_event (pipeline, event);
134 # define M_PI 3.14159265358979323846 /* pi */
138 #include "gstdtmfsrc.h"
140 #define GST_TONE_DTMF_TYPE_EVENT 0
141 #define DEFAULT_PACKET_INTERVAL 50 /* ms */
142 #define MIN_PACKET_INTERVAL 10 /* ms */
143 #define MAX_PACKET_INTERVAL 50 /* ms */
144 #define SAMPLE_RATE 8000
145 #define SAMPLE_SIZE 16
150 #define MAX_VOLUME 36
154 typedef struct st_dtmf_key {
158 float high_frequency;
161 static const DTMF_KEY DTMF_KEYS[] = {
162 {"DTMF_KEY_EVENT_0", 0, 941, 1336},
163 {"DTMF_KEY_EVENT_1", 1, 697, 1209},
164 {"DTMF_KEY_EVENT_2", 2, 697, 1336},
165 {"DTMF_KEY_EVENT_3", 3, 697, 1477},
166 {"DTMF_KEY_EVENT_4", 4, 770, 1209},
167 {"DTMF_KEY_EVENT_5", 5, 770, 1336},
168 {"DTMF_KEY_EVENT_6", 6, 770, 1477},
169 {"DTMF_KEY_EVENT_7", 7, 852, 1209},
170 {"DTMF_KEY_EVENT_8", 8, 852, 1336},
171 {"DTMF_KEY_EVENT_9", 9, 852, 1477},
172 {"DTMF_KEY_EVENT_S", 10, 941, 1209},
173 {"DTMF_KEY_EVENT_P", 11, 941, 1477},
174 {"DTMF_KEY_EVENT_A", 12, 697, 1633},
175 {"DTMF_KEY_EVENT_B", 13, 770, 1633},
176 {"DTMF_KEY_EVENT_C", 14, 852, 1633},
177 {"DTMF_KEY_EVENT_D", 15, 941, 1633},
180 #define MAX_DTMF_EVENTS 16
183 DTMF_KEY_EVENT_1 = 1,
184 DTMF_KEY_EVENT_2 = 2,
185 DTMF_KEY_EVENT_3 = 3,
186 DTMF_KEY_EVENT_4 = 4,
187 DTMF_KEY_EVENT_5 = 5,
188 DTMF_KEY_EVENT_6 = 6,
189 DTMF_KEY_EVENT_7 = 7,
190 DTMF_KEY_EVENT_8 = 8,
191 DTMF_KEY_EVENT_9 = 9,
192 DTMF_KEY_EVENT_0 = 0,
193 DTMF_KEY_EVENT_STAR = 10,
194 DTMF_KEY_EVENT_POUND = 11,
195 DTMF_KEY_EVENT_A = 12,
196 DTMF_KEY_EVENT_B = 13,
197 DTMF_KEY_EVENT_C = 14,
198 DTMF_KEY_EVENT_D = 15,
201 /* elementfactory information */
202 static const GstElementDetails gst_dtmf_src_details =
203 GST_ELEMENT_DETAILS ("DTMF tone generator",
205 "Generates DTMF tones",
206 "Youness Alaoui <youness.alaoui@collabora.co.uk>");
208 GST_DEBUG_CATEGORY_STATIC (gst_dtmf_src_debug);
209 #define GST_CAT_DEFAULT gst_dtmf_src_debug
217 static GstStaticPadTemplate gst_dtmf_src_template =
218 GST_STATIC_PAD_TEMPLATE ("src",
221 GST_STATIC_CAPS ("audio/x-raw-int, "
224 "endianness = (int) 1234, "
225 "signed = (bool) true, "
226 "rate = (int) 8000, "
227 "channels = (int) 1")
230 static GstElementClass *parent_class = NULL;
232 static void gst_dtmf_src_base_init (gpointer g_class);
233 static void gst_dtmf_src_class_init (GstDTMFSrcClass * klass);
234 static void gst_dtmf_src_init (GstDTMFSrc * dtmfsrc, gpointer g_class);
235 static void gst_dtmf_src_finalize (GObject * object);
238 gst_dtmf_src_get_type (void)
240 static GType base_src_type = 0;
242 if (G_UNLIKELY (base_src_type == 0)) {
243 static const GTypeInfo base_src_info = {
244 sizeof (GstDTMFSrcClass),
245 (GBaseInitFunc) gst_dtmf_src_base_init,
247 (GClassInitFunc) gst_dtmf_src_class_init,
252 (GInstanceInitFunc) gst_dtmf_src_init,
255 base_src_type = g_type_register_static (GST_TYPE_ELEMENT,
256 "GstDTMFSrc", &base_src_info, 0);
258 return base_src_type;
261 static void gst_dtmf_src_set_property (GObject * object, guint prop_id,
262 const GValue * value, GParamSpec * pspec);
263 static void gst_dtmf_src_get_property (GObject * object, guint prop_id,
264 GValue * value, GParamSpec * pspec);
265 static gboolean gst_dtmf_src_handle_event (GstPad * pad, GstEvent * event);
266 static GstStateChangeReturn gst_dtmf_src_change_state (GstElement * element,
267 GstStateChange transition);
268 static void gst_dtmf_src_generate_tone(GstDTMFSrc *dtmfsrc, DTMF_KEY key, float duration,
270 static void gst_dtmf_src_push_next_tone_packet (GstDTMFSrc *dtmfsrc);
271 static void gst_dtmf_src_start (GstDTMFSrc *dtmfsrc, gint event_number,
273 static void gst_dtmf_src_stop (GstDTMFSrc *dtmfsrc);
276 gst_dtmf_src_base_init (gpointer g_class)
278 GstElementClass *element_class = GST_ELEMENT_CLASS (g_class);
280 GST_DEBUG_CATEGORY_INIT (gst_dtmf_src_debug,
281 "dtmfsrc", 0, "dtmfsrc element");
283 gst_element_class_add_pad_template (element_class,
284 gst_static_pad_template_get (&gst_dtmf_src_template));
286 gst_element_class_set_details (element_class, &gst_dtmf_src_details);
290 gst_dtmf_src_class_init (GstDTMFSrcClass * klass)
292 GObjectClass *gobject_class;
293 GstElementClass *gstelement_class;
295 gobject_class = G_OBJECT_CLASS (klass);
296 gstelement_class = GST_ELEMENT_CLASS (klass);
298 parent_class = g_type_class_peek_parent (klass);
300 gobject_class->finalize = GST_DEBUG_FUNCPTR (gst_dtmf_src_finalize);
301 gobject_class->set_property =
302 GST_DEBUG_FUNCPTR (gst_dtmf_src_set_property);
303 gobject_class->get_property =
304 GST_DEBUG_FUNCPTR (gst_dtmf_src_get_property);
306 g_object_class_install_property (G_OBJECT_CLASS (klass), PROP_INTERVAL,
307 g_param_spec_int ("interval", "Interval between tone packets",
308 "Interval in ms between two tone packets", MIN_PACKET_INTERVAL,
309 MAX_PACKET_INTERVAL, DEFAULT_PACKET_INTERVAL, G_PARAM_READWRITE));
311 gstelement_class->change_state =
312 GST_DEBUG_FUNCPTR (gst_dtmf_src_change_state);
316 gst_dtmf_src_init (GstDTMFSrc * dtmfsrc, gpointer g_class)
319 gst_pad_new_from_static_template (&gst_dtmf_src_template, "src");
320 GST_DEBUG_OBJECT (dtmfsrc, "adding src pad");
321 gst_element_add_pad (GST_ELEMENT (dtmfsrc), dtmfsrc->srcpad);
323 gst_pad_set_event_function (dtmfsrc->srcpad, gst_dtmf_src_handle_event);
325 dtmfsrc->interval = DEFAULT_PACKET_INTERVAL;
329 GST_DEBUG_OBJECT (dtmfsrc, "init done");
333 gst_dtmf_src_finalize (GObject * object)
337 dtmfsrc = GST_DTMF_SRC (object);
339 G_OBJECT_CLASS (parent_class)->finalize (object);
343 gst_dtmf_src_handle_dtmf_event (GstDTMFSrc *dtmfsrc,
344 const GstStructure * event_structure)
350 if (!gst_structure_get_int (event_structure, "type", &event_type) ||
351 !gst_structure_get_boolean (event_structure, "start", &start) ||
352 (start == TRUE && event_type != GST_TONE_DTMF_TYPE_EVENT))
355 if (gst_structure_get_int (event_structure, "method", &method)) {
365 if (!gst_structure_get_int (event_structure, "number", &event_number) ||
366 !gst_structure_get_int (event_structure, "volume", &event_volume))
369 GST_DEBUG_OBJECT (dtmfsrc, "Received start event %d with volume %d",
370 event_number, event_volume);
371 gst_dtmf_src_start (dtmfsrc, event_number, event_volume);
375 GST_DEBUG_OBJECT (dtmfsrc, "Received stop event");
376 gst_dtmf_src_stop (dtmfsrc);
385 gst_dtmf_src_handle_custom_upstream (GstDTMFSrc *dtmfsrc,
388 gboolean result = FALSE;
389 const GstStructure *structure;
391 if (GST_STATE (dtmfsrc) != GST_STATE_PLAYING) {
392 GST_DEBUG_OBJECT (dtmfsrc, "Received event while not in PLAYING state");
396 GST_DEBUG_OBJECT (dtmfsrc, "Received event is of our interest");
397 structure = gst_event_get_structure (event);
398 if (structure && gst_structure_has_name (structure, "dtmf-event"))
399 result = gst_dtmf_src_handle_dtmf_event (dtmfsrc, structure);
406 gst_dtmf_src_handle_event (GstPad * pad, GstEvent * event)
409 gboolean result = FALSE;
411 dtmfsrc = GST_DTMF_SRC (GST_PAD_PARENT (pad));
413 GST_DEBUG_OBJECT (dtmfsrc, "Received an event on the src pad");
414 switch (GST_EVENT_TYPE (event)) {
415 case GST_EVENT_CUSTOM_UPSTREAM:
417 result = gst_dtmf_src_handle_custom_upstream (dtmfsrc, event);
420 /* Ideally this element should not be flushed but let's handle the event
421 * just in case it is */
422 case GST_EVENT_FLUSH_START:
423 gst_dtmf_src_stop (dtmfsrc);
426 case GST_EVENT_FLUSH_STOP:
427 gst_segment_init (&dtmfsrc->segment, GST_FORMAT_UNDEFINED);
429 case GST_EVENT_NEWSEGMENT:
434 gint64 start, stop, position;
436 gst_event_parse_new_segment (event, &update, &rate, &fmt, &start,
438 gst_segment_set_newsegment (&dtmfsrc->segment, update, rate, fmt,
439 start, stop, position);
443 result = gst_pad_event_default (pad, event);
447 gst_event_unref (event);
452 gst_dtmf_src_set_property (GObject * object, guint prop_id,
453 const GValue * value, GParamSpec * pspec)
457 dtmfsrc = GST_DTMF_SRC (object);
461 dtmfsrc->interval = g_value_get_int (value);
464 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
470 gst_dtmf_src_get_property (GObject * object, guint prop_id, GValue * value,
475 dtmfsrc = GST_DTMF_SRC (object);
479 g_value_set_uint (value, dtmfsrc->interval);
482 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
488 gst_dtmf_src_set_stream_lock (GstDTMFSrc *dtmfsrc, gboolean lock)
491 GstStructure *structure;
493 structure = gst_structure_new ("stream-lock",
494 "lock", G_TYPE_BOOLEAN, lock, NULL);
496 event = gst_event_new_custom (GST_EVENT_CUSTOM_DOWNSTREAM_OOB, structure);
497 gst_pad_push_event (dtmfsrc->srcpad, event);
501 gst_dtmf_prepare_timestamps (GstDTMFSrc *dtmfsrc)
505 clock = GST_ELEMENT_CLOCK (dtmfsrc);
507 dtmfsrc->timestamp = gst_clock_get_time (GST_ELEMENT_CLOCK (dtmfsrc));
510 GST_ERROR_OBJECT (dtmfsrc, "No clock set for element %s",
511 GST_ELEMENT_NAME (dtmfsrc));
512 dtmfsrc->timestamp = GST_CLOCK_TIME_NONE;
517 gst_dtmf_src_start (GstDTMFSrc *dtmfsrc,
518 gint event_number, gint event_volume)
520 GstCaps * caps = gst_pad_get_pad_template_caps (dtmfsrc->srcpad);
522 dtmfsrc->event = CLAMP (event_number, MIN_EVENT, MAX_EVENT);
523 dtmfsrc->volume = CLAMP (event_volume, MIN_VOLUME, MAX_VOLUME);
525 gst_dtmf_prepare_timestamps (dtmfsrc);
527 /* Don't forget to get exclusive access to the stream */
528 gst_dtmf_src_set_stream_lock (dtmfsrc, TRUE);
530 if (!gst_pad_set_caps (dtmfsrc->srcpad, caps))
531 GST_ERROR_OBJECT (dtmfsrc,
532 "Failed to set caps %" GST_PTR_FORMAT " on src pad", caps);
534 GST_DEBUG_OBJECT (dtmfsrc,
535 "caps %" GST_PTR_FORMAT " set on src pad", caps);
538 if (!gst_pad_start_task (dtmfsrc->srcpad,
539 (GstTaskFunction) gst_dtmf_src_push_next_tone_packet, dtmfsrc)) {
540 GST_ERROR_OBJECT (dtmfsrc, "Failed to start task on src pad");
545 gst_dtmf_src_stop (GstDTMFSrc *dtmfsrc)
547 /* Don't forget to release the stream lock */
548 gst_dtmf_src_set_stream_lock (dtmfsrc, FALSE);
550 if (!gst_pad_pause_task (dtmfsrc->srcpad)) {
551 GST_ERROR_OBJECT (dtmfsrc, "Failed to pause task on src pad");
558 gst_dtmf_src_generate_tone(GstDTMFSrc *dtmfsrc, DTMF_KEY key, float duration, GstBuffer * buffer)
563 double amplitude, f1, f2;
565 /* Create a buffer for the tone */
566 tone_size = ((duration/1000)*SAMPLE_RATE*SAMPLE_SIZE*CHANNELS)/8;
567 GST_BUFFER_SIZE (buffer) = tone_size;
568 GST_BUFFER_MALLOCDATA (buffer) = g_malloc(tone_size);
569 GST_BUFFER_DATA (buffer) = GST_BUFFER_MALLOCDATA (buffer);
571 p = (gint16 *) GST_BUFFER_MALLOCDATA (buffer);
574 * For each sample point we calculate 'x' as the
575 * the amplitude value.
577 for (i = 0; i < (tone_size / (SAMPLE_SIZE/8)); i++) {
579 * We add the fundamental frequencies together.
581 f1 = sin(2 * M_PI * key.low_frequency * (dtmfsrc->sample / SAMPLE_RATE));
582 f2 = sin(2 * M_PI * key.high_frequency * (dtmfsrc->sample / SAMPLE_RATE));
584 amplitude = (f1 + f2) / 2;
586 /* Make the [-1:1] interval into a [-32767:32767] interval */
589 /* Store it in the data buffer */
590 *(p++) = (gint16) amplitude;
597 gst_dtmf_src_wait_for_buffer_ts (GstDTMFSrc *dtmfsrc, GstBuffer * buf)
601 clock = GST_ELEMENT_CLOCK (dtmfsrc);
604 GstClockReturn clock_ret;
606 clock_id = gst_clock_new_single_shot_id (clock, GST_BUFFER_TIMESTAMP (buf));
607 clock_ret = gst_clock_id_wait (clock_id, NULL);
608 if (clock_ret != GST_CLOCK_OK && clock_ret != GST_CLOCK_EARLY) {
609 GST_ERROR_OBJECT (dtmfsrc, "Failed to wait on clock %s",
610 GST_ELEMENT_NAME (clock));
612 gst_clock_id_unref (clock_id);
616 GST_ERROR_OBJECT (dtmfsrc, "No clock set for element %s",
617 GST_ELEMENT_NAME (dtmfsrc));
623 gst_dtmf_src_create_next_tone_packet (GstDTMFSrc *dtmfsrc)
625 GstBuffer *buf = NULL;
628 GST_DEBUG_OBJECT (dtmfsrc,
629 "Creating buffer for tone");
631 /* create buffer to hold the tone */
632 buf = gst_buffer_new ();
634 /* Generate the tone */
635 gst_dtmf_src_generate_tone(dtmfsrc, DTMF_KEYS[dtmfsrc->event], dtmfsrc->interval, buf);
638 /* timestamp and duration of GstBuffer */
639 GST_BUFFER_DURATION (buf) = dtmfsrc->interval * GST_MSECOND;
640 GST_BUFFER_TIMESTAMP (buf) = dtmfsrc->timestamp;
641 dtmfsrc->timestamp += GST_BUFFER_DURATION (buf) /2;
643 /* FIXME: Should we sync to clock ourselves or leave it to sink */
644 gst_dtmf_src_wait_for_buffer_ts (dtmfsrc, buf);
646 /* Set caps on the buffer before pushing it */
647 gst_buffer_set_caps (buf, GST_PAD_CAPS (dtmfsrc->srcpad));
653 gst_dtmf_src_push_next_tone_packet (GstDTMFSrc *dtmfsrc)
655 GstBuffer *buf = NULL;
658 buf = gst_dtmf_src_create_next_tone_packet (dtmfsrc);
662 GST_DEBUG_OBJECT (dtmfsrc,
663 "pushing buffer on src pad of size %d", GST_BUFFER_SIZE (buf));
664 ret = gst_pad_push (dtmfsrc->srcpad, buf);
665 if (ret != GST_FLOW_OK) {
666 GST_ERROR_OBJECT (dtmfsrc, "Failed to push buffer on src pad", GST_BUFFER_SIZE (buf));
669 gst_buffer_unref(buf);
670 GST_DEBUG_OBJECT (dtmfsrc, "pushed DTMF tone on src pad");
674 static GstStateChangeReturn
675 gst_dtmf_src_change_state (GstElement * element, GstStateChange transition)
678 GstStateChangeReturn result;
679 gboolean no_preroll = FALSE;
681 dtmfsrc = GST_DTMF_SRC (element);
683 switch (transition) {
684 case GST_STATE_CHANGE_READY_TO_PAUSED:
685 gst_segment_init (&dtmfsrc->segment, GST_FORMAT_UNDEFINED);
686 /* Indicate that we don't do PRE_ROLL */
689 case GST_STATE_CHANGE_PAUSED_TO_PLAYING:
690 /* gst_dtmf_src_start (dtmfsrc, 6, 30); */
697 GST_ELEMENT_CLASS (parent_class)->change_state (element,
698 transition)) == GST_STATE_CHANGE_FAILURE)
701 switch (transition) {
702 case GST_STATE_CHANGE_PLAYING_TO_PAUSED:
703 /* Indicate that we don't do PRE_ROLL */
704 /* gst_dtmf_src_stop (dtmfsrc); */
711 if (no_preroll && result == GST_STATE_CHANGE_SUCCESS)
712 result = GST_STATE_CHANGE_NO_PREROLL;
719 GST_ERROR_OBJECT (dtmfsrc, "parent failed state change");
725 gst_dtmf_src_plugin_init (GstPlugin * plugin)
727 return gst_element_register (plugin, "dtmfsrc",
728 GST_RANK_NONE, GST_TYPE_DTMF_SRC);