audiere.h

Go to the documentation of this file.

#ifndef AUDIERE_H
#define AUDIERE_H


#include <vector>
#include <string>

#ifdef _MSC_VER
#pragma warning(disable : 4786)
#endif


#ifndef __cplusplus
  #error Audiere requires C++
#endif


// DLLs in Windows should use the standard (Pascal) calling convention
#ifndef ADR_CALL
  #if defined(WIN32) || defined(_WIN32)
    #define ADR_CALL __stdcall
  #else
    #define ADR_CALL
  #endif
#endif

// Export functions from the DLL
#ifndef ADR_DECL
#  if defined(WIN32) || defined(_WIN32)
#    ifdef AUDIERE_EXPORTS
#      define ADR_DECL __declspec(dllexport)
#    else
#      define ADR_DECL __declspec(dllimport)
#    endif
#  else
#    define ADR_DECL
#  endif
#endif



#define ADR_FUNCTION(ret) extern "C" ADR_DECL ret ADR_CALL
#define ADR_METHOD(ret) virtual ret ADR_CALL


namespace audiere {

  class RefCounted {
  protected:
    ~RefCounted() { }

  public:
    ADR_METHOD(void) ref() = 0;

    ADR_METHOD(void) unref() = 0;
  };


  template<typename T>
  class RefPtr {
  public:
    RefPtr(T* ptr = 0) {
      m_ptr = 0;
      *this = ptr;
    }

    RefPtr(const RefPtr<T>& ptr) {
      m_ptr = 0;
      *this = ptr;
    }

    ~RefPtr() {
      if (m_ptr) {
        m_ptr->unref();
        m_ptr = 0;
      }
    }
 
    RefPtr<T>& operator=(T* ptr) {
      if (ptr != m_ptr) {
        if (m_ptr) {
          m_ptr->unref();
        }
        m_ptr = ptr;
        if (m_ptr) {
          m_ptr->ref();
        }
      }
      return *this;
    }

    RefPtr<T>& operator=(const RefPtr<T>& ptr) {
      *this = ptr.m_ptr;
      return *this;
    }

    T* operator->() const {
      return m_ptr;
    }

    T& operator*() const {
      return *m_ptr;
    }

    operator bool() const {
      return (m_ptr != 0);
    }

    T* get() const {
      return m_ptr;
    }

  private:
    T* m_ptr;
  };


  template<typename T, typename U>
  bool operator==(const RefPtr<T>& a, const RefPtr<U>& b) {
      return (a.get() == b.get());
  }

  template<typename T>
  bool operator==(const RefPtr<T>& a, const T* b) {
      return (a.get() == b);
  }

  template<typename T>
  bool operator==(const T* a, const RefPtr<T>& b) {
      return (a == b.get());
  }
  

  template<typename T, typename U>
  bool operator!=(const RefPtr<T>& a, const RefPtr<U>& b) {
      return (a.get() != b.get());
  }

  template<typename T>
  bool operator!=(const RefPtr<T>& a, const T* b) {
      return (a.get() != b);
  }

  template<typename T>
  bool operator!=(const T* a, const RefPtr<T>& b) {
      return (a != b.get());
  }


  template<class Interface>
  class RefImplementation : public Interface {
  protected:
    RefImplementation() {
      m_ref_count = 0;
    }

    virtual ~RefImplementation() { }

  public:
    void ADR_CALL ref() {
      ++m_ref_count;
    }

    void ADR_CALL unref() {
      if (--m_ref_count == 0) {
        delete this;
      }
    }

  private:
    int m_ref_count;
  };


  class File : public RefCounted {
  protected:
    ~File() { }

  public:
    enum SeekMode {
      BEGIN,
      CURRENT,
      END,
    };

    ADR_METHOD(int) read(void* buffer, int size) = 0;

    ADR_METHOD(bool) seek(int position, SeekMode mode) = 0;

    ADR_METHOD(int) tell() = 0;
  };
  typedef RefPtr<File> FilePtr;


  enum SampleFormat {
    SF_U8,  
    SF_S16, 
  };


  enum FileFormat {
    FF_AUTODETECT,
    FF_WAV,
    FF_OGG,
    FF_FLAC,
    FF_MP3,
    FF_MOD,
    FF_AIFF,
    FF_SPEEX,
  };


