PTLib  Version 2.10.10
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
sound.h
Go to the documentation of this file.
1 /*
2  * sound.h
3  *
4  * Sound interface class.
5  *
6  * Portable Windows Library
7  *
8  * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
9  *
10  * The contents of this file are subject to the Mozilla Public License
11  * Version 1.0 (the "License"); you may not use this file except in
12  * compliance with the License. You may obtain a copy of the License at
13  * http://www.mozilla.org/MPL/
14  *
15  * Software distributed under the License is distributed on an "AS IS"
16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
17  * the License for the specific language governing rights and limitations
18  * under the License.
19  *
20  * The Original Code is Portable Windows Library.
21  *
22  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
23  *
24  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
25  * All Rights Reserved.
26  *
27  * Contributor(s): ______________________________________.
28  *
29  * $Revision: 28275 $
30  * $Author: rjongbloed $
31  * $Date: 2012-08-29 21:42:35 -0500 (Wed, 29 Aug 2012) $
32  */
33 
34 
35 #ifndef PTLIB_SOUND_H
36 #define PTLIB_SOUND_H
37 
38 #ifdef P_USE_PRAGMA
39 #pragma interface
40 #endif
41 
42 #include <ptlib/plugin.h>
43 #include <ptlib/pluginmgr.h>
44 
52 class PSound : public PBYTEArray
53 {
54  PCLASSINFO(PSound, PBYTEArray);
55 
56  public:
65  PSound(
66  unsigned numChannels = 1,
67  unsigned sampleRate = 8000,
68  unsigned bitsPerSample = 16,
69  PINDEX bufferSize = 0,
70  const BYTE * data = NULL
71  );
72 
75  PSound(
76  const PFilePath & filename
77  );
78 
81  PSound & operator=(
82  const PBYTEArray & data
83  );
85 
97  PBoolean Load(
98  const PFilePath & filename
99  );
100 
107  PBoolean Save(
108  const PFilePath & filename
109  );
111 
114  PBoolean Play();
116 
118  PBoolean Play(const PString & device);
119 
123  void SetFormat(
124  unsigned numChannels,
125  unsigned sampleRate,
126  unsigned bitsPerSample
127  );
128 
132  unsigned GetEncoding() const { return encoding; }
133 
135  unsigned GetChannels() const { return numChannels; }
136 
138  unsigned GetSampleRate() const { return sampleRate; }
139 
141  unsigned GetSampleSize() const { return sampleSize; }
142 
144  DWORD GetErrorCode() const { return dwLastError; }
145 
147  PINDEX GetFormatInfoSize() const { return formatInfo.GetSize(); }
148 
150  const void * GetFormatInfoData() const { return (const BYTE *)formatInfo; }
152 
163  static PBoolean PlayFile(
164  const PFilePath & file,
165  PBoolean wait = true
166  );
167 
169  static void Beep();
171 
172  protected:
174  unsigned encoding;
176  unsigned numChannels;
178  unsigned sampleRate;
180  unsigned sampleSize;
182  DWORD dwLastError;
185 };
186 
187 
251 class PSoundChannel : public PChannel
252 {
253  PCLASSINFO(PSoundChannel, PChannel);
254 
255  public:
258  enum Directions {
259  Closed = -1,
262  };
263 
265  PSoundChannel();
266 
271  const PString & device,
272  Directions dir,
273  unsigned numChannels = 1,
274  unsigned sampleRate = 8000,
275  unsigned bitsPerSample = 16
276  );
277  //
278 
279  virtual ~PSoundChannel();
280  // Destroy and close the sound driver
282 
288  PPluginManager * pluginMgr = NULL
289  );
290 
296  const PString & driverName,
297  Directions direction,
298  PPluginManager * pluginMgr = NULL
299  );
300 
301  // For backward compatibility
303  const PString & driverName,
304  Directions direction,
305  PPluginManager * pluginMgr = NULL
306  ) { return GetDriversDeviceNames(driverName, direction, pluginMgr); }
307 
310  static PSoundChannel * CreateChannel (
311  const PString & driverName,
312  PPluginManager * pluginMgr = NULL
313  );
314 
315  /* Create the matching sound channel that corresponds to the device name.
316  So, for "fake" return a device that will generate fake video.
317  For "Phillips 680 webcam" (eg) will return appropriate grabber.
318  Note that Phillips will return the appropriate grabber also.
319 
320  This is typically used with the return values from GetDeviceNames().
321  */
323  const PString & deviceName,
324  Directions direction,
325  PPluginManager * pluginMgr = NULL
326  );
327 
334  const PString & driverName,
335  const PString & deviceName,
336  Directions direction,
337  unsigned numChannels = 1,
338  unsigned sampleRate = 8000,
339  unsigned bitsPerSample = 16,
340  PPluginManager * pluginMgr = NULL
341  );
342 
351  static PString GetDefaultDevice(
352  Directions dir // Sound I/O direction
353  );
354 
368  Directions direction,
369  PPluginManager * pluginMgr = NULL
370  );
371 
378  virtual PBoolean Open(
379  const PString & device,
380  Directions dir,
381  unsigned numChannels = 1,
382  unsigned sampleRate = 8000,
383  unsigned bitsPerSample = 16
384  );
385 
391  virtual PBoolean IsOpen() const;
392 
397  virtual PBoolean Close();
398 
404  virtual int GetHandle() const;
405 
407  virtual PString GetName() const;
408 
411  {
412  return activeDirection;
413  }
414 
416  static const char * GetDirectionText(Directions dir);
417 
418  virtual const char * GetDirectionText() const
419  {
421  }
422 
430  virtual PBoolean Abort();
432 
444  virtual PBoolean SetFormat(
445  unsigned numChannels = 1,
446  unsigned sampleRate = 8000,
447  unsigned bitsPerSample = 16
448  );
449 
451  virtual unsigned GetChannels() const;
452 
454  virtual unsigned GetSampleRate() const;
455 
457  virtual unsigned GetSampleSize() const;
458 
467  virtual PBoolean SetBuffers(
468  PINDEX size,
469  PINDEX count = 2
470  );
471 
477  virtual PBoolean GetBuffers(
478  PINDEX & size, // Size of each buffer
479  PINDEX & count // Number of buffers
480  );
481 
482  enum {
483  MaxVolume = 100
484  };
485 
494  virtual PBoolean SetVolume(
495  unsigned volume
496  );
497 
506  virtual PBoolean GetVolume(
507  unsigned & volume
508  );
509 
515  virtual bool SetMute(
516  bool mute
517  );
518 
524  virtual bool GetMute(
525  bool & mute
526  );
527 
529 
532 
553  virtual PBoolean Write(const void * buf, PINDEX len);
554 
555 
578  virtual PBoolean Write(
579  const void * buf,
580  PINDEX len,
581  const void * mark
582  );
583 
585  virtual PINDEX GetLastWriteCount() const;
586 
603  virtual PBoolean PlaySound(
604  const PSound & sound,
605  PBoolean wait = true
606  );
607 
623  virtual PBoolean PlayFile(
624  const PFilePath & file,
625  PBoolean wait = true
626  );
627 
634  virtual PBoolean HasPlayCompleted();
635 
643 
645 
676  virtual PBoolean Read(
677  void * buf,
678  PINDEX len
679  );
680 
682  PINDEX GetLastReadCount() const;
683 
701  virtual PBoolean RecordSound(
702  PSound & sound
703  );
704 
717  virtual PBoolean RecordFile(
718  const PFilePath & file
719  );
720 
727  virtual PBoolean StartRecording();
728 
736  virtual PBoolean IsRecordBufferFull();
737 
747 
756 
767 
768  protected:
771 
777 };
778 
779 
781 
782 // define the sound plugin service descriptor
783 
785 {
786  public:
787  virtual PObject * CreateInstance(int /*userData*/) const { return new className; }
788  virtual PStringArray GetDeviceNames(int userData) const { return className::GetDeviceNames((PSoundChannel::Directions)userData); }
789 };
790 
791 #define PCREATE_SOUND_PLUGIN(name, className) \
792  static PSoundChannelPluginServiceDescriptor<className> className##_descriptor; \
793  PCREATE_PLUGIN(name, PSoundChannel, &className##_descriptor)
794 
795 #ifdef _WIN32
796  PPLUGIN_STATIC_LOAD(WindowsMultimedia, PSoundChannel);
797 #elif defined(__BEOS__)
799 #endif
800 
801 #if defined(P_DIRECTSOUND)
802  PPLUGIN_STATIC_LOAD(DirectSound, PSoundChannel);
803 #endif
804 
805 #if defined(P_WAVFILE)
807 #endif
808 
809 
810 #endif // PTLIB_SOUND_H
811 
812 
813 // End Of File ///////////////////////////////////////////////////////////////
Directions GetDirection() const
Get the direction of the channel.
Definition: sound.h:410
Definition: sound.h:483
static PSoundChannel * CreateOpenedChannel(const PString &driverName, const PString &deviceName, Directions direction, unsigned numChannels=1, unsigned sampleRate=8000, unsigned bitsPerSample=16, PPluginManager *pluginMgr=NULL)
Create an opened sound channel that corresponds to the specified names.
virtual PBoolean PlayFile(const PFilePath &file, PBoolean wait=true)
Play a sound file to the open device.
virtual PBoolean Close()
Close the channel, shutting down the link to the data source.
Abstract class for a generalised sound channel, and an implementation of PSoundChannel for old code t...
Definition: sound.h:251
PSound(unsigned numChannels=1, unsigned sampleRate=8000, unsigned bitsPerSample=16, PINDEX bufferSize=0, const BYTE *data=NULL)
Create a new sound, using the parameters provided.
Directions
Definition: sound.h:258
static PBoolean PlayFile(const PFilePath &file, PBoolean wait=true)
Play a sound file to the default device.
virtual PString GetName() const
Get the name of the open channel.
virtual PBoolean WaitForPlayCompletion()
Block calling thread until the sound play begun with PlaySound() or PlayFile() has completed...
unsigned GetChannels() const
Get the number of channels (mono/stereo) in the sound.
Definition: sound.h:135
unsigned GetSampleSize() const
Get the sample size in bits per sample.
Definition: sound.h:141
Directions activeDirection
This is the direction that this sound channel is opened for use in.
Definition: sound.h:776
static void Beep()
Play the &quot;standard&quot; warning beep for the platform.
Definition: plugin.h:109
virtual PBoolean GetVolume(unsigned &volume)
Get the volume of the play/read process.
const void * GetFormatInfoData() const
Get pointer to the platform dependent format info.
Definition: sound.h:150
static PStringArray GetDriversDeviceNames(const PString &driverName, Directions direction, PPluginManager *pluginMgr=NULL)
Get sound devices that correspond to the specified driver name.
virtual PBoolean SetVolume(unsigned volume)
Set the volume of the play/read process.
Definition: pluginmgr.h:57
PSound & operator=(const PBYTEArray &data)
Set new data bytes for the sound.
virtual unsigned GetSampleSize() const
Get the sample size in bits per sample.
PSoundChannel * m_baseChannel
Definition: sound.h:769
virtual PObject * CreateInstance(int) const
Definition: sound.h:787
virtual PBoolean HasPlayCompleted()
Indicate if the sound play begun with PlayBuffer() or PlayFile() has completed.
virtual PINDEX GetLastWriteCount() const
Get number of bytes written in last Write() operation.
This class describes a full description for a file on the particular platform.
Definition: filepath.h:65
virtual PBoolean RecordFile(const PFilePath &file)
Record into the platform dependent sound file all of the buffer&#39;s of sound data.
virtual PBoolean Read(void *buf, PINDEX len)
Low level read from the channel.
virtual PBoolean SetFormat(unsigned numChannels=1, unsigned sampleRate=8000, unsigned bitsPerSample=16)
Set the format for play/record.
static PSoundChannel * CreateChannelByName(const PString &deviceName, Directions direction, PPluginManager *pluginMgr=NULL)
This is an array collection class of PString objects.
Definition: pstring.h:2024
virtual PBoolean StartRecording()
Start filling record buffers.
virtual PBoolean AreAllRecordBuffersFull()
Determine if all of the record buffer allocated has been filled.
static PStringArray GetDriverNames(PPluginManager *pluginMgr=NULL)
Get the list of available sound drivers (plug-ins)
virtual PBoolean Abort()
Abort the background playing/recording of the sound channel.
DWORD GetErrorCode() const
Get the platform dependent error code from the last file load.
Definition: sound.h:144
virtual ~PSoundChannel()
Definition: sound.h:260
virtual PStringArray GetDeviceNames(int userData) const
Definition: sound.h:788
BOOL PBoolean
Definition: object.h:102
PBoolean Load(const PFilePath &filename)
Load a platform dependent sound file (eg .WAV file for Win32) into the object.
virtual PBoolean IsRecordBufferFull()
Determine if a record buffer has been filled, so that the next Read() call will not block...
virtual PBoolean WaitForRecordBufferFull()
Block the thread until a record buffer has been filled, so that the next Read() call will not block...
PINDEX GetFormatInfoSize() const
Get the size of the platform dependent format info.
Definition: sound.h:147
A class representing a sound.
Definition: sound.h:52
Definition: sound.h:259
Array of unsigned characters.
Definition: array.h:670
PBoolean Play()
Play the sound on the default sound device.
virtual PBoolean WaitForAllRecordBuffersFull()
Block the thread until all of the record buffer allocated has been filled.
virtual PBoolean Write(const void *buf, PINDEX len)
Low level write (or play) to the channel.
virtual unsigned GetSampleRate() const
Get the sample rate in samples per second.
static PString GetDefaultDevice(Directions dir)
Get the name for the default sound devices/driver that is on this platform.
static PSoundChannel * CreateChannel(const PString &driverName, PPluginManager *pluginMgr=NULL)
Create the sound channel that corresponds to the specified driver name.
PPLUGIN_STATIC_LOAD(FakeVideo, PVideoInputDevice)
Abstract class defining I/O channel semantics.
Definition: channel.h:107
Definition: sound.h:261
virtual PINDEX GetSize() const
Get the current size of the container.
PINDEX GetLastReadCount() const
Return number of bytes read in last Read() call.
The character string class.
Definition: pstring.h:108
DWORD dwLastError
Last error code for Load()/Save() functions.
Definition: sound.h:182
virtual PBoolean GetBuffers(PINDEX &size, PINDEX &count)
Get the internal buffers for the sound channel I/O.
void SetFormat(unsigned numChannels, unsigned sampleRate, unsigned bitsPerSample)
Set the internal sound format to linear PCM at the specification in the parameters.
PBoolean Save(const PFilePath &filename)
Save a platform dependent sound file (eg .WAV file for Win32) from the object.
unsigned GetEncoding() const
Get the current encoding.
Definition: sound.h:132
unsigned sampleSize
Number of bits per sample.
Definition: sound.h:180
virtual int GetHandle() const
Get the OS specific handle for the PSoundChannel.
PReadWriteMutex m_baseMutex
Definition: sound.h:770
PBYTEArray formatInfo
Full info on the format (platform dependent)
Definition: sound.h:184
virtual bool SetMute(bool mute)
Set the mute state of the play/read process.
virtual unsigned GetChannels() const
Get the number of channels (mono/stereo) in the sound.
static PStringArray GetDeviceNames(const PString &driverName, Directions direction, PPluginManager *pluginMgr=NULL)
Definition: sound.h:302
unsigned sampleRate
Samples per second.
Definition: sound.h:178
virtual const char * GetDirectionText() const
Definition: sound.h:418
virtual PBoolean PlaySound(const PSound &sound, PBoolean wait=true)
Play a sound to the open device.
virtual bool GetMute(bool &mute)
Get the mute state of the play/read process.
This class defines a thread synchronisation object.
Definition: syncthrd.h:251
virtual PBoolean Open(const PString &device, Directions dir, unsigned numChannels=1, unsigned sampleRate=8000, unsigned bitsPerSample=16)
Open the specified device for playing or recording.
PSoundChannel()
Create a sound channel.
virtual PBoolean IsOpen() const
Test if this instance of PSoundChannel is open.
unsigned numChannels
Number of channels eg mono/stereo.
Definition: sound.h:176
Ultimate parent class for all objects in the class library.
Definition: object.h:1118
virtual PBoolean RecordSound(PSound &sound)
Record into the sound object all of the buffer&#39;s of sound data.
virtual PBoolean SetBuffers(PINDEX size, PINDEX count=2)
Set the internal buffers for the sound channel I/O.
unsigned encoding
Format code.
Definition: sound.h:174
unsigned GetSampleRate() const
Get the sample rate in samples per second.
Definition: sound.h:138