dsp_process was enhanced to work with alaw and ulaw in addition to slin.
[asterisk/asterisk.git] / include / asterisk / dsp.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 1999 - 2005, Digium, Inc.
5  *
6  * Mark Spencer <markster@digium.com>
7  *
8  * See http://www.asterisk.org for more information about
9  * the Asterisk project. Please do not directly contact
10  * any of the maintainers of this project for assistance;
11  * the project provides a web site, mailing lists and IRC
12  * channels for your use.
13  *
14  * This program is free software, distributed under the terms of
15  * the GNU General Public License Version 2. See the LICENSE file
16  * at the top of the source tree.
17  */
18
19 /*! \file
20  * \brief Convenient Signal Processing routines
21  */
22
23 #ifndef _ASTERISK_DSP_H
24 #define _ASTERISK_DSP_H
25
26 #define DSP_FEATURE_SILENCE_SUPPRESS    (1 << 0)
27 #define DSP_FEATURE_BUSY_DETECT         (1 << 1)
28 #define DSP_FEATURE_DIGIT_DETECT        (1 << 3)
29 #define DSP_FEATURE_FAX_DETECT          (1 << 4)
30
31 #define DSP_DIGITMODE_DTMF                      0                               /*!< Detect DTMF digits */
32 #define DSP_DIGITMODE_MF                        1                               /*!< Detect MF digits */
33
34 #define DSP_DIGITMODE_NOQUELCH          (1 << 8)                /*!< Do not quelch DTMF from in-band */
35 #define DSP_DIGITMODE_MUTECONF          (1 << 9)                /*!< Mute conference */
36 #define DSP_DIGITMODE_MUTEMAX           (1 << 10)               /*!< Delay audio by a frame to try to extra quelch */
37 #define DSP_DIGITMODE_RELAXDTMF         (1 << 11)               /*!< "Radio" mode (relaxed DTMF) */
38
39 #define DSP_PROGRESS_TALK               (1 << 16)               /*!< Enable talk detection */
40 #define DSP_PROGRESS_RINGING            (1 << 17)               /*!< Enable calling tone detection */
41 #define DSP_PROGRESS_BUSY               (1 << 18)               /*!< Enable busy tone detection */
42 #define DSP_PROGRESS_CONGESTION         (1 << 19)               /*!< Enable congestion tone detection */
43 #define DSP_FEATURE_CALL_PROGRESS       (DSP_PROGRESS_TALK | DSP_PROGRESS_RINGING | DSP_PROGRESS_BUSY | DSP_PROGRESS_CONGESTION)
44 #define DSP_FEATURE_WAITDIALTONE        (1 << 20)               /*!< Enable dial tone detection */
45
46 #define DSP_FAXMODE_DETECT_CNG          (1 << 0)
47 #define DSP_FAXMODE_DETECT_CED          (1 << 1)
48 #define DSP_FAXMODE_DETECT_V21          (1 << 2)
49 #define DSP_FAXMODE_DETECT_SQUELCH      (1 << 3)
50 #define DSP_FAXMODE_DETECT_ALL  (DSP_FAXMODE_DETECT_CNG | DSP_FAXMODE_DETECT_CED | DSP_FAXMODE_DETECT_V21)
51
52 #define DSP_TONE_STATE_SILENCE  0
53 #define DSP_TONE_STATE_RINGING  1
54 #define DSP_TONE_STATE_DIALTONE 2
55 #define DSP_TONE_STATE_TALKING  3
56 #define DSP_TONE_STATE_BUSY     4
57 #define DSP_TONE_STATE_SPECIAL1 5
58 #define DSP_TONE_STATE_SPECIAL2 6
59 #define DSP_TONE_STATE_SPECIAL3 7
60 #define DSP_TONE_STATE_HUNGUP   8
61
62 struct ast_dsp;
63
64 struct ast_dsp_busy_pattern {
65         /*! Number of elements. */
66         int length;
67         /*! Pattern elements in on/off time durations. */
68         int pattern[4];
69 };
70
71 enum threshold {
72         /* Array offsets */
73         THRESHOLD_SILENCE = 0,
74         /* Always the last */
75         THRESHOLD_MAX = 1,
76 };
77
78 /*! \brief Allocates a new dsp with a specific internal sample rate used
79  * during processing. */
80 struct ast_dsp *ast_dsp_new_with_rate(unsigned int sample_rate);
81
82 /*! \brief Allocates a new dsp, assumes 8khz for internal sample rate */
83 struct ast_dsp *ast_dsp_new(void);
84
85 void ast_dsp_free(struct ast_dsp *dsp);
86
87 /*! \brief Retrieve the sample rate this DSP structure was
88  * created with */
89 unsigned int ast_dsp_get_sample_rate(const struct ast_dsp *dsp);
90
91 /*! \brief Set threshold value for silence */
92 void ast_dsp_set_threshold(struct ast_dsp *dsp, int threshold);
93
94 /*! \brief Set number of required cadences for busy */
95 void ast_dsp_set_busy_count(struct ast_dsp *dsp, int cadences);
96
97 /*! \brief Set expected lengths of the busy tone */
98 void ast_dsp_set_busy_pattern(struct ast_dsp *dsp, const struct ast_dsp_busy_pattern *cadence);
99
100 /*! \brief Scans for progress indication in audio */
101 int ast_dsp_call_progress(struct ast_dsp *dsp, struct ast_frame *inf);
102
103 /*! \brief Set zone for doing progress detection */
104 int ast_dsp_set_call_progress_zone(struct ast_dsp *dsp, char *zone);
105
106 /*! \brief Return AST_FRAME_NULL frames when there is silence, AST_FRAME_BUSY on
107    busies, and call progress, all dependent upon which features are enabled */
108 struct ast_frame *ast_dsp_process(struct ast_channel *chan, struct ast_dsp *dsp, struct ast_frame *inf);
109
110 /*! \brief Return non-zero if this is silence.  Updates "totalsilence" with the total
111    number of seconds of silence  */
112 int ast_dsp_silence(struct ast_dsp *dsp, struct ast_frame *f, int *totalsilence);
113
114 /*! \brief Return non-zero if this is silence.  Updates "totalsilence" with the total
115    number of seconds of silence. Returns the average energy of the samples in the frame
116    in frames_energy variable. */
117 int ast_dsp_silence_with_energy(struct ast_dsp *dsp, struct ast_frame *f, int *totalsilence, int *frames_energy);
118
119 /*!
120  * \brief Return non-zero if this is noise.  Updates "totalnoise" with the total
121  * number of seconds of noise
122  * \since 1.6.1
123  */
124 int ast_dsp_noise(struct ast_dsp *dsp, struct ast_frame *f, int *totalnoise);
125
126 /*! \brief Return non-zero if historically this should be a busy, request that
127   ast_dsp_silence has already been called */
128 int ast_dsp_busydetect(struct ast_dsp *dsp);
129
130 /*! \brief Return non-zero if DTMF hit was found */
131 int ast_dsp_digitdetect(struct ast_dsp *dsp, struct ast_frame *f);
132
133 /*! \brief Reset total silence count */
134 void ast_dsp_reset(struct ast_dsp *dsp);
135
136 /*! \brief Reset DTMF detector */
137 void ast_dsp_digitreset(struct ast_dsp *dsp);
138
139 /*! \brief Select feature set */
140 void ast_dsp_set_features(struct ast_dsp *dsp, int features);
141
142 /*! \brief Get pending DTMF/MF digits */
143 int ast_dsp_getdigits(struct ast_dsp *dsp, char *buf, int max);
144
145 /*! \brief Set digit mode
146  * \version 1.6.1 renamed from ast_dsp_digitmode to ast_dsp_set_digitmode
147  */
148 int ast_dsp_set_digitmode(struct ast_dsp *dsp, int digitmode);
149
150 /*! \brief Set fax mode */
151 int ast_dsp_set_faxmode(struct ast_dsp *dsp, int faxmode);
152
153 /*!
154  * \brief Returns true if DSP code was muting any fragment of the last processed frame.
155  * Muting (squelching) happens when DSP code removes DTMF/MF/generic tones from the audio
156  * \since 1.6.1
157  */
158 int ast_dsp_was_muted(struct ast_dsp *dsp);
159
160 /*! \brief Get tstate (Tone State) */
161 int ast_dsp_get_tstate(struct ast_dsp *dsp);
162
163 /*! \brief Get tcount (Threshold counter) */
164 int ast_dsp_get_tcount(struct ast_dsp *dsp);
165
166 /*!
167  * \brief Get silence threshold from dsp.conf
168  * \since 1.6.1
169  */
170 int ast_dsp_get_threshold_from_settings(enum threshold which);
171
172 /*!
173  * \brief Reloads dsp settings from dsp.conf
174  * \since 1.6.1
175  */
176 int ast_dsp_reload(void);
177
178 /*!
179  * \brief Load dsp settings from dsp.conf
180  * \since 1.6.1
181  */
182 int ast_dsp_init(void);
183
184 #endif /* _ASTERISK_DSP_H */