summaryrefslogtreecommitdiff
path: root/src/audioio.h
blob: 78667513ae0f43b888f294a16ed7e4b3b8b9d71c (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
/* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* vim: set et sw=2 ts=2: */
/***************************************************************************
 *            audioio.h
 *
 *  Thu Sep 25 15:55:14 CEST 2014
 *  Copyright 2014 Bent Bisballe Nyeng
 *  deva@aasimon.org
 ****************************************************************************/

/*
 *  This file is part of LibAudioIO.
 *
 *  LibAudioIO is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public
 *  License as published by the Free Software Foundation; either
 *  version 2.1 of the License, or (at your option) any later version.
 *  
 *  LibAudioIO 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
 *  Lesser General Public License for more details.
 *  
 *  You should have received a copy of the GNU Lesser General Public
 *  License along with LibAudioIO; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 */
#ifndef __LIBAUDIOIO_AUDIOIO_H__
#define __LIBAUDIOIO_AUDIOIO_H__

#ifdef __cplusplus
extern "C" {
#endif

#define NO_ERROR                     0

#define OUT_OF_MEMORY              -101
#define MISSING_HANDLE             -102
#define MISSING_MIXER_HANDLE       -102
#define MISSING_PCM_HANDLE         -104
#define MIXER_INIT_FAILED          -105
#define NO_SUCH_CHANNEL            -106
#define SAMPLE_READ_ERROR          -107
#define SAMPLE_WRITE_ERROR         -108
#define MIXER_ERROR                -109
#define COULD_NOT_OPEN_DEVICE      -110
#define INVALID_MIXER_LEVEL        -111

struct aio_t;

/**
 * Initalise the AudioIO library and connect to a soundcard and a mixer.
 * @param err An int pointer containing error value if function is unsuccessful.
 * @param device A string containing the device name to connect to. A list 
 * possible devices can be seen with the 'aplay -L' command. The device
 * "default" are usually the one needed.
 * @param mixer A string containing the mixer interface to connect to. A list
 * of possible interfaces can be seen with the 'amixer scontrols' command.
 * Usually the interface "Capture" is the one needed.
 * @param samplerate An unsigned integer containing the desired samplerate in
 * Hertz.
 * @param channels An unsigned integer containing the desired number of
 * channels. The channel samples will be interleaved in the data stream whe
 * ai_read is called.
 * @return A pointer to the newly created handle or NULL on failure.
 */
struct aio_t *aio_init(int *err,
                       const char *playback_device,
                       const char *playback_mixer,
                       const char *capture_device,
                       const char *capture_mixer,
                       unsigned int samplerate,
                       unsigned int channels);

/**
 * Read samples from the soundcard.
 * @param err An int pointer containing error value if function is unsuccessful.
 * @param handle A pointer to the handle to be used.
 * @param pcm Buffer cotaining which will be filled with samples.
 * @param maxsize The maximum number of bytes (not samples) to read.
 * @return Returns the number of bytes (not samples) read or -1 on error.
 * NOTE: to get the number of samples read, devide the return value with the
 * sample width (2 bytes / 16 bits) and the number of interleaved channels
 * (usually 1 or 2).
 */
int aio_read(struct aio_t *handle, char *pcm, unsigned int maxsize);

/**
 * Write samples to the soundcard.
 * @param err An int pointer containing error value if function is unsuccessful.
 * @param handle A pointer to the handle to be used.
 * @param size The maximum number of bytes (not samples) to be written.
 * @return Returns the number of bytes (not samples) written or -1 on error.
 * NOTE: to get the number of samples read, devide the return value with the
 * sample width (2 bytes / 16 bits) and the number of interleaved channels
 * (usually 1 or 2).
 */
int aio_write(struct aio_t *handle, const char *pcm, unsigned int size);

/**
 * Adjust playback channel mixer levels.
 * @param handle A pointer to the handle to be used.
 * @param channel The channel number to set mixer level of. 0 or 1 should be
 * used for the two channels of a stereo interface.
 * @param level The mixer level to set in dB
 * @return Returns error code.
 */
int aio_set_playback_mixer_level(struct aio_t *handle, unsigned int channel,
                                 float level);

/**
 * Get playback channel mixer levels.
 * @param handle A pointer to the handle to be used.
 * @param channel The channel number to get mixer level of. 0 or 1 should be
 * used for the two channels of a stereo interface.
 * @param level A pointer to a float which after a successful call will contain
 * the channel amplification level in dB.
 * @return Returns error code.
 */
int aio_get_playback_mixer_level(struct aio_t *handle, unsigned int channel,
                                 float *level);

/**
 * Get playback channel amplification range in dB.
 * @param handle A pointer to the handle to be used.
 * @param min A pointer to a float in which the min value will be returned.
 * @param max A pointer to a float in which the max value will be returned.
 * @return Returns error code.
 */
int aio_get_playback_mixer_level_range(struct aio_t *handle,
                                       float *min, float *max);

/**
 * Adjust capture channel mixer levels.
 * @param handle A pointer to the handle to be used.
 * @param channel The channel number to set mixer level of. 0 or 1 should be
 * used for the two channels of a stereo interface.
 * @param level The mixer level to set in dB
 * @return Returns error code.
 */
int aio_set_capture_mixer_level(struct aio_t *handle, unsigned int channel,
                                float level);

/**
 * Get channel mixer levels.
 * @param handle A pointer to the handle to be used.
 * @param channel The channel number to get mixer level of. 0 or 1 should be
 * used for the two channels of a stereo interface.
 * @param level A pointer to a float which after a successful call will contain
 * the channel amplification level in dB.
 * @return Returns error code.
 */
int aio_get_capture_mixer_level(struct aio_t *handle, unsigned int channel,
                                float *level);

/**
 * Get capture channel amplification range in dB.
 * @param handle A pointer to the handle to be used.
 * @param min A pointer to a float in which the min value will be returned.
 * @param max A pointer to a float in which the max value will be returned.
 * @return Returns error code.
 */
int aio_get_capture_mixer_level_range(struct aio_t *handle,
                                      float *min, float *max);

/**
 * Get actual samplerate.
 * The samplerate set in ai_init may or may not match a possible samplerate for
 * the audio hardware and therefore the ALSA library might decide to use another
 * samplerate than the one specified.
 * This function can be called to obtain the actual samplerate that the hardware
 * has been configured to use.
 * @param err An int pointer containing error value if function is unsuccessful.
 * @param handle A pointer to the handle to be used.
 * @return The samplerate as an integer or -1 on error.
 */
int aio_get_samplerate(struct aio_t *handle);

int aio_get_buffer_size(struct aio_t *handle);

/**
 * Close and free the handle.
 * @param err An int pointer containing error value if function is unsuccessful.
 * @param handle A pointer to the handle to be closed.
 */
int aio_close(struct aio_t *handle);

#ifdef __cplusplus
}
#endif

#endif/*__LIBAUDIOIO_AUDIOIO_H__*/