  class SampleSource : public RefCounted {
  protected:
    ~SampleSource() { }

  public:
    ADR_METHOD(void) getFormat(
      int& channel_count,
      int& sample_rate,
      SampleFormat& sample_format) = 0;

    ADR_METHOD(int) read(int frame_count, void* buffer) = 0;

    ADR_METHOD(void) reset() = 0;

    ADR_METHOD(bool) isSeekable() = 0;

    ADR_METHOD(int) getLength() = 0;
    
    ADR_METHOD(void) setPosition(int position) = 0;

    ADR_METHOD(int) getPosition() = 0;

    ADR_METHOD(bool) getRepeat() = 0;

    ADR_METHOD(void) setRepeat(bool repeat) = 0;

    ADR_METHOD(int) getTagCount() = 0;

    virtual const char* ADR_CALL getTagKey(int i) = 0;

    virtual const char* ADR_CALL getTagValue(int i) = 0;

    virtual const char* ADR_CALL getTagType(int i) = 0;
  };
  typedef RefPtr<SampleSource> SampleSourcePtr;


  class LoopPointSource : public SampleSource {
  protected:
    ~LoopPointSource() { }

  public:
    ADR_METHOD(void) addLoopPoint(
      int location, int target, int loopCount) = 0;

    ADR_METHOD(void) removeLoopPoint(int index) = 0;

    ADR_METHOD(int) getLoopPointCount() = 0;

    ADR_METHOD(bool) getLoopPoint(
      int index, int& location, int& target, int& loopCount) = 0;
  };
  typedef RefPtr<LoopPointSource> LoopPointSourcePtr;


  class OutputStream : public RefCounted {
  protected:
    ~OutputStream() { }

  public:
    ADR_METHOD(void) play() = 0;

    ADR_METHOD(void) stop() = 0;

    ADR_METHOD(bool) isPlaying() = 0;

    ADR_METHOD(void) reset() = 0;

    ADR_METHOD(void) setRepeat(bool repeat) = 0;

    ADR_METHOD(bool) getRepeat() = 0;

    ADR_METHOD(void) setVolume(float volume) = 0;

    ADR_METHOD(float) getVolume() = 0;

    ADR_METHOD(void) setPan(float pan) = 0;

    ADR_METHOD(float) getPan() = 0;

    ADR_METHOD(void) setPitchShift(float shift) = 0;

    ADR_METHOD(float) getPitchShift() = 0;

    ADR_METHOD(bool) isSeekable() = 0;

    ADR_METHOD(int) getLength() = 0;
    
    ADR_METHOD(void) setPosition(int position) = 0;

    ADR_METHOD(int) getPosition() = 0;
  };
  typedef RefPtr<OutputStream> OutputStreamPtr;


  enum EventType {
    ET_STOP, 
  };


  class Event : public RefCounted {
  protected:
    ~Event() { }

  public:
    ADR_METHOD(EventType) getType() = 0;
  };
  typedef RefPtr<Event> EventPtr;


  class StopEvent : public Event {
  protected:
    ~StopEvent() { }

  public:
    EventType ADR_CALL getType() { return ET_STOP; }

    enum Reason {
      STOP_CALLED,  
      STREAM_ENDED, 
    };

    ADR_METHOD(OutputStream*) getOutputStream() = 0;

    ADR_METHOD(Reason) getReason() = 0;
  };
  typedef RefPtr<StopEvent> StopEventPtr;


  class Callback : public RefCounted {
  protected:
    ~Callback() { }

  public:
    ADR_METHOD(EventType) getType() = 0;

    ADR_METHOD(void) call(Event* event) = 0;
  };
  typedef RefPtr<Callback> CallbackPtr;

  
  class StopCallback : public Callback {
  protected:
    ~StopCallback() { }

  public:
    EventType ADR_CALL getType() { return ET_STOP; }
    void ADR_CALL call(Event* event) {
      streamStopped(static_cast<StopEvent*>(event));
    }

    ADR_METHOD(void) streamStopped(StopEvent* event) = 0;
  };
  typedef RefPtr<StopCallback> StopCallbackPtr;


  class AudioDevice : public RefCounted {
  protected:
    ~AudioDevice() { }

