CascadeAudioPlayer.h

Go to the documentation of this file.

//
// CascadeAudioPlayer.h - header file for class CascadeAudioPlayer
//
// Copyright (c) 2004, Roku, LLC.  All rights reserved.
//

#ifndef _ROKU_INCLUDE_CASCADE_AV_CASCADEAUDIOPLAYER_H
#define _ROKU_INCLUDE_CASCADE_AV_CASCADEAUDIOPLAYER_H

#include <cascade/av/CascadeAudioCodec.h>
#include <cascade/av/CascadeAudioPlaybackDevice.h>
#include <cascade/util/CascadeStream.h>

#ifndef DOXY_SKIP
    namespace CascadePrivate { class CascadeAudioPlayerInitializer; };
#endif

class CascadeAudioPlayer : public CascadeObject
{
public: class Client;   // forward declaration
public:
        CascadeAudioPlayer();
        virtual ~CascadeAudioPlayer();
public:
    virtual bool Open(Client * pClient = NULL);
    virtual void Close();
    virtual bool IsOpen();
    enum { kOutputFlagAnalog = (1 << 0), kOutputFlagSPDIF = (1 << 1) };    
    virtual bool QueueStream(CascadeStream & stream, const char * pType = NULL, u32 nOutputFlags = (kOutputFlagAnalog|kOutputFlagSPDIF));
        //   "PCM:samplerate:numchannels:bitspersample:polarity:endianness:order:durationinmilliseconds"
    virtual bool Stop();
    virtual bool Pause();
    virtual bool Resume();
        virtual bool SetVolume(u16 nVolume);
        virtual bool SetVolumePercent(u8 nVolume);
    virtual bool IsPlaying();
    virtual bool IsStopped();
    virtual bool IsPaused();
    virtual bool AttachDevice(CascadeAudioPlaybackDevice & device);
    virtual bool DetachDevice();
public:    
    class SampleSet
    {
    public:
        u32  m_nStreamID;               
        u32  m_nSequenceNumber;         
        u32  m_nNumSamples;             
        u8 * m_pSamples;                
        u32  m_nTimestampMilliseconds;  
        u32  m_nDurationMilliseconds;   
        u32  m_nSampleBytes;            
    public:
        u32 m_nNumChannels;             
        u32 m_nSampleRate;              
        u32 m_nBitsPerSample;           
    };

    enum PlaybackResult
    { 
        kNormalCompletion = 0,              
        kPlaybackStopped,                   
        kErrorUnknown,                      
        kErrorOutOfMemory,                  
        kErrorUnsupportedSampleRate,        
        kErrorUnsupportedBitsPerSample,     
        kErrorUnsupportedNumChannels,       
        kErrorUnsupportedSamplePolarity,    
        kErrorUnsupportedSampleEndianness,  
        kErrorUnsupportedSampleOrder,       
        kErrorUnknownAudioType,             
        kErrorCodecInputFailure,            
        kErrorStreamReadFailure,            
        kErrorDeviceNonexistant,            
        kErrorDeviceFailure,                
        kErrorDeviceUnavailable,            
        kErrorUnsupportedOutputFlags,       
    };
    
    static const char * PlaybackResultToString(PlaybackResult result);

    class Client
    {
    public:
        virtual void OnAudioDecodeBegin(u32 nStreamID, CascadeStream * pStream, u32 nDurationInMilliseconds);
            // called when decoding of the stream begins
            // NOTE the nStreamID which is assigned to the stream indicated by pStream.
            // You'll need to NOTE it because that is what subsequent notifications use to uniquely identify the stream.
        virtual void OnAudioBuffering(u32 nStreamID, u32 nBuffersFilled, u32 nBuffersToFill);
            // Indicates that buffering is occurring either becuase of an initial pre-load or because
            // an underflow occurred.  nBuffersFilled / nBuffersToFill * 100 is the percent complete
            // of the buffering phase.  OnAudioBuffering gets called throughout the buffering
            // phase until nBuffersFilled == nBuffersToFill.
        virtual void OnAudioPlaybackBegin(u32 nStreamID);
            // Indicates audio has started to come out.  This function is called after pre-loading of buffers
            // is complete and audio starts actually playing, and also after an underflow when audio-buffering
            // has been re-engaged and finished, and audio is again flowing.
        virtual void OnAudioDecodeEnd(u32 nStreamID, CascadeStream * pStream, PlaybackResult result, u32 nPlaybackResultData);
            // Indicates that the player has finished decoding (and using) pStream.
            // pStream is now owned by the client again (CascadeAudioPlayer assumed ownership when QueueStream() was
            // called).  The client may feel free to delete pStream if they wish.
            // Note that OnAudioDecodeEnd() may be called significantly in advance of the end of the actual
            // audio playback.
        virtual void OnAudioPlaybackEnd(u32 nStreamID, PlaybackResult result);
            // Called when audio has finished playing.

        virtual void OnVisualizePrepare(u32 nStreamID, const SampleSet & samples);
        virtual void OnVisualizeExecute(u32 nStreamID, u32 nSequenceNumber, u32 nTimestampMilliseconds, u32 nBuffersQueued, u32 nTotalBuffers);
        virtual void OnPlaybackPause();
        virtual void OnPlaybackResume();
        virtual void OnPlaybackStop();
    };
#ifndef DOXY_SKIP
    private:
        friend class CascadePrivate::CascadeAudioPlayerInitializer;
#endif
private:
    class Player;
    Player * m_pPlayer;
};

#endif // #ifndef _ROKU_INCLUDE_CASCADE_AV_CASCADEAUDIOPLAYER_H

//  LOG
//  07-Mar-04   dwoodward       created from CascadeMP3Player
//  29-Mar-04   dwoodward   added codec registration
//  25-May-04   mjkobb      Updated a comment
//  16-Jun-04   dsletten    added nStreamUniqueID to SampleSet and OnVisualizeExecute()
//  23-Jun-04   dwoodward   added Open() and Close()
//  29-Sep-04   dwoodward   Added nOutputFlags parameter to QueueStream()
//  09-Dec-04   mjkobb      Added SetVolumePercent
//  28-Mar-05   dwoodward   got rid of RegisterCodec
//  15-Apr-05   dwoodward   added OnPlaybackPause(), OnPlaybackResume(), OnPlaybackStop(), PlaybackResultToString()

---