2
* Ekiga -- A VoIP and Video-Conferencing application
3
* Copyright (C) 2000-2008 Damien Sandras
5
* This program is free software; you can redistribute it and/or modify
6
* it under the terms of the GNU General Public License as published by
7
* the Free Software Foundation; either version 2 of the License, or (at
8
* your option) any later version. This program is distributed in the hope
9
* that it will be useful, but WITHOUT ANY WARRANTY; without even the
10
* implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
11
* See the GNU General Public License for more details.
13
* You should have received a copy of the GNU General Public License along
14
* with this program; if not, write to the Free Software Foundation, Inc.,
15
* 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA.
17
* Ekiga is licensed under the GPL license and as a special exception, you
18
* have permission to link or otherwise combine this program with the
19
* programs OPAL, OpenH323 and PWLIB, and distribute the combination, without
20
* applying the requirements of the GNU GPL to the OPAL, OpenH323 and PWLIB
21
* programs, as long as you do follow the requirements of the GNU GPL for all
22
* the rest of the software thus combined.
27
* audiooutput-core.h - description
28
* ------------------------------------------
29
* begin : written in 2008 by Matthias Schneider
30
* copyright : (c) 2008 by Matthias Schneider
31
* description : Declaration of the interface of a audiooutput core.
32
* A audioout core manages AudioOutputManagers.
36
#ifndef __AUDIOOUTPUT_CORE_H__
37
#define __AUDIOOUTPUT_CORE_H__
41
#include "audiooutput-core.h"
43
#include "audiooutput-gmconf-bridge.h"
44
#include "audiooutput-info.h"
45
#include "audiooutput-scheduler.h"
47
#include <sigc++/sigc++.h>
51
#include "ptbuildopts.h"
54
#define AUDIO_OUTPUT_FALLBACK_DEVICE_TYPE "Ekiga"
55
#define AUDIO_OUTPUT_FALLBACK_DEVICE_SOURCE "Ekiga"
56
#define AUDIO_OUTPUT_FALLBACK_DEVICE_NAME "SILENT"
61
* @defgroup audiooutput
65
class AudioOutputManager;
66
class AudioOutputCore;
68
/** Core object for the audio output support
69
* The audio output core abstracts all functionality related to audio output
70
* in a thread safe manner. Typically, most of the functions except start(),
71
* stop(), set_buffer_size() and set_frame_data() will be called from a UI thread,
72
* while the three mentioned funtions will be used by an audio streaming thread.
74
* The audio output core abstracts different audio output managers, which can
75
* represent different backends like PTLIB, from the application and can
76
* switch the output device transparently for the audio streaming thread,
77
* even while audio output is in progress.
79
* If the removal of an audio output device is detected by a failed
80
* write or by a message from the HalCore, the audio output core will
81
* determine the responsible audio output manager and send a signal to the UI,
82
* which can be used to update device lists. Also, if the removed device was the
83
* currently used one, the core falls back to the backup device.
85
* A similar procedure is performed on the addition of a device. In case we fell
86
* back due to a removed device, and the respective device is re-added to the system,
87
* it will be automatically activated.
98
* @param _runtime reference to Ekiga runtime.
100
AudioOutputCore (Ekiga::Runtime & _runtime);
106
/** Set up gmconf bridge
108
void setup_conf_bridge();
111
/*** Service Implementation ***/
113
/** Returns the name of the service.
114
* @return The service name.
116
const std::string get_name () const
117
{ return "audiooutput-core"; }
119
/** Returns the description of the service.
120
* @return The service description.
122
const std::string get_description () const
123
{ return "\tAudioOutput Core managing AudioOutput Manager objects"; }
125
/** Adds a AudioOutputManager to the AudioOutputCore service.
126
* @param The manager to be added.
128
void add_manager (AudioOutputManager &manager);
130
/** Triggers a callback for all Ekiga::AudioOutputManager sources of the
131
* AudioOutputCore service.
133
void visit_managers (sigc::slot<bool, AudioOutputManager &> visitor);
135
/** This signal is emitted when a Ekiga::AudioOutputManager has been
136
* added to the AudioOutputCore Service.
138
sigc::signal<void, AudioOutputManager &> manager_added;
141
/** Get a list of all devices supported by all managers registered to the core.
142
* @param devices a vector of device names to be filled by the core.
144
void get_devices(std::vector <AudioOutputDevice> & devices);
146
/** Set a specific device
147
* This function sets the current primary or secondary audio output device. This function can
148
* also be used while in a stream or in preview mode. In that case the old
149
* device is closed and the new device opened automatically.
150
* @param ps whether referring to the primary or secondary device.
151
* @param device the new device to be used.
153
void set_device(AudioOutputPS ps, const AudioOutputDevice & device);
155
/** Inform the core of an added audiooutput device
156
* This function is called by the HalCore when an audio output device is added.
157
* It determines responsible managers for that specific device and informs the
158
* GUI about the device that was added (via device_added signal).
159
* In case the added device was the desired device and we fell back,
160
* we will reactivate it. MUST be called from main thread,
161
* @param sink the device sink (e.g. alsa).
162
* @param device_name the name of the added device.
163
* @param manager the HalManger detected the addition.
165
void add_device (const std::string & sink, const std::string & device_name, HalManager* manager);
167
/** Inform the core of a removed audiooutput device
168
* This function is called by the HalCore when an audio output device is removed.
169
* It determines responsible managers for that specific device and informs the
170
* GUI about the device that was removed (via device_removed signal).
171
* In case the removed device was the current device we fall back to the
172
* fallback device. MUST be called from main thread,
173
* @param sink the device sink (e.g. alsa).
174
* @param device_name the name of the removed device.
175
* @param manager the HalManger detected the removal.
177
void remove_device (const std::string & sink, const std::string & device_name, HalManager* manager);
180
/*** Event Management ***/
182
/** Add a mapping between event and file name to the event list
183
* An event shall refer to a specific sound file. This mapping is set here.
184
* @param event_name the name of the event.
185
* @param file_name the name of the file.
186
* @param ps whether the event shall be played on the primary or secondary device preferrably.
187
* @param enabled if the event is enabled.
189
void add_event (const std::string & event_name, const std::string & file_name, AudioOutputPS ps, bool enabled);
191
/** Play a sound specified by a file name
192
* Play a sound file once.
193
* The sound will be played in the background as soon as the Scheduler
195
* This function only adds the sound to the Scheduler queue and returns immediately.
196
* The sound will be played on the primary device
197
* @param file_name the name of the file.
199
void play_file (const std::string & file_name);
201
/** Play a sound specified by an event name
202
* Play a sound associated to the event speficied by its name once.
203
* The sound will be played in the background as soon as the Scheduler
205
* This function only adds the sound to the Scheduler queue and returns immediately.
206
* The sound will be played on the primary or seconday device depending on
207
* how this specific event was configured. In case it was to be played on the secondary device
208
* and not secondary device is available or configured, it will be played on the primary device.
209
* The event will only be played if it is enabled.
210
* @param event_name the name of the event.
212
void play_event (const std::string & event_name);
214
/** Play a sound specified by an event name
215
* Play a sound associated to the event specified by its name repeatingly.
216
* The sound will be played in the background as soon as the Scheduler
218
* This function only adds the sound to the Scheduler queue and returns immediately.
219
* The sound will be played on the primary or seconday device depending on
220
* how this specific event was configured. In case it was to be played on the secondary device
221
* and not secondary device is available or configured, it will be played on the primary device.
222
* The event will only be played if it is enabled.
223
* The event will be removed from the scheduler queue once it has been repeated "repetitions" times
224
* or if it has been removd from the queue via stop_play_event.
225
* @param event_name the name of the event.
226
* @param interval the interval of the repetitions in ms.
227
* @param repetitions the maximum number of repetitions.
229
void start_play_event (const std::string & event_name, unsigned interval, unsigned repetitions);
231
/** Stop playing a sound specified by an event name
232
* Stop playing sound associated to the event specified by its name.
233
* If the sound is currently playing, it will not be cut short.
234
* @param event_name the name of the event.
236
void stop_play_event (const std::string & event_name);
238
/** Play a sound event buffer
239
* This function is called by the Scheduler in order to play an already loaded sound.
240
* @param ps whether to play the sound on the primary or secondary device.
241
* @param buffer pointer to the sound in raw format.
242
* @param len the length in bytes of the sound.
243
* @param channels the number of channels.
244
* @param sample_rate the samplerate.
245
* @param bps bits per sample.
247
void play_buffer(AudioOutputPS ps, const char* buffer, unsigned long len, unsigned channels, unsigned sample_rate, unsigned bps);
250
/*** Stream Management ***/
252
/** Set the number and size of buffers
253
* Will be applied the next time the device is opened.
254
* @param buffer_size the size of each buffer in byte.
255
* @param num_buffers the number of buffers.
257
void set_buffer_size (unsigned buffer_size, unsigned num_buffers);
259
/** Start the audio output on the primary device
260
* @param channels the number of channels (1 or 2).
261
* @param samplerate the samplerate.
262
* @param bits_per_sample the number of bits per sample (e.g. 8, 16).
264
void start (unsigned channels, unsigned samplerate, unsigned bits_per_sample);
266
/** Stop the audio output of the primary device.
270
/** Set one audio buffer in the current manager.
271
* This function will pass one buffer to the current manager.
272
* Requires the audio output to be started.
273
* In case the device returns an error writing the frame, set_frame_data()
274
* falls back to the fallback device and writes the frame there. Thus
275
* set_frame_data() always be succesful.
276
* In case a new volume has bee set, it will be applied here.
277
* @param data a pointer to the buffer that is to be written to the device.
278
* @param size the number of bytes to be written.
279
* @param bytes_written number of bytes actually written.
281
void set_frame_data (const char *data, unsigned size, unsigned & bytes_written);
283
/** Set the volume of the next opportunity
284
* Sets the volume to the specified value the next time
285
* get_frame_data() is called.
286
* @param ps whether the volume of the primary or seconday device shall be set.
287
* @param volume the new volume level (0..255).
289
void set_volume (AudioOutputPS ps, unsigned volume);
291
/** Turn average collecion on and off
292
* The average values can be collected via get_average_level()
293
* This applies to primary device only.
294
* @param on_off whether to turn the collection on or off.
296
void set_average_collection (bool on_off) { calculate_average = on_off; }
298
/** Get the average volume level
299
* Get the average volume level ove the last read buffer of the primary device.
300
* @return the average volume level.
302
float get_average_level () { return average_level; }
307
/** See audiooutput-manager.h for the API
309
sigc::signal<void, AudioOutputManager &, AudioOutputPS, AudioOutputDevice&, AudioOutputSettings&> device_opened;
310
sigc::signal<void, AudioOutputManager &, AudioOutputPS, AudioOutputDevice&> device_closed;
311
sigc::signal<void, AudioOutputManager &, AudioOutputPS, AudioOutputDevice&, AudioOutputErrorCodes> device_error;
313
/** This signal is emitted when an audio output device has been added to the system.
314
* This signal will be emitted if add_device was called with a device name and
315
* a manager claimed support for this device.
316
* @param device the audio output device that was added.
318
sigc::signal<void, AudioOutputDevice, bool> device_added;
320
/** This signal is emitted when an audio output device has been removed from the system.
321
* This signal will be emitted if remove_device was called with a device name and
322
* a manager claimed support for this device.
323
* @param device the audio output device that was removed.
325
sigc::signal<void, AudioOutputDevice, bool> device_removed;
328
void on_device_opened (AudioOutputPS ps,
329
AudioOutputDevice device,
330
AudioOutputSettings settings,
331
AudioOutputManager *manager);
332
void on_device_closed (AudioOutputPS ps, AudioOutputDevice device, AudioOutputManager *manager);
333
void on_device_error (AudioOutputPS ps, AudioOutputDevice device, AudioOutputErrorCodes error_code, AudioOutputManager *manager);
335
void internal_set_primary_device(const AudioOutputDevice & device);
336
void internal_set_manager (AudioOutputPS ps, const AudioOutputDevice & device);
337
void internal_set_primary_fallback();
339
bool internal_open (AudioOutputPS ps, unsigned channels, unsigned samplerate, unsigned bits_per_sample);
340
void internal_close(AudioOutputPS ps);
342
void internal_play(AudioOutputPS ps, const char* buffer, unsigned long len, unsigned channels, unsigned sample_rate, unsigned bps);
344
void calculate_average_level (const short *buffer, unsigned size);
346
std::set<AudioOutputManager *> managers;
347
Ekiga::Runtime & runtime;
349
typedef struct DeviceConfig {
353
unsigned bits_per_sample;
354
unsigned buffer_size;
355
unsigned num_buffers;
358
DeviceConfig current_primary_config;
360
AudioOutputManager* current_manager[2];
361
AudioOutputDevice desired_primary_device;
362
AudioOutputDevice current_device[2];
363
unsigned desired_primary_volume;
364
unsigned current_primary_volume;
366
PMutex core_mutex[2];
369
AudioOutputCoreConfBridge* audiooutput_core_conf_bridge;
370
AudioEventScheduler audio_event_scheduler;
373
bool calculate_average;
added
removed
lib/engine/audiooutput/skel/audiooutput-core.h
