PTLib  Version 2.10.11
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 {
254 
255  public:
258  enum Directions {
259  Closed = -1,
261  Player
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 
287  static PStringArray GetDriverNames(
288  PPluginManager * pluginMgr = NULL
289  );
290 
295  static PStringArray GetDriversDeviceNames(
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  */
322  static PSoundChannel * CreateChannelByName(
323  const PString & deviceName,
324  Directions direction,
325  PPluginManager * pluginMgr = NULL
326  );
327 
333  static PSoundChannel * CreateOpenedChannel(
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 
367  static PStringArray GetDeviceNames(
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  {
420  return GetDirectionText(activeDirection);
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 
642  virtual PBoolean WaitForPlayCompletion();
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 
746  virtual PBoolean AreAllRecordBuffersFull();
747 
755  virtual PBoolean WaitForRecordBufferFull();
756 
765  virtual PBoolean WaitForAllRecordBuffersFull();
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
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.
unsigned GetChannels() const
Get the number of channels (mono/stereo) in the sound.
Definition: sound.h:135
#define PCLASSINFO(cls, par)
Declare all the standard PTLib class information.
Definition: object.h:1049
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 "standard" warning beep for the platform.
Definition: plugin.h:109
const void * GetFormatInfoData() const
Get pointer to the platform dependent format info.
Definition: sound.h:150
Definition: pluginmgr.h:57
PSound & operator=(const PBYTEArray &data)
Set new data bytes for the sound.
PSoundChannel * m_baseChannel
Definition: sound.h:769
virtual PObject * CreateInstance(int) const
Definition: sound.h:787
This class describes a full description for a file on the particular platform.
Definition: filepath.h:65
This is an array collection class of PString objects.
Definition: pstring.h:2024
DWORD GetErrorCode() const
Get the platform dependent error code from the last file load.
Definition: sound.h:144
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.
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
Array of unsigned characters.
Definition: array.h:670
PBoolean Play()
Play the sound on the default sound device.
PPLUGIN_STATIC_LOAD(FakeVideo, PVideoInputDevice)
Abstract class defining I/O channel semantics.
Definition: channel.h:107
virtual PINDEX GetSize() const
Get the current size of the container.
The character string class.
Definition: pstring.h:108
DWORD dwLastError
Last error code for Load()/Save() functions.
Definition: sound.h:182
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
PReadWriteMutex m_baseMutex
Definition: sound.h:770
PBYTEArray formatInfo
Full info on the format (platform dependent)
Definition: sound.h:184
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
This class defines a thread synchronisation object.
Definition: syncthrd.h:251
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
unsigned encoding
Format code.
Definition: sound.h:174
unsigned GetSampleRate() const
Get the sample rate in samples per second.
Definition: sound.h:138