1 /* 2 * libjingle 3 * Copyright 2004--2010, Google Inc. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 8 * 1. Redistributions of source code must retain the above copyright notice, 9 * this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright notice, 11 * this list of conditions and the following disclaimer in the documentation 12 * and/or other materials provided with the distribution. 13 * 3. The name of the author may not be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED 17 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 18 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO 19 * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 20 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 21 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 22 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 23 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 24 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 25 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26 */ 27 28 #ifndef TALK_SOUND_SOUNDSYSTEMINTERFACE_H_ 29 #define TALK_SOUND_SOUNDSYSTEMINTERFACE_H_ 30 31 #include <vector> 32 33 #include "talk/base/constructormagic.h" 34 35 namespace cricket { 36 37 class SoundDeviceLocator; 38 class SoundInputStreamInterface; 39 class SoundOutputStreamInterface; 40 41 // Interface for a platform's sound system. 42 // Implementations must guarantee thread-safety for at least the following use 43 // cases: 44 // 1) Concurrent enumeration and opening of devices from different threads. 45 // 2) Concurrent use of different Sound(Input|Output)StreamInterface 46 // instances from different threads (but concurrent use of the _same_ one from 47 // different threads need not be supported). 48 class SoundSystemInterface { 49 public: 50 typedef std::vector<SoundDeviceLocator *> SoundDeviceLocatorList; 51 52 enum SampleFormat { 53 // Only one supported sample format at this time. 54 // The values here may be used in lookup tables, so they shouldn't change. 55 FORMAT_S16LE = 0, 56 }; 57 58 enum Flags { 59 // Enable reporting the current stream latency in 60 // Sound(Input|Output)StreamInterface. See those classes for more details. 61 FLAG_REPORT_LATENCY = (1 << 0), 62 }; 63 64 struct OpenParams { 65 // Format for the sound stream. 66 SampleFormat format; 67 // Sampling frequency in hertz. 68 unsigned int freq; 69 // Number of channels in the PCM stream. 70 unsigned int channels; 71 // Misc flags. Should be taken from the Flags enum above. 72 int flags; 73 // Desired latency, measured as number of bytes of sample data 74 int latency; 75 }; 76 77 // Special values for the "latency" field of OpenParams. 78 // Use this one to say you don't care what the latency is. The sound system 79 // will optimize for other things instead. 80 static const int kNoLatencyRequirements = -1; 81 // Use this one to say that you want the sound system to pick an appropriate 82 // small latency value. The sound system may pick the minimum allowed one, or 83 // a slightly higher one in the event that the true minimum requires an 84 // undesirable trade-off. 85 static const int kLowLatency = 0; 86 87 // Max value for the volume parameters for Sound(Input|Output)StreamInterface. 88 static const int kMaxVolume = 255; 89 // Min value for the volume parameters for Sound(Input|Output)StreamInterface. 90 static const int kMinVolume = 0; 91 92 // Helper for clearing a locator list and deleting the entries. 93 static void ClearSoundDeviceLocatorList(SoundDeviceLocatorList *devices); 94 ~SoundSystemInterface()95 virtual ~SoundSystemInterface() {} 96 97 virtual bool Init() = 0; 98 virtual void Terminate() = 0; 99 100 // Enumerates the available devices. (Any pre-existing locators in the lists 101 // are deleted.) 102 virtual bool EnumeratePlaybackDevices(SoundDeviceLocatorList *devices) = 0; 103 virtual bool EnumerateCaptureDevices(SoundDeviceLocatorList *devices) = 0; 104 105 // Gets a special locator for the default device. 106 virtual bool GetDefaultPlaybackDevice(SoundDeviceLocator **device) = 0; 107 virtual bool GetDefaultCaptureDevice(SoundDeviceLocator **device) = 0; 108 109 // Opens the given device, or returns NULL on error. 110 virtual SoundOutputStreamInterface *OpenPlaybackDevice( 111 const SoundDeviceLocator *device, 112 const OpenParams ¶ms) = 0; 113 virtual SoundInputStreamInterface *OpenCaptureDevice( 114 const SoundDeviceLocator *device, 115 const OpenParams ¶ms) = 0; 116 117 // A human-readable name for this sound system. 118 virtual const char *GetName() const = 0; 119 120 protected: SoundSystemInterface()121 SoundSystemInterface() {} 122 123 private: 124 DISALLOW_COPY_AND_ASSIGN(SoundSystemInterface); 125 }; 126 127 } // namespace cricket 128 129 #endif // TALK_SOUND_SOUNDSYSTEMINTERFACE_H_ 130