Document rtpdtmfdepay a bit
[platform/upstream/gstreamer.git] / gst / dtmf / gstrtpdtmfdepay.c
1 /* GstRtpDtmfDepay
2  *
3  * Copyright (C) 2008 Collabora Limited
4  * Copyright (C) 2008 Nokia Corporation
5  *   Contact: Youness Alaoui <youness.alaoui@collabora.co.uk>
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Library General Public
9  * License as published by the Free Software Foundation; either
10  * version 2 of the License, or (at your option) any later version.
11  *
12  * This library is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15  * Library General Public License for more details.
16  *
17  * You should have received a copy of the GNU Library General Public
18  * License along with this library; if not, write to the
19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20  * Boston, MA 02111-1307, USA.
21  */
22 /**
23  * SECTION:element-rtpdtmfdepay
24  * @short_description: Transforms RFC 4733/2833 RTP dtmf packets into sound
25  * @see_also: rtpdtmfsrc, rtpdtmfmux
26  *
27  * This element takes RTP DTMF packets and produces sound. It also emits a
28  * message on the #GstBus.
29  *
30  * The message is called "dtmf-event" and has the following fields
31  * <informaltable>
32  * <tgroup cols='4'>
33  * <colspec colname='Name' />
34  * <colspec colname='Type' />
35  * <colspec colname='Possible values' />
36  * <colspec colname='Purpose' />
37  * <thead>
38  * <row>
39  * <entry>Name</entry>
40  * <entry>GType</entry>
41  * <entry>Possible values</entry>
42  * <entry>Purpose</entry>
43  * </row>
44  * </thead>
45  * <tbody>
46  * <row>
47  * <entry></entry>
48  * <entry>G_TYPE_INT</entry>
49  * <entry>0-1</entry>
50  * <entry>Which of the two methods
51  * specified in RFC 2833 to use. The value should be 0 for tones and 1 for
52  * named events. Tones are specified by their frequencies and events are specied
53  * by their number. This element currently only recognizes events.
54  * Do not confuse with "method" which specified the output.
55  * </entry>
56  * </row>
57  * <row>
58  * <entry>number</entry>
59  * <entry>G_TYPE_INT</entry>
60  * <entry>0-16</entry>
61  * <entry>The event number.</entry>
62  * </row>
63  * <row>
64  * <entry>volume</entry>
65  * <entry>G_TYPE_INT</entry>
66  * <entry>0-36</entry>
67  * <entry>This field describes the power level of the tone, expressed in dBm0
68  * after dropping the sign. Power levels range from 0 to -63 dBm0. The range of
69  * valid DTMF is from 0 to -36 dBm0.
70  * </entry>
71  * </row>
72  * <row>
73  * <entry>method</entry>
74  * <entry>G_TYPE_INT</entry>
75  * <entry>1</entry>
76  * <entry>This field will always been 1 (ie RTP event) from this element.
77  * </entry>
78  * </row>
79  * </tbody>
80  * </tgroup>
81  * </informaltable>
82  */
83
84 #ifdef HAVE_CONFIG_H
85 #  include "config.h"
86 #endif
87
88 #include <string.h>
89 #include <math.h>
90
91 #include <gst/rtp/gstrtpbuffer.h>
92 #include "gstrtpdtmfdepay.h"
93
94 #ifndef M_PI
95 # define M_PI           3.14159265358979323846  /* pi */
96 #endif
97
98
99 #define DEFAULT_PACKET_INTERVAL  50     /* ms */
100 #define MIN_PACKET_INTERVAL      10     /* ms */
101 #define MAX_PACKET_INTERVAL      50     /* ms */
102 #define SAMPLE_RATE              8000
103 #define SAMPLE_SIZE              16
104 #define CHANNELS                 1
105 #define MIN_EVENT                0
106 #define MAX_EVENT                16
107 #define MIN_VOLUME               0
108 #define MAX_VOLUME               36
109 #define MIN_INTER_DIGIT_INTERVAL 100
110 #define MIN_PULSE_DURATION       250
111 #define MIN_DUTY_CYCLE           (MIN_INTER_DIGIT_INTERVAL + MIN_PULSE_DURATION)
112
113 #define MIN_UNIT_TIME            0
114 #define MAX_UNIT_TIME            1000
115 #define DEFAULT_UNIT_TIME        0
116
117 #define DEFAULT_MAX_DURATION     0
118
119 typedef struct st_dtmf_key
120 {
121   char *event_name;
122   int event_encoding;
123   float low_frequency;
124   float high_frequency;
125 } DTMF_KEY;
126
127 static const DTMF_KEY DTMF_KEYS[] = {
128   {"DTMF_KEY_EVENT_0", 0, 941, 1336},
129   {"DTMF_KEY_EVENT_1", 1, 697, 1209},
130   {"DTMF_KEY_EVENT_2", 2, 697, 1336},
131   {"DTMF_KEY_EVENT_3", 3, 697, 1477},
132   {"DTMF_KEY_EVENT_4", 4, 770, 1209},
133   {"DTMF_KEY_EVENT_5", 5, 770, 1336},
134   {"DTMF_KEY_EVENT_6", 6, 770, 1477},
135   {"DTMF_KEY_EVENT_7", 7, 852, 1209},
136   {"DTMF_KEY_EVENT_8", 8, 852, 1336},
137   {"DTMF_KEY_EVENT_9", 9, 852, 1477},
138   {"DTMF_KEY_EVENT_S", 10, 941, 1209},
139   {"DTMF_KEY_EVENT_P", 11, 941, 1477},
140   {"DTMF_KEY_EVENT_A", 12, 697, 1633},
141   {"DTMF_KEY_EVENT_B", 13, 770, 1633},
142   {"DTMF_KEY_EVENT_C", 14, 852, 1633},
143   {"DTMF_KEY_EVENT_D", 15, 941, 1633},
144 };
145
146 #define MAX_DTMF_EVENTS 16
147
148 enum
149 {
150   DTMF_KEY_EVENT_1 = 1,
151   DTMF_KEY_EVENT_2 = 2,
152   DTMF_KEY_EVENT_3 = 3,
153   DTMF_KEY_EVENT_4 = 4,
154   DTMF_KEY_EVENT_5 = 5,
155   DTMF_KEY_EVENT_6 = 6,
156   DTMF_KEY_EVENT_7 = 7,
157   DTMF_KEY_EVENT_8 = 8,
158   DTMF_KEY_EVENT_9 = 9,
159   DTMF_KEY_EVENT_0 = 0,
160   DTMF_KEY_EVENT_STAR = 10,
161   DTMF_KEY_EVENT_POUND = 11,
162   DTMF_KEY_EVENT_A = 12,
163   DTMF_KEY_EVENT_B = 13,
164   DTMF_KEY_EVENT_C = 14,
165   DTMF_KEY_EVENT_D = 15,
166 };
167
168 /* elementfactory information */
169 static const GstElementDetails gst_rtp_dtmfdepay_details =
170 GST_ELEMENT_DETAILS ("RTP DTMF packet depayloader",
171     "Codec/Depayloader/Network",
172     "Generates DTMF Sound from telephone-event RTP packets",
173     "Youness Alaoui <youness.alaoui@collabora.co.uk>");
174
175 GST_DEBUG_CATEGORY_STATIC (gst_rtp_dtmf_depay_debug);
176 #define GST_CAT_DEFAULT gst_rtp_dtmf_depay_debug
177
178 enum
179 {
180
181
182   /* FILL ME */
183   LAST_SIGNAL
184 };
185
186 enum
187 {
188   PROP_0,
189   PROP_UNIT_TIME,
190   PROP_MAX_DURATION
191 };
192
193 enum
194 {
195   ARG_0
196 };
197
198 static GstStaticPadTemplate gst_rtp_dtmf_depay_src_template =
199 GST_STATIC_PAD_TEMPLATE ("src",
200     GST_PAD_SRC,
201     GST_PAD_ALWAYS,
202     GST_STATIC_CAPS ("audio/x-raw-int, "
203         "width = (int) 16, "
204         "depth = (int) 16, "
205         "endianness = (int) " G_STRINGIFY (G_BYTE_ORDER) ", "
206         "signed = (boolean) true, "
207         "rate = (int) [0, MAX], " "channels = (int) 1")
208     );
209
210 static GstStaticPadTemplate gst_rtp_dtmf_depay_sink_template =
211 GST_STATIC_PAD_TEMPLATE ("sink",
212     GST_PAD_SINK,
213     GST_PAD_ALWAYS,
214     GST_STATIC_CAPS ("application/x-rtp, "
215         "media = (string) \"audio\", "
216         "payload = (int) " GST_RTP_PAYLOAD_DYNAMIC_STRING ", "
217         "clock-rate = (int) [ 0, MAX ], "
218         "encoding-name = (string) \"TELEPHONE-EVENT\"")
219     );
220
221 GST_BOILERPLATE (GstRtpDTMFDepay, gst_rtp_dtmf_depay, GstBaseRTPDepayload,
222     GST_TYPE_BASE_RTP_DEPAYLOAD);
223
224 static void gst_rtp_dtmf_depay_set_property (GObject * object, guint prop_id,
225     const GValue * value, GParamSpec * pspec);
226 static void gst_rtp_dtmf_depay_get_property (GObject * object, guint prop_id,
227     GValue * value, GParamSpec * pspec);
228 static GstBuffer *gst_rtp_dtmf_depay_process (GstBaseRTPDepayload * depayload,
229     GstBuffer * buf);
230 gboolean gst_rtp_dtmf_depay_setcaps (GstBaseRTPDepayload * filter,
231     GstCaps * caps);
232
233 static void
234 gst_rtp_dtmf_depay_base_init (gpointer klass)
235 {
236   GstElementClass *element_class = GST_ELEMENT_CLASS (klass);
237
238   gst_element_class_add_pad_template (element_class,
239       gst_static_pad_template_get (&gst_rtp_dtmf_depay_src_template));
240   gst_element_class_add_pad_template (element_class,
241       gst_static_pad_template_get (&gst_rtp_dtmf_depay_sink_template));
242
243
244   GST_DEBUG_CATEGORY_INIT (gst_rtp_dtmf_depay_debug,
245       "rtpdtmfdepay", 0, "rtpdtmfdepay element");
246   gst_element_class_set_details (element_class, &gst_rtp_dtmfdepay_details);
247 }
248
249 static void
250 gst_rtp_dtmf_depay_class_init (GstRtpDTMFDepayClass * klass)
251 {
252   GObjectClass *gobject_class;
253   GstElementClass *gstelement_class;
254   GstBaseRTPDepayloadClass *gstbasertpdepayload_class;
255
256   gobject_class = (GObjectClass *) klass;
257   gstelement_class = (GstElementClass *) klass;
258   gstbasertpdepayload_class = (GstBaseRTPDepayloadClass *) klass;
259
260   parent_class = g_type_class_peek_parent (klass);
261
262   gobject_class->set_property =
263       GST_DEBUG_FUNCPTR (gst_rtp_dtmf_depay_set_property);
264   gobject_class->get_property =
265       GST_DEBUG_FUNCPTR (gst_rtp_dtmf_depay_get_property);
266
267   g_object_class_install_property (G_OBJECT_CLASS (klass), PROP_UNIT_TIME,
268       g_param_spec_uint ("unit-time", "Duration unittime",
269           "The smallest unit (ms) the duration must be a multiple of (0 disables it)",
270           MIN_UNIT_TIME, MAX_UNIT_TIME, DEFAULT_UNIT_TIME, G_PARAM_READWRITE));
271
272   g_object_class_install_property (G_OBJECT_CLASS (klass), PROP_MAX_DURATION,
273       g_param_spec_uint ("max-duration", "Maximum duration",
274           "The maxumimum duration (ms) of the outgoing soundpacket. "
275           "(0 = no limit)", 0, G_MAXUINT, DEFAULT_MAX_DURATION,
276           G_PARAM_READWRITE));
277
278   gstbasertpdepayload_class->process =
279       GST_DEBUG_FUNCPTR (gst_rtp_dtmf_depay_process);
280   gstbasertpdepayload_class->set_caps =
281       GST_DEBUG_FUNCPTR (gst_rtp_dtmf_depay_setcaps);
282
283 }
284
285 static void
286 gst_rtp_dtmf_depay_init (GstRtpDTMFDepay * rtpdtmfdepay,
287     GstRtpDTMFDepayClass * klass)
288 {
289   rtpdtmfdepay->unit_time = DEFAULT_UNIT_TIME;
290 }
291
292 static void
293 gst_rtp_dtmf_depay_set_property (GObject * object, guint prop_id,
294     const GValue * value, GParamSpec * pspec)
295 {
296   GstRtpDTMFDepay *rtpdtmfdepay;
297
298   rtpdtmfdepay = GST_RTP_DTMF_DEPAY (object);
299
300   switch (prop_id) {
301     case PROP_UNIT_TIME:
302       rtpdtmfdepay->unit_time = g_value_get_uint (value);
303       break;
304     case PROP_MAX_DURATION:
305       rtpdtmfdepay->max_duration = g_value_get_uint (value);
306       break;
307     default:
308       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
309       break;
310   }
311 }
312
313 static void
314 gst_rtp_dtmf_depay_get_property (GObject * object, guint prop_id,
315     GValue * value, GParamSpec * pspec)
316 {
317   GstRtpDTMFDepay *rtpdtmfdepay;
318
319   rtpdtmfdepay = GST_RTP_DTMF_DEPAY (object);
320
321   switch (prop_id) {
322     case PROP_UNIT_TIME:
323       g_value_set_uint (value, rtpdtmfdepay->unit_time);
324       break;
325     case PROP_MAX_DURATION:
326       g_value_set_uint (value, rtpdtmfdepay->max_duration);
327       break;
328     default:
329       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
330       break;
331   }
332 }
333
334 gboolean
335 gst_rtp_dtmf_depay_setcaps (GstBaseRTPDepayload * filter, GstCaps * caps)
336 {
337   GstCaps *srccaps;
338   GstStructure *structure = gst_caps_get_structure (caps, 0);
339   gint clock_rate = 8000;       /* default */
340
341   gst_structure_get_int (structure, "clock-rate", &clock_rate);
342   filter->clock_rate = clock_rate;
343
344   srccaps = gst_caps_new_simple ("audio/x-raw-int",
345       "width", G_TYPE_INT, 16,
346       "depth", G_TYPE_INT, 16,
347       "endianness", G_TYPE_INT, G_BYTE_ORDER,
348       "signed", G_TYPE_BOOLEAN, TRUE,
349       "channels", G_TYPE_INT, 1, "rate", G_TYPE_INT, clock_rate, NULL);
350   gst_pad_set_caps (GST_BASE_RTP_DEPAYLOAD_SRCPAD (filter), srccaps);
351   gst_caps_unref (srccaps);
352
353   return TRUE;
354 }
355
356 static void
357 gst_dtmf_src_generate_tone (GstRtpDTMFDepay * rtpdtmfdepay,
358     GstRTPDTMFPayload payload, GstBuffer * buffer)
359 {
360   gint16 *p;
361   gint tone_size;
362   double i = 0;
363   double amplitude, f1, f2;
364   double volume_factor;
365   DTMF_KEY key = DTMF_KEYS[payload.event];
366   guint32 clock_rate = 8000 /* default */ ;
367   GstBaseRTPDepayload *depayload = GST_BASE_RTP_DEPAYLOAD (rtpdtmfdepay);
368   gint volume;
369
370   clock_rate = depayload->clock_rate;
371
372   /* Create a buffer for the tone */
373   tone_size = (payload.duration * SAMPLE_SIZE * CHANNELS) / 8;
374   GST_BUFFER_SIZE (buffer) = tone_size;
375   GST_BUFFER_MALLOCDATA (buffer) = g_malloc (tone_size);
376   GST_BUFFER_DATA (buffer) = GST_BUFFER_MALLOCDATA (buffer);
377   GST_BUFFER_DURATION (buffer) = payload.duration * GST_SECOND / clock_rate;
378   volume = payload.volume;
379
380   p = (gint16 *) GST_BUFFER_MALLOCDATA (buffer);
381
382   volume_factor = pow (10, (-volume) / 20);
383
384   /*
385    * For each sample point we calculate 'x' as the
386    * the amplitude value.
387    */
388   for (i = 0; i < (tone_size / (SAMPLE_SIZE / 8)); i++) {
389     /*
390      * We add the fundamental frequencies together.
391      */
392     f1 = sin (2 * M_PI * key.low_frequency * (rtpdtmfdepay->sample /
393             clock_rate));
394     f2 = sin (2 * M_PI * key.high_frequency * (rtpdtmfdepay->sample /
395             clock_rate));
396
397     amplitude = (f1 + f2) / 2;
398
399     /* Adjust the volume */
400     amplitude *= volume_factor;
401
402     /* Make the [-1:1] interval into a [-32767:32767] interval */
403     amplitude *= 32767;
404
405     /* Store it in the data buffer */
406     *(p++) = (gint16) amplitude;
407
408     (rtpdtmfdepay->sample)++;
409   }
410 }
411
412
413 static GstBuffer *
414 gst_rtp_dtmf_depay_process (GstBaseRTPDepayload * depayload, GstBuffer * buf)
415 {
416
417   GstRtpDTMFDepay *rtpdtmfdepay = NULL;
418   GstBuffer *outbuf = NULL;
419   gint payload_len;
420   guint8 *payload = NULL;
421   guint32 timestamp;
422   GstRTPDTMFPayload dtmf_payload;
423   gboolean marker;
424   GstStructure *structure = NULL;
425   GstMessage *dtmf_message = NULL;
426
427   rtpdtmfdepay = GST_RTP_DTMF_DEPAY (depayload);
428
429   if (!gst_rtp_buffer_validate (buf))
430     goto bad_packet;
431
432   payload_len = gst_rtp_buffer_get_payload_len (buf);
433   payload = gst_rtp_buffer_get_payload (buf);
434
435   if (payload_len != sizeof (GstRTPDTMFPayload))
436     goto bad_packet;
437
438   memcpy (&dtmf_payload, payload, sizeof (GstRTPDTMFPayload));
439
440   if (dtmf_payload.event > MAX_EVENT)
441     goto bad_packet;
442
443
444   marker = gst_rtp_buffer_get_marker (buf);
445
446   timestamp = gst_rtp_buffer_get_timestamp (buf);
447
448   dtmf_payload.duration = g_ntohs (dtmf_payload.duration);
449
450   /* clip to whole units of unit_time */
451   if (rtpdtmfdepay->unit_time) {
452     guint unit_time_clock =
453         (rtpdtmfdepay->unit_time * depayload->clock_rate) / 1000;
454     if (dtmf_payload.duration % unit_time_clock) {
455       /* Make sure we don't overflow the duration */
456       if (dtmf_payload.duration < G_MAXUINT16 - unit_time_clock)
457         dtmf_payload.duration += unit_time_clock -
458             (dtmf_payload.duration % unit_time_clock);
459       else
460         dtmf_payload.duration -= dtmf_payload.duration % unit_time_clock;
461     }
462   }
463
464   /* clip to max duration */
465   if (rtpdtmfdepay->max_duration) {
466     guint max_duration_clock =
467         (rtpdtmfdepay->max_duration * depayload->clock_rate) / 1000;
468
469     if (max_duration_clock < G_MAXUINT16 &&
470         dtmf_payload.duration > max_duration_clock)
471       dtmf_payload.duration = max_duration_clock;
472   }
473
474   GST_DEBUG_OBJECT (depayload, "Received new RTP DTMF packet : "
475       "marker=%d - timestamp=%u - event=%d - duration=%d",
476       marker, timestamp, dtmf_payload.event, dtmf_payload.duration);
477
478   GST_DEBUG_OBJECT (depayload,
479       "Previous information : timestamp=%u - duration=%d",
480       rtpdtmfdepay->previous_ts, rtpdtmfdepay->previous_duration);
481
482   /* First packet */
483   if (marker || rtpdtmfdepay->previous_ts != timestamp) {
484     rtpdtmfdepay->sample = 0;
485     rtpdtmfdepay->previous_ts = timestamp;
486     rtpdtmfdepay->previous_duration = dtmf_payload.duration;
487     rtpdtmfdepay->first_gst_ts = GST_BUFFER_TIMESTAMP (buf);
488
489     structure = gst_structure_new ("dtmf-event",
490         "number", G_TYPE_INT, dtmf_payload.event,
491         "volume", G_TYPE_INT, dtmf_payload.volume,
492         "type", G_TYPE_INT, 1, "method", G_TYPE_INT, 1, NULL);
493     if (structure) {
494       dtmf_message =
495           gst_message_new_element (GST_OBJECT (depayload), structure);
496       if (dtmf_message) {
497         if (!gst_element_post_message (GST_ELEMENT (depayload), dtmf_message)) {
498           GST_ERROR_OBJECT (depayload,
499               "Unable to send dtmf-event message to bus");
500         }
501       } else {
502         GST_ERROR_OBJECT (depayload, "Unable to create dtmf-event message");
503       }
504     } else {
505       GST_ERROR_OBJECT (depayload, "Unable to create dtmf-event structure");
506     }
507   } else {
508     guint16 duration = dtmf_payload.duration;
509     dtmf_payload.duration -= rtpdtmfdepay->previous_duration;
510     /* If late buffer, ignore */
511     if (duration > rtpdtmfdepay->previous_duration)
512       rtpdtmfdepay->previous_duration = duration;
513   }
514
515   GST_DEBUG_OBJECT (depayload, "new previous duration : %d - new duration : %d"
516       " - diff  : %d - clock rate : %d - timestamp : %llu",
517       rtpdtmfdepay->previous_duration, dtmf_payload.duration,
518       (rtpdtmfdepay->previous_duration - dtmf_payload.duration),
519       depayload->clock_rate, GST_BUFFER_TIMESTAMP (buf));
520
521   /* If late or duplicate packet (like the redundant end packet). Ignore */
522   if (dtmf_payload.duration > 0) {
523     outbuf = gst_buffer_new ();
524     gst_dtmf_src_generate_tone (rtpdtmfdepay, dtmf_payload, outbuf);
525
526
527     GST_BUFFER_TIMESTAMP (outbuf) = rtpdtmfdepay->first_gst_ts +
528         (rtpdtmfdepay->previous_duration - dtmf_payload.duration) *
529         GST_SECOND / depayload->clock_rate;
530     GST_BUFFER_OFFSET (outbuf) =
531         (rtpdtmfdepay->previous_duration - dtmf_payload.duration) *
532         GST_SECOND / depayload->clock_rate;
533     GST_BUFFER_OFFSET_END (outbuf) = rtpdtmfdepay->previous_duration *
534         GST_SECOND / depayload->clock_rate;
535
536     GST_DEBUG_OBJECT (depayload, "timestamp : %llu - time %" GST_TIME_FORMAT,
537         GST_BUFFER_TIMESTAMP (buf), GST_TIME_ARGS (GST_BUFFER_TIMESTAMP (buf)));
538
539   }
540
541   return outbuf;
542
543
544 bad_packet:
545   GST_ELEMENT_WARNING (rtpdtmfdepay, STREAM, DECODE,
546       ("Packet did not validate"), (NULL));
547   return NULL;
548 }
549
550 gboolean
551 gst_rtp_dtmf_depay_plugin_init (GstPlugin * plugin)
552 {
553   return gst_element_register (plugin, "rtpdtmfdepay",
554       GST_RANK_MARGINAL, GST_TYPE_RTP_DTMF_DEPAY);
555 }