summaryrefslogtreecommitdiffstats
path: root/audio/filter/af.h
blob: 31abe1edeef9fadc66f5316f2febd0f570908455 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
/*
 * This file is part of MPlayer.
 *
 * MPlayer is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * MPlayer is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License along
 * with MPlayer; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */

#ifndef MPLAYER_AF_H
#define MPLAYER_AF_H

#include <stdio.h>

#include "config.h"

#include "core/options.h"
#include "audio/format.h"
#include "control.h"
#include "core/mp_msg.h"

struct af_instance;

// Number of channels
#ifndef AF_NCH
#define AF_NCH 8
#endif

// Audio data chunk
struct mp_audio {
    void *audio; // data buffer
    int len;    // buffer length
    int rate;   // sample rate
    int nch;    // number of channels
    int format; // format
    int bps;    // bytes per sample
};


// Flags used for defining the behavior of an audio filter
#define AF_FLAGS_REENTRANT      0x00000000
#define AF_FLAGS_NOT_REENTRANT  0x00000001

/* Audio filter information not specific for current instance, but for
   a specific filter */
struct af_info {
    const char *info;
    const char *name;
    const char *author;
    const char *comment;
    const int flags;
    int (*open)(struct af_instance *vf);
};

// Linked list of audio filters
struct af_instance {
    struct af_info *info;
    int (*control)(struct af_instance *af, int cmd, void *arg);
    void (*uninit)(struct af_instance *af);
    struct mp_audio * (*play)(struct af_instance *af, struct mp_audio *data);
    void *setup;  // setup data for this specific instance and filter
    struct mp_audio *data; // configuration for outgoing data stream
    struct af_instance *next;
    struct af_instance *prev;
    double delay; /* Delay caused by the filter, in units of bytes read without
                   * corresponding output */
    double mul; /* length multiplier: how much does this instance change
                   the length of the buffer. */
};

// Initialization flags
extern int *af_cpu_speed;

#define AF_INIT_AUTO            0x00000000
#define AF_INIT_SLOW            0x00000001
#define AF_INIT_FAST            0x00000002
#define AF_INIT_FORCE           0x00000003
#define AF_INIT_TYPE_MASK       0x00000003

#define AF_INIT_INT             0x00000000
#define AF_INIT_FLOAT           0x00000004
#define AF_INIT_FORMAT_MASK     0x00000004

// Default init type
#ifndef AF_INIT_TYPE
#define AF_INIT_TYPE (af_cpu_speed ? *af_cpu_speed : AF_INIT_SLOW)
#endif

// Configuration switches
struct af_cfg {
    int force;  // Initialization type
    char **list; /* list of names of filters that are added to filter
                    list during first initialization of stream */
};

// Current audio stream
struct af_stream {
    // The first and last filter in the list
    struct af_instance *first;
    struct af_instance *last;
    // Storage for input and output data formats
    struct mp_audio input;
    struct mp_audio output;
    // Configuration for this stream
    struct af_cfg cfg;
    struct MPOpts *opts;
};

/*********************************************
   // Return values
 */

#define AF_DETACH   2
#define AF_OK       1
#define AF_TRUE     1
#define AF_FALSE    0
#define AF_UNKNOWN -1
#define AF_ERROR   -2
#define AF_FATAL   -3



/*********************************************
   // Export functions
 */

/**
 * \defgroup af_chain Audio filter chain functions
 * \{
 * \param s filter chain
 */

/**
 * \brief Initialize the stream "s".
 * \return 0 on success, -1 on failure
 *
 * This function creates a new filter list if necessary, according
 * to the values set in input and output. Input and output should contain
 * the format of the current movie and the format of the preferred output
 * respectively.
 * Filters to convert to the preferred output format are inserted
 * automatically, except when they are set to 0.
 * The function is reentrant i.e. if called with an already initialized
 * stream the stream will be reinitialized.
 */
int af_init(struct af_stream *s);

/**
 * \brief Uninit and remove all filters from audio filter chain
 */
void af_uninit(struct af_stream *s);

/**
 * \brief  Reinit the filter list from the given filter on downwards
 * \param  Filter instance to begin the reinit from
 * \return AF_OK on success or AF_ERROR on failure
 */
int af_reinit(struct af_stream *s, struct af_instance *af);

/**
 * \brief This function adds the filter "name" to the stream s.
 * \param name name of filter to add
 * \return pointer to the new filter, NULL if insert failed
 *
 * The filter will be inserted somewhere nice in the
 * list of filters (i.e. at the beginning unless the
 * first filter is the format filter (why??).
 */
struct af_instance *af_add(struct af_stream *s, char *name);

/**
 * \brief Uninit and remove the filter "af"
 * \param af filter to remove
 */
void af_remove(struct af_stream *s, struct af_instance *af);

/**
 * \brief find filter in chain by name
 * \param name name of the filter to find
 * \return first filter with right name or NULL if not found
 *
 * This function is used for finding already initialized filters
 */