  public:
    ADR_METHOD(void) update() = 0;

    ADR_METHOD(OutputStream*) openStream(SampleSource* source) = 0;

    ADR_METHOD(OutputStream*) openBuffer(
      void* samples,
      int frame_count,
      int channel_count,
      int sample_rate,
      SampleFormat sample_format) = 0;

    ADR_METHOD(const char*) getName() = 0;

    ADR_METHOD(void) registerCallback(Callback* callback) = 0;
    
    ADR_METHOD(void) unregisterCallback(Callback* callback) = 0;

    ADR_METHOD(void) clearCallbacks() = 0;
  };
  typedef RefPtr<AudioDevice> AudioDevicePtr;


  class SampleBuffer : public RefCounted {
  protected:
    ~SampleBuffer() { }

  public:

    ADR_METHOD(void) getFormat(
      int& channel_count,
      int& sample_rate,
      SampleFormat& sample_format) = 0;

    ADR_METHOD(int) getLength() = 0;

    virtual const void* ADR_CALL getSamples() = 0;

    ADR_METHOD(SampleSource*) openStream() = 0;
  };
  typedef RefPtr<SampleBuffer> SampleBufferPtr;


  enum SoundEffectType {
    SINGLE,
    MULTIPLE,
  };


  class SoundEffect : public RefCounted {
  protected:
    ~SoundEffect() { }

  public:
    ADR_METHOD(void) play() = 0;

    ADR_METHOD(void) stop() = 0;

    ADR_METHOD(void) setVolume(float volume) = 0;

    ADR_METHOD(float) getVolume() = 0;

    ADR_METHOD(void) setPan(float pan) = 0;

    ADR_METHOD(float) getPan() = 0;

    ADR_METHOD(void) setPitchShift(float shift) = 0;

    ADR_METHOD(float) getPitchShift() = 0;
  };
  typedef RefPtr<SoundEffect> SoundEffectPtr;


  class CDDevice : public RefCounted {
  protected:
    virtual ~CDDevice() { }

  public:
    virtual const char* ADR_CALL getName() = 0;

    ADR_METHOD(int) getTrackCount() = 0;

    ADR_METHOD(void) play(int track) = 0;

    ADR_METHOD(void) stop() = 0;
    
    ADR_METHOD(void) pause() = 0;

    ADR_METHOD(void) resume() = 0;

    ADR_METHOD(bool) isPlaying() = 0;

    ADR_METHOD(bool) containsCD() = 0;

    ADR_METHOD(bool) isDoorOpen() = 0;

    ADR_METHOD(void) openDoor() = 0;

    ADR_METHOD(void) closeDoor() = 0;
  };
  typedef RefPtr<CDDevice> CDDevicePtr;


  class MIDIStream : public RefCounted {
  protected:
    virtual ~MIDIStream() { }

  public:
    ADR_METHOD(void) play() = 0;

    ADR_METHOD(void) stop() = 0;

    ADR_METHOD(void) pause() = 0;

    ADR_METHOD(bool) isPlaying() = 0;

    ADR_METHOD(int) getLength() = 0;

    ADR_METHOD(int) getPosition() = 0;

    ADR_METHOD(void) setPosition(int position) = 0;

    ADR_METHOD(bool) getRepeat() = 0;

    ADR_METHOD(void) setRepeat(bool repeat) = 0;
  };
  typedef RefPtr<MIDIStream> MIDIStreamPtr;


  class MIDIDevice : public RefCounted {
  protected:
    virtual ~MIDIDevice() { }

  public:
    ADR_METHOD(const char*) getName() = 0;

    ADR_METHOD(MIDIStream*) openStream(const char* filename) = 0;
  };
  typedef RefPtr<MIDIDevice> MIDIDevicePtr;


  namespace hidden {

    // these are extern "C" so we don't mangle the names

    ADR_FUNCTION(const char*) AdrGetVersion();

    ADR_FUNCTION(const char*) AdrGetSupportedFileFormats();

    ADR_FUNCTION(const char*) AdrGetSupportedAudioDevices();

    ADR_FUNCTION(int) AdrGetSampleSize(SampleFormat format);

    ADR_FUNCTION(AudioDevice*) AdrOpenDevice(
      const char* name,
      const char* parameters);

