taptaudio.h

Go to the documentation of this file.

/* $Id: taptaudio.h 192 2005-08-05 09:35:16Z tapted $ $URL: svn+ssh://pc-g33-9.it.usyd.edu.au/var/svn/pub/taptaudio/trunk/include/taptaudio.h $ */
#ifndef TAPTAUDIO_DOT_AITCH
#define TAPTAUDIO_DOT_AITCH

/**\file taptaudio.h
 * Tapted's Audio Subsystem manager singleton
 * \author Trent Apted <tapted@it.usyd.edu.au>
 * $Revision: 192 $
 * $Date: 2005-08-05 19:35:16 +1000 (Fri, 05 Aug 2005) $
 */

#ifndef SWIG
#include <string>
#endif

/** Possible PCM Audio formats */
enum AUDIO_FORMAT {
    AF_Default,     ///< Default format (Int16)
    AF_Float32,     ///< 32-bit floats
    AF_Int16,       ///< 16-bit signed ints
    AF_Int32,       ///< 32-bit signed ints
    AF_Int24,       ///< NFI - not supported
    AF_PackedInt24, ///< NFI - not supported
    AF_Int8,        ///< 8-bit signed ints
    AF_UInt8,       ///< 8-bit unsigned ints (not supported)
    AF_CustomFormat ///< Some custom format (not supported)
};

class AudioSystemImpl; //forward dec
class ASSample; //forward dec

/**
 * The audio system. Only one of these may exist at a time.
 * You may delete the old copy and make a new one if you wish.
 */
class AudioSystem {
public:
    /* configuration variables */
    /**
     * Number of audio tracks in mixer.
     *  - 0 will disable audio (singleton will never be created)
     *  - 1 will use a super-fast non-mixer version
     *  - >1 will use a stereo/mono N-track mixer
     * default: 32
     * \note track overhead is negligible
     */
    static unsigned AUDIO_TRACKS;


protected:
    ///no copying - we are a Singleton
    AudioSystem(const AudioSystem&) {}
    ///no assignment - we are a Singleton
    AudioSystem& operator=(const AudioSystem&) {return *this;}

    AudioSystemImpl* impl; ///< The pointer implementation
    static AudioSystem* instance; ///< The singleton
public:
    /**
     * Create the audio system
     */
    AudioSystem(AUDIO_FORMAT format = AF_Default,
                double sampleRate = 0.0,
                int inputChannels = 2,
                int outputChannels = 2,
                int deviceIDin = 0,
                int deviceIDout = 0
               );

    /**
     * Get the singleton instance. Returns NULL if it has
     * not been created, or it has been destroyed.
     */
    static AudioSystem* get() {return instance;}

    /**
     * Returns true if the AudioSystem is running.
     */
    static bool isRunning() {return instance;}

    /**
     * Set the debugging level for the audio system. 0 for none,
     * higher means more messages
     */
    static void setDebugLevel(unsigned level);

    /**
     * Set the FILE* at which debugging output is sent
     */
    static void setDebugFile(void* FILESTAR);

    /**
     * Lists the device IDs to stderr
     */
    static void listDevices();

    /**
     * Destructor destroys the singleton, allowing another to be made.
     */
    ~AudioSystem();

    /**
     * Load a sample that will be managed by the AudioSystem.
     * Client code will just use the return value as a pointer
     * to pass back into the audio system. Most of this can occur
     * in a background thread .. but maybe not two at once.
     *
     * \note If \a name is not registered, it must refer to a file AND
     * the file must be in a format convertible to the audio system.
     *
     * \param name A filename, or the name of a sample "known" to the AudioSystem
     * \return a loaded sample, that can be passed back to the AudioSystem
     */
    ASSample* loadSample(const char* name);
#ifndef SWIG
    /**\overload */
    ASSample* loadSample(const std::string &name);
#endif

    /**
     * Free all resources used by a sample, ONLY IF THE REFERENCE COUNT IS ZERO.
     * Will also remove itself from the sample registry. Only ever use this to
     * free a sample -- never delete() your reference.
     *
     * \param samp the sample to free
     * \return true if the reference count was zero and the sample was freed (i.e. success)
     */
    bool freeSample(ASSample* samp);

    /**
     * Load a raw sample from memory. Must match the format of the loaded
     * AudioSystem.
     */
    ASSample* loadRawSample(const char* name, void* data, unsigned long size);
#ifndef SWIG
    /**\overload */
    ASSample* loadRawSample(const std::string &name, void* data, unsigned long size);
#endif