struct af_instance *af_get(struct af_stream *s, char *name);

/**
 * \brief filter data chunk through the filters in the list
 * \param data data to play
 * \return resulting data
 * \ingroup af_chain
 */
struct mp_audio *af_play(struct af_stream *s, struct mp_audio *data);

/**
 * \brief send control to all filters, starting with the last until
 *        one accepts the command with AF_OK.
 * \param cmd filter control command
 * \param arg argument for filter command
 * \return the accepting filter or NULL if none was found
 */
struct af_instance *af_control_any_rev(struct af_stream *s, int cmd, void *arg);

/**
 * \brief calculate average ratio of filter output lenth to input length
 * \return the ratio
 */
double af_calc_filter_multiplier(struct af_stream *s);

/**
 * \brief Calculate the total delay caused by the filters
 * \return delay in bytes of "missing" output
 */
double af_calc_delay(struct af_stream *s);

/** \} */ // end of af_chain group

// Helper functions and macros used inside the audio filters

/**
 * \defgroup af_filter Audio filter helper functions
 * \{
 */

/* Helper function called by the macro with the same name only to be
   called from inside filters */
int af_resize_local_buffer(struct af_instance *af, struct mp_audio *data);

/* Helper function used to calculate the exact buffer length needed
   when buffers are resized. The returned length is >= than what is
   needed */
int af_lencalc(double mul, struct mp_audio *data);

/**
 * \brief convert dB to gain value
 * \param n number of values to convert
 * \param in [in] values in dB, <= -200 will become 0 gain
 * \param out [out] gain values
 * \param k input values are divided by this
 * \param mi minimum dB value, input will be clamped to this
 * \param ma maximum dB value, input will be clamped to this
 * \return AF_ERROR on error, AF_OK otherwise
 */
int af_from_dB(int n, float *in, float *out, float k, float mi, float ma);

/**
 * \brief convert gain value to dB
 * \param n number of values to convert
 * \param in [in] gain values, 0 wil become -200 dB
 * \param out [out] values in dB
 * \param k output values will be multiplied by this
 * \return AF_ERROR on error, AF_OK otherwise
 */
int af_to_dB(int n, float *in, float *out, float k);

/**
 * \brief convert milliseconds to sample time
 * \param n number of values to convert
 * \param in [in] values in milliseconds
 * \param out [out] sample time values
 * \param rate sample rate
 * \param mi minimum ms value, input will be clamped to this
 * \param ma maximum ms value, input will be clamped to this
 * \return AF_ERROR on error, AF_OK otherwise
 */
int af_from_ms(int n, float *in, int *out, int rate, float mi, float ma);

/**
 * \brief convert sample time to milliseconds
 * \param n number of values to convert
 * \param in [in] sample time values
 * \param out [out] values in milliseconds
 * \param rate sample rate
 * \return AF_ERROR on error, AF_OK otherwise
 */
int af_to_ms(int n, int *in, float *out, int rate);

/**
 * \brief test if output format matches
 * \param af audio filter
 * \param out needed format, will be overwritten by available
 *            format if they do not match
 * \return AF_FALSE if formats do not match, AF_OK if they match
 *
 * compares the format, bps, rate and nch values of af->data with out
 */
int af_test_output(struct af_instance *af, struct mp_audio *out);

/**
 * \brief soft clipping function using sin()
 * \param a input value
 * \return clipped value
 */
float af_softclip(float a);

/** \} */ // end of af_filter group, but more functions of this group below

/** Print a list of all available audio filters */
void af_help(void);

/**
 * \brief fill the missing parameters in the struct mp_audio structure
 * \param data structure to fill
 * \ingroup af_filter
 *
 * Currently only sets bps based on format
 */
void af_fix_parameters(struct mp_audio *data);

/** Memory reallocation macro: if a local buffer is used (i.e. if the
   filter doesn't operate on the incoming buffer this macro must be
   called to ensure the buffer is big enough.
 * \ingroup af_filter
 */
#define RESIZE_LOCAL_BUFFER(a, d) \
    ((a->data->len < \
      af_lencalc(a->mul, d)) ? af_resize_local_buffer(a, d) : AF_OK)

/* Some other useful macro definitions*/
#ifndef min
#define min(a, b)(((a) > (b)) ? (b) : (a))
#endif

#ifndef max
#define max(a, b)(((a) > (b)) ? (a) : (b))
#endif

#ifndef clamp
#define clamp(a, min, max) (((a) > (max)) ? (max) : (((a) < (min)) ? (min) : (a)))
#endif

#ifndef sign
#define sign(a) (((a) > 0) ? (1) : (-1))
#endif

#ifndef lrnd
#define lrnd(a, b) ((b)((a) >= 0.0 ? (a) + 0.5 : (a) - 0.5))
#endif

#endif /* MPLAYER_AF_H */