Binaural synthesis (confbridge): Adds binaural synthesis to bridge_softmix.
[asterisk/asterisk.git] / bridges / bridge_softmix / include / bridge_softmix_internal.h
1 /*
2  * Asterisk -- An open source telephony toolkit.
3  *
4  * Copyright (C) 2011, Digium, Inc.
5  *
6  * Joshua Colp <jcolp@digium.com>
7  * David Vossel <dvossel@digium.com>
8  *
9  * See http://www.asterisk.org for more information about
10  * the Asterisk project. Please do not directly contact
11  * any of the maintainers of this project for assistance;
12  * the project provides a web site, mailing lists and IRC
13  * channels for your use.
14  *
15  * This program is free software, distributed under the terms of
16  * the GNU General Public License Version 2. See the LICENSE file
17  * at the top of the source tree.
18  */
19
20 /*! \file
21  *
22  * \brief Multi-party software based channel mixing (header)
23  *
24  * \author Joshua Colp <jcolp@digium.com>
25  * \author David Vossel <dvossel@digium.com>
26  *
27  * \ingroup bridges
28  */
29
30 #ifndef _ASTERISK_BRIDGE_SOFTMIX_INTERNAL_H
31 #define _ASTERISK_BRIDGE_SOFTMIX_INTERNAL_H
32
33 #include "asterisk.h"
34 #include <stdio.h>
35 #include <stdlib.h>
36 #include <string.h>
37 #include <sys/time.h>
38 #include <signal.h>
39 #include <errno.h>
40 #include <unistd.h>
41
42 #include "asterisk/module.h"
43 #include "asterisk/channel.h"
44 #include "asterisk/bridge.h"
45 #include "asterisk/bridge_technology.h"
46 #include "asterisk/frame.h"
47 #include "asterisk/options.h"
48 #include "asterisk/logger.h"
49 #include "asterisk/slinfactory.h"
50 #include "asterisk/astobj2.h"
51 #include "asterisk/timing.h"
52 #include "asterisk/translate.h"
53
54 #ifdef BINAURAL_RENDERING
55 #include <fftw3.h>
56 #endif
57
58 #if defined(__Darwin__) || defined(__OpenBSD__) || defined(__FreeBSD__) || defined(__NetBSD__) || defined(__CYGWIN__)
59 #include <float.h>
60 #else
61 #include <values.h>
62 #endif
63
64 #define MAX_DATALEN 8096
65 #define DEFAULT_ENERGY_HISTORY_LEN 150
66
67 /*! Setting the sample rate to 48000 by default if binaural is activated. */
68 #define SOFTMIX_BINAURAL_SAMPLE_RATE 48000
69 /*! We only support 20 ms interval length with binaural data at the moment. */
70 #define BINAURAL_MIXING_INTERVAL 20
71
72 struct convolve_channel {
73         /*! The head related transfer function used for convolving */
74         double *hrtf;
75         /*! Input signals for fftw */
76         double *fftw_in;
77         /*! Output signals from the fftw */
78         double *fftw_out;
79         /*! Signals for overlap add */
80         float *overlap_add;
81         /*! The resulting data after the convolution */
82         int16_t *out_data;
83 #ifdef BINAURAL_RENDERING
84         /*! The fftw plan for binaural signaling */
85         fftw_plan fftw_plan;
86         /*! The inverse fftw plan for binaural signaling */
87         fftw_plan fftw_plan_inverse;
88 #endif
89 };
90
91 struct convolve_channel_pair {
92         /*! The left channel of a stereo channel pair */
93         struct convolve_channel chan_left;
94         /*! The right channel of a stereo channel pair */
95         struct convolve_channel chan_right;
96 };
97
98 struct convolve_data {
99         /*! A count of all channels potentialy having input data for the conference. */
100         int number_channels;
101         /*! Will set to true if there is at least one binaural output.
102          * Only if set to true data will be convolved. */
103         int binaural_active;
104         /*! The length of the head related transfer function */
105         unsigned int hrtf_length;
106         /*! Number of channels available for convolving.
107          * We do not delete a channel when a member leaves, cause we can reuse it for the next one. */
108         int chan_size;
109         /*! The positions of the single channels in the virtual room */
110         int *pos_ids;
111         /*! Each channel has a stereo pair of channels for the convolution */
112         struct convolve_channel_pair **cchan_pair;
113 };
114
115 struct video_follow_talker_data {
116         /*! audio energy history */
117         int energy_history[DEFAULT_ENERGY_HISTORY_LEN];
118         /*! The current slot being used in the history buffer, this
119          *  increments and wraps around */
120         int energy_history_cur_slot;
121         /*! The current energy sum used for averages. */
122         int energy_accum;
123         /*! The current energy average */
124         int energy_average;
125 };
126
127 /*! \brief Structure which contains per-channel mixing information */
128 struct softmix_channel {
129         /*! Lock to protect this structure */
130         ast_mutex_t lock;
131         /*! Factory which contains audio read in from the channel */
132         struct ast_slinfactory factory;
133         /*! Frame that contains mixed audio to be written out to the channel */
134         struct ast_frame write_frame;
135         /*! Current expected read slinear format. */
136         struct ast_format *read_slin_format;
137         /*! DSP for detecting silence */
138         struct ast_dsp *dsp;
139         /*!
140          * \brief TRUE if a channel is talking.
141          *
142          * \note This affects how the channel's audio is mixed back to
143          * it.
144          */
145         unsigned int talking:1;
146         /*! TRUE if the channel provided audio for this mixing interval */
147         unsigned int have_audio:1;
148         /*! We set binaural also as channel data, to have better tracking.
149          *  It is also present in transpvt.
150          */
151         unsigned int binaural:1;
152         /*! TRUE if this is an announcement channel (data will not be convolved) */
153         unsigned int is_announcement:1;
154         /*! The position of the channel in the virtual room represented by an id
155          *      This ID has to be set even if the channel has no binaural output!
156          */
157         unsigned int binaural_pos;
158         /*! The channel pair for this channel */
159         struct convolve_channel_pair *our_chan_pair;
160         /*! Marks the channel for suspending all binaural activity on the output */
161         unsigned int binaural_suspended:1;
162         /*! Channel sample rate, stored to retrieve it after unsuspending the channel */
163         int rate;
164         /*! Buffer containing final mixed audio from all sources */
165         short final_buf[MAX_DATALEN];
166         /*! Buffer containing only the audio from the channel */
167         short our_buf[MAX_DATALEN];
168         /*! Data pertaining to talker mode for video conferencing */
169         struct video_follow_talker_data video_talker;
170 };
171
172 struct softmix_bridge_data {
173         struct ast_timer *timer;
174         /*!
175          * \brief Bridge pointer passed to the softmix mixing thread.
176          *
177          * \note Does not need a reference because the bridge will
178          * always exist while the mixing thread exists even if the
179          * bridge is no longer actively using the softmix technology.
180          */
181         struct ast_bridge *bridge;
182         /*! Lock for signaling the mixing thread. */
183         ast_mutex_t lock;
184         /*! Condition, used if we need to wake up the mixing thread. */
185         ast_cond_t cond;
186         /*! Thread handling the mixing */
187         pthread_t thread;
188         unsigned int internal_rate;
189         unsigned int internal_mixing_interval;
190         /*! TRUE if the mixing thread should stop */
191         unsigned int stop:1;
192         /*! The default sample size (e.g. using Opus at 48khz and 20 ms mixing
193          * interval, sample size is 960) */
194         unsigned int default_sample_size;
195         /*! All data needed for binaural signaling */
196         struct convolve_data convolve;
197         /*! TRUE if the first attempt to init binaural rendering data was done
198          * (does not guarantee success)
199          */
200         unsigned int binaural_init;
201 };
202
203 struct softmix_mixing_array {
204         unsigned int max_num_entries;
205         unsigned int used_entries;
206         int16_t **buffers;
207         /*! Stereo channel pairs used to store convolved binaural signals */
208         struct convolve_channel_pair **chan_pairs;
209 };
210
211 /*!
212  * \brief Deletes left over signals on a channel that it can be reused.
213  *
214  * \param channel_pair The channel pair which contains the left and right audio channel.
215  * \param default_sample_size The sample size which the channel pair uses.
216  */
217 void reset_channel_pair(struct convolve_channel_pair *channel_pair,
218                 unsigned int default_sample_size);
219
220 /*!
221  * \brief Randomly changes the virtual positions of conference participants.
222  *
223  * \param softmix_data The structure containing all position informations.
224  */
225 void random_binaural_pos_change(struct softmix_bridge_data *softmix_data);
226
227 /*!
228  * \brief Binaural convolving of audio data for a channel.
229  *
230  * \param chan The channel that will contain the binaural audio data as result.
231  * \param in_samples The audio data which will be convolved.
232  * \param in_sample_size The size of the audio data.
233  * \param hrtf_length The length of the head related transfer function used to convolve the audio.
234  *
235  * \retval 0 success
236  * \retval -1 failure
237  */
238 int do_convolve(struct convolve_channel *chan, int16_t *in_samples,
239                 unsigned int in_sample_size, unsigned int hrtf_length);
240
241 /*!
242  * \brief Binaural convolving of audio data for a channel pair (left and right channel).
243  *
244  * \param data  Contains the left and right audio channel.
245  * \param pos_id The position the channel has in the virtual enviroment.
246  * \param in_samples The audio data which will be convolved for both channels.
247  * \param in_sample_size The size of the audio data.
248  * \param channel_name The name of the channel
249  *
250  * \retval The channel pair with convolved audio on success.
251  * \retval NULL failure
252  */
253 struct convolve_channel_pair *do_convolve_pair(struct convolve_data *data,
254                 unsigned int pos_id, int16_t *in_samples, unsigned int in_sample_size,
255                 const char *channel_name);
256
257 /*!
258  * \brief Provides a head related impulse response for the given position in the virtual
259  * enviroment.
260  *
261  * \param chan_pos The position of the channel in the virtual enviroment.
262  * \param chan_side 0 for the left audio channel, 1 for the right.
263  *
264  * \retval The hrir for the given position in the virtual room for either the left or right
265  *  channels.
266  * \retval NULL on failure.
267  *
268  */
269 float *get_hrir(unsigned int chan_pos, unsigned int chan_side);
270
271 /*!
272  * \brief Initializes all data needed for binaural audio processing.
273  *
274  * \param channel The channel used for binaural audio processing.
275  * \param hrtf_len The length of the head related impulse response used for binaural processing.
276  * \param chan_pos The position of the channel in the virtual enviroment.
277  * \param chan_side 0 for the left audio channel, 1 for the right.
278  * \param default_sample_size The default size of audio samples.
279  *
280  * \retval 0 on success
281  * \retval -1 on failure
282  */
283 int init_convolve_channel(struct convolve_channel *channel, unsigned int hrtf_len,
284                 unsigned int chan_pos, unsigned int chan_side, unsigned int default_sample_size);
285
286 /*!
287  * \brief Initializies all data needed for binaural audio processing of a channel pair
288  * (left and right).
289  *
290  * \param cchan_pair The channel pair used for binaural audio processing.
291  * \param hrtf_len The length of the head related impulse response used for binaural processing.
292  * \param chan_pos The position of the channel in the virtual enviroment.
293  * \param default_sample_size The default size of audio samples.
294  *
295  * \retval 0 on success
296  * \retval -1 on failure
297  */
298 int init_convolve_channel_pair(struct convolve_channel_pair *cchan_pair,
299                 unsigned int hrtf_len, unsigned int chan_pos, unsigned int default_sample_size);
300
301 /*!
302  * \brief Preinits a specific number of channels (CONVOVLE_CHANNEL_PREALLOC)
303  * at the beginning of a conference.
304  *
305  * \param data Contains all channels and data needed for binaural processing
306  *  (e.g. head related transfer functions).
307  * \param default_sample_size The default size of audio samples.
308  *
309  * \retval 0 on success
310  * \retval -1 on failure
311  */
312 int init_convolve_data(struct convolve_data *data, unsigned int default_sample_size);
313
314 /*!
315  * \brief Frees all data needed for binaural processing by an audio channel.
316  *
317  * \param cchan The channel to clean up.
318  */
319 void free_convolve_channel(struct convolve_channel *cchan);
320
321 /*!
322  * \brief Frees all data needed for binaural processing by a pair of audio channels
323  *  (left and right).
324  *
325  * \param cchan_pair The channel pair to clean up.
326  */
327 void free_convolve_channel_pair(struct convolve_channel_pair *cchan_pair);
328
329 /*!
330  * \brief Frees all channels and data needed for binaural audio processing.
331  *
332  * \param data Contains all channels and data for the cleanup process.
333  */
334 void free_convolve_data(struct convolve_data *data);
335
336 /*!
337  * \brief Joins a channel into a virtual enviroment build with the help of binaural sythesis.
338  *
339  * \param data Contains all channels and data needed for binaural processing
340  *  (e.g. head related transfer functions).
341  * \param default_sample_size The default size of audio samples.
342  *
343  * \retval The position of the channel in the virtual enviroment.
344  * \retval -1 on failure
345  */
346 int set_binaural_data_join(struct convolve_data *data, unsigned int default_sample_size);
347
348 /*!
349  * \brief Removes a channel from the binaural conference bridge. Marks the position in
350  *  the virtual room as unused that it can be reused by the next channel which enters the
351  *  conference.
352  *
353  * \param data Contains all channels and data needed for binaural processing
354  *  (e.g. head related transfer functions).
355  * \param pos The position of the channel in the virtual enviroment.
356  * \param default_sample_size The default size of audio samples.
357  */
358 void set_binaural_data_leave(struct convolve_data *data, unsigned int pos,
359                 unsigned int default_sample_size);
360
361 /*!
362  * \brief Writes the binaural audio to a channel.
363  *
364  * \param sc The softmix channel.
365  * \param default_sample_size The default size of audio samples.
366  */
367 void softmix_process_write_binaural_audio(struct softmix_channel *sc,
368                 unsigned int default_sample_size);
369
370 /*!
371  * \brief Checks if a position change in the virual enviroment is requested by one of
372  * the participants.
373  *
374  * \param bridge The conference bridge.
375  * \param softmix_data The data used by the softmix bridge.
376  * \param bridge_channel The bridge channel.
377  */
378 void check_binaural_position_change(struct ast_bridge *bridge,
379                 struct softmix_bridge_data *softmix_data, struct ast_bridge_channel *bridge_channel);
380
381 /*!
382  * \brief Processes audio data with the binaural synthesis and adds the result to the mixing array.
383  *
384  * \param bridge The conference bridge needed to check if binaural processing is active or not.
385  * \param softmix_data Contains all data for the softmix bridge and for the binaural processing.
386  * \param softmix_samples The sample size.
387  * \param mixing_array The array which holds all audio data for mixing.
388  * \param sc The channel which contains the audio data to process.
389  * \param channel_name The name of the channel
390  */
391 void add_binaural_mixing(struct ast_bridge *bridge, struct softmix_bridge_data *softmix_data,
392                 unsigned int softmix_samples, struct softmix_mixing_array *mixing_array,
393                 struct softmix_channel *sc, const char *channel_name);
394
395 /*!
396  * \brief Mixes all binaural audio data contained in the mixing array.
397  *
398  * \param bridge The conference bridge needed to check if binaural processing is active or not.
399  * \param softmix_data Contains all data for the softmix bridge and for the binaural processing.
400  * \param mixing_array The array which holds all audio data for mixing.
401  * \param bin_buf The buffer that will contain the mixing results.
402  * \param ann_buf The buffer that will contain mixed announcements in an interleaved format.
403  */
404 void binaural_mixing(struct ast_bridge *bridge, struct softmix_bridge_data *softmix_data,
405                 struct softmix_mixing_array *mixing_array, int16_t *bin_buf, int16_t *ann_buf);
406
407 /*!
408  * \brief Creates a frame out of binaural audio data.
409  *
410  * \param bridge_channel Contains the information if binaural processing is active or not.
411  *  If active binaural audio data will be copied, if not mono data will be provided in an
412  *  interleaved format.
413  * \param sc The softmix channel holding all informations for the process.
414  * \param bin_buf The buffer that contains all mixing results.
415  * \param ann_buf The buffer that contains mixed announcements in an interleaved format.
416  * \param softmix_datalen The size of the audio data.
417  * \param softmix_samples The number of audio samples.
418  * \param buf The buffer that contains all mono mixing results, used if binaural processing is
419  *  inactive.
420  */
421 void create_binaural_frame(struct ast_bridge_channel *bridge_channel,
422                 struct softmix_channel *sc, int16_t *bin_buf, int16_t *ann_buf,
423                 unsigned int softmix_datalen, unsigned int softmix_samples, int16_t *buf);
424
425 #endif /* _ASTERISK_BRIDGE_SOFTMIX_INTERNAL_H */