    /**
     * Mix a loaded sample into the output audio stream.
     *
     * \param samp the sample to play
     * \param record_after if true, we will start recording when the sample is finished
     * \param record_size the size of the record buffer in seconds
     * \param vol the volume at which to mix the (output) sample
     * \param trackno if non-null, this will be set to the track number assigned to the sample
     * \returns true if there is a free track in which to play the sample
     */
    bool mixSample(ASSample *samp, bool record_after, double record_size = 30.0, float vol = 1.0f, unsigned* trackno = 0);

    /**\overload */
    bool mixSample(ASSample *samp, float vol = 1.0f, unsigned* trackno = 0);

    /**
     * Loop a sample. Stop it with stopSample.
     *
     * \note it makes no sense to record after one of these
     * \param samp the sample to play
     * \param vol the volume at which to mix the sample
     * \param trackno if non-null, this will be set to the track number assigned to the sample
     * \returns true if our mixer supports looping and
     *          there is a free track in which to play the sample
     */
    bool loopSample(ASSample *samp, float vol = 1.0f, unsigned* trackno = 0);

    /**
     * Stop playing instances of a sample.
     *
     * \param samp the sample to stop playing.
     * \param trackno the track (holding a playing \a samp) to stop; -1 for all
     * \returns the number of samples stopped
     */
    unsigned stopSample(ASSample *samp, int trackno = -1);

    /**
     * Adjust the volume of all playing instances of a sample
     *
     * \param samp the sample to adjust
     * \param vol the volume to set
     * \param trackno the track (holding a playing \a samp) to adjust; -1 for all
     * \returns the number of samples adjusted
     */
    unsigned setVolume(ASSample *samp, float vol = 1.0f, int trackno = -1);

    /**
     * Start buffering data from the audio input (microphone) into
     * the (single) recording buffer.
     *
     * \param secondsMax the maximum amount of time we will record for (we will trim the buffer if we record less)
     * \return true if we were able to start recording (false if we are already recording)
     */
    bool startRec(double secondsMax = 30.0);

    /**
     * Returns true if we are currently recording.
     */
    bool isRecording();

    /**
     * Stop *ALL* audio operations
     */
    void stop();

    /**
     * Stop buffering and create a sample from the recorded audio.
     *
     * \param name if non-null use \a name to identify the sample in the registry
     *             if null, a name will be generated based on the current time
     * \param save if true, the sample will be saved to disk, using \a name as the filename
     * \param save_in_thread if true, we will start a thread to save the data
     */
    ASSample* stopRec(const char* name = "", bool save = false, bool save_in_thread = false);
#ifndef SWIG
    /**\overload */
    ASSample* stopRec(const std::string &name = "", bool save = false, bool save_in_thread = false);
#endif

};

/**
 * This is an AudioSystem Sample. Nothing to do with ample amounts of donkeys.
 * We can maybe move this to the cpp file...
 */
class ASSample {
public:
    friend class AudioSystemImpl; ///Allow AudioSystemImpl to delete instances
#ifndef SWIG_MUST_PEEK
protected:
#endif
    /** Virtual Destructor -- does nothing, but private --
     * must be deleted by the audio system; NOT YOU! */
    virtual ~ASSample() {}
public:
    /** Number of non-registry references to this sample */
    unsigned refs;
    /** Constructor (refs start at 0) */
    ASSample() : refs(0) {}
    /** Return the number of channels in this sample */
    virtual unsigned getChannels() = 0;
    /** Return the format of this sample */
    virtual AUDIO_FORMAT getFormat() = 0;
    /** Return the number of bytes in this sample */
    virtual unsigned long numBytes() = 0;
    /** Get a pointer to the first byte of this sample */
    virtual const void* getBytes() = 0;
    /** Return the sample rate of this sample */
    virtual double getSamRate() = 0;
    /** Tell this sample that \a frames of its data were mixed by \a handle.
     * This function may by called at the interrupt level so cannot allocate
     * memory.
     */
    virtual void mixed(unsigned long /*frames*/, void* /*handle*/ = 0) {}
};

/** \example record_basic.cpp
 * Basic Recording
 */

/** \example record.cpp
 * Extended Recording
 */

/** \example volumes.cpp
 * Playing with given volumes
 */

/**
 * \example mixing.cpp
 * Mixing multiple tracks
 */

/** \example loopmix.cpp
 * Mixing and looping
 */

/** \example pytests.py
 * Python bindings
 */


#endif

---