sound.h

Go to the documentation of this file.

/*
 * sound.h
 *
 * Sound interface class.
 *
 * Portable Windows Library
 *
 * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Portable Windows Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
 * All Rights Reserved.
 *
 * Contributor(s): ______________________________________.
 *
 * $Revision: 31801 $
 * $Author: rjongbloed $
 * $Date: 2014-04-29 14:00:16 +1000 (Tue, 29 Apr 2014) $
 */


#ifndef PTLIB_SOUND_H
#define PTLIB_SOUND_H

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <ptlib/plugin.h>
#include <ptlib/pluginmgr.h>

class PSound : public PBYTEArray
{
  PCLASSINFO(PSound, PBYTEArray);

  public:
    PSound(
      unsigned numChannels = 1,    
      unsigned sampleRate = 8000,  
      unsigned bitsPerSample = 16, 
      PINDEX   bufferSize = 0,     
      const BYTE * data = NULL     
    );

    PSound(
      const PFilePath & filename   
    );

    PSound & operator=(
      const PBYTEArray & data  
    );

    PBoolean Load(
      const PFilePath & filename   
    );

    PBoolean Save(
      const PFilePath & filename   
    );


    PBoolean Play();

    PBoolean Play(const PString & device);

    void SetFormat(
      unsigned numChannels,   
      unsigned sampleRate,    
      unsigned bitsPerSample  
    );

    unsigned GetEncoding()   const { return encoding; }

    unsigned GetChannels()   const { return numChannels; }

    unsigned GetSampleRate() const { return sampleRate; }

    unsigned GetSampleSize() const { return sampleSize; }

    DWORD    GetErrorCode()  const { return dwLastError; }

    PINDEX   GetFormatInfoSize()  const { return formatInfo.GetSize(); }

    const void * GetFormatInfoData() const { return (const BYTE *)formatInfo; }

    static PBoolean PlayFile(
      const PFilePath & file, 
      PBoolean wait = true        
    );

    static void Beep();

  protected:
    unsigned   encoding;      
    unsigned   numChannels;   
    unsigned   sampleRate;    
    unsigned   sampleSize;    
    DWORD      dwLastError;   
    PBYTEArray formatInfo;    
};


class PSoundChannel : public PIndirectChannel
{
  PCLASSINFO(PSoundChannel, PIndirectChannel);

  public:
    P_DECLARE_STREAMABLE_ENUM(Directions,
      Recorder,
      Player,
      Closed
    );

    PSoundChannel();

    enum {
      DefaultBufferSize = 320, // 20ms at 8kHz
      DefaultBufferCount = 2
    };

    struct Params {
      Params(
        Directions dir = Player,
        const PString & device = PString::Empty(),
        const PString & driver = PString::Empty(),
        unsigned channels = 1,
        unsigned sampleRate = 8000,
        unsigned bitsPerSample = 16,
        unsigned bufferSize =   DefaultBufferSize,
        unsigned bufferCount = DefaultBufferCount,
        PPluginManager * pluginMgr = NULL
      );

      Directions m_direction;     
      PString    m_device;        
      PString    m_driver;        
      unsigned   m_channels;      
      unsigned   m_sampleRate;    
      unsigned   m_bitsPerSample; 
      unsigned   m_bufferSize;    
      unsigned   m_bufferCount;   
      PPluginManager * m_pluginMgr;
      
      void SetBufferCountFromMS(unsigned milliseconds);
      friend ostream & operator<<(ostream &, const Params & params);
    };

    PSoundChannel(
      const Params & params  
    );

    // Backward compatibility
    PSoundChannel(
      const PString & device,       
      Directions dir,               
      unsigned numChannels = 1,     
      unsigned sampleRate = 8000,   
      unsigned bitsPerSample = 16   
    );

    static PStringArray GetDriverNames(
      PPluginManager * pluginMgr = NULL   
    );

    static PStringArray GetDriversDeviceNames(
      const PString & driverName,         
      Directions direction,               
      PPluginManager * pluginMgr = NULL   
    );

    // For backward compatibility
    static inline PStringArray GetDeviceNames(
      const PString & driverName,
      Directions direction,
      PPluginManager * pluginMgr = NULL
    ) { return GetDriversDeviceNames(driverName, direction, pluginMgr); }

    static PSoundChannel * CreateChannel (
      const PString & driverName,         
      PPluginManager * pluginMgr = NULL   
    );

    /* Create the matching sound channel that corresponds to the device name.
       So, for "fake" return a device that will generate fake video.
       For "Phillips 680 webcam" (eg) will return appropriate grabber.
       Note that Phillips will return the appropriate grabber also.

       This is typically used with the return values from GetDeviceNames().
     */
    static PSoundChannel * CreateChannelByName(
      const PString & deviceName,         
      Directions direction,               
      PPluginManager * pluginMgr = NULL   
    );

    static PSoundChannel * CreateOpenedChannel(
      const Params & params   
    );

    // For backward compatibility
    static PSoundChannel * CreateOpenedChannel(
      const PString & driverName,         
      const PString & deviceName,         
      Directions direction,               
      unsigned numChannels = 1,           
      unsigned sampleRate = 8000,         
      unsigned bitsPerSample = 16,        
      PPluginManager * pluginMgr = NULL   
    );

