Home | History | Annotate | Download | only in sound 
      1 /*
      2  *  Copyright 2004 The WebRTC Project Authors. All rights reserved.
      3  *
      4  *  Use of this source code is governed by a BSD-style license
      5  *  that can be found in the LICENSE file in the root of the source
      6  *  tree. An additional intellectual property rights grant can be found
      7  *  in the file PATENTS.  All contributing project authors may
      8  *  be found in the AUTHORS file in the root of the source tree.
      9  */
     10 
     11 #ifndef WEBRTC_SOUND_SOUNDSYSTEMINTERFACE_H_
     12 #define WEBRTC_SOUND_SOUNDSYSTEMINTERFACE_H_
     13 
     14 #include <vector>
     15 
     16 #include "webrtc/base/constructormagic.h"
     17 
     18 namespace rtc {
     19 
     20 class SoundDeviceLocator;
     21 class SoundInputStreamInterface;
     22 class SoundOutputStreamInterface;
     23 
     24 // Interface for a platform's sound system.
     25 // Implementations must guarantee thread-safety for at least the following use
     26 // cases:
     27 // 1) Concurrent enumeration and opening of devices from different threads.
     28 // 2) Concurrent use of different Sound(Input|Output)StreamInterface
     29 // instances from different threads (but concurrent use of the _same_ one from
     30 // different threads need not be supported).
     31 class SoundSystemInterface {
     32  public:
     33   typedef std::vector<SoundDeviceLocator *> SoundDeviceLocatorList;
     34 
     35   enum SampleFormat {
     36     // Only one supported sample format at this time.
     37     // The values here may be used in lookup tables, so they shouldn't change.
     38     FORMAT_S16LE = 0,
     39   };
     40 
     41   enum Flags {
     42     // Enable reporting the current stream latency in
     43     // Sound(Input|Output)StreamInterface. See those classes for more details.
     44     FLAG_REPORT_LATENCY = (1 << 0),
     45   };
     46 
     47   struct OpenParams {
     48     // Format for the sound stream.
     49     SampleFormat format;
     50     // Sampling frequency in hertz.
     51     unsigned int freq;
     52     // Number of channels in the PCM stream.
     53     unsigned int channels;
     54     // Misc flags. Should be taken from the Flags enum above.
     55     int flags;
     56     // Desired latency, measured as number of bytes of sample data
     57     int latency;
     58   };
     59 
     60   // Special values for the "latency" field of OpenParams.
     61   // Use this one to say you don't care what the latency is. The sound system
     62   // will optimize for other things instead.
     63   static const int kNoLatencyRequirements = -1;
     64   // Use this one to say that you want the sound system to pick an appropriate
     65   // small latency value. The sound system may pick the minimum allowed one, or
     66   // a slightly higher one in the event that the true minimum requires an
     67   // undesirable trade-off.
     68   static const int kLowLatency = 0;
     69 
     70   // Max value for the volume parameters for Sound(Input|Output)StreamInterface.
     71   static const int kMaxVolume = 255;
     72   // Min value for the volume parameters for Sound(Input|Output)StreamInterface.
     73   static const int kMinVolume = 0;
     74 
     75   // Helper for clearing a locator list and deleting the entries.
     76   static void ClearSoundDeviceLocatorList(SoundDeviceLocatorList *devices);
     77 
     78   virtual ~SoundSystemInterface() {}
     79 
     80   virtual bool Init() = 0;
     81   virtual void Terminate() = 0;
     82 
     83   // Enumerates the available devices. (Any pre-existing locators in the lists
     84   // are deleted.)
     85   virtual bool EnumeratePlaybackDevices(SoundDeviceLocatorList *devices) = 0;
     86   virtual bool EnumerateCaptureDevices(SoundDeviceLocatorList *devices) = 0;
     87 
     88   // Gets a special locator for the default device.
     89   virtual bool GetDefaultPlaybackDevice(SoundDeviceLocator **device) = 0;
     90   virtual bool GetDefaultCaptureDevice(SoundDeviceLocator **device) = 0;
     91 
     92   // Opens the given device, or returns NULL on error.
     93   virtual SoundOutputStreamInterface *OpenPlaybackDevice(
     94       const SoundDeviceLocator *device,
     95       const OpenParams &params) = 0;
     96   virtual SoundInputStreamInterface *OpenCaptureDevice(
     97       const SoundDeviceLocator *device,
     98       const OpenParams &params) = 0;
     99 
    100   // A human-readable name for this sound system.
    101   virtual const char *GetName() const = 0;
    102 
    103  protected:
    104   SoundSystemInterface() {}
    105 
    106  private:
    107   DISALLOW_COPY_AND_ASSIGN(SoundSystemInterface);
    108 };
    109 
    110 }  // namespace rtc
    111 
    112 #endif  // WEBRTC_SOUND_SOUNDSYSTEMINTERFACE_H_
    113