    ADR_FUNCTION(SampleSource*) AdrOpenSampleSource(
      const char* filename,
      FileFormat file_format);
    ADR_FUNCTION(SampleSource*) AdrOpenSampleSourceFromFile(
      File* file,
      FileFormat file_format);
    ADR_FUNCTION(SampleSource*) AdrCreateTone(double frequency);
    ADR_FUNCTION(SampleSource*) AdrCreateSquareWave(double frequency);
    ADR_FUNCTION(SampleSource*) AdrCreateWhiteNoise();
    ADR_FUNCTION(SampleSource*) AdrCreatePinkNoise();

    ADR_FUNCTION(LoopPointSource*) AdrCreateLoopPointSource(
      SampleSource* source);

    ADR_FUNCTION(OutputStream*) AdrOpenSound(
      AudioDevice* device,
      SampleSource* source,
      bool streaming);

    ADR_FUNCTION(SampleBuffer*) AdrCreateSampleBuffer(
      void* samples,
      int frame_count,
      int channel_count,
      int sample_rate,
      SampleFormat sample_format);
    ADR_FUNCTION(SampleBuffer*) AdrCreateSampleBufferFromSource(
      SampleSource* source);

    ADR_FUNCTION(SoundEffect*) AdrOpenSoundEffect(
      AudioDevice* device,
      SampleSource* source,
      SoundEffectType type);

    ADR_FUNCTION(File*) AdrOpenFile(
      const char* name,
      bool writeable);

    ADR_FUNCTION(File*) AdrCreateMemoryFile(
      const void* buffer,
      int size);

    ADR_FUNCTION(const char*) AdrEnumerateCDDevices();

    ADR_FUNCTION(CDDevice*) AdrOpenCDDevice(
      const char* name);  // Parameters?

    ADR_FUNCTION(MIDIDevice*) AdrOpenMIDIDevice(
      const char* name);  // Parameters?
  }




  /*-------- PUBLIC API FUNCTIONS --------*/


  inline const char* GetVersion() {
    return hidden::AdrGetVersion();
  }


  inline void SplitString(
    std::vector<std::string>& out,
    const char* in,
    char delim)
  {
    out.clear();
    while (*in) {
      const char* next = strchr(in, delim);
      if (next) {
        out.push_back(std::string(in, next));
      } else {
        out.push_back(in);
      }

      in = (next ? next + 1 : "");
    }
  }


  struct FileFormatDesc {
    std::string description;

    std::vector<std::string> extensions;
  };

  inline void GetSupportedFileFormats(std::vector<FileFormatDesc>& formats) {
    std::vector<std::string> descriptions;
    SplitString(descriptions, hidden::AdrGetSupportedFileFormats(), ';');

    formats.resize(descriptions.size());
    for (unsigned i = 0; i < descriptions.size(); ++i) {
      const char* d = descriptions[i].c_str();
      const char* colon = strchr(d, ':');
      formats[i].description.assign(d, colon);

      SplitString(formats[i].extensions, colon + 1, ',');
    }
  }


  struct AudioDeviceDesc {
    std::string name;

    // Textual description of device.
    std::string description;
  };

  inline void GetSupportedAudioDevices(std::vector<AudioDeviceDesc>& devices) {
    std::vector<std::string> descriptions;
    SplitString(descriptions, hidden::AdrGetSupportedAudioDevices(), ';');

    devices.resize(descriptions.size());
    for (unsigned i = 0; i < descriptions.size(); ++i) {
      std::vector<std::string> d;
      SplitString(d, descriptions[i].c_str(), ':');
      devices[i].name        = d[0];
      devices[i].description = d[1];
    }
  }


  inline int GetSampleSize(SampleFormat format) {
    return hidden::AdrGetSampleSize(format);
  }

  inline AudioDevice* OpenDevice(
    const char* name = 0,
    const char* parameters = 0)
  {
    return hidden::AdrOpenDevice(name, parameters);
  }

  inline SampleSource* OpenSampleSource(
    const char* filename,
    FileFormat file_format = FF_AUTODETECT)
  {
    return hidden::AdrOpenSampleSource(filename, file_format);
  }