    static PString GetDefaultDevice(
      Directions dir    // Sound I/O direction
    );

    static PStringArray GetDeviceNames(
      Directions direction,               
      PPluginManager * pluginMgr = NULL   
    );

    virtual bool Open(
      const Params & params   
    );

    // For backward compatibility
    bool Open(
      const PString & device,       
      Directions dir,               
      unsigned numChannels = 1,     
      unsigned sampleRate = 8000,   
      unsigned bitsPerSample = 16,  
      PPluginManager * pluginMgr = NULL   
    );

    Directions GetDirection() const
    {
      return activeDirection;
    }

    static const char * GetDirectionText(Directions dir);

    virtual const char * GetDirectionText() const
    {
      return GetDirectionText(activeDirection);
    }

    virtual PBoolean Abort();

    virtual PBoolean SetFormat(
      unsigned numChannels = 1,     
      unsigned sampleRate = 8000,   
      unsigned bitsPerSample = 16   
    );

    virtual unsigned GetChannels() const;

    virtual unsigned GetSampleRate() const;

    virtual unsigned GetSampleSize() const;

    virtual PBoolean SetBuffers(
      PINDEX size,      
      PINDEX count = 2  
    );

    virtual PBoolean GetBuffers(
      PINDEX & size,    // Size of each buffer in bytes
      PINDEX & count    // Number of buffers
    );

    enum {
      MaxVolume = 100
    };

    virtual PBoolean SetVolume(
      unsigned volume   
    );

    virtual PBoolean GetVolume(
      unsigned & volume   
    );

    virtual bool SetMute(
      bool mute   
    );

    virtual bool GetMute(
      bool & mute   
    );


    virtual PBoolean PlaySound(
      const PSound & sound,   
      PBoolean wait = true        
    );

    virtual PBoolean PlayFile(
      const PFilePath & file, 
      PBoolean wait = true        
    );

    virtual PBoolean HasPlayCompleted();

    virtual PBoolean WaitForPlayCompletion();

    static PString TestPlayer(
      const Params & params,        
      const PNotifier & progress = PNotifier(), 
      const char * toneSpec = NULL  
    );

    virtual PBoolean RecordSound(
      PSound & sound 
    );

    virtual PBoolean RecordFile(
      const PFilePath & file 
    );

    virtual PBoolean StartRecording();

    virtual PBoolean IsRecordBufferFull();

    virtual PBoolean AreAllRecordBuffersFull();

    virtual PBoolean WaitForRecordBufferFull();

    virtual PBoolean WaitForAllRecordBuffersFull();

    static PString TestRecorder(
      const Params & recorderParams,  
      const Params & playerParams,    
      const PNotifier & progress = PNotifier(), 
      unsigned seconds = 5            
    );

  protected:
    PSoundChannel * GetSoundChannel() const { return dynamic_cast<PSoundChannel *>(readChannel); }

    Directions activeDirection;

    P_REMOVE_VIRTUAL(PBoolean, Open(const PString &,Directions,unsigned,unsigned,unsigned),false);
};



// define the sound plugin service descriptor

PCREATE_PLUGIN_DEVICE(PSoundChannel);

#define PCREATE_SOUND_PLUGIN_EX(name, InstanceClass, extra) \
   PCREATE_PLUGIN(name, PSoundChannel, InstanceClass, PPlugin_PSoundChannel, \
      virtual PStringArray GetDeviceNames(P_INT_PTR userData) const { return InstanceClass::GetDeviceNames((PSoundChannel::Directions)userData); } \
      extra)

#define PCREATE_SOUND_PLUGIN(name, InstanceClass) PCREATE_SOUND_PLUGIN_EX(name, InstanceClass, )


#define P_NULL_AUDIO_DEVICE "NullAudio"
PPLUGIN_STATIC_LOAD(NullAudio, PSoundChannel)

#ifdef _WIN32
  #define P_WINDOWS_MULTIMEDIA_DRIVER "WindowsMultimedia"
  PPLUGIN_STATIC_LOAD(WindowsMultimedia, PSoundChannel);
#elif defined(P_ANDROID)
  PPLUGIN_STATIC_LOAD(OpenSL_ES, PSoundChannel);
#elif defined(P_MACOSX) || defined(P_IOS)
  PPLUGIN_STATIC_LOAD(Apple, PSoundChannel);
#elif defined(__BEOS__)
  PPLUGIN_STATIC_LOAD(BeOS, PSoundChannel);
#endif

#if defined(P_DIRECTSOUND)
  #define P_DIRECT_SOUND_DRIVER "DirectSound"
  PPLUGIN_STATIC_LOAD(DirectSound, PSoundChannel);
#endif

#if defined(P_WAVFILE)
  #define P_WAV_FILE_DRIVER "WAVFile"
  PPLUGIN_STATIC_LOAD(WAVFile, PSoundChannel)
#endif

#if P_DTMF
  PPLUGIN_STATIC_LOAD(Tones, PSoundChannel)
#endif


#endif // PTLIB_SOUND_H


// End Of File ///////////////////////////////////////////////////////////////