  inline SampleSource* OpenSampleSource(
    const FilePtr& file,
    FileFormat file_format = FF_AUTODETECT)
  {
    return hidden::AdrOpenSampleSourceFromFile(file.get(), file_format);
  }

  inline SampleSource* CreateTone(double frequency) {
    return hidden::AdrCreateTone(frequency);
  }

  inline SampleSource* CreateSquareWave(double frequency) {
    return hidden::AdrCreateSquareWave(frequency);
  }

  inline SampleSource* CreateWhiteNoise() {
    return hidden::AdrCreateWhiteNoise();
  }

  inline SampleSource* CreatePinkNoise() {
    return hidden::AdrCreatePinkNoise();
  }

  inline LoopPointSource* CreateLoopPointSource(
    const SampleSourcePtr& source)
  {
    return hidden::AdrCreateLoopPointSource(source.get());
  }

  inline LoopPointSource* CreateLoopPointSource(
    const char* filename,
    FileFormat file_format = FF_AUTODETECT)
  {
    return CreateLoopPointSource(OpenSampleSource(filename, file_format));
  }

  inline LoopPointSource* CreateLoopPointSource(
    const FilePtr& file,
    FileFormat file_format = FF_AUTODETECT)
  {
    return CreateLoopPointSource(OpenSampleSource(file, file_format));
  }

  inline OutputStream* OpenSound(
    const AudioDevicePtr& device,
    const SampleSourcePtr& source,
    bool streaming = false)
  {
    return hidden::AdrOpenSound(device.get(), source.get(), streaming);
  }

  inline OutputStream* OpenSound(
    const AudioDevicePtr& device,
    const char* filename,
    bool streaming = false,
    FileFormat file_format = FF_AUTODETECT)
  {
    SampleSource* source = OpenSampleSource(filename, file_format);
    return OpenSound(device, source, streaming);
  }

  inline OutputStream* OpenSound(
    const AudioDevicePtr& device,
    const FilePtr& file,
    bool streaming = false,
    FileFormat file_format = FF_AUTODETECT)
  {
    SampleSource* source = OpenSampleSource(file, file_format);
    return OpenSound(device, source, streaming);
  }

  inline SampleBuffer* CreateSampleBuffer(
    void* samples,
    int frame_count,
    int channel_count,
    int sample_rate,
    SampleFormat sample_format)
  {
    return hidden::AdrCreateSampleBuffer(
      samples, frame_count,
      channel_count, sample_rate, sample_format);
  }

  inline SampleBuffer* CreateSampleBuffer(const SampleSourcePtr& source) {
    return hidden::AdrCreateSampleBufferFromSource(source.get());
  }

  inline SoundEffect* OpenSoundEffect(
    const AudioDevicePtr& device,
    const SampleSourcePtr& source,
    SoundEffectType type)
  {
    return hidden::AdrOpenSoundEffect(device.get(), source.get(), type);
  }

  inline SoundEffect* OpenSoundEffect(
    const AudioDevicePtr& device,
    const char* filename,
    SoundEffectType type,
    FileFormat file_format = FF_AUTODETECT)
  {
    SampleSource* source = OpenSampleSource(filename, file_format);
    return OpenSoundEffect(device, source, type);
  }

  inline SoundEffect* OpenSoundEffect(
    const AudioDevicePtr& device,
    const FilePtr& file,
    SoundEffectType type,
    FileFormat file_format = FF_AUTODETECT)
  {
    SampleSource* source = OpenSampleSource(file, file_format);
    return OpenSoundEffect(device, source, type);
  }

  inline File* OpenFile(const char* filename, bool writeable) {
    return hidden::AdrOpenFile(filename, writeable);
  }

  inline File* CreateMemoryFile(const void* buffer, int size) {
    return hidden::AdrCreateMemoryFile(buffer, size);
  }

  inline void EnumerateCDDevices(std::vector<std::string>& devices) {
    const char* d = hidden::AdrEnumerateCDDevices();
    while (d && *d) {
      devices.push_back(d);
      d += strlen(d) + 1;
    }
  }

  inline CDDevice* OpenCDDevice(const char* device) {
    return hidden::AdrOpenCDDevice(device);
  }

  inline MIDIDevice* OpenMIDIDevice(const char* device) {
    return hidden::AdrOpenMIDIDevice(device);
  }

}


#endif

---